Batch Cohort

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 |