Installation

SynthPopCan is a command-line tool and Python library. Using it requires opening a terminal — a text window where you type commands rather than clicking buttons. If you have not used a terminal before, these introductions are written for humanities researchers and require no prior programming experience:

Read one of those first, then return here.

SynthPopCan can be installed from PyPI, run as a one-off command with uvx, or installed from a source checkout for development. If we only want to use the command line or beginner Python API, start with the PyPI installation. If we want to edit the code, documentation, or tests, use the source checkout.

Requirements

  • Python 3.11 or newer. Download from python.org/downloads. If you have not used Python before, the Programming Historian’s Introduction to Python is a good starting point.

  • Git, only when cloning from the repository.

  • pip, which is included with most Python installations.

  • Optional: uv, when using uvx for one-off commands or when working on the source checkout.

  • Local source data staged outside git when working with real census or private files.

You do not need a database, a cloud account, or a web server for the command-line workflows.

Install From PyPI

For most users, install the published package from PyPI:

python -m pip install synthpopcan

Then check that the command is available:

synthpopcan --help

This is the best path when we want to run command-line examples, use the beginner API in a notebook, or build small teaching workflows without editing SynthPopCan itself.

For notebook work, install SynthPopCan into the same Python environment that Jupyter uses. A minimal notebook smoke test is:

import synthpopcan as spc

spc.__version__

Run One-Off Commands With uvx

If we have uv installed but do not want to install SynthPopCan into the current environment, uvx can download the package and run the synthpopcan command in an isolated temporary environment:

uvx synthpopcan --help
uvx synthpopcan guide ipf

This is useful for trying the CLI or running a short command. For repeated work in a project folder or notebook, a normal pip installation is usually easier to reason about.

Install From a Source Checkout

A source checkout is a local copy of the SynthPopCan repository cloned from GitHub. Use one when we want to edit SynthPopCan, run the tests, build the documentation locally, or work against unreleased changes.

Clone the repository, then enter the checkout:

git clone https://github.com/dlq/synthpopcan.git
cd synthpopcan

The repository currently uses uv for repeatable local development. If we do not have uv, install it from the official installation guide.

From the repository root:

uv sync

This creates a local environment and installs SynthPopCan with its runtime dependencies.

For documentation work:

uv sync --group docs

Run the Command

If SynthPopCan was installed with pip, run:

synthpopcan --help

When working directly from a source checkout with uv, prefix commands with uv run so they use the checkout’s isolated Python environment — a separate installation that keeps SynthPopCan’s dependencies from interfering with other Python projects on the same machine:

uv run synthpopcan --help

The rest of the documentation usually shows synthpopcan ... to focus on the tool itself. If we are using uvx, replace synthpopcan ... with uvx synthpopcan .... If we are working from a checkout, use uv run synthpopcan ....

Beginner command-line guidance is available with:

synthpopcan guide ipf
synthpopcan guide model

Quick Getting Started

This tiny fixture workflow fits two seed rows to age and sex controls. It does not download public data and does not use private microdata.

This is a smoke test for the command-line setup. For a fuller explanation of each IPF step, see IPF. For the equivalent notebook-oriented Python workflow, see Getting Started With the Beginner API.

synthpopcan microdata export-seed \
  tests/fixtures/workflows/microdata_ipf/hierarchical.csv \
  --input-format statcan-2016-hierarchical \
  --columns AGEGRP,SEX \
  --out seed.csv

synthpopcan ipf check-inputs \
  --seed seed.csv \
  --controls tests/fixtures/workflows/microdata_ipf/controls.csv

synthpopcan ipf fit \
  --seed seed.csv \
  --controls tests/fixtures/workflows/microdata_ipf/controls.csv \
  --weight-field WEIGHT \
  --out weights.csv \
  --report fit-report.json

synthpopcan ipf report fit-report.json

synthpopcan validate controls \
  --population weights.csv \
  --controls tests/fixtures/workflows/microdata_ipf/controls.csv \
  --kind weights

If we are running from a source checkout without activating the environment, we can add uv run before each synthpopcan command.

Build the Documentation

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

The -W flag treats warnings as errors. This is intentional: it catches broken links and malformed documentation before Read the Docs publishes the site.

Check the reStructuredText source files with:

uv run --group docs doc8 docs

Check Markdown formatting with:

uv run --group docs mdformat --check docs README.md

Apply Markdown formatting with:

uv run --group docs mdformat docs README.md

When changing examples, also run the examples that are presented as runnable. Good examples are part of the interface: check command names, fixture paths, column names, output files, and whether the example still makes sense in the surrounding explanation.

Local Data

SynthPopCan looks for local data under data/ by default. Raw and private data should stay out of git.

data/
  raw/
  private/

Check the expected local layout with:

uv run synthpopcan data doctor

Use --data-root PATH or SYNTHPOPCAN_DATA_ROOT when the data lives somewhere else.

Working Folder Advice

Run commands from the repository root unless a page says otherwise. In examples, lines ending with \ continue onto the next line.

Most examples write small files such as seed.csv, weights.csv, and fit-report.json in the current directory. For a real project, create a separate working folder so outputs from different runs do not get mixed together.

Find SynthPopCan Online