Why a Regression Data Dictionary Matters
A regression result is only interpretable if readers know what the model’s variables represent. A column called group might contain treatment labels, numeric codes, or a derived classification; a column called change might mean follow-up minus baseline or the reverse. Those differences affect how model terms should be understood.
A regression data dictionary is a structured record of the variables used in an analysis. It gives each variable a clear meaning and documents its type, units, possible values, coding, reference level when relevant, and derivation when it was created from other fields. The dictionary is not a substitute for the data or the analysis; it makes the connection between them explicit.
The dictionary should describe the variables as they are actually used in the analysis, not just the fields as they appeared in a source file. A raw field named visit2_bp might become the analysis variable followup_systolic_bp; a recorded height in centimetres might be converted to metres before a derived body-mass index is calculated. Documenting the analysis variable and its connection to its source fields helps another analyst understand and reproduce that preparation.
What to Record for Each Variable
A useful entry starts with a name that identifies the analysis variable and a plain-language definition that says what it measures and, where necessary, when it was measured. It then records the analysis type, units, valid values and coding. For categorical predictors, specify the reference level. For a derived variable, give the formula, the input variables, and enough detail to determine the direction and units of the calculation.
| Dictionary field | What to record |
|---|---|
| Analysis-variable name | The exact name used for the variable in the prepared analysis data. |
| Meaning | What is measured or classified, including timing or population when needed. |
| Analysis type | For example, continuous quantitative, count, binary categorical, or categorical with multiple levels. |
| Units | The measurement scale, such as years, kilograms, or millimetres of mercury; write “not applicable” for categories. |
| Valid values and coding | Allowed values and their meanings, including the mapping from recorded codes to labels. |
| Reference level | The comparison category for a categorical predictor; state “not applicable” for variables without categories. |
| Derivation | The exact formula and input variables, or “none” if the variable is not derived. |
Distinguish the analysis type from how values happen to be stored. For example, a binary group may be stored as 0 and 1, but its substantive meaning is categorical. Conversely, a number stored as text may represent a quantitative measurement after preparation. Explain the meaning of numeric codes rather than relying on readers to infer it.
For a categorical predictor, the reference level is the category used as the comparison in its coding. Naming that level prevents the common ambiguity of knowing that a variable is categorical without knowing which group the model terms compare against. A continuous predictor has no category reference level. State this explicitly as “not applicable” rather than leaving the field blank.
A dictionary should also distinguish valid values from missing or unavailable values when that distinction matters. For example, a value of 0 should not be described as missing if it is a valid measurement, and a special code such as 99 should not be treated as a meaningful measurement if it represents “not recorded.” State how such codes are represented in the analysis data. Do not invent a missing-value convention when the data preparation has not established one.
Worked Example: Documenting a Two-Group Predictor
Consider a clearly hypothetical analysis of systolic blood pressure measured at a follow-up visit for adults assigned in a simulated example to either a standard program or an enhanced program. The analysis uses follow-up blood pressure as the outcome and program group as a predictor. Suppose the prepared group variable is coded 0 for standard and 1 for enhanced.
A dictionary entry for the outcome could read: Name: followup_systolic_bp. Meaning: systolic blood pressure at the follow-up visit. Analysis type: continuous quantitative. Units: mmHg. Valid values: recorded blood-pressure measurements in mmHg. Coding: measurement value in mmHg; no category labels. Reference level: not applicable. Derivation: none.
A dictionary entry for the predictor could read: Name: program_group. Meaning: assigned program group. Analysis type: binary categorical. Units: not applicable. Valid values and coding: 0 = standard program; 1 = enhanced program. Reference level: standard program (0). Derivation: none.
This entry makes a later model term for program_group understandable: the coding identifies the two categories, and the stated reference identifies the comparison. It does not by itself establish a causal effect or determine whether a regression model is appropriate. Those questions require the study design and the analysis, not just a dictionary.
How Reference Levels Clarify Model Terms
The role of coding can be seen in a simple model for a continuous outcome \(Y\) and a two-level predictor \(D\). Suppose \(D=0\) denotes the reference group and \(D=1\) denotes the other group, and the specified conditional-mean model is \(E(Y\mid D)=\beta_0+\beta_1D\). Here \(\beta_0\) is the modelled mean for the reference group and \(\beta_1\) is the difference between the modelled means for the group coded 1 and the group coded 0.
Subtracting the first modelled mean from the second gives \((\beta_0+\beta_1)-\beta_0=\beta_1\). This is an algebraic consequence of the stated coding and model form. Reversing the 0 and 1 labels reverses the direction of that contrast, which is why a dictionary must record both the coding and the reference level.
For a categorical predictor with more than two levels, a dictionary should list every level and name the reference. A common representation uses indicator variables: each indicator equals 1 for one specified non-reference category and 0 otherwise. The category represented by all-zero indicators is the reference. The dictionary need not replace the model description, but it should make clear which category each indicator represents and which category serves as the comparison.
Worked Example: Recording a Multi-Level Category
Suppose a hypothetical study records smoking status as “never,” “former,” or “current.” For a regression analysis, the analyst uses never smoking as the reference level. The dictionary entry should preserve the substantive labels as well as the numeric indicator coding.
Name: smoking_status. Meaning: smoking-status category recorded at the study assessment. Analysis type: categorical with three levels. Units: not applicable. Valid values: never, former, current. Reference level: never. Derivation: none.
If the prepared analysis data represent this predictor with two indicators, record the mappings explicitly: former_smoker = 1 for former and 0 otherwise; current_smoker = 1 for current and 0 otherwise. A never smoker has both indicators equal to 0. For a hypothetical person whose status is former, the values are \(1\) and \(0\); for a current smoker, they are \(0\) and \(1\); for a never smoker, they are \(0\) and \(0\).
The entry therefore makes it possible to identify the comparison group and the meaning of each indicator without guessing from its name. If the analysis uses a different coding scheme, the dictionary should describe that actual scheme instead.
Derived Variables Need Reproducible Formulas
A derived variable is calculated from one or more other variables. Its name and definition should make clear what it represents, but that is not enough to reproduce it: the dictionary must also give the exact formula, the input variables, and any units or direction conventions that affect the result. Words such as “change,” “rate,” or “standardized score” are not formulas.
For a difference between two measurements, explicitly state which measurement is subtracted from which. If the formula is follow-up minus baseline, a negative value means the follow-up measurement is lower than the baseline measurement. If the order is reversed, the sign meaning reverses too. The dictionary should document the chosen order rather than leave it implicit.
Worked Example: Defining a Change Variable
In a hypothetical blood-pressure data set, a participant has a baseline systolic blood pressure of 142 mmHg and a follow-up value of 138 mmHg. The analysis creates a variable called sbp_change.
A complete entry states: Name: sbp_change. Meaning: change in systolic blood pressure from baseline to follow-up. Analysis type: continuous quantitative. Units: mmHg. Valid values and coding: signed numerical differences; negative values indicate a lower follow-up value. Reference level: not applicable. Derivation: follow-up systolic blood pressure minus baseline systolic blood pressure, in mmHg.
For the stated hypothetical measurements, the calculation is \(138-142=-4\) mmHg. The negative sign indicates a 4 mmHg decrease from baseline to follow-up under this formula. If the formula instead used baseline minus follow-up, the result would be \(142-138=4\) mmHg and the sign would have the opposite interpretation. Recording the equation removes that ambiguity.
Checking a Dictionary Before Use
A dictionary is most useful when its entries agree with the prepared analysis data. Check that every variable used in the analysis has an entry, that labels and codes match the actual values, and that derived-variable formulas match the preparation steps. Check that units are given for measurements and that category reference levels are named. These checks are documentation checks; they do not establish that the chosen model is valid or that the variables were measured without error.
Keep definitions specific enough to distinguish variables that might otherwise be confused. For example, “age” could mean age at enrollment or age at follow-up; “weight” could mean kilograms or pounds; and “treatment” could mean assigned group or treatment actually received. A concise definition that states the relevant timing, scale, or status prevents a vague name from carrying more meaning than it actually does.
Common Mistakes
- Leaving numeric codes unexplained. The correction is to map each code to its category and state which category is the reference.
- Using a variable name as its definition. “Change score” does not tell a reader which measurement is subtracted. Give the exact formula and direction.
- Omitting units. A value such as 70 could be a measurement in kilograms, inches, or another scale. Record the unit used in the analysis data.
- Treating storage format as variable type. A value stored as 0 or 1 can represent a categorical predictor. Explain what the codes mean, not just how they are stored.
- Leaving the reference level unstated. Naming all the categories is not enough when model terms depend on a comparison. State the reference explicitly.
Check Your Understanding
Use these questions to check whether you can make a dictionary entry unambiguous.
- A predictor is stored as 0 for “usual care” and 1 for “new program.” What coding and reference-level details should its dictionary entry include?
- Why is “change in weight” an incomplete definition of a derived variable? Write the extra information needed to reproduce it.
- A three-level categorical predictor has levels A, B, and C, with B as the reference. What should the dictionary record about the coding and reference?
- A measurement is stored in centimetres, then converted to metres for analysis. Which scale and units should the analysis-variable entry describe?
- Why should an analysis dictionary state that a category reference level is not applicable for a continuous predictor rather than leave the field unexplained?