goals-scenario

Goals scenario analysis

• Github repository: https://github.com/avenirhealth-org/goals-scenario/
• Documentation: https://avenirhealth-org.github.io/goals-scenario/

Installation

pip install avenir_goals_scenario

After installation, the goals-scenario command is available on your PATH.

Quick start

For full details of the CLI see the CLI reference.

goals-scenario --help      # or -h
goals-scenario --version

Both commands are driven by a single JSON config file. Field names are case-insensitive.

{
  "pjnz_dir": "path/to/pjnz/files",
  "definition_path": "scenario_definitions.csv",
  "scenario_path": "draws.json",
  "output_dir": "path/to/output",
  "base_year": 2025,
  "output_indicators": ["p_hivpop", "p_infections", "p_hiv_deaths", "h_artpop"],
  "n_simulations": 100,
  "seed": null
}

One-shot run (draw and run together)

Set definition_path in the config and omit scenario_path. Draws are saved automatically to <output_dir>/draws.json.

goals-scenario run config.json

Two-step run (draw first, then run)

Useful when you want to inspect draws before committing to a full model run, or to reuse the same draws across multiple runs. Set both definition_path and scenario_path in the config.

goals-scenario draw config.json   # saves draws to scenario_path
goals-scenario run config.json    # reuses the same draws

If you call run with both paths set and scenario_path already exists, the existing draws are reused. If the file is missing, draws are regenerated and saved.

Tab completion

To install shell tab completion:

goals-scenario --install-completion

Development

Architecture

Prerequisites

• uv for installing Python, package management

• (Optionally) make. Should be installed by default, except on windows, where it is easiest to install it via Chocolatey choco install make

• Test data (PJNZ files) are stored in a git submodule. Initialise it after cloning:

  git submodule update --init --recursive
  

Development with make

There is a Makefile which wraps some common uv commands you will need during development.

Set Up Your Development Environment

Install the environment and the pre-commit hooks with

make install

This will also generate your uv.lock file.

Run code checks

make check

Run tests

make test

Build docs site

make docs

Development with uv

If you choose not to use make, you can use uv directly.

Set Up Your Development Environment

Install the environment and the pre-commit hooks with

uv sync
uv run pre-commit install

This will also generate your uv.lock file.

Run code checks

Run pre-commit checks, include ruff linting and formatting

uv run pre-commit run -a

Run type checking

uv run ty check

Check for vulnerabilities in pypi dependencies

uv run pip-audit --desc -s osv

Run tests

uv run pytest

Build docs site

uv run mkdocs serve

Run compatibility tests

Compatability tests with tox are configured. Run them with

uv run tox

These are also run on CI, so not the end of the world if you don't do it locally.

Vendored SpectrumEngine import code

We need to re-use some of the PJNZ import code from SpectrumEngine. At the moment, this is vendored here directly. There is a script to update the vendored code which should be run before a release. The script uses a file ./scripts/spectrum_engine_ref to clone the specified branch or ref.

With make:

make pjnz-import-code

Run script directly

uv run ./scripts/update_pjnz_import_code.py

CLI

The CLI is built using typer which builds CLI docs automatically from python type hints and decorators. It also gives us some neat things like auto completion. And progress bars down the line!

Release process

Creating a release will

1. Build & push the package to PyPI
2. Build an updated docs site
3. Build a Windows .exe and attach it as goals-scenario.zip to the GitHub release

To create a release you need to

1. Update the version number in the pyproject.toml or ensure it has updated since the last release
2. Go to the releases page and "Draft a new release"
3. Create a new tag, I usually use a tag which matches the version number you are releasing. Set a release title and text. Usually useful to include in the text a summary of the changes since the last release.
4. Publish the release. This will trigger a GitHub action which will push the package to PyPI, update the docs site, and build the Windows executable.

Building the Windows executable locally

The Windows .exe is built with PyInstaller using the spec file at packaging/goals-scenario.spec. To build it locally on Windows:

uv run pyinstaller --distpath dist --workpath build packaging/goals-scenario.spec

The output lands in dist/goals-scenario/. The goals-scenario.exe inside that folder is the entry point. You can test it by running dist\goals-scenario\goals-scenario.exe --version.

The packaging/Dockerfile.win Docker image is used in CI to smoke-test the built exe in an isolated Windows Server Core container. To build and test it locally (requires Docker in Windows container mode):

docker build -f packaging/Dockerfile.win -t goals-scenario-test .
docker run --rm goals-scenario-test --version

To run draw and run via Docker, mount your data directory and an output directory into the container. The config file must reference the container-side paths and be accessible from a mounted directory:

# Place your config.json in the output directory before running.
# Example config.json referencing container paths:
# {
#   "pjnz_dir": "C:/data/pjnz",
#   "definition_path": "C:/data/scenario_definitions.csv",
#   "scenario_path": "C:/output/draws.json",
#   "output_dir": "C:/output",
#   "base_year": 2025,
#   "output_indicators": ["p_hivpop", "p_infections", "p_hiv_deaths", "h_artpop"],
#   "n_simulations": 100
# }

docker run --rm `
  -v "C:\path\to\your\data:C:\data" `
  -v "C:\path\to\output:C:\output" `
  goals-scenario-test draw C:\output\config.json

docker run --rm `
  -v "C:\path\to\your\data:C:\data" `
  -v "C:\path\to\output:C:\output" `
  goals-scenario-test run C:\output\config.json