medsci-skills 4.1.0

package/skills/batch-cohort/references/batch_template_generator.R

@@ -0,0 +1,222 @@
+#!/usr/bin/env Rscript
+# ==============================================================================
+# Batch Cohort Analysis Generator
+# Generates N analysis scripts from a base template × variable combinations
+#
+# Usage:
+#   Rscript batch_template_generator.R \
+#     --template base_template.R \
+#     --combinations combinations.csv \
+#     --outdir batch_20260417/ \
+#     --mode code_only|execute|full
+#
+# Combinations CSV columns:
+#   id, exposure_var, exposure_label, exposure_coding,
+#   outcome_var, outcome_label, outcome_coding,
+#   covariates_remove (comma-separated vars to drop from default set)
+# ==============================================================================
+
+suppressPackageStartupMessages({
+  library(optparse)
+  library(glue)
+})
+
+# --- CLI Arguments ---
+option_list <- list(
+  make_option("--template", type = "character", help = "Path to base R template"),
+  make_option("--combinations", type = "character", help = "CSV with variable combinations"),
+  make_option("--outdir", type = "character", default = "batch_output", help = "Output directory"),
+  make_option("--mode", type = "character", default = "code_only",
+              help = "code_only | execute | full"),
+  make_option("--parallel", type = "integer", default = 1, help = "Number of parallel workers")
+)
+opt <- parse_args(OptionParser(option_list = option_list))
+
+# --- Read Inputs ---
+template_code <- readLines(opt$template)
+combos <- read.csv(opt$combinations, stringsAsFactors = FALSE)
+cat(glue("Loaded {nrow(combos)} combinations from {opt$combinations}\n\n"))
+
+# --- Create Output Structure ---
+dir.create(file.path(opt$outdir, "scripts"), recursive = TRUE, showWarnings = FALSE)
+dir.create(file.path(opt$outdir, "template"), showWarnings = FALSE)
+dir.create(file.path(opt$outdir, "logs"), showWarnings = FALSE)
+
+# Freeze template
+writeLines(template_code, file.path(opt$outdir, "template", "base_template.R"))
+
+# --- Generate Scripts ---
+script_paths <- character(nrow(combos))
+
+for (i in seq_len(nrow(combos))) {
+  combo <- combos[i, ]
+  script_name <- sprintf("%02d_%s_%s.R", i, combo$exposure_var, combo$outcome_var)
+  script_path <- file.path(opt$outdir, "scripts", script_name)
+
+  # Results directory for this combination
+  results_dir <- file.path(opt$outdir, "results",
+                           sprintf("%02d_%s_%s", i, combo$exposure_var, combo$outcome_var))
+  dir.create(results_dir, recursive = TRUE, showWarnings = FALSE)
+
+  # Replace slot variables in template
+  code <- template_code
+  code <- gsub("\\{\\{EXPOSURE_VAR\\}\\}", combo$exposure_var, code)
+  code <- gsub("\\{\\{EXPOSURE_LABEL\\}\\}", combo$exposure_label, code)
+  code <- gsub("\\{\\{EXPOSURE_CODING\\}\\}", combo$exposure_coding, code)
+  code <- gsub("\\{\\{OUTCOME_VAR\\}\\}", combo$outcome_var, code)
+  code <- gsub("\\{\\{OUTCOME_LABEL\\}\\}", combo$outcome_label, code)
+  code <- gsub("\\{\\{OUTCOME_CODING\\}\\}", combo$outcome_coding, code)
+  code <- gsub("\\{\\{RESULTS_DIR\\}\\}", results_dir, code)
+  code <- gsub("\\{\\{COMBO_ID\\}\\}", sprintf("%02d", i), code)
+
+  # Handle covariate removal (self-adjustment prevention)
+  if (!is.na(combo$covariates_remove) && nchar(combo$covariates_remove) > 0) {
+    remove_vars <- trimws(strsplit(combo$covariates_remove, ",")[[1]])
+    remove_str <- paste0('"', remove_vars, '"', collapse = ", ")
+    code <- gsub("\\{\\{COVARIATES_REMOVE\\}\\}", remove_str, code)
+  } else {
+    code <- gsub("\\{\\{COVARIATES_REMOVE\\}\\}", "", code)
+  }
+
+  writeLines(code, script_path)
+  script_paths[i] <- script_path
+  cat(glue("  Generated: {script_name}\n"))
+}
+
+# --- Generate Master Runner ---
+runner_path <- file.path(opt$outdir, "scripts", "run_all.R")
+runner_code <- c(
+  "#!/usr/bin/env Rscript",
+  "# Master runner — executes all batch scripts sequentially",
+  "# Auto-generated by batch_template_generator.R",
+  "",
+  'cat("=== Batch Cohort Analysis ===\\n")',
+  glue('cat("Combinations: {nrow(combos)}\\n")'),
+  glue('cat("Started: ", format(Sys.time(), "%Y-%m-%d %H:%M:%S"), "\\n\\n")'),
+  "",
+  "results_log <- data.frame(",
+  "  id = character(), exposure = character(), outcome = character(),",
+  "  status = character(), time_sec = numeric(), error_msg = character(),",
+  "  stringsAsFactors = FALSE",
+  ")",
+  "",
+  "scripts <- c(",
+  paste0('  "', script_paths, '"', collapse = ",\n"),
+  ")",
+  "",
+  "for (i in seq_along(scripts)) {",
+  "  cat(sprintf('\\n--- Running %d/%d: %s ---\\n', i, length(scripts), basename(scripts[i])))",
+  "  t0 <- proc.time()['elapsed']",
+  "  status <- tryCatch({",
+  "    source(scripts[i], local = new.env())",
+  '    "SUCCESS"',
+  "  }, error = function(e) {",
+  '    paste0("FAILED: ", conditionMessage(e))',
+  "  })",
+  "  elapsed <- round(proc.time()['elapsed'] - t0, 1)",
+  "  is_ok <- startsWith(status, 'SUCCESS')",
+  "  results_log <- rbind(results_log, data.frame(",
+  paste0("    id = sprintf('%02d', i),"),
+  "    exposure = basename(scripts[i]),",
+  "    outcome = '',",
+  '    status = ifelse(is_ok, "SUCCESS", "FAILED"),',
+  "    time_sec = elapsed,",
+  '    error_msg = ifelse(is_ok, "", status),',
+  "    stringsAsFactors = FALSE",
+  "  ))",
+  "  cat(sprintf('  %s (%.1fs)\\n', status, elapsed))",
+  "}",
+  "",
+  "# Save execution log",
+  glue('write.csv(results_log, "{file.path(opt$outdir, "logs", "batch_execution.csv")}", row.names = FALSE)'),
+  "",
+  'cat("\\n=== Batch Complete ===\\n")',
+  'cat(sprintf("Success: %d / %d\\n", sum(results_log$status == "SUCCESS"), nrow(results_log)))',
+  'cat(sprintf("Failed:  %d / %d\\n", sum(results_log$status == "FAILED"), nrow(results_log)))'
+)
+writeLines(runner_code, runner_path)
+cat(glue("\nMaster runner: {runner_path}\n"))
+
+# --- Generate Summary Aggregator ---
+aggregator_path <- file.path(opt$outdir, "scripts", "aggregate_results.R")
+aggregator_code <- c(
+  "#!/usr/bin/env Rscript",
+  "# Aggregate results from all batch runs into summary matrix",
+  "",
+  glue('results_base <- "{file.path(opt$outdir, "results")}"'),
+  "dirs <- list.dirs(results_base, recursive = FALSE)",
+  "",
+  "all_main <- list()",
+  "all_subgroup <- list()",
+  "",
+  "for (d in dirs) {",
+  '  main_file <- file.path(d, "main_results.csv")',
+  "  if (file.exists(main_file)) {",
+  "    df <- read.csv(main_file, stringsAsFactors = FALSE)",
+  "    df$combo_id <- basename(d)",
+  "    all_main[[length(all_main) + 1]] <- df",
+  "  }",
+  '  sub_file <- file.path(d, "subgroup_results.csv")',
+  "  if (file.exists(sub_file)) {",
+  "    df <- read.csv(sub_file, stringsAsFactors = FALSE)",
+  "    df$combo_id <- basename(d)",
+  "    all_subgroup[[length(all_subgroup) + 1]] <- df",
+  "  }",
+  "}",
+  "",
+  "if (length(all_main) > 0) {",
+  "  summary_matrix <- do.call(rbind, all_main)",
+  glue('  write.csv(summary_matrix, "{file.path(opt$outdir, "summary", "summary_matrix.csv")}", row.names = FALSE)'),
+  '  cat(sprintf("Summary matrix: %d rows from %d combinations\\n", nrow(summary_matrix), length(all_main)))',
+  "}",
+  "",
+  "if (length(all_subgroup) > 0) {",
+  "  subgroup_matrix <- do.call(rbind, all_subgroup)",
+  glue('  write.csv(subgroup_matrix, "{file.path(opt$outdir, "summary", "subgroup_matrix.csv")}", row.names = FALSE)'),
+  '  cat(sprintf("Subgroup matrix: %d rows\\n", nrow(subgroup_matrix)))',
+  "}"
+)
+dir.create(file.path(opt$outdir, "summary"), showWarnings = FALSE)
+writeLines(aggregator_code, aggregator_path)
+cat(glue("Aggregator: {aggregator_path}\n"))
+
+# --- Execute if requested ---
+if (opt$mode %in% c("execute", "full")) {
+  cat("\n=== Executing batch ===\n")
+  source(runner_path)
+
+  cat("\n=== Aggregating results ===\n")
+  source(aggregator_path)
+}
+
+# --- Generate README ---
+readme_path <- file.path(opt$outdir, "README.md")
+readme <- c(
+  glue("# Batch Cohort Analysis — {Sys.Date()}"),
+  "",
+  glue("- **Template**: `{opt$template}`"),
+  glue("- **Combinations**: {nrow(combos)}"),
+  glue("- **Mode**: {opt$mode}"),
+  "",
+  "## Combination Matrix",
+  "",
+  "| # | Exposure | Outcome | Covariates Removed |",
+  "|---|----------|---------|-------------------|",
+  apply(combos, 1, function(row) {
+    sprintf("| %s | %s | %s | %s |",
+            row["id"], row["exposure_label"], row["outcome_label"],
+            ifelse(is.na(row["covariates_remove"]), "—", row["covariates_remove"]))
+  }),
+  "",
+  "## Notes",
+  "",
+  "- This is an **exploratory** analysis for hypothesis generation, not confirmation.",
+  "- Multiple comparisons: interpret p-values with caution (Bonferroni threshold shown in summary).",
+  "- Survey weights applied to all analyses.",
+  glue("- Data file SHA256: [compute with `shasum -a 256 <datafile>`]"),
+  ""
+)
+writeLines(readme, readme_path)
+
+cat(glue("\n✅ Batch generation complete: {opt$outdir}/\n"))
+cat(glue("   {nrow(combos)} scripts generated\n"))

package/skills/batch-cohort/references/variable_coding_registry.md

@@ -0,0 +1,136 @@
+# Variable Coding Registry
+
+Pre-validated variable definitions for batch code generation.
+Each entry provides raw variable names, coding logic, and human-readable labels
+for KNHANES and NHANES. Add new variables as they are validated in replication studies.
+
+## Exposures
+
+### Depression (PHQ-9 ≥ 10)
+
+| Field | KNHANES | NHANES |
+|-------|---------|--------|
+| Raw vars | BP_PHQ_1 ~ BP_PHQ_9 | DPQ010 ~ DPQ090 |
+| Coding | sum(BP_PHQ_1:9), NA if any missing | recode text→0-3, sum, NA if any missing |
+| Binary | phq_score ≥ 10 → 1 | phq_score ≥ 10 → 1 |
+| Label | Depression (PHQ-9 ≥ 10) | Depression (PHQ-9 ≥ 10) |
+| Notes | Items are numeric 0-3 | Items are TEXT: "Not at all"→0, "Several days"→1, "More than half the days"→2, "Nearly every day"→3 |
+
+### Obesity
+
+| Field | KNHANES | NHANES |
+|-------|---------|--------|
+| Raw vars | HE_obe (or BMXBMI) | BMXBMI (BMX_J) |
+| Coding | HE_obe ≥ 4 (Asian cutoff: BMI ≥ 25) | BMXBMI ≥ 30 (WHO cutoff) |
+| Binary | obesity = 1 if HE_obe ≥ 4 | obesity = 1 if BMXBMI ≥ 30 |
+| Label | Obesity (BMI ≥ 25, Asian) | Obesity (BMI ≥ 30, WHO) |
+| Notes | 6-level: 1=underweight to 6=morbid obesity | Continuous BMI; use 25 for Asian-Americans analysis |
+
+### Current Smoking
+
+| Field | KNHANES | NHANES |
+|-------|---------|--------|
+| Raw vars | BS3_1 | SMQ020, SMQ040 |
+| Coding | BS3_1 %in% c(1,2) → current; 3 → former; 8 → never | SMQ020=="Yes" & SMQ040 %in% c("Every day","Some days") → current |
+| Binary | smoking_current = 1 if BS3_1 in (1,2) | smoking_current = 1 if above |
+| Label | Current smoking | Current smoking |
+| Notes | 1=daily, 2=occasional, 3=former, 8=never | Two-step: ≥100 lifetime cigs + currently smoke |
+
+### Heavy/Frequent Drinking
+
+| Field | KNHANES | NHANES |
+|-------|---------|--------|
+| Raw vars | BD1_11 | ALQ111, ALQ121 |
+| Coding | BD1_11 in 2:6 → frequent; 1 → occasional; 8 → never | ALQ111=="No" → never; ALQ121 frequency mapping |
+| Binary | drinking_freq = 1 if BD1_11 in 2:6 | drinking_freq = 1 if ALQ121 indicates monthly+ |
+| Label | Frequent alcohol use | Frequent alcohol use |
+| Notes | 1=past-year abstainer, 2-6=frequency levels, 8=lifetime never | ALQ121 text labels; never=ALQ111=="No" (ALQ121 is NA) |
+
+### Low Education
+
+| Field | KNHANES | NHANES |
+|-------|---------|--------|
+| Raw vars | edu | DMDEDUC2 |
+| Coding | edu in 1:3 → non-college; 4 → college+ | "Less than 9th grade"/"9-11th grade"/"High school" → non-college |
+| Binary | low_edu = 1 if edu in 1:3 | low_edu = 1 if non-college |
+| Label | Non-college education | Non-college education |
+
+### Low Income
+
+| Field | KNHANES | NHANES |
+|-------|---------|--------|
+| Raw vars | incm | INDFMPIR (INQ_J) |
+| Coding | incm in 1:3 → bottom 80% | INDFMPIR < 1.3 → low income |
+| Binary | low_income = 1 if incm in 1:3 | low_income = 1 if PIR < 1.3 |
+| Label | Lower income (bottom 80%) | Low income (PIR < 1.3) |
+| Notes | 4-level quartile | Poverty income ratio; threshold varies by study |
+
+## Outcomes
+
+### Diabetes
+
+| Field | KNHANES | NHANES |
+|-------|---------|--------|
+| Raw vars | HE_glu, HE_HbA1c, DE1_dg | LBXSGL (BIOPRO_J), LBXGH (GHB_J), DIQ010 |
+| Coding | HE_glu≥126 \| HE_HbA1c≥6.5 \| DE1_dg==1 | LBXSGL≥126 \| LBXGH≥6.5 \| DIQ010=="Yes" |
+| Label | Diabetes mellitus | Diabetes mellitus |
+| Notes | FPG=fasting plasma glucose | LBXSGL not LBXSGLU; DIQ010 is text |
+
+### Hypertension
+
+| Field | KNHANES | NHANES |
+|-------|---------|--------|
+| Raw vars | HE_sbp, HE_dbp, DI1_dg | BPXOSY1-4, BPXODI1-4, BPQ020 |
+| Coding | mean(SBP)≥140 \| mean(DBP)≥90 \| DI1_dg==1 | mean(SBP readings)≥140 \| mean(DBP)≥90 \| BPQ020=="Yes" |
+| Label | Hypertension | Hypertension |
+| Notes | HE_sbp/dbp are already averaged | Average of up to 4 readings; BPQ020 is text |
+
+### CVD History
+
+| Field | KNHANES | NHANES |
+|-------|---------|--------|
+| Raw vars | DI4_dg, DI5_dg, DI6_dg | MCQ160B, MCQ160C, MCQ160D |
+| Coding | any == 1 → CVD | any == "Yes" → CVD |
+| Label | Cardiovascular disease history | Cardiovascular disease history |
+| Notes | 4=MI, 5=angina, 6=stroke | B=CHF, C=CHD, D=angina |
+
+### Metabolic Syndrome
+
+| Field | KNHANES | NHANES |
+|-------|---------|--------|
+| Raw vars | HE_wc, HE_sbp, HE_dbp, HE_TG, HE_HDL_st2, HE_glu | BMXWAIST, BPXOSY, BPXODI, LBXSTR, LBDHDD, LBXSGL |
+| Coding | NCEP ATP III: ≥3 of 5 criteria | NCEP ATP III: ≥3 of 5 criteria |
+| Label | Metabolic syndrome (NCEP ATP III) | Metabolic syndrome (NCEP ATP III) |
+| Notes | Waist: M≥90, F≥85 (Korean) | Waist: M≥102, F≥88 (US/WHO) |
+
+## Standard Covariate Set
+
+Default covariates for fully adjusted model (remove exposure if overlap):
+
+| Covariate | KNHANES var | NHANES var | Type |
+|-----------|-------------|------------|------|
+| Age | age | RIDAGEYR | Continuous |
+| Sex | sex | RIAGENDR | Binary |
+| Education | edu | DMDEDUC2 | Binary (college vs non) |
+| Income | incm | INDFMPIR | Binary (threshold varies) |
+| Smoking | BS3_1 | SMQ020+SMQ040 | 3-level (current/former/never) |
+| Alcohol | BD1_11 | ALQ111+ALQ121 | 3-level (frequent/occasional/never) |
+| Obesity | HE_obe | BMXBMI | Binary (country-specific cutoff) |
+| CVD | DI4-6_dg | MCQ160B-D | Binary |
+
+## Survey Design
+
+| Component | KNHANES | NHANES |
+|-----------|---------|--------|
+| Strata | kstrata | SDMVSTRA |
+| PSU/Cluster | psu | SDMVPSU |
+| Weight | wt_itvex | WTMEC2YR (single-cycle) or WTMECPRP (pooled) |
+| R function | svydesign(id=~psu, strata=~kstrata, weights=~wt_itvex, nest=TRUE) | svydesign(id=~SDMVPSU, strata=~SDMVSTRA, weights=~WTMEC2YR, nest=TRUE) |
+
+## Adding New Variables
+
+When a new variable is validated through /replicate-study or /cross-national:
+1. Add an entry in the appropriate section (Exposure or Outcome)
+2. Include both KNHANES and NHANES coding
+3. Note any text-label gotchas for NHANES
+4. Document the source paper that validated the coding

package/skills/batch-cohort/skill.yml

@@ -0,0 +1,35 @@
+schema_version: 2
+name: batch-cohort
+layer: B
+owner_domain: batch_analysis
+
+when_to_use: "Generate N analysis scripts from one validated methodology template across many exposure/outcome combinations."
+when_NOT_to_use: "A single analysis (use analyze-stats); cross-country comparison (use cross-national)."
+
+inputs:
+  - "methodology template"
+  - "exposure/outcome combination matrix"
+outputs:
+  - "N analysis scripts"
+  - "summary matrix"
+side_effects:
+  - writes_project_artifacts
+downstream_consumers:
+  - analyze-stats
+  - self-review
+forbidden_actions:
+  - alter_methodology_per_combination_without_disclosure
+  - fabricate_results_matrix
+
+# v2.1 quality card
+purpose: "Scale one validated method across many variable combinations, swapping only exposure/outcome, never the method."
+safety_boundaries:
+  - "The methodology is held constant across all generated scripts; deviations are disclosed."
+  - "Generated scripts run on real data; no results are pre-filled."
+known_limitations:
+  - "Inherits the source template's assumptions; a flawed template propagates."
+  - "No standalone demo; outputs are code to be executed and reviewed."
+validation_commands:
+  - "execute each generated script and reconcile the summary matrix"
+  - "/self-review"
+evidence_surface: manual_workflow