MCHS NWAU Calculator

NWAU Calculator

[PR CI] [Docs Site] [PyPI] [Python] [License: MIT]

Contributing | Security | Code of Conduct | Citation

This project provides Python translations of the IHACPA SAS funding calculators. Modules cover acute, emergency department, mental health, subacute and outpatient activity along with HAC and AHR adjustment logic. The implementation is being brought into explicit parity with the official SAS calculators, but validation is tracked per calculator and year rather than claimed as complete across the whole repository. The current implementation still uses pandas-based paths, while the longer-term data stack is moving toward Arrow-backed interchange and Polars where parity work allows it. A lightweight command line interface is available via the funding-calculator script.

The public documentation site is published from the Starlight scaffold in docs-site/ and serves as the canonical docs front door. The GitHub Pages deployment path is wired through .github/workflows/docs-site.yml. Open the docs at https://edithatogo.github.io/mchs/.

Releases

Releases are tag-driven and start from v0.2.0-style tags. The repo uses release drafts for notes and a release workflow to build distributions and publish GitHub Releases from tagged commits. Tagged releases also trigger Python package publishing to PyPI through trusted publishing. The Rust GA workflow also publishes Rust artifacts to GitHub Releases, but crates.io submission is not wired in this repository yet. The conda-forge recipe draft is maintained under conda/recipe/; new conda packages are currently recipe-only until a staged-recipes PR is accepted and the package appears on the public channel; users should treat conda-forge as unpublished until that registry record exists. All release claims still depend on the CI and validation gates passing for the tagged source.

Maven Central readiness

The JVM binding has repo-side Maven publishing metadata and a manual GitHub Actions workflow. Maven Central publication is still not claimed because the external Central Portal account gates remain open:

• a registered Central Portal namespace for the publishable JVM coordinates;
• CENTRAL_PORTAL_DEPLOY_URL, CENTRAL_PORTAL_USERNAME, and CENTRAL_PORTAL_PASSWORD provisioned in the release secret store;
• MAVEN_SIGNING_KEY and MAVEN_SIGNING_PASSWORD provisioned in the release secret store.
• Local JVM readiness checks use exact Gradle commands:
  • gradle -p bindings/jvm tasks --all
  • gradle -p bindings/jvm publishAllPublicationsToCentralPortalRepository --dry-run --console=plain
• Real publish attempts fail closed unless deploy URL, credentials, and signing secrets are supplied; dry-runs are intentionally credential-free.

Package registry status

As of 2026-05-26:

Do not state registry submission success (including crates.io, npm, CRAN, NuGet, etc.) unless a registry page exists and is linked in evidence.

The repository also contains a Rust workspace scaffold for calculator-core migration. Python remains the current validated runtime path until Rust parity is proven calculator by calculator. The intended architecture is a polyglot library: a shared Rust calculator core with thin bindings or adapters for Python, Rust, R, Julia, C#/.NET, Go, TypeScript/WASM, Java/JVM, C ABI, SQL/DuckDB, SAS interoperability, CLI/file workflows, web demos, and Power Platform orchestration. Those surfaces must consume shared contracts and validation fixtures rather than duplicating formula logic.

The CLI exposes an explicit runtime selector for calculation commands: --runtime python|rust|auto, with NWAU_RUNTIME available for CI or automation overrides. Python remains the default. The only Rust-backed CLI slice currently promoted is opt-in acute 2025 CSV execution; unsupported Rust requests fail closed rather than falling back silently. See docs/roadmaps/rust-cli-runtime-boundary.md for the support boundary.

The MCP stdio server keeps its Python transport shim for registry-compatible local execution, but mchs.calculate can opt into the same Rust acute 2025 formula slice with options.runtime = "rust". MCP support-status resources distinguish the Python stdio transport from Rust-backed formula execution. No CLI or MCP Rust-default claim is made; the promotion matrix in contracts/runtime/rust-cli-mcp-promotion-matrix.json keeps Rust default promotion blocked until cross-surface evidence covers unsupported calculators, years, formats, diagnostics, and rollback.

Calculator modules

Each module below mirrors a SAS program from the IHACPA package.

Historical SAS calculators from IHACPA should be extracted to archive/sas/<YEAR>/. Rename the downloaded directory so only the year remains (for example archive/sas/2025). Each folder then contains the original SAS programs and data tables for that pricing year.

Calculators

The project includes Python versions of each funding calculator. The table below lists the corresponding SAS programs and shows which pricing years have validated weights and formulas.

Weights and formulas are currently verified for 2024 and 2025. Earlier years remain in progress until their outputs are validated against trusted reference material.

Installation

The preferred development workflow uses uv:

uv sync --locked --group dev --group test --group coverage --group typing --group property --group mutation --group profiling --group docs

Published releases are available from PyPI:

python -m pip install nwau-py

After the conda-forge staged-recipes submission is accepted and the package is publicly available, conda users can install with:

conda install -c conda-forge nwau-py

Extract the official SAS calculators under archive/sas/<YEAR>/ so the Python modules can load the reference tables for each year.

Dependencies

The calculators rely on several core Python packages:

• NumPy for numerical helpers
• Pandas for legacy tabular paths that remain under parity validation
• Polars and PyArrow for Arrow/Parquet interoperability and the newer bundle layer
• LightGBM for readmission risk scoring

The active development stack also uses:

• uv for environment and dependency management
• Ruff for linting and formatting
• ty for type checking
• pytest and Codecov for test execution and coverage reporting
• Hypothesis for property-based tests
• mutmut for mutation testing
• Scalene for profiling

Use uv run to execute tools inside the project environment:

uv run pytestuv run ruff check .uv run ty check

Maintenance automation

Dependency updates are reviewed through Renovate, and documentation or validation claims are checked with Vale before they are merged.

Historical data

Place each year's SAS calculator under archive/sas/<YEAR>/ and ensure the folder name is just the year. After extraction the directory should contain the SAS programs and reference tables for that pricing year.

The Excel workbooks may also be archived under excel_calculator/archive/<year> for historical comparison. A helper script (excel_calculator/scripts/extract_all.py) can recreate weights.csv and formula.json from the workbooks but this is only required when reproducing the original spreadsheets.

Directory layout

archive/  sas/<YEAR>/        # SAS reference tablesexcel_calculator/  data/    weights.csv      # default (current year)    formula.json    <YEAR>/weights.csv    <YEAR>/formula.json

Dropping the SAS folder and matching weights.csv/formula.json files for a new edition is all that's required to add support for that year.

The repository currently includes verified weights and formulas for the 2024 and 2025 editions. Additional years can be added once their outputs are validated.

Data availability matrix

Adding a new pricing year

1. Extract the SAS calculator for the new edition under archive/sas/<YEAR>/. Rename the folder so only the year remains.
2. Copy the Excel workbook to excel_calculator/archive/<YEAR> and run python excel_calculator/scripts/extract_all.py. This writes weights.csv and formula.json to excel_calculator/data/<YEAR>/.
3. If the remoteness classification year changes update nwau_py/utils.RA_VERSION accordingly.
4. Each calculator can then be invoked with --year <YEAR> or by passing year="<YEAR>" when calling the Python functions.

SAS program mapping

The original SAS calculators are archived under archive/sas/<YEAR>/calculators. Each Python module in nwau_py mirrors one of these programs. The table below lists the main equivalences.

Usage

Weights and the pricing formula are stored in excel_calculator/data. Each pricing year has its own subdirectory, e.g. excel_calculator/data/2025. The top-level files remain as the default for 2025 so existing scripts continue to work. Funding calculators can be executed directly via python -m nwau_py.cli.main. For example, to process acute activity:

python -m nwau_py.cli.main acute patient_data.csv --output funding.csv

Replace acute with ed or non-admitted for other activity types. The --year option selects which SAS release to use.

After installing the development environment you can run the tests, linting, type checking, property tests, mutation testing, and profiling entry points with uv run. Coverage reports are generated locally for Codecov upload in CI.

uv sync --locked --group dev --group test --group coverage --group typing --group property --group mutation --group profiling --group docsuv run pytestuv run pytest --cov=nwau_py --cov-report=term-missing --cov-report=xml --cov-fail-under=80uv run ty checkuv run pytest -m hypothesisuv run mutmut runuv run scalene nwau_py/cli/main.py

See nwau_py/docs/calculators.md for an overview of each calculator module. The nwau_py package exposes both a command line interface and functions for use within Python.

Validation Status

Validation claims in this repository are intentionally specific. Prefer calculator- and year-scoped statements backed by fixture packs, parity tests, or archived source artifacts. Avoid broad claims about project-wide or all-years validation unless the supporting evidence is committed alongside the claim.

Remoteness classification

The calculators rely on the IHACPA remoteness area (RA) classification. The edition used varies by pricing year. nwau_py.utils.RA_VERSION maps each year to its RA edition and the helper function ra_suffix(year) returns the suffix used in dataset column names.

from nwau_py.utils import ra_suffix
assert ra_suffix("2025") == "ra2021"

Handling missing demographics

When remoteness or Indigenous status is missing from the input data the calculators can impute adjustment values using population distributions. Pass a dictionary of proportions to the parameter dataclass:

from nwau_py.calculators import AcuteParams, calculate_acute
rem_dist = {"RA1": 0.55, "RA2": 0.25, "RA3": 0.15, "RA4": 0.04, "RA5": 0.01}ind_dist = {0: 0.8, 1: 0.2}params = AcuteParams(    remoteness_distribution=rem_dist,    indigenous_distribution=ind_dist,)result = calculate_acute(df, params)

Missing adjustments are replaced by the weighted average of the relevant table using the provided distribution.

Command line

After installation the funding-calculator entry point is available. You can select a specific pricing year with --year:

funding-calculator --year 2024 patient_data.csv > funding.csv

The --year option selects the data directory for that pricing year. The example above uses the 2024 weights but you can also choose --year 2025 once verified data is available. patient_data.csv should contain the columns referenced in excel_calculator/data/2024/formula.json and the output will include a NWAU24 column.

To calculate funding using an older edition simply pass the relevant year. For example, to run the 2024 calculator use:

funding-calculator --year 2024 patient_data.csv > funding.csv

This instructs the tool to load weights and the formula from excel_calculator/data/2024/.

The nwau_py package also exposes a lightweight command line interface via python -m nwau_py.cli.main. The --year flag works with any supported edition (currently 2024 and 2025). The subcommands acute, ed and non-admitted mirror the SAS calculators:

python -m nwau_py.cli.main acute INPUT.csv --output out.csv --year 2025

Common options allow the weights directory to be overridden with --params and enable or disable adjustments using --icu/--no-icu and --covid/--no-covid.

Python modules

The calculators can also be called directly from Python:

from nwau_py.calculators import AcuteParams, calculate_acute
patient_df = ...  # tabular episode-level data frameresult = calculate_acute(patient_df, AcuteParams())

Pass year="2024" (for example) to use a different pricing edition.

Additional modules under nwau_py.calculators provide helpers for acute, emergency, mental health and other activity types. See examples/run_acute.py for a minimal demonstration.

Calculator examples

The individual calculators can be invoked directly when you need fine grained control. Each function expects a tabular input frame and returns the input with an additional NWAU25 column.

from nwau_py.calculators import AcuteParams, calculate_acute
result = calculate_acute(acute_df, AcuteParams())

from nwau_py.calculators import EDParams, calculate_ed
result = calculate_ed(ed_df, EDParams())

from nwau_py.calculators import MHParams, calculate_mh
result = calculate_mh(mh_df, MHParams())

from nwau_py.calculators import SubacuteParams, calculate_subacute
result = calculate_subacute(sa_df, SubacuteParams())

from nwau_py.calculators import OutpatientParams, calculate_outpatients
result = calculate_outpatients(op_df, OutpatientParams())

from nwau_py.calculators import calculate_adjusted_nwau
result = calculate_adjusted_nwau(weight_df)

Current development runtime: repository-local Python 3.15.1, selected by .python-version. See runtime qualification, NEP26 scope and NEP25 correction. No new release or full official-calculator parity is claimed by these changes.