Summary
Please add a normative definition of NA(c) to the tagged-NA documentation and tests:
NA(c) means that cchsflow could not generate a requested variable for a survey cycle because the required source variable, or an approved equivalent or derivation, was absent from the input data for that cycle.
The definition concerns the data supplied to cchsflow. It does not assert why the source is absent. Possible reasons include that the survey did not collect the question in that cycle, that the data product (PUMF, Master, share file) omits the variable, that a province-specific file excludes optional content, or that the user left the source variable out of their extract.
What NA(c) does not mean
NA(c) is not respondent-level missingness. When the source variable is present in the input, a respondent who did not qualify for the question stays NA(a) (not applicable) and one who did not answer stays NA(b) (don't know, refused, not stated). cchsflow should not generate NA(c) for an individual respondent because of a skip pattern or a non-response.
Invariant: all or none per variable and survey cycle
Availability is a property of the requested variable and the survey cycle. Within one cycle, a cchsflow-generated variable is either available, with no NA(c), or unavailable, with NA(c) for every respondent in that cycle:
n[NA(c)] in {0, n[respondents in the cycle]} for each variable x cycle
A partial count of NA(c) within a cycle is a defect. A study that pools several cycles may legitimately hold observed values, NA(a), NA(b) and NA(c) in one column, because each cycle satisfies the invariant on its own.
Examples
- National PUMF, variable asked in every cycle: no
NA(c) in any cycle.
- National PUMF, question introduced in 2003:
NA(c) for every 2001 respondent; none from 2003 onward.
- Province-specific file that omits an optional content module:
NA(c) for every respondent in that file for the module's variables, even though the national file has values for the same cycle.
- User extract that omits a source variable: cchsflow returns
NA(c) for every respondent in that cycle. The result is indistinguishable from "not collected"; a downstream check that knows the variable should be available can detect it (cshm does this against its variable-details worksheet).
- Pooled 2001 to 2022 study: one column with values,
NA(a) and NA(b) for supported cycles and NA(c) for unsupported cycles.
Approved pathways prevent NA(c)
When a grouped variable or a midpoint-based pseudo-Master derivation is an approved pathway for a target, cchsflow produces the derived value. It is an approximation with provenance (the derivation rule), not NA(c). Only a target with no direct source and no approved derivation for the cycle is NA(c).
Documentation inconsistency to correct
vignettes/tagged_na_usage.Rmd describes cycle absence as NA(a) in prose (about lines 38 to 41: a question not asked in a specific cycle "recoded to NA(a)") while the table at about line 51 assigns "question not asked in the survey cycle" to NA(c). The table matches the definition above; the prose should be changed to NA(c).
Related schema
inst/metadata/schemas/cchs/cchs_missing_data.yaml defines the a and b tags through source-code patterns. It has no normative sentence for c, which is not a source code but a property of the variable and cycle. A short cycle_absence section stating the definition and the invariant would give the schema and the vignette one source.
Known limitation
cchsflow does not consistently record whether a potential derivation for a cycle was assessed and rejected, or has not yet been assessed. That limits provenance and diagnostics; the operational meaning of NA(c) is unchanged.
Future: logging and summaries
A per-run summary of which requested variables were generated as NA(c) and for which cycles, consistent with the planned version 4 logging work, would let users distinguish an expected gap from an incomplete extract. This issue does not prescribe the interface.
How cshm uses the definition
cshm tags plain missing values NA(c) where its variable-details worksheet has no rule for the cycle, checks the all-or-none invariant against the worksheet (a supported pair must have no NA(c); an unsupported pair must be all NA(c)), and stops on any untagged missing value unless it is a filed defect in an explicit allowlist. Table 1a reports NA(a), NA(b) and NA(c) as separate rows.
Opened from the Canadian Smoking Histories Model (cshm) project, where the definition and the cycle-level check are now implemented; happy to contribute the vignette and schema wording as a PR.
Summary
Please add a normative definition of
NA(c)to the tagged-NA documentation and tests:The definition concerns the data supplied to cchsflow. It does not assert why the source is absent. Possible reasons include that the survey did not collect the question in that cycle, that the data product (PUMF, Master, share file) omits the variable, that a province-specific file excludes optional content, or that the user left the source variable out of their extract.
What NA(c) does not mean
NA(c)is not respondent-level missingness. When the source variable is present in the input, a respondent who did not qualify for the question staysNA(a)(not applicable) and one who did not answer staysNA(b)(don't know, refused, not stated). cchsflow should not generateNA(c)for an individual respondent because of a skip pattern or a non-response.Invariant: all or none per variable and survey cycle
Availability is a property of the requested variable and the survey cycle. Within one cycle, a cchsflow-generated variable is either available, with no
NA(c), or unavailable, withNA(c)for every respondent in that cycle:A partial count of
NA(c)within a cycle is a defect. A study that pools several cycles may legitimately hold observed values,NA(a),NA(b)andNA(c)in one column, because each cycle satisfies the invariant on its own.Examples
NA(c)in any cycle.NA(c)for every 2001 respondent; none from 2003 onward.NA(c)for every respondent in that file for the module's variables, even though the national file has values for the same cycle.NA(c)for every respondent in that cycle. The result is indistinguishable from "not collected"; a downstream check that knows the variable should be available can detect it (cshm does this against its variable-details worksheet).NA(a)andNA(b)for supported cycles andNA(c)for unsupported cycles.Approved pathways prevent NA(c)
When a grouped variable or a midpoint-based pseudo-Master derivation is an approved pathway for a target, cchsflow produces the derived value. It is an approximation with provenance (the derivation rule), not
NA(c). Only a target with no direct source and no approved derivation for the cycle isNA(c).Documentation inconsistency to correct
vignettes/tagged_na_usage.Rmddescribes cycle absence asNA(a)in prose (about lines 38 to 41: a question not asked in a specific cycle "recoded to NA(a)") while the table at about line 51 assigns "question not asked in the survey cycle" toNA(c). The table matches the definition above; the prose should be changed toNA(c).Related schema
inst/metadata/schemas/cchs/cchs_missing_data.yamldefines theaandbtags through source-code patterns. It has no normative sentence forc, which is not a source code but a property of the variable and cycle. A shortcycle_absencesection stating the definition and the invariant would give the schema and the vignette one source.Known limitation
cchsflow does not consistently record whether a potential derivation for a cycle was assessed and rejected, or has not yet been assessed. That limits provenance and diagnostics; the operational meaning of
NA(c)is unchanged.Future: logging and summaries
A per-run summary of which requested variables were generated as
NA(c)and for which cycles, consistent with the planned version 4 logging work, would let users distinguish an expected gap from an incomplete extract. This issue does not prescribe the interface.How cshm uses the definition
cshm tags plain missing values
NA(c)where its variable-details worksheet has no rule for the cycle, checks the all-or-none invariant against the worksheet (a supported pair must have noNA(c); an unsupported pair must be allNA(c)), and stops on any untagged missing value unless it is a filed defect in an explicit allowlist. Table 1a reportsNA(a),NA(b)andNA(c)as separate rows.Opened from the Canadian Smoking Histories Model (cshm) project, where the definition and the cycle-level check are now implemented; happy to contribute the vignette and schema wording as a PR.