Protocol v0.4.2 and Phase 1 task 1.2 (estimation window) - #13
Merged
Conversation
…he initiation floor The initiation denominator began in 1965 (apc.period_min) while initiation events before 1965 were kept, so those cells had events equal to population (26% of weighted events in the synthetic reproduction). The window start is now derived, apc_period_min(cfg) = cohort_min + initiation_floor_age (PUMF 1933, Master 1928); a configured period_min is an error. build_initiation_data() stops if any event falls outside the window. The cessation denominator is bounded by each person's entry age and cohort_min only. Rate tables and reported histories start at apc.report_period_min (1965). Tests: every event above the floor has the same cohort at risk in the year before it; 0 <= weighted events <= population in every cell; an early-cohort initiation in 1940 keeps its risk years. Protocol v0.4.2 records the amendment (section 3.4.1).
…ge-range conventions note Reference conventions (Holford 2014, Manuel 2020): initiation from 8, cessation from 15, two-year durability, age-85 ceiling. Where this study differs: PUMF initiation floor of 13 as a data limit; cessation risk from each person's own entry age, reported from 15. Reported-value ranges come from the cchsflow recoding rules and are not analysis limits. docs/development/age-range-conventions.md records the sources and the derived ranges.
…) in config for Stage 9; note updated
…in verbs; version entry as sentences)
… in place of operates, ensures, enables, handles, captures
…e, pending amendments)
Task 1.2: estimation window aligned with the initiation floor (protocol v0.4.2)
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the study protocol to v0.4.2 and implements Phase 1 task 1.2 by deriving the APC initiation estimation window start from cohort_min + initiation_floor_age (rather than a configured period_min), adding safeguards/tests to ensure initiation events are supported by person-years at risk, and documenting/reporting boundaries for downstream stages.
Changes:
- Derive initiation estimation window start via
apc_period_min(cfg)and treat any configuredcfg$apc$period_minas an error. - Enforce a task 1.2 invariant in
build_initiation_data()(stop if any initiation event falls outside the estimation window) and adjust cessation denominator bounds. - Expand tests and documentation to reflect the new estimation/reporting window rules and new reporting config keys.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| tests/testthat/test-apc-data.R | Adds/updates tests for apc_period_min() and task 1.2 invariants (window bounds, event support, event ≤ population). |
| R/config-utils.R | Introduces apc_period_min(cfg) and documents derived estimation-window semantics. |
| R/apc-model.R | Switches initiation period_min to apc_period_min(cfg); adds a hard stop for out-of-window initiation events; bounds cessation denom by entry age/cohort_min. |
| docs/workflow/7-apc-data-preparation.qmd | Documents the derived estimation window and reporting start separation for stages. |
| docs/protocol/full-protocol.qmd | Bumps protocol to v0.4.2 and updates §3.4.1 and wording to reflect the derived window and age/time conventions. |
| docs/development/age-range-conventions.md | Adds investigation notes summarizing reference-study conventions vs protocol/code and where limits originate. |
| config.yml | Removes configured apc.period_min; adds apc.report_period_min, apc.report_cessation_min_age, and apc.max_age for Stage 9. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| We will use the `cchsflow` R package (version 3.0) to harmonize smoking-related variables across all CCHS cycles. This library provides a standardized metadata-driven approach to recoding survey responses into unified variables, which keeps coding consistent despite changes in survey questions over time. | ||
|
|
||
| Compared to the US National Health Interview Survey (NHIS) used in existing CISNET models, the CCHS provides more granular data on non-daily smoking. While the NHIS categorizes current smokers as "every day" or "some days," the CCHS captures more detailed information about occasional smokers. The NHIS has fewer annual respondents (approximately 27,000 for the NHIS versus 65,000 for the CCHS), but with an earlier start date for tobacco questions (1965 for NHIS versus 2001 for the CCHS) [@backinger2008]. The potential effect of these differences are more statistically stable earlier birth cohorts for NHIS, and greater statistical power for regional estimates using the CCHS. | ||
| Compared to the US National Health Interview Survey (NHIS) used in existing CISNET models, the CCHS provides more granular data on non-daily smoking. While the NHIS categorizes current smokers as "every day" or "some days," the CCHS records more detail about occasional smokers. The NHIS has fewer annual respondents (approximately 27,000 for the NHIS versus 65,000 for the CCHS), but with an earlier start date for tobacco questions (1965 for NHIS versus 2001 for the CCHS) [@backinger2008]. The potential effect of these differences are more statistically stable earlier birth cohorts for NHIS, and greater statistical power for regional estimates using the CCHS. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Protocol v0.4.2 and Phase 1 task 1.2.
Protocol (v0.4.1 → v0.4.2). Estimation window start derived from the data: the APC models are estimated on person-years from the calendar year the earliest cohort (1920) reaches the initiation floor (1933 PUMF, 1928 Master) to the last survey year; reported rates start in 1965. Section 3.4.1 now states the age and time ranges: the conventions of Holford et al. (2014) and Manuel et al. (2020), the two places this study differs (PUMF initiation floor of 13 as a data limit; cessation risk from each person's own entry age, reported from 15), and that reported-value ranges come from the cchsflow recoding rules. Plain-verb wording pass throughout. A to-do section for the study team follows the version history.
Pipeline (task 1.2).
apc_period_min(cfg) = cohort_min + initiation_floor_agereplaces the configuredperiod_min;build_initiation_data()stops if any event falls outside the window; the cessation denominator is bounded by entry age andcohort_min.apc.report_period_min,apc.report_cessation_min_age,apc.max_ageadded for Stage 9. Tests: every event has the same cohort at risk the year before;0 <= events <= populationper cell; early-cohort initiation keeps its risk years.Also:
docs/development/age-range-conventions.mdanddocs/development/phase1-1.9-1.10-investigation.md(investigation notes).