SynthPopCan

SynthPopCan helps researchers create, inspect, and validate modelled Canadian households and people from Census-derived data. It supports reproducible work without requiring researchers to expose private source data or become software developers first.

SynthPopCan is an independent research-software project. It is not affiliated with, endorsed by, or sponsored by Statistics Canada or the Government of Canada.

Core workflows:

1. Provide a Python library and CLI that can create synthetic populations through IPF from Statistics Canada margin/control tables.
2. Maintain explicit 2016 and 2021 Census microdata workflows for household- and person-level synthetic populations using tree-based generation plus calibration, while keeping source adapters and metadata appropriately census-vintage-specific.
3. Maintain a local web app for configuring runs, inspecting controls, generating from prepared models, validating outputs, and downloading results.

Version 1.1.1 preserves the stable, explicitly bounded interface established by 1.0.0. Its packaged 1.x compatibility contract freezes the documented CLI, curated Python API, callable signatures, and supported persisted schemas while permitting additive extension. This maintenance release includes validation, internal-boundary, and dependency fixes. It retains 24 reviewed 2016/2021 small-area control packs: eight stable core packs, eight expanded-housing packs, and eight broad packs that can apply nine household and five person margins together with explicit runtime invariants. That bounded evidence is not a universal representativeness, privacy, or fitness claim.

It also includes a complete 2016/2021 field-eligibility inventory, a bilingual Quebec 2021 case study, dated preservation and software-management records, and an accepted open-by-default prepared-model policy. All 32 public Census-derived model concepts now point to verified, non-overwriting versions with embedded scoped licensing and preserved source provenance. The release boundary and post-1.0 research tracks are recorded in PLANS.md.

Detailed documentation is published at https://synthpopcan.readthedocs.io/. The source files live under docs/; start with docs/index.rst for task-based navigation to the web app, IPF from StatCan margin tables, generated-from-model workflows, the beginner Python API, and advanced microdata/model-training material.

The development branch and the latest documentation may describe the next release before it reaches PyPI. The PyPI badge above identifies what pip install synthpopcan currently installs; use the stable documentation for that published version. Maintained Can-FED and ODEF adapters are included in 0.7.2 and later.

Project records have distinct jobs:

Quick Start

These commands use a Unix-style shell. Windows readers should first complete the WSL setup in the Installation guide, then run the same commands inside the Ubuntu terminal.

Install the published package from PyPI:

Network required for installation.

python3 -m pip install synthpopcan

The base installation is enough to generate from portable frequency or CART models. Starting with 0.7.0, only researchers training new CART models need python3 -m pip install "synthpopcan[model-build]".

For a guided first look, start the local browser workbench:

synthpopcan serve

It opens forms, previews, run history, and downloads on this computer only. The local web app guide includes fictional teaching data and explains what stays on disk. Use the command line below when the work needs to be scripted or repeated exactly.

Then inspect the command line:

synthpopcan --help

Run a small offline smoke test with the bundled fictional model:

Runnable teaching example. Enter both commands in order.

synthpopcan models generate demo-linked-household-person \
  --households 10 \
  --condition "geo=Demo North" \
  --out synthpopcan-quickstart \
  --random-seed 42
synthpopcan validate linked synthpopcan-quickstart

This verifies linked household/person generation, but it does not create a representative Canadian population. The documentation explains how to choose research sources, controls, and model packages.

For a one-off command without installing the tool into the current environment, use uvx:

Network and uv required. See the Installation guide before using this route if uvx --version is not already available.

uvx synthpopcan --help
uvx synthpopcan guide ipf
uvx synthpopcan guide model
uvx synthpopcan guide small-area

From a source checkout for development:

Source checkout, network, Git, and uv required.

git clone https://github.com/dlq/synthpopcan.git
cd synthpopcan
uv sync
uv run synthpopcan --help

For installation details, see docs/installation.md.

Where To Start

Most readers should start in the Sphinx documentation rather than in this README:

Build the documentation locally with:

Source checkout required. Contributor setup is documented in CONTRIBUTING.md.

uv run sphinx-build -W -b html docs docs/_build/html

Data Policy

Large, raw, private, or access-controlled data are not tracked in git. Local source caches, derived artifacts, and scratch work have separate roles and must retain their provenance and access classification. See the maintained Data and Local Workspace chapter for the directory contract, licensing boundary, and safe handling rules.

Model Packages

Only the tiny fictional demo model is bundled. Larger reviewed models are downloaded on demand. List the current catalogue and generate from a selected package with:

synthpopcan models fetch quebec-2021-all-fields
synthpopcan models generate quebec-2021-all-fields \
  --households 1000 --out quebec-2021-population/

Prepared packages are derived research artifacts, not raw Census microdata or claims of official approval, privacy certification, or universal fitness. See Generate From a Model Package for ordinary use and Tree Models for training, audit, packaging, licensing, and release guidance.

How To Cite

Releases and prepared model packages are archived on Zenodo, so cite whichever matches what your work actually depended on.

For reproducibility, prefer the version DOI for the release and the model package DOI for each package you generated from: together they pin the exact code and the exact artifact, and every model record publishes the checksums needed to verify the file you downloaded.

Citation metadata lives in CITATION.cff, which GitHub renders as a ready-made citation from the sidebar.

The source history through v1.1.0 is also independently preserved in Software Heritage. Use its SWHIDs to identify source objects; continue to use the release DOI and artifact checksums to identify the software and model bytes used in research. The earlier captures through v1.0.0 and v0.9.0 remain available in the 2026-08-16 and 2026-08-15 preservation records.

Prepared model packages are derived from Statistics Canada public use microdata files under the Statistics Canada Open Licence. The catalogue, archive records, and current registered package bytes carry the required attribution and machine-readable rights contract. Historical package versions remain available under their original identifiers and checksums for reproducibility; the registry now selects the verified non-overwriting v1.0.0-rights.1 versions. See docs/data.md for the full attribution and licensing terms. The accepted open-by-default policy in ADR-0014 offers CC BY 4.0 only for original prepared-model rights the package author owns or controls. That scoped grant is cumulative with the continuing Statistics Canada conditions; it does not cover source Information, facts, or unprotectable results, and it does not relax privacy or provenance safeguards. The fail-closed existing-record correction implementation passed independent review, and all 32 metadata corrections, 32 non-overwriting versions, remote byte checks, and 32 registry updates completed on 2026-08-16. The durable correction record preserves sanitized evidence. External review remains welcome but is not a 1.0.0 gate.

Development Acknowledgement

Development of SynthPopCan has been supplemented by the use of large language models for tasks including code generation, review, testing, documentation, and research assistance. All resulting contributions remain subject to human review and the project's automated correctness and quality checks. Responsibility for the project and its releases rests with its maintainer.