Configuration

The most straightforward way to customize a codebook is by using a settings object whose properties describe the chart's behavior and appearance. Parameters for the settings object are described in detail below. All defaults can be over-written by users when creating a codebook.

settings

object

An object passed to webcodebook.createCodebook() (or its alias webcodebook.createChart()) which controls the settings and appearance of the output.

settings.dataName

character

Added in V1.2. A short description of the data set used in the title section.

default: null

settings.filters

array

Specifies which data columns should be used to create filters. For example, filters:["Sex", "Age", "Site"] would create filters for the 3 specified variables. If no values are specified (as is the default), filters are created using the autofilters setting described below.

default: []

settings.autofilter

number

Ignored when settings.filters is specified. When no filters are specified by the user, filters are created for all categorical variables with least 2 unique levels, but no more than settings.autofilter unique levels. So, by default filters are created for categorical variables with 2-10 levels.

default: 10

settings.groups

array

Specifies which data columns should be included in the "group by" drop down. If no values are specified (as is the default), the dropdown is populated using the autogroups setting described below.

default: []

settings.autogroups

number

Ignored when settings.groups is specified. When no groups are specified by the user, the group dropdown is populated with all categorical variables with least 2 unique levels, but no more than setting.autogroups unique levels. So, by default, the group dropdown includes categorical variables with 2-5 levels.

default: 5

settings.autobins

boolean

Specifies whether the number of bins for each continuous variable should be calculated using the Freedman-Diaconis rule or whether a set number of bins (established in settings.nBins) should be used for all variables.

default: true

settings.nBins

number

Ignored when settings.autobins is set to true. Specifies the number of bins used in each histogram.

default: 100

settings.levelSplit

number

Specifies the number of levels in a categorical variable above which the vertical bar chart renderer should be used instead the horizontal bar chart renderer.

default: 5

settings.maxLevels

number

Added in v1.7. Specifies the number of levels above which the column is considered to be a character variable (as opposed to categorical). No bar chart is drawn by default for character variables, but can be requested by a user with a button push.

default: 100

settings.controlVisibility

character

Added in v1.1. Sets control visibility on initial load, with the following valid options:

• "visible" - filters are visible, filter toggle is visible
• "minimized" - filters are hidden, filter toggle is visible
• "hidden" - filters are hidden, filter toggle is hidden (must be set by user when creating the codebook)

default: "visible"

settings.chartVisibility

character

Added in v1.3. Sets visibility for codebook charts on initial load, with the following valid options:

• "visible" - charts are visible, chart toggle is visible
• "minimized" - charts are hidden, chart toggle is visible
• "hidden" - charts are hidden, chart toggle is hidden

default: "visible"

settings.tabs

array of character or object

Sets tabs to be included in the codebook. The simplest way to specify tabs is via an array of strings. Valid options are as follows (others are ignored):

• "codebook"
• "listing"
• "chartMaker" (added in v1.3)
• "settings"
• "files" (recommended use on in conjunction with explorer functionality)

Alternatively, users can specify an array of objects to customize the label and instructions components of the tabs. The key parameter of the object should match the text string described above. Other object labels will overwrite the default behavior specified in this file. For example, this array would show the codebook and settings tabs only, with a custom label for settings: {"tabs":["codebook",{key:"settings", label:"Customize Settings"}]}.

default: ["codebook","listing","chartMaker","settings"]

settings.defaultTab

character

Added in v1.1. Specify which tab to be shown on initial load from values in settings.tabs.

default: First value in settings.tabs.

settings.hiddenVariables

array of variable

Added in v1.1. Specifies a list of variables for whom no summary rows, filters or group selections will be displayed. Any variable names included in the array that are not found in the raw data will be silently ignored.

default: []

settings.meta

array of objects

Added in v1.2. Each object in the array provides metadata for the columns in the loaded data. value_col (required) and label (optional) have special meanings described below. All other key/value pairs are simply reported as provided in the "Meta" section header view on the "Summary Table" tab.

default: []

meta[].value_col

string required

A string matching a column in the dataset. meta objects with no matching data column are ignored.

meta[].label

string optional

If a label parameter is provided, it is included in the settings.variableLabels array described below. Labels defined settings.meta can be overwritten by a second label is provided in settings.variableLabels.

meta[].type

string optional

Added in v1.6. If meta[].type is specified, the column is treated as either "categorical" or "continuous" (the 2 valid options). Types defined settings.meta can be overwritten by a second type provided in settings.variableTypes. When type is not specified in either location (or an invalid entry is given), the column's type is determined algorithmically.

settings.variableLabels

array of objects

Added in v1.1. Specifies a list of value_col/label objects whose label value propagates to group options, filter labels, summary row titles, grouped chart titles, and data listing headers

default: []

settings.variableTypes

array of objects

Added in v1.6. Specifies a list of value_col/type objects whose type value determines whether the column is treated as "continuous" or "categorical" (the 2 valid options). When type is not specified either here or in the congfig.meta object as described above (or an invalid entry is given), the column's type is determined algorithmically.

default: []

settings.whiteSpaceAsMissing

boolean

Added in v1.6. Specifies whether whitespace should be considered missing. When true values matching the following regular expression are flagged as missing: /^\s*$/

default: true

settings.missingValues

array

An array of values that are be considered missing.

default: [null, NaN, undefined]