SynthPopCan

SynthPopCan is an early-stage project for building Canadian synthetic population tooling.

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

Near-term goals:

1. Provide a Python library and CLI that can create synthetic populations through IPF from Statistics Canada margin/control tables.
2. Build census microdata workflows for household- and person-level synthetic populations using a tree-based synthetic population generator plus calibration. The local 2016 Census material is the first available microdata source, but the tooling should be census-year agnostic.
3. Maintain a local web app for configuring runs, inspecting controls, generating from prepared models, validating outputs, and downloading results.

Broader SynthEco-style enrichment with cohort, environmental, school, healthcare, and food-access layers is intentionally deferred until the base population synthesis workflow is stable.

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.

Project planning and research notes are tracked separately:

• PLANS.md: current roadmap, open work, sequencing, and design decisions.
• NOTES.md: research synthesis from local materials and external literature.
• CHANGELOG.md: public release notes and completed release highlights.

Quick Start

Install the published package from PyPI:

python -m pip install synthpopcan

Then inspect the command line:

synthpopcan --help

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

uvx synthpopcan --help
uvx synthpopcan guide ipf

From a source checkout for development:

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:

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

Developer Benchmarks

Benchmark fixtures are developer tooling, not normal user workflows:

uv run python scripts/benchmarks.py ipf
uv run python scripts/benchmarks.py small-area
uv run python scripts/benchmarks.py small-area --province-scale
uv run python scripts/benchmarks.py ipf-backends

Use --seed-records for smaller or larger IPF runs. The province-scale small-area timing check is opt-in because it depends on the machine. Optional SciPy CSR and Polars comparisons remain benchmark probes rather than runtime backends, and full-data tree-model smoke tests remain outside the default suite.

Data Policy

Large, raw, private, or access-controlled data are not tracked in git.

• data/raw/ is a local ignored cache for central raw inputs, including public Census Profile and WDS downloads.
• data/private/ is a local ignored cache for access-controlled or sensitive later-use datasets.
• references/ is a local ignored cache for copied papers, proposals, and legacy code references.

Public geography, school, healthcare, road, and environmental layers should generally be fetched from authoritative public sources such as Statistics Canada, open.canada.ca, donneesquebec.ca, and municipal/provincial open-data portals rather than stored in this repository.

Local-only manifests may exist inside ignored data directories to document what is present on a development machine.

Model Packages

Reviewed model packages may be distributed with the project when they are explicitly intended as public research artifacts. The installed package should stay small: only the tiny demo model is bundled. Larger published models are downloaded on demand with synthpopcan models fetch MODEL_ID.

Release assets are gzip-compressed to keep downloads small. The CLI handles decompression and stores a normal JSON model package in the local cache.

Bundled model packages are not raw Census microdata. They should still be treated as derived research artifacts with provenance, disclosure-risk checks, and limitations. A model package being marked as a publishable candidate means it passed the project's current checks; it is not a claim of official approval, legal privacy certification, or fitness for every research use.

Before publishing a new model package, review docs/data.md, docs/tree.md, PLANS.md, and CONTRIBUTING.md.