MCHS NWAU Calculator

NWAU 计算器

参与贡献 | 安全 | 行为准则 | 引用

本项目提供 IHACPA SAS 资金计算器的 Python 移植版本。各模块涵盖急性医疗、急诊科、精神健康、亚急性医疗和门诊活动，以及 HAC 和 AHR 调整逻辑。目前正逐步确保实现与官方 SAS 计算器明确一致，但验证情况按计算器和年份分别跟踪，不会宣称整个代码库已完成验证。目前的实现仍使用基于 pandas 的处理路径；从长远来看，数据技术栈正逐步转向基于 Arrow 的数据交换，并在一致性验证工作允许的情况下采用 Polars。项目通过 funding-calculator 脚本提供轻量级命令行界面。

公开文档网站基于 docs-site/ 中的 Starlight 框架发布，是文档的官方入口。 GitHub Pages 部署路径通过 .github/workflows/docs-site.yml 配置。 可在 https://edithatogo.github.io/mchs/ 查看文档。

发布

发布由标签驱动，起始标签格式为 v0.2.0。 仓库使用发布草稿编写说明，并通过发布工作流构建发行包，再从带标签的提交创建 GitHub Releases。 带标签的发布也会通过可信发布机制触发 Python 包发布到 PyPI。 Rust GA 工作流也会将 Rust 构件发布到 GitHub Releases， 但此仓库尚未配置向 crates.io 提交。 conda-forge 配方草稿维护在 conda/recipe/ 下；目前新的 conda 包仅有配方，需等到 staged-recipes PR 获得接受且包出现在公开频道后才会发布；在注册表记录出现之前，用户应将 conda-forge 视为尚未发布。 所有发布声明仍以带标签源代码通过 CI 和验证门槛为前提。

Maven Central 就绪情况

JVM 绑定已在仓库中配置 Maven 发布元数据和手动 GitHub Actions 工作流。由于外部 Central Portal 账户的相关门槛尚未满足，目前不会宣称已发布到 Maven Central：

• 已为可发布的 JVM 坐标注册 Central Portal 命名空间；
• 已在发布机密存储中配置 CENTRAL_PORTAL_DEPLOY_URL、CENTRAL_PORTAL_USERNAME 和 CENTRAL_PORTAL_PASSWORD；
• 已在发布机密存储中配置 MAVEN_SIGNING_KEY 和 MAVEN_SIGNING_PASSWORD。
• 本地 JVM 就绪情况检查使用以下精确的 Gradle 命令：
  • gradle -p bindings/jvm tasks --all
  • gradle -p bindings/jvm publishAllPublicationsToCentralPortalRepository --dry-run --console=plain
• 除非提供部署 URL、凭据和签名机密，否则实际发布尝试会安全失败；试运行有意不使用凭据。

软件包注册表状态

截至 2026-05-26：

界面	分发证据	注册表状态
Python 软件包（nwau-py）	pyproject.toml、发布工作流和 PyPI 徽章链接	已在 PyPI 上发布，版本为 nwau-py 0.2.2
Conda 软件包（nwau-py）	conda/recipe/meta.yaml	仅有配方（尚未在 conda-forge 上发布）
MCP 标准输入/输出服务（mchs-mcp）	nwau_py/mcp_server.py、contracts/mcp/registry/server.json、.github/workflows/publish-mcp-registry.yml	已在官方 MCP 注册表上发布，标识为 io.github.edithatogo/mchs，版本为 0.2.2；Rust 公式执行仅对 MCP acute 2025 开放选择启用
Rust crate（nwau-core、nwau-c-abi、nwau-py）	rust/crates/*/Cargo.toml	nwau-core 已在 crates.io 上发布，版本为 0.1.0；nwau-c-abi 和 nwau-py 仍为本地／私有脚手架
@edithatogo/mchs-wasm-binding 软件包清单	wasm-binding/package.json	已在 npm 上发布，版本为 0.1.0
R / Julia / Scala / Spark / Swift / Stata / MATLAB / Kotlin-Native / Power Platform	conductor/tracks/* 中的跟踪规格	私有／仅在路线图中；未声称存在注册表制品

除非存在注册表页面且有证据链接，否则不要声称注册表提交成功（包括 crates.io、npm、CRAN、NuGet 等）。

该代码库还包含用于迁移 calculator-core 的 Rust 工作区脚手架。在逐个计算器证明 Rust 与 Python 行为一致之前，Python 仍是当前经过验证的运行时路径。 预期架构是一个多语言库：共享的 Rust 计算器核心，以及面向 Python、Rust、R、Julia、C#/.NET、Go、TypeScript/WASM、Java/JVM、C ABI、SQL/DuckDB、SAS 互操作、CLI／文件工作流、Web 演示和 Power Platform 编排的轻量绑定或适配器。这些界面必须使用共享契约和验证固件，而不能重复实现公式逻辑。

CLI 为计算命令提供显式的运行时选择器： --runtime python|rust|auto，并支持通过 NWAU_RUNTIME 覆盖 CI 或自动化中的设置。Python 仍是默认选项。目前唯一已推广的 Rust 后端 CLI 功能是可选启用的 acute 2025 CSV 执行。对于不受支持的 Rust 请求，系统会安全失败，而不会静默回退。支持边界详见 docs/roadmaps/rust-cli-runtime-boundary.md。

MCP 标准输入/输出服务保留 Python 传输垫片，以支持兼容注册表的本地执行；但 mchs.calculate 可以选择使用同一 Rust acute 2025 公式切片，设置为 options.runtime = "rust"。MCP 支持状态资源会区分 Python 标准输入/输出传输与 Rust 后端公式执行。 不宣称 CLI 或 MCP 默认使用 Rust；contracts/runtime/rust-cli-mcp-promotion-matrix.json 中的推广矩阵规定，在跨界面证据覆盖不受支持的计算器、年份、格式、诊断和回滚之前，不得将 Rust 推广为默认选项。

计算器模块

以下每个模块都对应 IHACPA 软件包中的一个 SAS 程序。

模块	SAS 源文件	备注
acute	NWAU25_CALCULATOR_ACUTE.sas	使用当前的表格型 Python 执行路径计算急性住院病例的 NWAU25。实现 ICU 小时数逻辑、住院时长分类和私立患者调整。
ed	NWAU25_CALCULATOR_ED.sas	处理急诊科／服务活动。支持 UDG 和 AECC 分类，并进行偏远程度和原住民调整。
mh	NWAU25_CALCULATOR_MH.sas	实现心理健康服务对象模型。应用私立患者服务和住宿调整。
subacute	NWAU25_CALCULATOR_SUBACUTE.sas	根据 SNAP 计算亚急性住院活动的 NWAU25。
outpatients	NWAU25_CALCULATOR_OUTPATIENTS.sas	用于非住院门诊活动。进行偏远程度和原住民调整。
adjust	Calculate Adjusted NWAU.sas	将基础 NWAU 与医院获得性并发症（HAC）和可避免的医院再入院（AHR）调整合并。

应将 IHACPA 的历史 SAS 计算器解压到 archive/sas/<YEAR>/。重命名下载的目录，使其仅保留年份 （例如 archive/sas/2025）。之后，每个文件夹都包含该定价年份的 原始 SAS 程序和数据表。

计算器

项目包含每种拨款计算器的 Python 版本。下表列出了对应的 SAS 程序，并显示哪些定价年份的权重和公式已通过验证。

计算器	SAS 程序	Python	2014	2015	2016	2017	2018	2019	2020	2021	2022	2023	2024	2025
急性	NWAU25_CALCULATOR_ACUTE.sas	✓											✓	✓
急诊	NWAU25_CALCULATOR_ED.sas	✓											✓	✓
心理健康	NWAU25_CALCULATOR_MH.sas	✓											✓	✓
亚急性	NWAU25_CALCULATOR_SUBACUTE.sas	✓											✓	✓
门诊	NWAU25_CALCULATOR_OUTPATIENTS.sas	✓											✓	✓
调整	Calculate Adjusted NWAU.sas	✓											✓	✓
再入院	Avoidable Hospital Readmission Grouper 030.sas	✓											✓	✓

目前已验证 2024 和 2025 年的权重和公式。较早年份仍在进行中，待其输出通过可信参考资料验证后完成。

安装

推荐使用 uv 进行开发：

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

已发布的版本可从 PyPI 获取：

python -m pip install nwau-py

在 conda-forge staged-recipes 提交获批且软件包公开发布后，conda 用户可以 使用以下命令安装：

conda install -c conda-forge nwau-py

将官方 SAS 计算器解压到 archive/sas/<YEAR>/，以便 Python 模块加载各年份的参考表。

依赖项

这些计算器依赖多个核心 Python 软件包：

• NumPy 用于数值辅助功能
• Pandas 用于仍在进行一致性验证的旧版表格处理路径
• Polars 和 PyArrow 用于 Arrow／Parquet 互操作性以及较新的 bundle 层
• LightGBM 用于再入院风险评分

当前的开发工具栈还使用：

• uv 用于环境和依赖项管理
• Ruff 用于代码检查和格式化
• ty 用于类型检查
• pytest 和 Codecov 用于测试执行和覆盖率报告
• Hypothesis 用于基于属性的测试
• mutmut 用于变异测试
• Scalene 用于性能分析

使用 uv run 在项目环境中执行工具：

uv run pytest
uv run ruff check .
uv run ty check

维护自动化

依赖项更新通过 Renovate 审核；文档或验证声明则会在合并前使用 Vale 检查。

历史数据

将每年的 SAS 计算器放在 archive/sas/<YEAR>/ 下，并确保文件夹名称仅为年份。解压后，目录中应包含该定价年度的 SAS 程序和参考表。

Excel 工作簿也可以归档在 excel_calculator/archive/<year> 下，以便进行历史比较。辅助脚本 （excel_calculator/scripts/extract_all.py）可以从工作簿重新生成 weights.csv 和 formula.json，但只有在重现原始电子表格时才需要这样做。

目录结构

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

要添加对某个年份的支持，只需放入新的 SAS 文件夹以及对应的 weights.csv/formula.json 文件。

仓库目前包含经过验证的 2024 和 2025 版权重和公式。其他年份可在输出通过验证后添加。

数据可用性矩阵

年份	SAS 归档	已验证权重	已验证的 Python 实现
2014	✅	❌	❌
2015	✅	❌	❌
2016	✅	❌（仅样例）	❌
2017	✅	❌	❌
2018	✅	✅（样例）	❌
2019	✅	✅（样例）	❌
2020	✅	❌	❌
2021	✅	❌	❌
2022	✅	❌	❌
2023	✅	❌	❌
2024	✅	✅	✅
2025	✅	✅	✅

添加新的定价年份

1. 将新版本的 SAS 计算器解压到 archive/sas/<YEAR>/ 下。重命名文件夹，使其名称仅保留年份。
2. 将 Excel 工作簿复制到 excel_calculator/archive/<YEAR>，并运行 python excel_calculator/scripts/extract_all.py。该脚本会将 weights.csv 和 formula.json 写入 excel_calculator/data/<YEAR>/。
3. 如果偏远地区分类年份发生变化，请相应更新 nwau_py/utils.RA_VERSION。
4. 随后可以通过 --year <YEAR> 调用各个计算器，或在调用 Python 函数时传入 year="<YEAR>"。

SAS 程序映射

原始 SAS 计算器归档在 archive/sas/<YEAR>/calculators 下。nwau_py 中的每个 Python 模块都对应其中一个程序。下表列出了主要对应关系。

SAS 程序	Python 模块	说明
NWAU##_CALCULATOR_ACUTE.sas	nwau_py/calculators/acute.py	与 SAS 急性逻辑一致
NWAU##_CALCULATOR_ED.sas	nwau_py/calculators/ed.py	等效的 ED 计算
NWAU##_CALCULATOR_MH.sas	nwau_py/calculators/mh.py	心理健康患者模型
NWAU##_CALCULATOR_SUBACUTE.sas	nwau_py/calculators/subacute.py	基于 SNAP 的计算器
NWAU##_CALCULATOR_OUTPATIENTS.sas	nwau_py/calculators/outpatients.py	非住院活动
Calculate Adjusted NWAU.sas	nwau_py/calculators/adjust.py	应用 HAC 和 AHR 调整
Avoidable Hospital Readmission Grouper.sas	nwau_py/groupers/ahr.py	再入院分组器
Hospital Acquired Complication Grouper.sas	nwau_py/groupers/hac.py	HAC 分组器
Scorer_v3.py	src/nwau_py/scoring/scorer.py	LightGBM 再入院模型

使用方法

权重和定价公式存储在 excel_calculator/data 中。 每个定价年份都有自己的子目录，例如 excel_calculator/data/2025。 顶层文件仍保留为 2025 年的默认文件，以便现有脚本继续正常运行。 可以直接通过 python -m nwau_py.cli.main 执行资金计算器。 例如，要处理急性活动：

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

对于其他活动类型，将 acute 替换为 ed 或 non-admitted。--year 选项用于选择要使用的 SAS 版本。

安装开发环境后，可以使用 uv run 运行测试、代码检查、类型检查、属性测试、变异测试和性能分析入口。覆盖率报告会在本地生成，以便在 CI 中上传到 Codecov。

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

请参阅 nwau_py/docs/calculators.md，了解各个计算器模块的概述。 nwau_py 包提供命令行界面以及供 Python 代码调用的函数。

验证状态

本仓库中的验证声明有意具体明确。优先使用由 fixture 包、对照测试或归档源文件支持的、针对特定计算器和年份的声明。除非相应证据与声明一同提交，否则避免笼统声称项目整体或所有年份均已通过验证。

偏远程度分类

这些计算器依赖 IHACPA 偏远地区（RA）分类。所用版本因定价年份而异。nwau_py.utils.RA_VERSION 将各年份映射到对应的 RA 版本，而辅助函数 ra_suffix(year) 会返回数据集列名中使用的后缀。

from nwau_py.utils import ra_suffix

assert ra_suffix("2025") == "ra2021"

处理缺失的人口统计信息

如果输入数据中缺少偏远程度或原住民身份信息，计算器可以根据人口分布估算调整值。向参数数据类传入一个比例字典：

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)

缺失的调整值会根据所提供的分布，替换为相关表格的加权平均值。

命令行

安装后即可使用 funding-calculator 入口点。你可以使用 --year 选择特定的定价年份：

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

--year 选项用于选择该定价年份的数据目录。上面的示例使用 2024 年权重，但也可以在验证数据可用后选择 --year 2025。patient_data.csv 应包含 excel_calculator/data/2024/formula.json 中引用的列，输出将包含 NWAU24 列。

要使用较早版本进行资金计算，只需传入相应年份。例如，要运行 2024 年计算器，请使用：

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

这会指示工具从 excel_calculator/data/2024/ 加载权重和公式。

nwau_py 包还通过 python -m nwau_py.cli.main 提供轻量级命令行界面。--year 标志适用于任何受支持的版本（目前为 2024 和 2025）。子命令 acute、ed 和 non-admitted 与 SAS 计算器相对应：

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

常用选项允许通过 --params 覆盖权重目录，并使用 --icu/--no-icu 和 --covid/--no-covid 启用或禁用调整。

Python 模块

也可以直接从 Python 调用计算器：

from nwau_py.calculators import AcuteParams, calculate_acute

patient_df = ...  # tabular episode-level data frame
result = calculate_acute(patient_df, AcuteParams())

传入 year="2024"（例如）即可使用其他定价版本。

nwau_py.calculators 下的其他模块提供急性护理、急诊、心理健康和其他活动类型的辅助工具。最简示例请参见 examples/run_acute.py。

计算器示例

如需精细控制，可以直接调用各个计算器。每个函数都接受一个表格输入框架，并返回一个附加了 NWAU25 列的输入框架。

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)