/batch-cohort

name: batch-cohort
description: Use when one validated cohort analysis must be repeated across many exposure/outcome pairs. Generates one R/Python script per combination from a single methodology template, changing only the variables, and aggregates the results into a summary matrix.
model: opus
metadata:
  triggers: "batch cohort, batch analysis, 대량 분석, 변수 교체, variable swap, mass production, 80명 팀, batch generate, 일괄 코드 생성, exposure outcome matrix, combinatorial analysis"

Batch Cohort Analysis Skill

Generate one analysis script per exposure/outcome combination from a single validated methodology template; only the variables change between scripts.

Inputs

1. **Database path(s)**: CSV/SAS data files (KNHANES, NHANES, NHIS, or any cleaned cohort) 2. **Methodology template**: One of:

• Path to a validated R/Python analysis script (from /replicate-study or /cross-national)
• A paper type template name: `nhis_cohort`, `cross_national`, `survey_weighted`
• A source paper to extract methodology from (falls back to /replicate-study Phase 1)

3. **Combination spec**: A list of exposure/outcome pairs, provided as:

• Inline list: `exposures: [depression, obesity, smoking]; outcomes: [diabetes, hypertension, CVD]`
• CSV file with columns: `exposure`, `outcome`, (optional) `subgroup_vars`
• `"all"` keyword: generates all pairwise combinations from the lists

Optional Inputs

• **Covariate set**: Fixed covariate list for all analyses (default: use template's set)
• **Subgroup variables**: Variables to stratify by (default: sex, age group)
• **Output format**: `code_only` (just scripts) | `execute` (run + collect results) | `full` (code + results + summary)
• **Cross-national mode**: `cross_national: true` generates paired scripts for both countries per combination (see Cross-National Batch Mode)

Example:

/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

Workflow

Phase 1: Template Validation

1. Read the methodology template (R script or paper type reference). 2. Identify the **slot variables** — parts that change per combination: `EXPOSURE_VAR` (raw variable name in the database), `EXPOSURE_LABEL` (label for tables/figures), `EXPOSURE_CODING` (derivation of the binary/categorical exposure), and `OUTCOME_VAR`, `OUTCOME_LABEL`, `OUTCOME_CODING` likewise. 3. Confirm the survey design: weighted analysis is mandatory for KNHANES/NHANES and is inherited from the template; NHIS and other claims databases have no sampling weights (standard regression). 4. Verify the template runs successfully on at least one combination before batch generation. 5. Output: template summary with identified slots → user approval.

Phase 2: Variable Specification

For each exposure and outcome in the combination spec:

1. **Look up** the variable in the database: KNHANES — the name exists in the CSV header; NHANES — which table contains it (codebook.csv if available); NHIS — claims code or variable name. For ICD-10 claims algorithms read `${CLAUDE_SKILL_DIR}/../analyze-stats/references/analysis_guides/nhis_icd10_mapping.md`; for survey variable coding, `survey_weighted.md` in the same folder. If a mapping is uncertain, write `[VERIFY: variable_name]` and ask the user to confirm it against the data dictionary; never guess a variable name, column name or coding. 2. **Define coding**: binary as a threshold or category mapping (e.g., `HE_glu >= 126 → diabetes = 1`); categorical as level definitions (e.g., `smoking: current/former/never`). Outcome definitions MUST include physician diagnosis, because lab-only definitions systematically overestimate exposure→outcome associations: Diabetes = FPG≥126 OR HbA1c≥6.5 OR physician-diagnosed (KNHANES: DE1_dg=1, NHANES: DIQ010="Yes"); Hypertension = SBP≥140 OR DBP≥90 OR physician-diagnosed (KNHANES: DI1_dg=1, NHANES: BPQ020="Yes"). 3. **Set covariates**: the full 8-covariate set (age, sex, education, income, smoking, alcohol, obesity, CVD) is the default unless explicitly justified — minimal models (age+sex+BMI only) leave residual confounding, which can bias effects in either direction. Remove self-adjustment: if the exposure is (or derives from) a covariate, drop that covariate (exposure = BMI → drop obesity; exposure = education/income → drop the same variable); if outcome = MetS, consider dropping obesity. Document every removal in the matrix Notes. 4. Output: **combination matrix** (`combination_matrix.csv`) with all variable specifications.

| # | 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 |

Phase 3: Batch Code Generation

Never modify the core methodology across combinations — only swap exposure/outcome/covariates. For each combination in the matrix:

1. **Clone** the template script. 2. **Replace** slot variables with the combination-specific values. 3. **Apply** the combination's adjusted covariate set from the matrix. 4. **Set output paths**: each combination gets its own results subdirectory. 5. **Generate a master runner script** (`run_all.R` or `run_all.sh`) that executes all N scripts sequentially (or in parallel via `future`/`parallel`), captures errors per script without stopping the batch, and logs execution time per analysis. 6. **Generated-code quality gate**: one reproducibility slip (a missing seed, an absolute path, a hand-typed data literal) r