MCHS NWAU Calculator

NWAU Calculator

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/ /. 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/ / 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 pytest

uv 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/ / 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/ 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/ / # SAS reference tables excel_calculator/ data/ weights.csv # default (current year) formula.json /weights.csv /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/ /. Rename the folder so only the year remains.
2. Copy the Excel workbook to `excel_calc