batch-cohort

批量队列分析技能

从单个经过验证的方法学模板，为每个暴露/结局组合生成一个分析脚本；脚本之间仅变量不同。

输入

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]
   • 包含以下列的 CSV 文件：exposure、outcome、（可选）subgroup_vars
   • "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. 在批量生成前，验证模板至少能针对一个组合成功运行。
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 或 HbA1c≥6.5 或医生诊断（KNHANES：DE1_dg=1，NHANES：DIQ010="Yes"）；高血压 = SBP≥140 或 DBP≥90 或医生诊断（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. 生成主运行脚本（run_all.R 或 run_all.sh），按顺序（或通过 future/parallel 并行）执行全部 N 个脚本；逐个捕获错误，不因错误而停止批处理，并记录每项分析的执行时间。
6. 生成代码质量关卡：一次可复现性疏漏（缺少种子、使用绝对路径或手动输入数据字面值）会在整个批次中反复出现，因此请使用 /analyze-stats 代码质量关卡检查生成的脚本 （python3 ${CLAUDE_SKILL_DIR}/../analyze-stats/scripts/check_generated_code.py --code-dir {batch_dir} --strict），并在批处理执行前清除所有 Major（MISSING_SEED、HARDCODED_DATA_LITERAL、HARDCODED_ABS_PATH、INPLACE_SOURCE_OVERWRITE）。

阶段 4：批量执行（如果处于 execute 或 full 模式）

1. 事件数检查：运行前，确认每个模型参数至少有 10 个结局事件（计算暴露变量以及每个虚拟变量/样条项；使用 min(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 的双调查设计方法
• 汇总矩阵并排展示两个国家，并包含 OR 比值列（95% CI；P）；按 /cross-national 阶段 4 的方法计算，而不是使用方向一致性勾选项