batch-cohort

バッチコホート分析スキル

検証済みの単一の方法論テンプレートから、曝露とアウトカムの組み合わせごとに分析スクリプトを1つずつ生成します。スクリプト間で変更するのは変数のみです。

入力

1. データベースのパス：CSV/SAS データファイル（KNHANES、NHANES、NHIS、または任意のクリーンアップ済みコホート）
2. 方法論テンプレート：次のいずれか
   • 検証済みの R/Python 分析スクリプトへのパス（/replicate-study または /cross-national から）
   • 論文タイプのテンプレート名：nhis_cohort、cross_national、survey_weighted
   • 方法論を抽出する元論文（/replicate-study Phase 1 にフォールバックします）
3. 組み合わせの指定：曝露とアウトカムのペアのリスト。次の形式で指定します。
   • インラインリスト：exposures: [depression, obesity, smoking]; outcomes: [diabetes, hypertension, CVD]
   • 列が exposure、outcome、（任意で）subgroup_vars の CSV ファイル
   • "all" キーワード：リストからすべてのペアの組み合わせを生成します

任意の入力

• 共変量セット：すべての分析で共通して使用する共変量のリスト（デフォルトではテンプレートのセットを使用）
• サブグループ変数：層別化に使用する変数（デフォルトでは性別、年齢群）
• 出力形式：code_only（スクリプトのみ）｜execute（実行して結果を収集）｜full（コード＋結果＋要約）
• クロスナショナルモード：cross_national: true を指定すると、組み合わせごとに両国のスクリプトをペアで生成します（クロスナショナルバッチモードを参照）

例：

/batch-cohort

DB Korea: /path/to/knhanes/HN18.csv
DB US: /path/to/nhanes/
Template: cross_national
Exposures: [depression, obesity, smoking]
Outcomes: [diabetes, hypertension, metabolic_syndrome]
cross_national: true
Mode: execute

ワークフロー

フェーズ 1：テンプレートの検証

1. 方法論テンプレート（R スクリプトまたは論文タイプの参照資料）を読み込みます。
2. スロット変数、つまり組み合わせごとに変わる部分を特定します。EXPOSURE_VAR（データベース内の生の変数名）、EXPOSURE_LABEL（表・図用のラベル）、EXPOSURE_CODING（二値／カテゴリ別の曝露の導出）、および同様の OUTCOME_VAR、OUTCOME_LABEL、OUTCOME_CODING です。
3. 調査デザインを確認します。KNHANES/NHANES では加重分析が必須で、テンプレートから引き継がれます。NHIS やその他の請求データベースにはサンプリングウェイトがないため、標準的な回帰分析を行います。
4. バッチ生成の前に、少なくとも1つの組み合わせでテンプレートが正常に実行されることを確認します。
5. 出力：特定したスロットを含むテンプレートの概要 → ユーザーの承認。

フェーズ 2：変数の仕様

組み合わせ仕様の各曝露変数とアウトカムについて、次の手順を実行します。

1. 調べる：データベース内の変数を確認します。KNHANES の場合は CSV ヘッダーにその名前が存在するかを確認します。NHANES の場合は、その変数が含まれるテーブルを確認します（利用可能であれば codebook.csv を参照）。NHIS の場合は、請求コードまたは変数名を確認します。ICD-10 の請求アルゴリズムについては ${CLAUDE_SKILL_DIR}/../analyze-stats/references/analysis_guides/nhis_icd10_mapping.md を読みます。調査変数のコーディングについては、同じフォルダーにある survey_weighted.md を読みます。対応付けが不確かな場合は [VERIFY: variable_name] と記載し、データ辞書に照らして確認するようユーザーに依頼します。変数名、列名、コーディングを推測してはいけません。
2. コーディングを定義する：二値変数は閾値またはカテゴリの対応付けで定義します（例：HE_glu >= 126 → diabetes = 1）。カテゴリ変数は各水準の定義を記載します（例：smoking: current/former/never）。アウトカムの定義には、必ず医師による診断を含めます。検査値のみの定義では、曝露→アウトカムの関連が一貫して過大評価されるためです。糖尿病 = FPG≥126 OR HbA1c≥6.5 OR 医師による診断（KNHANES：DE1_dg=1、NHANES：DIQ010="Yes"）。高血圧 = SBP≥140 OR DBP≥90 OR 医師による診断（KNHANES：DI1_dg=1、NHANES：BPQ020="Yes"）。
3. 共変量を設定する：特に根拠を示して調整しない限り、8 つの共変量（年齢、性別、教育、所得、喫煙、飲酒、肥満、CVD）の全セットをデフォルトとします。最小限のモデル（年齢＋性別＋BMI のみ）では交絡が残り、効果がどちらの方向にも偏る可能性があります。自己調整を除きます。曝露変数が共変量そのものである、または共変量から導出される場合、その共変量を除外します（曝露変数 = BMI → 肥満を除外、曝露変数 = 教育／所得 → 同じ変数を除外）。アウトカム = MetS の場合は、肥満の除外を検討します。除外した項目はすべてマトリックスの Notes に記録します。
4. 出力：すべての変数仕様を含む組み合わせマトリックス（combination_matrix.csv）。

| # | Exposure | Exposure Coding | Outcome | Outcome Coding | Covariates (adjusted) | Notes |
|---|----------|-----------------|---------|----------------|----------------------|-------|
| 1 | Depression (PHQ≥10) | BP_PHQ sum ≥10 | Diabetes | HE_glu≥126|HbA1c≥6.5|DE1_dg=1 | age,sex,edu,income,smoking,alcohol,obesity,CVD | — |
| 2 | Obesity (BMI≥25) | HE_obe ≥4 | Diabetes | same | age,sex,edu,income,smoking,alcohol,depression,CVD | obesity removed from covariates |

フェーズ 3：バッチコード生成

組み合わせ間でコア手法を変更してはいけません。曝露変数／アウトカム／共変量のみを差し替えます。 マトリックス内の各組み合わせについて、次の手順を実行します。

1. テンプレートスクリプトを複製します。
2. スロット変数を組み合わせ固有の値に置き換えます。
3. マトリックスに記載された組み合わせの調整済み共変量セットを適用します。
4. 出力パスを設定します。各組み合わせに固有の結果サブディレクトリを用意します。
5. すべての N 個のスクリプトを順次（または future／parallel を使って並列に）実行し、バッチを停止させずにスクリプトごとのエラーを記録し、分析ごとの実行時間をログに記録するマスタースクリプト（run_all.R または run_all.sh）を生成します。
6. 生成コードの品質ゲート：再現性に関する不備（シードの欠落、絶対パス、手入力されたデータリテラル）が 1 つでもあると、バッチ全体にわたって複製されます。そのため、生成されたスクリプトを /analyze-stats のコード品質ゲートで lint し、バッチ実行前にすべての Major（MISSING_SEED、HARDCODED_DATA_LITERAL、HARDCODED_ABS_PATH、INPLACE_SOURCE_OVERWRITE）を解消します（python3 ${CLAUDE_SKILL_DIR}/../analyze-stats/scripts/check_generated_code.py --code-dir {batch_dir} --strict）。

フェーズ 4：バッチ実行（execute または full モードの場合）

1. イベント数を確認：実行前に、モデルパラメーター 1 つあたりのアウトカムイベント数が 10 件以上あることを確認します（曝露変数とすべてのダミー項／スプライン項を数え、events と non-events のうち少ない方を使用）。全サンプルと、モデル化する各サブグループで確認します。検出力が不十分な組み合わせにはフラグを付けます。
2. マスタースクリプトを実行します。
3. 各組み合わせの出力ディレクトリから結果を収集します。
4. 失敗した組み合わせとその理由（よくあるもの：収束の問題、イベント数不足、空のサブグループ）を failed_runs.csv に記録し、修正案を提示します。

フェーズ 5：サマリーマトリクス

すべての結果を単一のサマリーに集約します。すべての数値は、組み合わせの実行結果ファイルから取得します。セルに手作業で値を入力してはいけません。

メイン結果マトリクス（summary_matrix.csv）：

曝露	結果	N	イベント	モデル 1 OR（95% CI）	モデル 2 OR（95% CI）	モデル 3 OR（95% CI）	p 値	有意

サブグループサマリー（subgroup_matrix.csv）：同じ形式で、サブグループ変数ごとに層別化します。

ヒートマップ（任意）：効果量 × 有意性の視覚的なマトリクスです。Y 軸に曝露、X 軸に結果を配置します。

• 多重比較：複数の組み合わせを検定する場合は、サマリーマトリクスに Bonferroni（または Holm）補正済みの有意性列を含めます。m は報告するファミリー内の検定数（組み合わせ × モデル × サブグループ）とし、m を明記するとともに、探索的か確認的かの位置づけに関する注記を追加します。
• p ハッキングと誤解されない表現：サマリーマトリクスは確認のためではなく、仮説生成のためのものです。この点を README およびすべての原稿出力で明記します。引用を含める場合は、/search-lit で確認済みの DOI/PMID を使用します。確認できていない場合は [UNVERIFIED - NEEDS MANUAL CHECK] と記載します。

出力ファイル

{working_dir}/batch_{timestamp}/
├── README.md                    — Batch run summary (N combinations, template used, date)
├── combination_matrix.csv       — All exposure/outcome specs with coding
├── template/
│   └── base_template.R          — The validated template (frozen copy)
├── scripts/
│   ├── 01_depression_diabetes.R
│   ├── 02_obesity_diabetes.R
│   ├── ...
│   └── run_all.R                — Master execution script
├── results/
│   ├── 01_depression_diabetes/
│   │   ├── table1.csv
│   │   ├── main_results.csv
│   │   └── subgroup_results.csv
│   └── ...
├── summary/
│   ├── summary_matrix.csv       — Main results across all combinations
│   ├── subgroup_matrix.csv      — Subgroup results across all combinations
│   ├── failed_runs.csv          — Combinations that failed + error messages
│   └── heatmap.png              — Optional effect size × significance visual
└── logs/
    └── batch_execution.log      — Timing + error log

再現性：テンプレートのバージョン（template/）を固定し、README にデータファイルの SHA256 ハッシュを記載します。

国別バッチモード

cross_national: true の場合：

• /cross-national の二重調査設計のアプローチを使用して、組み合わせごとにペアのスクリプト（韓国 + 米国）を生成します
• サマリーマトリクスには両国の結果を並べて含め、/cross-national のフェーズ 4 に沿って算出した OR 比（95% CI；P）の列を追加します。方向一致のチェックマークは使用しません