CCHS Bootstrap Analysis Tool

A local Streamlit application for public health analysts and epidemiologists who work with Canadian Community Health Survey (CCHS) data. It supports geographic filtering, bootstrap prevalence estimates, CCHS release-quality indicators, age-stratified analysis, exports, and comparisons across annual cycles.

Project status: This is a public-health-unit analytical tool under active validation. It is not an official Statistics Canada product. Analysts remain responsible for following their CCHS data-sharing agreements, organizational privacy policies, and applicable release standards.

Full documentation, including the methodology and code reference, is published at https://docs.phiz.ca/cchs/.

• Single Cycle calculates estimates for one CCHS year.
• Multi-Cycle Trends calculates each selected year independently and compares the resulting estimates across years.

Multi-Cycle Trends does not pool respondent-level records or weights across cycles. Cycle pooling is a requested future feature and will require a separately validated statistical design before implementation.

Pooling is intentionally out of scope for the current release. A future design must define combined-cycle weights, target population and time-period semantics, variance estimation, cycle effects, comparability rules, and release-quality validation before any pooled estimate is exposed in the interface.

Supported configurations currently include CCHS 2021, 2022, 2023, and 2024.

The repository does not distribute CCHS respondent data, bootstrap weights, or codebook PDFs. Public health units run the application locally with files they are authorized to use.

Place cycle files under data/ using this convention:

data/
├── hs2021_on_distr.parquet
├── hs2021_on_bootwt.parquet
├── hs2022_on_distr.parquet
├── hs2022_on_bootwt.parquet
├── hs2023_on_distr.parquet
├── hs2023_on_bootwt.parquet
├── hs2024_on_distr.parquet
└── hs2024_on_bootwt.parquet

Main files must include ONT_ID, WTS_S, and the variables being analyzed. Bootstrap files must include ONT_ID and replicate-weight columns beginning with BSW. The application validates one-to-one joins. Multi-cycle trend processing also attaches the cycle year to both frames so identifiers cannot cross-join between years.

data/ and local codebook PDFs are Git-ignored. Do not commit CCHS microdata, derived respondent-level files, bootstrap weights, or codebooks.

The harmonization/CCHS_<year>.json, crosswalk.json, and categories.json files are also Git-ignored and not distributed with this repository, since they are extracted from codebook documentation each organization must obtain under its own CCHS agreement. Generate them locally with scripts/extract_codebook.py, scripts/build_crosswalk.py, and scripts/harmonize_categories.py - see Adding a New CCHS Cycle and Third-party data and metadata.

Requirements:

• Python 3.11 or newer
• uv

git clone https://github.com/WDGPH/CCHS.git
cd CCHS
uv sync --locked
uv run streamlit run app.py

Open http://127.0.0.1:8501.

pyproject.toml and uv.lock are the authoritative dependency files. This project intentionally does not maintain requirements.txt.

The committed .streamlit/config.toml binds the application to localhost and disables Streamlit usage-statistics collection. Routine analysis reads local files and performs calculations locally.

1. Select Multi-Cycle Trends.
2. Choose two or more cycles.
3. Select geography and inclusion filters.
4. Choose variables available across the selected cycles.
5. Run the analysis.
6. Review cycle-specific estimates, confidence intervals, release flags, and trend charts.

Harmonized names make equivalent variables easier to compare, but analysts must still confirm that concepts and response categories are comparable across years. The generated crosswalk uses automated matching and requires subject-matter review.

For each variable value, the tool reports:

• weighted prevalence and population
• unweighted numerator and denominator
• bootstrap variance and standard error
• confidence interval using the documented CCHS z = 2.0 convention
• coefficient of variation
• CCHS 2022+ A/E/F release category and action

Release flags are displayed by default for supported 2022+ cycles. Analysts should suppress category F estimates and apply their organization's complete review and rounding process before publication.

See:

• Bootstrap analysis methodology
• CCHS 2024 data-quality standards
• Privacy and security overview

Precomputing can improve local performance without changing the statistical method:

uv run python scripts/precompute_cycles.py
uv run python scripts/precompute_cycles.py --validate-only

Generated files remain under data/precomputed/ and are ignored by Git. Metadata is stored as JSON; regenerate older precomputed outputs that used pickle.

See Adding a New CCHS Cycle. Codebook extraction uses the declared pypdf dependency:

uv run python scripts/extract_codebook.py

Review all extracted descriptions, categories, and generated crosswalk mappings before analytical use.

Install the locked development environment and run the synthetic-data test suite:

uv sync --locked --dev
uv run pytest -q
uv run python -m compileall -q app.py config scripts src

Tests and continuous integration do not require CCHS data.

Documentation source stays in this repository. The PHIZ documentation hub provides the shared presentation, version selection, search, and publication. The Streamlit application continues to run locally as described above.

Build or serve the source documentation with the locked environment:

uv sync --locked --group docs
uv run --locked --group docs python -m mkdocs build --strict
uv run --locked --group docs python -m mkdocs serve

Open http://127.0.0.1:8000 for the local Material preview. The hub applies its shared theme when building these same pages. Pull requests and pushes to main run the strict documentation check; this repository does not publish a docs site.

When DOCS_HUB_NOTIFY_ENABLED is true, the no-checkout notification workflow uses DOCS_HUB_TRIGGER_TOKEN only to dispatch the hub's fixed workflows. Documentation builds do not receive that credential. Manual notification requests both a development build and release reconciliation; the hub controls publication.

Pushes to main request a full hub build that updates latest. Creation or updates of stable vX.Y.Z tags, and deletion of those tags, request release reconciliation. The hub proposes release-lock changes for review and builds the complete candidate before a maintainer merges it. The current manual is selected by the hub release lock; a tag notification does not select it automatically.

A reused or deleted older tag may have a workflow without this notifier. After changing historical tags, run Notify documentation hub from main, or run the hub's Propose documentation releases workflow with source_repo=WDGPH/CCHS. Review corrected or withdrawn versions in the resulting hub pull request. Notifications use fixed hub workflows on main; they do not check out source code or pass credentials to documentation builds. There is no polling workflow.

app.py                 Streamlit entry point
config/                Application and analysis settings
src/analysis/           Bootstrap and quality calculations
src/data/               Loading, harmonization, and preprocessing
src/ui/                 Streamlit interface components
harmonization/          Cycle metadata, crosswalks, and lookup tables
scripts/                Local conversion and precompute utilities
tests/                  Synthetic-data tests

See Third-party data and metadata. The repository's MIT license applies to project code; it does not replace the terms governing CCHS data or third-party metadata.

• Contributing guide
• Security policy
• Code of conduct

Project code is licensed under the MIT License.