Definition
The variable dictionary — often called a *codebook* — attaches to each column of the dataset a set of declared properties: a stable technical identifier, a readable label, a type, a measurement scale, a unit, bounds of the possible and the plausible, a closed list of categories for categorical variables, permitted reasons for absence, and mappings to standards.
Its decisive property is temporal: it is written before capture, not inferred afterwards. A dictionary reconstructed after the fact documents what the data appears to contain; a dictionary written in advance constrains what it may contain.
Why it matters
- It makes the column interpretable.
bmi = 31.2means nothing without knowing whether the value was measured or computed, on what date, and by which formula. - It makes absence legible. An empty cell can mean "not sought", "sought and not found", or "not applicable". Those three cases are handled differently in analysis, and only the dictionary tells them apart.
- It makes units comparable. A glucose value in
mg/dLand another inmmol/Ldo not aggregate; declaring the unit makes conversion possible and checkable. - It makes automatic checking possible. Without declared bounds, no rule can refuse an aberrant value at entry.
Example
A dictionary entry for a score variable, as it appears in a urology study:
| Property | Value | What it is for |
|---|---|---|
| Identifier | ipss_total | Stable, never renamed — this is what the analysis script calls |
| Label | Total IPSS score | What a human reads |
| Type | Integer | Forbids "moderate" in a numeric column |
| Scale | Ordinal | Determines which statistical tests are admissible |
| Unit | point (dimensionless) | Avoids confusion with a percentage |
| Possible bound | 0 – 35 | Beyond this the value is refused: the score does not exist |
| Plausible bound | 0 – 30 | Beyond this the value passes with a warning |
| Permitted absence | not sought · patient unable to answer | Two distinct situations, traced separately |
Related standards
CDASH supplies reusable variable names and definitions for capture; UCUM normalises how units are written; LOINC identifies laboratory observations; the FAIR principles make metadata the condition of reuse.