Variable schema reference • chmsflow

Overview

chmsflow uses two CSV metadata files to define how raw CHMS variables are harmonized. These files are bundled with the package in inst/extdata/ and are also available as data objects (variables and variable_details).

variables.csv – lists every harmonized variable with its name, label, type, and unit
variable-details.csv – defines the row-by-row recoding rules that rec_with_table() applies

This vignette is a column-by-column reference for both files. For an explanation of how these files fit into the harmonization workflow, see Methodology.

`variables.csv`

#> There are 211 variables, grouped in 24 subjects and 5 sections.

Columns

1. variable – the name of the harmonized variable.

2. label – a short label for the variable.

3. labelLong – a more detailed label for the variable.

4. section – the broad grouping where this variable belongs (e.g., sociodemographics, health behaviour, health status).

5. subject – the specific topic the variable pertains to (e.g., age, smoking, blood pressure).

6. variableType – whether the harmonized variable is Categorical or Continuous.

7. units – the units of the harmonized variable, or N/A if unitless.

8. databaseStart – the CHMS cycles that contain the variable, separated by commas.

9. variableStart – the source variable names as listed in each CHMS cycle. Uses the same format conventions as variable-details.csv (see below).

`variable-details.csv`

#> There are 1111 rows and 17 columns.

Row structure

Each row defines the recoding rule for one category of one variable. For a categorical variable with 4 categories, plus a not-applicable category, a missing category, and an else row, there are 7 rows.

Missing data rows use haven::tagged_na():

NA::a – valid skip (not applicable)
NA::b – missing (don’t know, refusal, not stated)

The else row catches values not matched by any other row.

Columns

We use clc_sex as a running example.

1. variable – name of the harmonized variable.

variable
clc_sex
clc_sex
clc_sex
clc_sex
clc_sex

2. dummyVariable – dummy variable name for each category (categorical variables only; N/A for continuous).

	variable	dummyVariable
297	clc_sex	clc_sex_cat2_1
298	clc_sex	clc_sex_cat2_2
299	clc_sex	clc_sex_cat2_NAa
300	clc_sex	clc_sex_cat2_NAb
301	clc_sex	clc_sex_cat2_NAb

3. typeEnd – variable type of the harmonized variable (cat or cont).

	variable	dummyVariable	typeEnd
297	clc_sex	clc_sex_cat2_1	cat
298	clc_sex	clc_sex_cat2_2	cat
299	clc_sex	clc_sex_cat2_NAa	cat
300	clc_sex	clc_sex_cat2_NAb	cat
301	clc_sex	clc_sex_cat2_NAb	cat

4. databaseStart – CHMS cycles containing this variable, separated by commas.

	variable	dummyVariable	typeEnd	databaseStart
297	clc_sex	clc_sex_cat2_1	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6
298	clc_sex	clc_sex_cat2_2	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6
299	clc_sex	clc_sex_cat2_NAa	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6
300	clc_sex	clc_sex_cat2_NAb	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6
301	clc_sex	clc_sex_cat2_NAb	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6

5. variableStart – source variable names in each CHMS cycle. Supports several formats:

Format	Meaning	Example
`[variable_name]`	Same name across all cycles	`[clc_sex]`
`cycle1::name1, [default_name]`	Cycle-specific exception with a default	`cycle1::amsdmva1, [ammdmva1]`
`DerivedVar::[var1, var2, ...]`	Computed by a function from listed inputs	`DerivedVar::[lab_bcre, pgdcgt, clc_sex, clc_age]`

	variable	dummyVariable	typeEnd	databaseStart	variableStart
297	clc_sex	clc_sex_cat2_1	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]
298	clc_sex	clc_sex_cat2_2	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]
299	clc_sex	clc_sex_cat2_NAa	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]
300	clc_sex	clc_sex_cat2_NAb	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]
301	clc_sex	clc_sex_cat2_NAb	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]

6. typeStart – variable type in the source CHMS data (cat or cont).

	variable	dummyVariable	typeEnd	databaseStart	variableStart	typeStart
297	clc_sex	clc_sex_cat2_1	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat
298	clc_sex	clc_sex_cat2_2	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat
299	clc_sex	clc_sex_cat2_NAa	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat
300	clc_sex	clc_sex_cat2_NAb	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat
301	clc_sex	clc_sex_cat2_NAb	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat

7. recEnd – the value to recode each category to. Special values:

copy – pass through unchanged (for continuous variables)
NA::a – not applicable
NA::b – missing
Func::function_name – derived variable computed by the named function

	variable	dummyVariable	typeEnd	databaseStart	variableStart	typeStart	recEnd
297	clc_sex	clc_sex_cat2_1	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	1
298	clc_sex	clc_sex_cat2_2	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	2
299	clc_sex	clc_sex_cat2_NAa	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::a
300	clc_sex	clc_sex_cat2_NAb	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::b
301	clc_sex	clc_sex_cat2_NAb	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::b

8. numValidCat – number of non-missing categories (categorical only; N/A for continuous). Not used by rec_with_table().

	variable	dummyVariable	typeEnd	databaseStart	variableStart	typeStart	recEnd	numValidCat
297	clc_sex	clc_sex_cat2_1	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	1	2
298	clc_sex	clc_sex_cat2_2	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	2	2
299	clc_sex	clc_sex_cat2_NAa	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::a	2
300	clc_sex	clc_sex_cat2_NAb	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::b	2
301	clc_sex	clc_sex_cat2_NAb	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::b	2

9. catLabel – short label for the category.

	variable	dummyVariable	typeEnd	databaseStart	variableStart	typeStart	recEnd	numValidCat	catLabel
297	clc_sex	clc_sex_cat2_1	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	1	2	Male
298	clc_sex	clc_sex_cat2_2	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	2	2	Female
299	clc_sex	clc_sex_cat2_NAa	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::a	2	not applicable
300	clc_sex	clc_sex_cat2_NAb	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::b	2	missing
301	clc_sex	clc_sex_cat2_NAb	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::b	2	missing

10. catLabelLong – detailed label, matching CHMS documentation where possible.

	variable	dummyVariable	typeEnd	databaseStart	variableStart	typeStart	recEnd	numValidCat	catLabel	catLabelLong
297	clc_sex	clc_sex_cat2_1	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	1	2	Male	Male
298	clc_sex	clc_sex_cat2_2	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	2	2	Female	Female
299	clc_sex	clc_sex_cat2_NAa	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::a	2	not applicable	not applicable
300	clc_sex	clc_sex_cat2_NAb	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::b	2	missing	missing
301	clc_sex	clc_sex_cat2_NAb	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::b	2	missing	missing

11. units – units of the variable, or N/A. Must be consistent across all rows of the same variable.

	variable	dummyVariable	typeEnd	databaseStart	variableStart	typeStart	recEnd	numValidCat	catLabel	catLabelLong	units
297	clc_sex	clc_sex_cat2_1	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	1	2	Male	Male	N/A
298	clc_sex	clc_sex_cat2_2	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	2	2	Female	Female	N/A
299	clc_sex	clc_sex_cat2_NAa	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::a	2	not applicable	not applicable	N/A
300	clc_sex	clc_sex_cat2_NAb	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::b	2	missing	missing	N/A
301	clc_sex	clc_sex_cat2_NAb	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::b	2	missing	missing	N/A

12. recStart – the source value or range to match. Uses interval notation:

[1, 4] – all integer values from 1 to 4
[1, 2.5] – all values from 1 to 2.5 (2.55 would not match)
else – all values not matched by other rows
copy – combined with else, copies unmatched values unchanged

	variable	dummyVariable	typeEnd	databaseStart	variableStart	typeStart	recEnd	numValidCat	catLabel	catLabelLong	units	recStart
297	clc_sex	clc_sex_cat2_1	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	1	2	Male	Male	N/A	1
298	clc_sex	clc_sex_cat2_2	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	2	2	Female	Female	N/A	2
299	clc_sex	clc_sex_cat2_NAa	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::a	2	not applicable	not applicable	N/A	6
300	clc_sex	clc_sex_cat2_NAb	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::b	2	missing	missing	N/A	[7, 9]
301	clc_sex	clc_sex_cat2_NAb	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::b	2	missing	missing	N/A	else

13. catStartLabel – label for the source category, matching CHMS documentation. For missing rows, describes each missing code and its value.

	variable	dummyVariable	typeEnd	databaseStart	variableStart	typeStart	recEnd	numValidCat	catLabel	catLabelLong	units	recStart	catStartLabel
297	clc_sex	clc_sex_cat2_1	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	1	2	Male	Male	N/A	1	Male
298	clc_sex	clc_sex_cat2_2	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	2	2	Female	Female	N/A	2	Female
299	clc_sex	clc_sex_cat2_NAa	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::a	2	not applicable	not applicable	N/A	6	Valid skip
300	clc_sex	clc_sex_cat2_NAb	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::b	2	missing	missing	N/A	[7, 9]	Don’t know (7); Refusal (8); Not stated (9)
301	clc_sex	clc_sex_cat2_NAb	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::b	2	missing	missing	N/A	else	else

14. variableStartShortLabel – short label for the source variable.

	variable	dummyVariable	typeEnd	databaseStart	variableStart	typeStart	recEnd	numValidCat	catLabel	catLabelLong	units	recStart	catStartLabel	variableStartShortLabel
297	clc_sex	clc_sex_cat2_1	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	1	2	Male	Male	N/A	1	Male	Sex
298	clc_sex	clc_sex_cat2_2	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	2	2	Female	Female	N/A	2	Female	Sex
299	clc_sex	clc_sex_cat2_NAa	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::a	2	not applicable	not applicable	N/A	6	Valid skip	Sex
300	clc_sex	clc_sex_cat2_NAb	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::b	2	missing	missing	N/A	[7, 9]	Don’t know (7); Refusal (8); Not stated (9)	Sex
301	clc_sex	clc_sex_cat2_NAb	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::b	2	missing	missing	N/A	else	else	Sex

15. variableStartLabel – detailed label for the source variable, matching CHMS documentation.

	variable	dummyVariable	typeEnd	databaseStart	variableStart	typeStart	recEnd	numValidCat	catLabel	catLabelLong	units	recStart	catStartLabel	variableStartShortLabel	variableStartLabel
297	clc_sex	clc_sex_cat2_1	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	1	2	Male	Male	N/A	1	Male	Sex	Sex
298	clc_sex	clc_sex_cat2_2	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	2	2	Female	Female	N/A	2	Female	Sex	Sex
299	clc_sex	clc_sex_cat2_NAa	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::a	2	not applicable	not applicable	N/A	6	Valid skip	Sex	Sex
300	clc_sex	clc_sex_cat2_NAb	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::b	2	missing	missing	N/A	[7, 9]	Don’t know (7); Refusal (8); Not stated (9)	Sex	Sex
301	clc_sex	clc_sex_cat2_NAb	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::b	2	missing	missing	N/A	else	else	Sex	Sex

16. notes – relevant notes about changes between CHMS cycles, missing categories, or variable type changes.

	variable	dummyVariable	typeEnd	databaseStart	variableStart	typeStart	recEnd	numValidCat	catLabel	catLabelLong	units	recStart	catStartLabel	variableStartShortLabel	variableStartLabel
297	clc_sex	clc_sex_cat2_1	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	1	2	Male	Male	N/A	1	Male	Sex	Sex
298	clc_sex	clc_sex_cat2_2	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	2	2	Female	Female	N/A	2	Female	Sex	Sex
299	clc_sex	clc_sex_cat2_NAa	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::a	2	not applicable	not applicable	N/A	6	Valid skip	Sex	Sex
300	clc_sex	clc_sex_cat2_NAb	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::b	2	missing	missing	N/A	[7, 9]	Don’t know (7); Refusal (8); Not stated (9)	Sex	Sex
301	clc_sex	clc_sex_cat2_NAb	cat	cycle1, cycle2, cycle3, cycle4, cycle5, cycle6	[clc_sex]	cat	NA::b	2	missing	missing	N/A	else	else	Sex	Sex

Derived variables

Derived variables use two special column values:

variableStart: DerivedVar::[var1, var2, var3] – lists the input variables
recEnd: Func::function_name – names the R function that computes the derived variable

See Derived variables for details on how derived variables work.

Next steps

See it in action – Follow the Analysis walkthrough to see how these metadata files drive a real analysis.
Understand the methodology – For the design rationale behind the rules-as-data approach, see Methodology.
Add your own variables – To extend the schema with custom variables, see How to add variables.