Why a Variable Dictionary Matters
A data file may contain columns named trt, visit, and crp, but those names alone do not establish what the columns mean. Is trt stored as text or as integers? Does a value of 1 mean treatment or control? Is crp measured in mg/L or another unit? These details affect how analysts interpret and prepare the data.
A variable dictionary records those details in a consistent, machine-readable form. In a MICE workflow, it provides a shared reference for understanding the analysis dataset and for checking whether its columns and observed values match their documented definitions. It does not determine the imputation model, replace a statistical analysis plan, or explain the history of every data transformation.
What to Put in Each Record
The variable name should match the dataset column exactly, including capitalization if the software treats capitalization as meaningful. Names should be unique. A label is a concise description for a person; unlike the name, it may contain spaces and explanatory wording. A useful label identifies what is recorded, and, when needed, the population or time point to which it refers.
The storage type describes how values are represented in the file, such as integer, decimal number, text, or date. It is not the same as a variable’s analytic meaning. For example, a treatment group may be stored as the integers 0 and 1 while representing a categorical variable. A continuous laboratory measurement might be stored as a decimal number. The dictionary should not leave readers to infer whether integer codes represent quantities or categories.
A unit states the scale of measurement, such as years, kilograms, or mg/L. It is useful to record a clear value such as “mg/L,” rather than a vague phrase such as “lab units.” If a variable has no meaningful physical unit—for example, a group indicator—record that explicitly as “not applicable” rather than leaving readers to guess.
Permitted values should describe what the dataset is intended to contain. For a categorical variable, list the allowed codes and their meanings. For a quantitative variable, specify an appropriate range or other constraint when one is known and justified. Do not claim a strict range merely because it seems typical: a plausible value range and a formally permitted range are not necessarily the same. If a restriction is not known, document that limitation rather than inventing one.
| Dictionary field | Purpose | Example |
|---|---|---|
| name | Exact dataset column identifier | crp_mg_l |
| label | Human-readable description | C-reactive protein at baseline |
| storage_type | Representation used in the file | decimal number |
| unit | Measurement scale, or explicit non-applicability | mg/L |
| permitted_values | Allowed categories or documented constraints | Non-negative numeric values |
A dictionary can also include useful fields such as the time point, data source, derivation rule, or an analytic role such as outcome or predictor. These additions are valuable only when their meanings are defined consistently. Keep descriptive metadata separate from judgments that may change across analyses: a variable’s role in one imputation model does not necessarily define its role in every later model.
Representing the Dictionary Consistently
A machine-readable format needs an agreed structure. For example, a project might use one record per variable, with the same named fields for every record. A table or structured text file can work if it represents multi-part values consistently. For a categorical variable, permitted values should be represented as code-and-label pairs, not as an unexplained string such as “0, 1.” For a numeric constraint, record whether it is a lower bound, upper bound, or both, and whether endpoints are included.
The following hypothetical records illustrate the distinction between code and meaning. The labels and constraints are part of the dictionary, not conclusions inferred from observing a particular dataset.
| name | label | storage_type | unit | permitted_values |
|---|---|---|---|---|
| arm | Assigned study group | integer | not applicable | 0 = usual care; 1 = intervention |
| age_years | Age at enrolment | decimal number | years | 18 through 90, inclusive |
| crp_mg_l | C-reactive protein at baseline | decimal number | mg/L | Non-negative numeric values |
The entry for arm says that the stored values are integers, but their meaning is categorical. The entry for age_years states a unit and a bounded range. The range should be included only if it is a defensible project requirement; it must not be silently substituted for a looser expectation about what values are common.
Worked Example: Drafting Entries for a Small Analysis Dataset
Suppose a hypothetical MICE analysis dataset has three columns: arm, coded 0 for usual care and 1 for intervention; age_years, recorded in years; and score_total, a questionnaire total designed to range from 0 to 40. Draft the essential dictionary entries.
Step 1: Record exact names and labels. Use the column names arm, age_years, and score_total. Labels can be “Assigned study group,” “Age at enrolment,” and “Questionnaire total score,” respectively.
Step 2: Document storage types and units. Suppose inspection of this hypothetical file shows that arm and score_total are stored as integers, and age_years as a decimal number. Record “not applicable” as the unit for arm, “years” for age_years, and “points” for score_total.
Step 3: Define permitted values. Record arm as 0 = usual care and 1 = intervention; age_years as a non-negative numeric value if that is all the project specification establishes; and score_total as an integer from 0 through 40, inclusive. The score constraint follows from the stated instrument design: 40 − 0 = 40 points between its endpoints. Do not add an age upper bound without a documented reason.
The entries now distinguish what is stored from what values mean. In particular, the numeric storage of arm does not make it a quantitative measurement.
Using the Dictionary to Check a Dataset
A practical check compares the dataset with the dictionary in a defined order. First compare the sets of documented names and dataset columns. Then examine each column’s representation and meaning, and finally compare its observed values with its documented permitted values. A discrepancy is a finding to investigate, not automatic permission to modify the data.
The set difference identifies columns present in the dataset but absent from the dictionary. The reverse difference identifies documented variables absent from the dataset. For values, let \(D_j\) be the observed values for variable \(j\), and let \(A_j\) be its documented set of permitted values when the variable is categorical. A value-level check looks for observations \(x\) such that \(x \notin A_j\). For a numeric interval, the corresponding check compares each value with the documented endpoints. These checks are meaningful only if the dictionary itself is clear and the dataset’s representation has been correctly identified.
This logic also explains why an unexpected value should not be silently recoded. It could be a data-entry error, a legitimate value omitted from the dictionary, a change in coding, or a misunderstanding of the column. The analyst needs to resolve its meaning and document the decision. The earlier material on preserving raw data and tracking provenance is relevant when recording such decisions.
Worked Example: Checking Categorical Values Against the Dictionary
Consider a hypothetical dataset with 12 records. The dictionary says arm is an integer-coded category with permitted values 0 = usual care and 1 = intervention. A check finds nine values of 0, two values of 1, and one value of 2.
The permitted set is \(A_{\text{arm}}=\{0,1\}\). The observed distinct-value set is \(D_{\text{arm}}=\{0,1,2\}\), so:
Thus, one of the 12 records has a value not documented as permitted. Its share of the records is \(1/12 \times 100 = 8.333\%\). This percentage describes the frequency of the discrepancy in this hypothetical dataset; it does not establish why the value occurred. The analyst should check the source and coding documentation before deciding whether the dictionary or the data need correction.
The dictionary also says what 0 and 1 mean, so the nine records coded 0 and two coded 1 can be described as usual-care and intervention records. Without those labels, reporting only the counts by code would be incomplete.
Units, Constraints, and Derived Variables
Units are especially important when a variable has been transformed. A column named weight could contain kilograms or pounds; a numeric range alone cannot resolve that ambiguity. If a project converts weight from pounds to kilograms, the dictionary should describe the resulting column and its unit. If a new variable is derived, document its derivation sufficiently for another analyst to understand its meaning, rather than assigning it a label that merely repeats its name.
Constraints should be tested in the same terms in which they are documented. If age is permitted from 18 through 90, inclusive, then values 18 and 90 satisfy the constraint, while values below 18 or above 90 do not. If a total score must be an integer from 0 through 40, a value of 20.5 fails the integer requirement even though it lies within the numerical endpoints. A check that tests only the interval would miss that violation.
Worked Example: Checking Both a Range and a Storage-Type Requirement
A hypothetical dictionary specifies that score_total is an integer number of points from 0 through 40, inclusive. A small extract contains the values 18, 40, 41, and 20.5.
Range check. Values 18, 40, and 20.5 satisfy \(0 \leq x \leq 40\), while 41 does not. Therefore, one of four values is outside the range: \(1/4 \times 100 = 25.00\%\).
Integer check. The values 18, 40, and 41 are integers. The value 20.5 is not, so one of four values fails the integer requirement: again, \(1/4 \times 100 = 25.00\%\).
Combined check. A value must satisfy both requirements. Here, 18 and 40 satisfy both; 41 fails the range requirement; and 20.5 fails the integer requirement. Two of four values therefore violate at least one requirement: \(2/4 \times 100 = 50.00\%\). These findings identify records for investigation; they do not justify rounding 20.5 or changing 41 without supporting information.
Common Pitfalls and Alternatives
- Confusing storage type and analytic meaning. An integer-coded group is not necessarily a quantitative variable. Record both its representation and the interpretation of its values.
- Using ambiguous permitted values. “Codes 0–3” does not explain the categories. Record each code and its meaning.
- Implying a unit through a column name. A name such as weight_kg is helpful, but the unit should also be explicit in the dictionary.
- Creating unsupported bounds. A value that is unusual is not automatically invalid. Distinguish documented constraints from expectations about typical observations.
- Treating a dictionary as a guarantee. Documentation states intended meaning; it does not prove that the dataset conforms.
A variable dictionary differs from a narrative codebook mainly in structure and intended use: a codebook may be written for a human reader, while a machine-readable dictionary uses stable fields and consistent value representations. It also differs from a full validation system, which can implement checks automatically. A dictionary can support such a system, but merely writing one does not run the checks or resolve discrepancies.
For MICE work, clear variable definitions help analysts understand which columns represent measurements, categories, or derived quantities before constructing an analysis dataset. However, the dictionary does not decide which variables belong in a particular imputation model, how missing values are represented, or which imputation method is appropriate. Those are separate decisions, and the dictionary should avoid silently making them on the analyst’s behalf.
Check Your Understanding
Answer each question, then compare your reasoning with the solutions below.
- A variable named group is stored as integers 1 and 2. What additional information should its dictionary entry provide?
- A dictionary permits a score from 0 through 10, inclusive. Is a value of 10 a violation? Is a value of 10.5 a violation if the variable must also be an integer?
- A dataset has a column not listed in the dictionary. What can be concluded from this discrepancy, and what cannot be concluded without further investigation?
- Why should a unit be recorded explicitly if it already appears in a column name?
- A categorical variable has permitted values \(\{0,1\}\). A dataset has 20 records: 8 values of 0, 10 values of 1, and 2 values of 3. What proportion of records have an undocumented value?
Solutions. (1) Record what groups 1 and 2 mean, the variable’s label, its integer storage type, and that it is categorical rather than a measured quantity. (2) A value of 10 is permitted because the upper endpoint is included. A value of 10.5 violates the integer requirement, even though it is within the numeric endpoints. (3) The column is undocumented, so the dataset and dictionary do not match. This does not establish whether the column is erroneous, newly added, or intentionally omitted; check its source and purpose. (4) A name can be ambiguous, changed, or overlooked. An explicit unit supports consistent interpretation and checking. (5) Two of 20 records have an undocumented value, so \(2/20 \times 100 = 10.00\%\). The finding identifies a discrepancy but does not explain its cause.