MCHS NWAU Calculator

NWAU Calculator

貢献 | セキュリティ | 行動規範 | 引用

このプロジェクトでは、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/ で管理されています。staged-recipes の PR が承認されてパッケージが公開チャンネルに掲載されるまでは、新しい conda パッケージはレシピのみの状態です。そのレジストリに登録されるまでは、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 stdio サーバー（mchs-mcp）	nwau_py/mcp_server.py、contracts/mcp/registry/server.json、.github/workflows/publish-mcp-registry.yml	公式 MCP Registry に io.github.edithatogo/mchs バージョン 0.2.2 として 公開済み。Rust による数式実行は MCP acute 2025 でのみオプトイン可能です
Rust クレート（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 が現在の検証済みランタイムです。 想定されるアーキテクチャは、ポリグロットライブラリです。共有 Rust 計算機コアに、Python、Rust、R、Julia、C#/.NET、Go、TypeScript/WASM、Java/JVM、C ABI、SQL/DuckDB、SAS 相互運用、CLI／ファイルワークフロー、ウェブデモ、Power Platform オーケストレーション向けの薄いバインディングまたはアダプターを組み合わせます。これらのサーフェスでは、数式ロジックを重複して実装するのではなく、共有コントラクトと検証フィクスチャを利用する必要があります。

CLI では、計算コマンドに明示的なランタイムセレクターを指定できます。 --runtime python|rust|auto を指定でき、CI または自動化で上書きする場合は NWAU_RUNTIME を使用できます。デフォルトは引き続き Python です。現在、Rust 対応として昇格されている CLI の範囲は、オプトインでの acute 2025 CSV 実行のみです。未対応の Rust リクエストは、暗黙にフォールバックせず、フェイルクローズします。対応範囲については docs/roadmaps/rust-cli-runtime-boundary.md を参照してください。

MCP stdio サーバーは、レジストリ互換のローカル実行に Python トランスポートシムを引き続き使用しますが、mchs.calculate では options.runtime = "rust" を指定して、同じ Rust acute 2025 数式スライスをオプトインできます。MCP のサポート状況リソースでは、Python stdio トランスポートと Rust による数式実行を区別しています。CLI または MCP で Rust がデフォルトであるとは主張しません。contracts/runtime/rust-cli-mcp-promotion-matrix.json の昇格マトリックスでは、未対応の計算機、年、形式、診断、ロールバックを網羅するサーフェス横断の根拠が揃うまで、Rust のデフォルトへの昇格を保留しています。

計算モジュール

以下の各モジュールは、IHACPA パッケージの SAS プログラムに対応しています。

モジュール	SAS ソース	備考
acute	NWAU25_CALCULATOR_ACUTE.sas	急性期の入院エピソードの NWAU25 を計算します。現在の表形式の Python 実行パスを使用して、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 の相互運用性と新しいバンドル層に使用します
• 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 を実行します。これにより、excel_calculator/data/<YEAR>/ に weights.csv と formula.json が書き込まれます。
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 を使ってテスト、リンティング、型チェック、プロパティテスト、ミューテーションテスト、プロファイリングの各エントリーポイントを実行できます。Codecov へのアップロード用のカバレッジレポートは、CI でローカルに生成されます。

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 内で使用する関数の両方を提供します。

検証状況

このリポジトリでの検証に関する記述は、意図的に具体的な内容にしています。フィクスチャーパック、パリティテスト、またはアーカイブされたソース成果物によって裏付けられた、計算機および年度を限定した記述を優先してください。裏付けとなる証拠が記述とともにコミットされていない限り、プロジェクト全体または全年度にわたる検証について広範な主張をすることは避けてください。

遠隔性の分類

各計算機は、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)