NHANES (design-correct survey analysis)

nhanes-mcp

NHANES のパブリックユースデータに、設計に沿った正確な方法で会話形式でアクセスするための MCP サーバーです。 Black Swan Causal Labs · MIT license · v0.5 · PyPI · MCP Registry

多くの「データセットとチャットする」レイヤーでは、エージェントが重み付けされていない平均を計算できます。NHANES では、その答えは誤りです。このサーバーは、妥当な分析を標準の動作にします。エージェントが平易な言葉で質問すると、サーバーがファイルを見つけ、SEQN で結合し、適切な重みを選択して、調査設計全体を維持しながら、NCHS の信頼性フラグ付きで設計に基づく推定値を報告します。

NCHS または CDC との提携や、これらの組織による推奨は受けていません。 データは National Center for Health Statistics が公開し、cdc.gov から直接ダウンロードした NHANES のパブリックユースファイルです。 ユーザーは、NCHS data use agreement を遵守する責任を負います。

このサーバーが対応すること

落とし穴	サーバーの対応
重みが誤っている／設定されていない	build_dataset は最も制約の厳しい重み（インタビュー → MEC → 空腹時／採血／余剰血清サブサンプル → 食事の1日目／2日目）を選び、その理由を説明して WT_ANALYSIS に保存します。上書き（build_dataset(weight=...)、set_weight）はすべての結果に表示されます。WT_ANALYSIS が暗黙に上書きされることはありません
推定前のサブセット化	domain= 式は調査設計全体を維持します（ドメイン外の重みはゼロ）
サイクルのプーリング	重みはサイクルの年数／合計年数で再スケーリングされます（2017–March 2020 は 3.2 年として計算）。1999–2002 には4年分の重みを使用し、層はサイクルごとに一意になるようにします。2017–2018 と 2017–2020 の重複は拒否します
ロング形式のテーブル（例：処方薬）	SEQN が重複するテーブルの結合は拒否します（重みが暗黙に重複するのを防ぐため）。flag_from_long_table はこれらのテーブルを1人につき1行に集約します
回答拒否／わからないコード	describe_variable は CDC のコードブックを読み取り、センチネルコードを提案します。set_missing でこれらを再コード化します
欠損値が黙って 0 になる	derive_variable は欠損値を伝播します（any／all／none）。coalesce、fillna、isna、notna、where を使って欠損値を明示的に処理できます
不規則なファイル名	既知のバリエーションを試します（例：1999–2000 年の余剰血清ファイル SSCMV_A、SSMUMP_A）
分散	テイラー線形化、層 × PSU、設計自由度を使用します。比率には Korn–Graubard 信頼区間と NCHS 2017 信頼性フラグを適用します
年齢調整	2000年の米国標準（20–39／40–59／60+）への直接調整を線形化 SE とともに行うか、呼び出し元が指定した任意の標準（年齢グループ＋母集団）に調整します。ドメイン内にグループ外の記録がある場合は警告します
死亡率	オプションでパブリックユースの Linked Mortality File（2019年まで追跡）を結合し、設計に基づく Cox モデルを使用します

ツール（17）

ステップ	ツール
概要を把握	list_cycles、analysis_guidance
探す	list_files、search_variables、describe_variable
構築	build_dataset（死亡率の結合はオプション）、describe_dataset
クリーニング／導出	set_missing、derive_variable、flag_from_long_table、set_weight
分析	survey_frequency、survey_estimate、survey_regression（線形／ロジスティック）、survey_cox（Cox PH、Binder 分散）
表示	show_results — テキスト＋構造化された結果。オプションの Results Explorer アドオンでインタラクティブに表示できます
エクスポート	export_dataset

サイクル：1999–2000 から 2017–2018 まで、2017–March 2020（パンデミック前、P_ ファイル）、および August 2021–August 2023。

結果エクスプローラー（オプションのアドオン）

show_results は、すべてのクライアントで設計ベースの結果をテキストと構造化データの両方で返します。オプションの NHANES Results Explorer アドオンがインストールされている場合、MCP Apps ホスト（Claude Desktop/web、ChatGPT、VS Code、Goose）では、CI と NCHS の信頼性バッジ付きの主要推定値、サーバー上で推定を再実行する粗推定／年齢調整済みの切り替え、分析計画、サブグループパネル、サーバーの警告、公表済み推定値とのベンチマーク、設計の来歴を含むインタラクティブなビューも表示されます。

このアドオンは、Black Swan Causal Labs が PolyForm Noncommercial License 1.0.0 のもとで提供する別パッケージです（学術、公衆衛生、その他の非営利目的での利用は無料です。商用利用にはライセンスが必要です — https://blackswancausallabs.com）。この MIT リポジトリには含まれていません。nhanes-mcp は、同じ Python 環境にインストールされている場合、NHANES_MCP_EXPLORER_PATH がアドオンを指している場合、または nhanes-mcp フォルダーの隣に nhanes-mcp-explorer という名前のフォルダーがある場合に、アドオンを検出します。

検証

推定値は、公表済みの NCHS の結果（validation/）と照合しました。

• 有病率： 公表済みの NCHS 推定値 57 件中 57 件を再現しました（Data Briefs 360、363、508、515、2015～2018 年のプールデータ、パンデミック前の 2017～2020 年 3 月）。
• 標準誤差： 20 件中 20 件が一致しました。公表済みの 95% CI の境界値 12 件中 11 件が完全に一致しました（残る 1 件は丸め境界で 0.1 異なります）。
• 死亡率： NHANES 1999～2006（25 歳以上の成人）の設計ベースの Cox モデルは、公表済みのハザード比 7 件中 6 件を各信頼区間内で再現します（NHSR 155）。メキシコ系アメリカ人の対比は再現できていません（0.71 対 公表値 1.12）。現在調査中です。ここでリンクされているファイルの追跡期間はより長くなっています（2019 年対 2015 年）。
• 高血圧（NCHS Data Brief 511、2021～2023 年、18 歳以上の成人）：有病率（粗推定および年齢調整済み、性別および年齢別）、認知、治療、コントロールについて、公表済み推定値 17 件中 17 件を完全に再現しました。
• CMV 血清有病率（Bate et al., Clin Infect Dis 2010、NHANES 1999～2004、余剰血清ウェイト）：tests/benchmark_nchs.py を参照してください。v0.4 より前のバージョンでは、サーバーがここで MEC ウェイトを黙って使用しており、1999～2000 年のファイルを読み込めませんでした。
• ユニットテスト（tests/）：分散を独立したループ実装および 1 PSU 削除ジャックナイフと照合し、Cox モデルを statsmodels PHReg およびジャックナイフと照合しました。また、ウェイトの選択、プーリング、ガード、式のセマンティクス、ロングテーブル、食事ウェイトの処理も検証しました。

インストール

最も簡単な方法：AI アシスタントにインストールを任せる

以下を Claude（Cowork または Claude Code）、またはコンピューターでコマンドを実行できるエージェントに貼り付けてください。

Claude Desktop 用の nhanes-mcp MCP サーバー（PyPI パッケージ nhanes-mcp）をインストールしてください。uv がなければインストールしてから、uvx のフルパスを使用して、このエントリを Claude Desktop の設定（claude_desktop_config.json）に追加してください："nhanes": {"command": "uvx", "args": ["nhanes-mcp"]}。 既存のサーバーはそのまま残してください。その後、Claude Desktop を再起動するように案内してください。

設定ファイルに 1 行追加（uvx）

uv をインストールしたうえで、claude_desktop_config.json に追加し、Claude Desktop を再起動してください（macOS では、which uvx で表示されるフルパスを使用します。例：/Users/<you>/.local/bin/uvx）。

"nhanes": {
  "command": "uvx",
  "args": ["nhanes-mcp"]
}

初回起動時に uvx が PyPI からサーバーを取得し、分離された環境にインストールします。リポジトリのクローンや仮想環境の管理は不要です。代わりに GitHub の最新コードを実行するには、"args": ["--from", "git+https://github.com/Black-Swan-Causal-Labs/nhanes-mcp", "nhanes-mcp"] を使用してください。

ソースからインストール（開発用）

python3 -m venv ~/.nhanes-mcp-venv
~/.nhanes-mcp-venv/bin/pip install "mcp>=1.2,<2" pandas numpy scipy pyreadstat httpx beautifulsoup4 lxml
git clone https://github.com/Black-Swan-Causal-Labs/nhanes-mcp.git ~/nhanes-mcp

"nhanes": {
  "command": "/Users/<you>/.nhanes-mcp-venv/bin/python",
  "args": ["-m", "nhanes_mcp"],
  "env": {"PYTHONPATH": "/Users/<you>/nhanes-mcp"}
}

ローカルの stdio サーバーを実行できる MCP クライアントであれば、同じ方法で使用できます。データは初回使用時に cdc.gov からダウンロードされ、~/.cache/nhanes-mcp にキャッシュされます（NHANES_MCP_CACHE で変更できます）。 オフラインで作業するには、手動でダウンロードした .xpt ファイルのフォルダーを NHANES_MCP_DATA_DIR に設定してください。

チームでのセットアップや、別の調査・データセットへの適応についてサポートが必要ですか？ Black Swan Causal Labs までお問い合わせください。

テスト

python tests/test_offline.py            # synthetic NHANES-shaped data, no network
python tests/test_cox.py
python tests/test_long_and_dietary.py
python tests/benchmark_nchs.py          # reproduces published NCHS estimates (needs network)

既知の未解決問題

• 2009～2010年以前の年齢調整済み成人肥満率は、NCHS Health E-Stat 111より0.1～0.7ポイント低くなっています （2011～2012年以降は完全に一致します）。プーリングと妊娠コードの処理は原因から除外されており、現在調査中です。
• CMV分析では、公開サープラス血清ファイルで検査を受けた6～49歳の参加者が14,198人と算出されますが、Bateらの報告では15,310人です。原因は不明です。
• NHANES III（1988～1994年）には対応していません。

変更履歴

• 0.5.1 — PyPI（uvx nhanes-mcp）および公式 MCP Registry（com.blackswancausallabs/nhanes-mcp）で初リリース。 パッケージのメタデータのみの変更で、分析内容に変更はありません。
• 0.5.0 — show_results ツール（テキストと構造化結果。オプションのResults Explorerアドオンでインタラクティブ表示が可能）、uvx によるワンコマンドインストール、分析ガイダンスルール11。
• 0.4.1 — 欠損値対応関数内の比較では、オペランドが欠損している場合に欠損値を返すようになりました。そのため、where(BPQ020 == 1, fillna(BPQ150, 2) == 1, 0) のようなスキップパターンの定義では、スクリーナーの質問を受けたことがない人の値は0ではなく欠損値になります。高血圧のベンチマーク（NCHS Data Brief 511）を追加しました。
• 0.4.0 — サープラス血清など、ファイル固有のサブサンプルウェイト（2Y／4Y サフィックス付き）を検出してプールするようになりました。1999～2000年の _A ファイル名を解決しました。build_dataset(weight=...) と新しい set_weight ツールを追加し、どちらもすべての結果に記録されます。設計列を derive_variable から保護しました。欠損値対応の式関数、カスタム年齢標準、CMVベンチマークを追加しました。
• 0.3.0 — 初回公開リリース。

制限事項

• 公開利用可能なファイルのみが対象です。制限付きデータ（NHANES–CMS Medicare/Medicaidリンケージを含む）には、NCHS Research Data Centerへのアクセスが必要です。
• 分散は、NCHSの推奨に従い、PSUを復元抽出されたものとして扱うテイラー線形化法で計算します。反復ウェイトは使用しません。
• サーバーはデータが裏付ける内容を報告します。研究デザインを選択するものではありません。