variable_details.csv

Source: vignettes/variable_details.Rmd

Introduction

The variable_details.csv worksheet contain details for the variables in variables.csv. Information from variable_details.csv worksheet is used by the rec_with_table() function to transform variables identified in variable_details$variableStart to the newly transformed variable in variable_details$variable.

#> In the `variable_details.csv` worksheet there are 1554 rows and 16 columns

Structure of variable_details.csv

Rows

Each row in variable_details.csv holds the recode rules for transforming a single category for a variable in variables.csv. An exception to this rule are the “don’t know”, “refusal”, and “not stated” categories, which are combined as a single missing category. For each unique variable, an else row is used to assign values not identified in other rows and are outside identified ranges. We recommend not combining variables across the CCHS if variable has an important change between CCHS cycles variable_details$notes is used to identify issues that may be relevant when transforming the variable or category.

If a categorical variable has 4 distinct categories, along with a “not applicable” category and the 3 missing categories, there will be 7 rows:

  • 4 for each distinct category

  • 1 for the not applicable category

  • 1 for the missing categories

  • 1 else row.

Naming convention for not applicable and missing values

rec_with_table() uses the tagged_na() function from the haven package to tag not applicable responses as NA(a), and missing values (don’t know, refusal, not stated) as NA(b). As you will see later, not applicable values are transformed to NA::a, and missing values are transformed to NA::b. See here for more information about tagged_na().

Columns

The following are the columns that are listed in variable_details.csv. Many of these columns need to be specified in order for rec_with_table() to be functional. We will use the sex variable to illustrate how each column is specified:

  1. variable: the name of the final transformed variable. In variable_details.csv, we have designated the variable names used in CCHS cycles from 2007 to 2014 as the final transformed variable name.
variable
CCC_91E
CCC_91E
CCC_91E
CCC_91E
CCC_91F
  1. dummyVariable: the dummy variable for each category in a transformed categorical variable. This is only applicable for categorical variables; for continuous variables it is set as N/A. The name of a dummy variable consists of the final variable name, the number of categories in the variable, and the category level for each category. Note that this column is not necessary for rec_with_table().
variable dummyVariable
198 CCC_91E CCC_91E_cat2_2
199 CCC_91E CCC_91E_cat2_NA::a
200 CCC_91E CCC_91E_cat2_NA::b
201 CCC_91E CCC_91E_cat2_NA::b
202 CCC_91F CCC_91F_cat2_1
  1. toType: the variable type of the final transformed variable. In this column, a transformed variable that is categorical will be specified as cat; while a transformed variable that is continuous will be specified as cont.
variable dummyVariable toType
198 CCC_91E CCC_91E_cat2_2 cat
199 CCC_91E CCC_91E_cat2_NA::a cat
200 CCC_91E CCC_91E_cat2_NA::b cat
201 CCC_91E CCC_91E_cat2_NA::b cat
202 CCC_91F CCC_91F_cat2_1 cat
  1. databaseStart: the CCHS surveys that contain the variable of interest, separated by commas. If the PUMF dataset from the CCHS is used, the survey names will have a _p suffix. If the Shared dataset from the CCHS is used, the survey names will have a _s suffix.
variable dummyVariable toType databaseStart
198 CCC_91E CCC_91E_cat2_2 cat cchs2005_p, cchs2007_2008_p
199 CCC_91E CCC_91E_cat2_NA::a cat cchs2005_p, cchs2007_2008_p
200 CCC_91E CCC_91E_cat2_NA::b cat cchs2005_p, cchs2007_2008_p
201 CCC_91E CCC_91E_cat2_NA::b cat cchs2005_p, cchs2007_2008_p
202 CCC_91F CCC_91F_cat2_1 cat cchs2005_p, cchs2007_2008_p
  1. variableStart: the original names of the variables as they are listed in each respective CCHS cycle, separated by commas. If the variable name in a particular CCHS survey is different from the transformed variable name, write out the CCHS survey identifier, add two colons, and write out the original variable name for that cycle. If the variable name in a particular CCHS survey is the same as the transformed variable name, the variable name is written out surrounded by square brackets. Note: this only needs to be written out once.
variable dummyVariable toType databaseStart variableStart
198 CCC_91E CCC_91E_cat2_2 cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E
199 CCC_91E CCC_91E_cat2_NA::a cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E
200 CCC_91E CCC_91E_cat2_NA::b cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E
201 CCC_91E CCC_91E_cat2_NA::b cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E
202 CCC_91F CCC_91F_cat2_1 cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91F, cchs2007_2008_p::CCC_91F

  • The categorical age variable in the 2001 CCHS survey is DHHAGAGE. If the final variable name for categorical age in the variable column is DHHGAGE, you would write the following in this column: cchs2001::DHHAGAGE

  • The categorical age variable in the CCHS surveys from 2007 to 2014 is DHHGAGE. Since it is the same as the final variable name, you would write in this column [DHHGAGE] once. The variable name that is denoted within the square brackets is the default variable name.

  1. fromType: the variable type as indicated in the CCHS surveys. As indicated in the toType column, categorical variables are denoted as cat and continuous variables are denoted as cont.
variable dummyVariable toType databaseStart variableStart fromType
198 CCC_91E CCC_91E_cat2_2 cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat
199 CCC_91E CCC_91E_cat2_NA::a cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat
200 CCC_91E CCC_91E_cat2_NA::b cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat
201 CCC_91E CCC_91E_cat2_NA::b cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat
202 CCC_91F CCC_91F_cat2_1 cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91F, cchs2007_2008_p::CCC_91F cat
  1. recTo: the value you would like to recode each category value to. For continuous variables that are not transformed in type, you would write in this column copy so that the function copies the values without any transformations. For the not applicable category, write NA::a. For missing & else categories, write NA::b
variable dummyVariable toType databaseStart variableStart fromType recTo
198 CCC_91E CCC_91E_cat2_2 cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat 2
199 CCC_91E CCC_91E_cat2_NA::a cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::a
200 CCC_91E CCC_91E_cat2_NA::b cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::b
201 CCC_91E CCC_91E_cat2_NA::b cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::b
202 CCC_91F CCC_91F_cat2_1 cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91F, cchs2007_2008_p::CCC_91F cat 1
  • For categorical variables that are not changing variable types (i.e. cat to cat), it is ideal to retain the same values as indicated in each CCHS survey. But for transformed categorical variables that have changed in type (i.e cat to cont), you will have to develop values that make the most sense to your analysis. In variable_details.csv, variables that have gone from cat to cont have used midpoints of each category.
  1. numValidCat: the number of categories for a variable. This only applies to variables in which the toType is cat. For continuous variables, numValidCat = N/A. Not applicable, missing, and else categories are not included in the category count. Note that this column is not necessary for rec_with_table().
variable dummyVariable toType databaseStart variableStart fromType recTo numValidCat
198 CCC_91E CCC_91E_cat2_2 cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat 2 2
199 CCC_91E CCC_91E_cat2_NA::a cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::a 2
200 CCC_91E CCC_91E_cat2_NA::b cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::b 2
201 CCC_91E CCC_91E_cat2_NA::b cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::b 2
202 CCC_91F CCC_91F_cat2_1 cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91F, cchs2007_2008_p::CCC_91F cat 1 2
  1. catLabel: short form label describing the category of a particular variable.
variable dummyVariable toType databaseStart variableStart fromType recTo numValidCat catLabel
198 CCC_91E CCC_91E_cat2_2 cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat 2 2 No emphysema
199 CCC_91E CCC_91E_cat2_NA::a cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::a 2 not applicable
200 CCC_91E CCC_91E_cat2_NA::b cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::b 2 missing
201 CCC_91E CCC_91E_cat2_NA::b cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::b 2 missing
202 CCC_91F CCC_91F_cat2_1 cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91F, cchs2007_2008_p::CCC_91F cat 1 2 COPD
  1. catLabelLong: more detailed label describing the category of a particular variable. This label should be identical to what is shown in the CCHS data documentation, unless you are creating derived variables and would like to create your own label for it.
variable dummyVariable toType databaseStart variableStart fromType recTo numValidCat catLabel catLabelLong
198 CCC_91E CCC_91E_cat2_2 cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat 2 2 No emphysema No emphysema
199 CCC_91E CCC_91E_cat2_NA::a cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::a 2 not applicable not applicable
200 CCC_91E CCC_91E_cat2_NA::b cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::b 2 missing missing
201 CCC_91E CCC_91E_cat2_NA::b cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::b 2 missing missing
202 CCC_91F CCC_91F_cat2_1 cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91F, cchs2007_2008_p::CCC_91F cat 1 2 COPD COPD
  1. units: the units of a particular variable. If there are no units for the variable, write N/A. Note, the function will not work if there different units between the rows of the same variable (i.e. height using both m and ft).
variable dummyVariable toType databaseStart variableStart fromType recTo numValidCat catLabel catLabelLong units
198 CCC_91E CCC_91E_cat2_2 cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat 2 2 No emphysema No emphysema N/A
199 CCC_91E CCC_91E_cat2_NA::a cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::a 2 not applicable not applicable N/A
200 CCC_91E CCC_91E_cat2_NA::b cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::b 2 missing missing N/A
201 CCC_91E CCC_91E_cat2_NA::b cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::b 2 missing missing N/A
202 CCC_91F CCC_91F_cat2_1 cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91F, cchs2007_2008_p::CCC_91F cat 1 2 COPD COPD N/A
  1. recFrom: the range of values for a particular category in a variable as indicated in the CCHS. See CCHS data documentation for each survey cycle and use the smallest and large values as your range to capture all values between the survey years.

The rules for each category of a new variable are a string in recFrom and value in recTo. These recode pairs are the same syntax as interval notation in which a closed range of values are specified using square brackets. See here for more information on interval notation. Recode pairs are obtained from the RecFrom and RecTo columns value range is indicated by a comma, e.g. recFrom= [1,4]; recTo = 1 (recodes all values from 1 to 4 into 1} value range for double vectors (with fractional part), all values within the specified range are recoded; e.g. recFrom = [1,2.5]; recTo = 1 recodes 1 to 2.5 into 1, but 2.55 would not be recoded (since it’s not included in the specified range). NA is used for missing values (don’t know, refusal, not stated) else is used all other values, which have not been specified yet, are indicated by else, e.g. recFrom = "else"; recTo = NA (recode all other values (not specified in other rows) to “NA”)} copy the else token can be combined with copy, indicating that all remaining, not yet recoded values should stay the same (are copied from the original value), e.g. recFrom = "else"; recTo = "copy"

variable dummyVariable toType databaseStart variableStart fromType recTo numValidCat catLabel catLabelLong units recFrom
198 CCC_91E CCC_91E_cat2_2 cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat 2 2 No emphysema No emphysema N/A 2
199 CCC_91E CCC_91E_cat2_NA::a cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::a 2 not applicable not applicable N/A 6
200 CCC_91E CCC_91E_cat2_NA::b cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::b 2 missing missing N/A [7,9]
201 CCC_91E CCC_91E_cat2_NA::b cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::b 2 missing missing N/A else
202 CCC_91F CCC_91F_cat2_1 cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91F, cchs2007_2008_p::CCC_91F cat 1 2 COPD COPD N/A 1
  1. catStartLabel: label describing each category. This label should be identical to what is shown in the CCHS data documentation. For the missing row, each missing category is described along with their coded values. You can import labels from the CCHS DDI files using bllflow helper functions. See bllflow documentation.
variable dummyVariable toType databaseStart variableStart fromType recTo numValidCat catLabel catLabelLong units recFrom catStartLabel
198 CCC_91E CCC_91E_cat2_2 cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat 2 2 No emphysema No emphysema N/A 2 No (Do you have emphysema?)
199 CCC_91E CCC_91E_cat2_NA::a cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::a 2 not applicable not applicable N/A 6 not applicable
200 CCC_91E CCC_91E_cat2_NA::b cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::b 2 missing missing N/A [7,9] don’t know (7); refusal (8); not stated (9)
201 CCC_91E CCC_91E_cat2_NA::b cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::b 2 missing missing N/A else else
202 CCC_91F CCC_91F_cat2_1 cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91F, cchs2007_2008_p::CCC_91F cat 1 2 COPD COPD N/A 1 Yes (Do you have COPD?)
  1. variableStartShortLabel: short form label describing the variable.
variable dummyVariable toType databaseStart variableStart fromType recTo numValidCat catLabel catLabelLong units recFrom catStartLabel variableStartShortLabel
198 CCC_91E CCC_91E_cat2_2 cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat 2 2 No emphysema No emphysema N/A 2 No (Do you have emphysema?) emphysema
199 CCC_91E CCC_91E_cat2_NA::a cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::a 2 not applicable not applicable N/A 6 not applicable emphysema
200 CCC_91E CCC_91E_cat2_NA::b cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::b 2 missing missing N/A [7,9] don’t know (7); refusal (8); not stated (9) emphysema
201 CCC_91E CCC_91E_cat2_NA::b cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::b 2 missing missing N/A else else emphysema
202 CCC_91F CCC_91F_cat2_1 cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91F, cchs2007_2008_p::CCC_91F cat 1 2 COPD COPD N/A 1 Yes (Do you have COPD?) COPD
  1. variableStartLabel: more detailed label describing the variable. This label should be identical to what is shown in the CCHS data documentation.
variable dummyVariable toType databaseStart variableStart fromType recTo numValidCat catLabel catLabelLong units recFrom catStartLabel variableStartShortLabel variableStartLabel
198 CCC_91E CCC_91E_cat2_2 cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat 2 2 No emphysema No emphysema N/A 2 No (Do you have emphysema?) emphysema Do you have emphysema?
199 CCC_91E CCC_91E_cat2_NA::a cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::a 2 not applicable not applicable N/A 6 not applicable emphysema Do you have emphysema?
200 CCC_91E CCC_91E_cat2_NA::b cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::b 2 missing missing N/A [7,9] don’t know (7); refusal (8); not stated (9) emphysema Do you have emphysema?
201 CCC_91E CCC_91E_cat2_NA::b cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::b 2 missing missing N/A else else emphysema Do you have emphysema?
202 CCC_91F CCC_91F_cat2_1 cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91F, cchs2007_2008_p::CCC_91F cat 1 2 COPD COPD N/A 1 Yes (Do you have COPD?) COPD Do you have COPD?
  1. notes: any relevant notes to inform the user running the recode-with-table function. Things to include here would be changes in wording between CCHS surveys, missing/changes in categories, and changes in variable type between CCHS surveys.
variable dummyVariable toType databaseStart variableStart fromType recTo numValidCat catLabel catLabelLong units recFrom catStartLabel variableStartShortLabel variableStartLabel notes
198 CCC_91E CCC_91E_cat2_2 cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat 2 2 No emphysema No emphysema N/A 2 No (Do you have emphysema?) emphysema Do you have emphysema?
199 CCC_91E CCC_91E_cat2_NA::a cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::a 2 not applicable not applicable N/A 6 not applicable emphysema Do you have emphysema?
200 CCC_91E CCC_91E_cat2_NA::b cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::b 2 missing missing N/A [7,9] don’t know (7); refusal (8); not stated (9) emphysema Do you have emphysema?
201 CCC_91E CCC_91E_cat2_NA::b cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91E, cchs2007_2008_p::CCC_91E cat NA::b 2 missing missing N/A else else emphysema Do you have emphysema?
202 CCC_91F CCC_91F_cat2_1 cat cchs2005_p, cchs2007_2008_p cchs2005_p::CCCE_91F, cchs2007_2008_p::CCC_91F cat 1 2 COPD COPD N/A 1 Yes (Do you have COPD?) COPD Do you have COPD?

Derived Variables

The same naming convention applies to derived variables with the exception of two columns:

  1. In variableStart, instead of database names being listed, DerivedVar:: is written followed with the list of CCHS variables used inside square brackets.
  • DerivedVar::[var1, var2, var3]
  1. In recTo, write Func:: followed with the name of the custom function used to create the derived variable.
  • Func::derivedFunction

A derived variable looks like this in variable_details.csv

variable dummyVariable toType databaseStart variableStart fromType recTo numValidCat catLabel catLabelLong units recFrom catStartLabel variableStartShortLabel variableStartLabel notes
HWTGBMI N/A cont cchs2001_p, cchs2003_p, cchs2005_p, cchs2007_2008_p, cchs2009_2010_p, cchs2010_p, cchs2011_2012_p, cchs2012_p, cchs2013_2014_p, cchs2014_p cchs2001_p::HWTAGBMI, cchs2003_p::HWTCGBMI, cchs2005_p::HWTEGBMI, [HWTGBMI] cont copy N/A BMI Body Mass Index kg/m2 [11.91,57.9] BMI / self-report - (D,G) BMI BMI / self-report - (D,G) CCHS 2001 restricts BMI to ages 20-64. Consider using using HWTGBMI_der for the most concistent BMI variable across all CCHS cycles. See documentation for BMI_fun() in derived variables for more details, or type ?BMI_fun in the console.