Metadata-Version: 2.4
Name: synthpopcan
Version: 0.6.0
Summary: Canadian synthetic population tooling for StatCan margin tables and Census microdata.
Project-URL: Homepage, https://github.com/dlq/synthpopcan
Project-URL: Documentation, https://synthpopcan.readthedocs.io/
Project-URL: Source, https://github.com/dlq/synthpopcan
Project-URL: Issues, https://github.com/dlq/synthpopcan/issues
Author-email: Darcy Quesnel <darcy.quesnel@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Darcy Quesnel
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: census,ipf,statistics canada,synthetic population
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Requires-Dist: click>=8.4.1
Requires-Dist: fastapi>=0.139.2
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.0
Requires-Dist: pyshp>=3.1.3
Requires-Dist: rich>=15.0.0
Requires-Dist: scikit-learn>=1.9.0
Requires-Dist: uvicorn>=0.51.0
Description-Content-Type: text/markdown

# SynthPopCan

[![CI](https://github.com/dlq/synthpopcan/actions/workflows/ci.yml/badge.svg)](https://github.com/dlq/synthpopcan/actions/workflows/ci.yml)
[![Extended correctness](https://github.com/dlq/synthpopcan/actions/workflows/correctness.yml/badge.svg)](https://github.com/dlq/synthpopcan/actions/workflows/correctness.yml)
[![Documentation Status](https://readthedocs.org/projects/synthpopcan/badge/?version=latest)](https://synthpopcan.readthedocs.io/en/latest/)
[![PyPI](https://img.shields.io/pypi/v/synthpopcan.svg)](https://pypi.org/project/synthpopcan/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

<p align="center">
  <img src="assets/branding/logo/synthpopcan-logo-512.png" alt="SynthPopCan logo" width="220">
</p>

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.
1. 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.
1. 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/`](docs/); start with [`docs/index.rst`](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`](PLANS.md): current roadmap, open work, sequencing, and design
  decisions.
- [`NOTES.md`](NOTES.md): research synthesis from local materials and external
  literature.
- [`CHANGELOG.md`](CHANGELOG.md): public release notes and completed release
  highlights.
- [`CORRECTNESS.md`](CORRECTNESS.md): tested correctness claims, evidence,
  limitations, and reproducibility commands.

## Quick Start

These commands use a Unix-style shell. Windows readers should first complete
the [WSL setup in the Installation guide](docs/installation.md),
then run the same commands inside the Ubuntu terminal.

Install the published package from PyPI:

**Network required for installation.**

```bash
python3 -m pip install synthpopcan
```

Then inspect the command line:

```bash
synthpopcan --help
```

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

**Runnable teaching example.** Enter both commands in order.

```bash
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.

```bash
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.**

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

For installation details, see [`docs/installation.md`](docs/installation.md).

## Where To Start

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

| Task | Documentation |
| --- | --- |
| Choose a first workflow | [`docs/getting-started.md`](docs/getting-started.md) |
| Start a reproducible command-line workflow | [`docs/command-line.md`](docs/command-line.md) |
| Use the local browser app | [`docs/web-app.md`](docs/web-app.md) |
| Generate with IPF from margin/control tables | [`docs/ipf.md`](docs/ipf.md), [`docs/controls.md`](docs/controls.md), [`docs/statcan.md`](docs/statcan.md) |
| Assign linked households and people to small areas | [`docs/small-area.md`](docs/small-area.md) |
| Use the beginner Python API | [`docs/library-getting-started.md`](docs/library-getting-started.md) |
| Work with local data layout and `data doctor` | [`docs/data.md`](docs/data.md) |
| Inspect source files safely | [`docs/data.md`](docs/data.md), [`docs/statcan.md`](docs/statcan.md), [`docs/microdata.md`](docs/microdata.md) |
| Work with census microdata adapters | [`docs/microdata.md`](docs/microdata.md) |
| Train, audit, package, or use tree models | [`docs/tree.md`](docs/tree.md) |
| Validate generated outputs | [`docs/validate.md`](docs/validate.md) |
| Understand correctness evidence and limitations | [`CORRECTNESS.md`](CORRECTNESS.md) |
| Check current plans and implementation notes | [`PLANS.md`](PLANS.md), [`CHANGELOG.md`](CHANGELOG.md) |

Build the documentation locally with:

**Source checkout required.** Contributor setup is documented in
[`CONTRIBUTING.md`](CONTRIBUTING.md).

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

## Developer Benchmarks

Benchmark fixtures are developer tooling, not normal user workflows:

**Source checkout required.** The province-scale timing run can also require
substantial time and memory.

```bash
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.
The CLI, beginner Python API, and local web app call the same Python workflow
and domain implementations. Browser guidance and durable artifacts do not
define a separate computational tier; scale limits come from the selected
workflow, model, output size, and available machine resources.

## 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/data.md),
[`docs/tree.md`](docs/tree.md), [`PLANS.md`](PLANS.md), and
[`CONTRIBUTING.md`](CONTRIBUTING.md).
