medsci-skills 4.1.0

package/skills/author-strategy/skill.yml

@@ -0,0 +1,34 @@
+schema_version: 2
+name: author-strategy
+layer: D
+owner_domain: author_profile_analysis
+
+when_to_use: "Analyze a PubMed author profile (study-type mix, trends) and produce a strategy report."
+when_NOT_to_use: "Finding meta-analysis topics (use ma-scout); literature search for a manuscript (use search-lit)."
+
+inputs:
+  - "author name / PubMed identifier"
+outputs:
+  - "study-type classification"
+  - "profile visualization"
+  - "strategy report"
+side_effects:
+  - writes_report_artifacts
+  - network_access_pubmed
+downstream_consumers:
+  - ma-scout
+forbidden_actions:
+  - fabricate_publication_records
+  - infer_identity_without_disambiguation
+
+# v2.1 quality card
+purpose: "Summarize an author's PubMed publication profile and surface strategy options from the actual record."
+safety_boundaries:
+  - "Records are fetched from PubMed, not recalled from memory; author disambiguation is explicit."
+  - "Reports describe the public record only; no private or speculative attribution."
+known_limitations:
+  - "Name collisions on PubMed can blur profiles; disambiguation is best-effort."
+  - "No standalone demo; output is an advisory report."
+validation_commands:
+  - "manual review of the fetched record against PubMed"
+evidence_surface: manual_workflow

package/skills/batch-cohort/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: batch-cohort
+description: Generate N analysis scripts from a single methodology template × multiple exposure/outcome combinations. The "80-person team" pattern — same validated method, swap variables only. Produces batch R/Python code + summary matrix.
+triggers: batch cohort, batch analysis, 대량 분석, 변수 교체, variable swap, mass production, 80명 팀, batch generate, 일괄 코드 생성, exposure outcome matrix, combinatorial analysis
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: opus
+---
+
+# Batch Cohort Analysis Skill
+
+You are assisting a medical researcher in generating multiple analysis scripts from a single
+validated methodology template, each differing only in the exposure/outcome variable combination.
+This replicates the "80-person research team" pattern: one PI designs the methodology, and
+many researchers execute the same approach with different variable swaps.
+
+## When to Use
+
+- Researcher has a **validated analysis template** (e.g., from /replicate-study or /cross-national)
+- Wants to explore **multiple exposure → outcome combinations** on the same database
+- Goal: systematic variable-swap code generation + batch execution + result matrix
+
+## 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**: If TRUE, generates paired scripts for both countries per combination
+
+## 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`: human-readable label for tables/figures
+   - `EXPOSURE_CODING`: how to derive binary/categorical exposure
+   - `OUTCOME_VAR`: raw variable name
+   - `OUTCOME_LABEL`: human-readable label
+   - `OUTCOME_CODING`: how to derive binary outcome
+3. Verify the template runs successfully on at least one combination before batch generation.
+4. 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: check variable name exists in the CSV header
+   - NHANES: check which table contains the variable (use codebook.csv if available)
+   - NHIS: check claims code or variable name
+2. **Define coding**:
+   - Binary: threshold or category mapping (e.g., `HE_glu >= 126 → diabetes = 1`)
+   - Categorical: level definitions (e.g., `smoking: current/former/never`)
+3. **Check covariate overlap**: If the exposure IS one of the standard covariates, remove it from the adjustment set for that analysis (no self-adjustment).
+4. Output: **combination matrix** 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
+
+For each combination in the matrix:
+
+1. **Clone** the template script.
+2. **Replace** slot variables with the combination-specific values.
+3. **Adjust covariates**: Remove exposure variable from covariate list if present.
+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
+   - Logs execution time per analysis
+
+### Phase 4: Batch Execution (if `execute` or `full` mode)
+
+1. Run the master script.
+2. Collect results from each combination's output directory.
+3. Handle failures gracefully:
+   - Log which combinations failed and why
+   - Common failures: convergence issues, too few events, empty subgroups
+   - Suggest fixes for failed combinations
+
+### Phase 5: Summary Matrix
+
+Aggregate all results into a single summary:
+
+**Main Results Matrix** (`summary_matrix.csv`):
+
+| Exposure | Outcome | N | Events | Model 1 OR (95% CI) | Model 2 OR (95% CI) | Model 3 OR (95% CI) | p-value | Significant |
+|----------|---------|---|--------|---------------------|---------------------|---------------------|---------|-------------|
+| Depression | Diabetes | 5,811 | 487 | 2.14 (1.52–3.01) | 1.89 (1.33–2.69) | 1.36 (0.91–2.05) | 0.137 | No |
+| Obesity | Diabetes | 5,811 | 487 | 3.45 (2.71–4.39) | 3.38 (2.65–4.32) | 3.12 (2.42–4.02) | <0.001 | Yes |
+| ... | | | | | | | | |
+
+**Subgroup Summary** (`subgroup_matrix.csv`): Same format, stratified by subgroup variables.
+
+**Heatmap** (optional): Visual matrix of effect sizes × significance, exposure on Y-axis, outcome on X-axis.
+
+## Output Files
+
+```
+{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
+│   ├── 02_obesity_diabetes/
+│   │   └── ...
+│   └── ...
+├── 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
+```
+
+## Critical Rules
+
+1. **Never modify the core methodology** across combinations — only swap exposure/outcome/covariates.
+2. **Remove self-adjustment**: If exposure = BMI, remove obesity from covariates. If exposure = education/income, remove the same variable from covariates. If outcome = MetS, consider removing obesity from covariates. Document all removals.
+3. **Weighted analysis mandatory** for KNHANES/NHANES/NHIS — inherited from template.
+4. **Event count check**: Before running, verify each outcome has ≥10 events per covariate (EPV rule). Flag underpowered combinations.
+5. **Multiple comparisons**: When generating >5 combinations, include a Bonferroni-corrected significance column in the summary matrix. Add a note about exploratory vs confirmatory framing.
+6. **Reproducibility**: Freeze the template version. Include a SHA256 hash of the data file in README.
+7. **No p-hacking framing**: The summary matrix is for **hypothesis generation**, not confirmation. State this explicitly in README and any manuscript output.
+8. **Outcome definitions MUST include physician diagnosis**: 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"). Lab-only definitions systematically overestimate exposure→outcome associations (validated: Joo 2026 replication showed US depression→DM wOR 1.92 without vs 1.54 with physician dx).
+9. **Full covariate set is default**: Always use 8 covariates (age, sex, education, income, smoking, alcohol, obesity, CVD) unless explicitly justified. Minimal models (age+sex+BMI only) overestimate effects due to residual confounding.
+10. **Generated-code quality gate**: Because this skill emits N near-identical scripts, a single reproducibility slip (a missing seed, an absolute path, a hand-typed data literal) replicates across the whole batch. After Phase 3, lint the generated scripts with the `/analyze-stats` code-quality gate (`check_generated_code.py --code-dir {batch_dir} --strict`) and clear every Major (`MISSING_SEED`, `HARDCODED_DATA_LITERAL`, `HARDCODED_ABS_PATH`, `INPLACE_SOURCE_OVERWRITE`) before batch execution.
+
+## Cross-National Batch Mode
+
+When `cross_national: true`:
+- Generate paired scripts for each combination (Korea + US)
+- Summary matrix includes both countries side-by-side
+- Direction agreement column: ✓ if both countries show same direction of effect
+- Uses /cross-national skill's dual-survey-design approach
+
+## Integration with Upstream Skills
+
+| Need | Skill |
+|------|-------|
+| Variable coding lookup | `analyze-stats` survey_weighted guide |
+| Template creation from paper | `/replicate-study` Phase 1–3 |
+| Cross-national paired analysis | `/cross-national` |
+| ICD-10 claims algorithms | `analyze-stats` nhis_icd10_mapping guide |
+| Write manuscript from results | `/write-paper` (nhis_cohort or cross_national type) |
+| Figure generation | `/make-figures` (forest plot of all combinations) |
+
+## Example Invocations
+
+### Basic: Single DB, Multiple Exposures × Single Outcome
+
+```
+/batch-cohort
+
+DB: /path/to/knhanes/HN18.csv
+Template: /path/to/validated_analysis.R
+Exposures: [depression, obesity, smoking, heavy_drinking, low_income, low_education]
+Outcome: diabetes
+Mode: full
+```
+
+### Cross-National: Full Matrix
+
+```
+/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
+```
+
+### NHIS Cohort: Claims-Based Batch
+
+```
+/batch-cohort
+
+DB: /path/to/nhis_sample_cohort.csv
+Template: nhis_cohort
+Exposures: [atrial_fibrillation, heart_failure, COPD, CKD]
+Outcomes: [all_cause_mortality, cardiovascular_death, stroke]
+Mode: code_only
+```
+
+## Anti-Hallucination
+
+- **Never fabricate variable names, dataset column names, or variable codings.** If a variable mapping is uncertain, output `[VERIFY: variable_name]` and ask the user to confirm against the data dictionary.
+- **Never fabricate statistical results** — no invented p-values, effect sizes, confidence intervals, or sample sizes. All numbers must come from executed code output.
+- **Never generate references from memory.** Use `/search-lit` for all citations.
+- If a function, package, or API does not exist or you are unsure, say so explicitly rather than guessing.

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

@@ -0,0 +1,210 @@
+#!/usr/bin/env Rscript
+# ==============================================================================
+# KNHANES Survey-Weighted Logistic Regression — Batch Template
+# Combo: {{COMBO_ID}} | {{EXPOSURE_LABEL}} → {{OUTCOME_LABEL}}
+#
+# Slot variables (replaced by batch_template_generator.R):
+#   {{EXPOSURE_VAR}}, {{EXPOSURE_LABEL}}, {{EXPOSURE_CODING}}
+#   {{OUTCOME_VAR}}, {{OUTCOME_LABEL}}, {{OUTCOME_CODING}}
+#   {{RESULTS_DIR}}, {{COMBO_ID}}, {{COVARIATES_REMOVE}}
+#
+# Data: KNHANES single-cycle CSV (e.g., HN18.csv)
+# ==============================================================================
+
+suppressPackageStartupMessages({
+  library(survey)
+  library(dplyr)
+  library(tidyr)
+})
+
+# --- CONFIG (edit these paths for your setup) ---
+DATA_PATH     <- "{{DATA_PATH}}"       # e.g., /path/to/HN18.csv
+RESULTS_DIR   <- "{{RESULTS_DIR}}"
+COMBO_ID      <- "{{COMBO_ID}}"
+AGE_MIN       <- 20
+AGE_MAX       <- Inf
+
+# --- Standard Covariates ---
+# Full set; exposure-specific removals applied below
+ALL_COVARIATES <- c("age", "sex_binary", "edu_binary", "income_binary",
+                     "smoking_3cat", "alcohol_3cat", "obesity_binary", "cvd_binary")
+REMOVE_COVARS  <- c({{COVARIATES_REMOVE}})
+COVARIATES     <- setdiff(ALL_COVARIATES, REMOVE_COVARS)
+
+# --- Load & Clean ---
+raw <- read.csv(DATA_PATH)
+
+df <- raw %>%
+  filter(age >= AGE_MIN, age <= AGE_MAX) %>%
+  mutate(
+    # --- Demographics ---
+    sex_binary     = ifelse(sex == 1, 0, 1),  # 0=male, 1=female
+    edu_binary     = ifelse(edu %in% 1:3, 0, 1),  # 0=non-college, 1=college
+    income_binary  = ifelse(incm %in% 1:3, 0, 1),  # 0=bottom80, 1=top20
+
+    # --- Standard Covariates ---
+    smoking_3cat = case_when(
+      BS3_1 %in% c(1, 2) ~ "current",
+      BS3_1 == 3          ~ "former",
+      BS3_1 == 8          ~ "never",
+      TRUE                ~ NA_character_
+    ),
+    alcohol_3cat = case_when(
+      BD1_11 %in% 2:6 ~ "frequent",
+      BD1_11 == 1      ~ "occasional",
+      BD1_11 == 8      ~ "never",
+      TRUE             ~ NA_character_
+    ),
+    obesity_binary = ifelse(HE_obe >= 4, 1, 0),
+    cvd_binary     = ifelse(DI4_dg == 1 | DI5_dg == 1 | DI6_dg == 1, 1, 0),
+
+    # --- Exposure (SLOT) ---
+    exposure = {{EXPOSURE_CODING}},
+
+    # --- Outcome (SLOT) ---
+    outcome = {{OUTCOME_CODING}}
+  ) %>%
+  filter(!is.na(exposure), !is.na(outcome))
+
+cat(sprintf("[%s] N after filtering: %d (exposure=1: %d, outcome=1: %d)\n",
+            COMBO_ID, nrow(df), sum(df$exposure == 1), sum(df$outcome == 1)))
+
+# --- EPV Check ---
+n_events <- min(sum(df$outcome == 1), sum(df$outcome == 0))
+n_params <- length(COVARIATES) + 1  # +1 for exposure
+epv <- n_events / n_params
+if (epv < 10) {
+  warning(sprintf("[%s] EPV = %.1f (< 10). Results may be unreliable.", COMBO_ID, epv))
+}
+
+# --- Survey Design ---
+design <- svydesign(
+  id      = ~psu,
+  strata  = ~kstrata,
+  weights = ~wt_itvex,
+  nest    = TRUE,
+  data    = df
+)
+
+# --- Table 1: Weighted Demographics by Exposure ---
+table1_vars <- c("age", "sex_binary", "edu_binary", "income_binary",
+                 "smoking_3cat", "alcohol_3cat", "obesity_binary", "cvd_binary", "outcome")
+
+table1_rows <- lapply(table1_vars, function(v) {
+  tryCatch({
+    if (is.numeric(df[[v]])) {
+      means <- svyby(as.formula(paste0("~", v)), ~exposure, design, svymean, na.rm = TRUE)
+      data.frame(variable = v,
+                 unexposed_mean = means[means$exposure == 0, v],
+                 exposed_mean   = means[means$exposure == 1, v],
+                 stringsAsFactors = FALSE)
+    } else {
+      props <- svyby(as.formula(paste0("~factor(", v, ")")), ~exposure, design, svymean, na.rm = TRUE)
+      data.frame(variable = paste0(v, "_", names(props)[-1]),
+                 unexposed_mean = as.numeric(props[props$exposure == 0, -1]),
+                 exposed_mean   = as.numeric(props[props$exposure == 1, -1]),
+                 stringsAsFactors = FALSE)
+    }
+  }, error = function(e) NULL)
+})
+table1 <- do.call(rbind, Filter(Negate(is.null), table1_rows))
+write.csv(table1, file.path(RESULTS_DIR, "table1.csv"), row.names = FALSE)
+
+# --- Helper: extract OR + CI + p from svyglm ---
+extract_or <- function(model) {
+  or_val  <- unname(exp(coef(model)["exposure"]))
+  ci_vals <- unname(exp(confint(model))["exposure", ])
+  p_val   <- unname(summary(model)$coefficients["exposure", "Pr(>|t|)"])
+  c(OR = or_val, lower = ci_vals[1], upper = ci_vals[2], p = p_val)
+}
+
+# --- Main Analysis: Sequential Models ---
+results <- list()
+
+# Model 1: Unadjusted
+m1 <- svyglm(outcome ~ exposure, design = design, family = quasibinomial())
+results[["Model 1 (unadjusted)"]] <- extract_or(m1)
+
+# Model 2: Age + Sex
+m2 <- svyglm(outcome ~ exposure + age + sex_binary, design = design, family = quasibinomial())
+results[["Model 2 (age+sex)"]] <- extract_or(m2)
+
+# Model 3: Fully adjusted
+formula_full <- as.formula(paste("outcome ~ exposure +", paste(COVARIATES, collapse = " + ")))
+m3 <- svyglm(formula_full, design = design, family = quasibinomial())
+results[["Model 3 (fully adjusted)"]] <- extract_or(m3)
+
+# Save main results
+main_df <- data.frame(
+  combo_id = COMBO_ID,
+  exposure = "{{EXPOSURE_LABEL}}",
+  outcome  = "{{OUTCOME_LABEL}}",
+  model    = names(results),
+  N        = nrow(df),
+  events   = sum(df$outcome == 1),
+  OR       = sapply(results, `[`, "OR"),
+  lower    = sapply(results, `[`, "lower"),
+  upper    = sapply(results, `[`, "upper"),
+  p_value  = sapply(results, `[`, "p"),
+  row.names = NULL
+)
+write.csv(main_df, file.path(RESULTS_DIR, "main_results.csv"), row.names = FALSE)
+
+# --- Subgroup Analyses (Model 3 within strata) ---
+subgroup_vars <- list(
+  sex     = list(var = "sex_binary", levels = c(0, 1), labels = c("Male", "Female")),
+  age_grp = list(var = "age_group",  levels = c("20-39", "40-59", "60+"), labels = NULL),
+  edu     = list(var = "edu_binary", levels = c(0, 1), labels = c("Non-college", "College")),
+  income  = list(var = "income_binary", levels = c(0, 1), labels = c("Lower", "Higher"))
+)
+
+# Create age groups
+df$age_group <- cut(df$age, breaks = c(20, 40, 60, Inf), right = FALSE,
+                    labels = c("20-39", "40-59", "60+"))
+design <- update(design, age_group = df$age_group)
+
+subgroup_results <- list()
+for (sg_name in names(subgroup_vars)) {
+  sg <- subgroup_vars[[sg_name]]
+  for (lev in sg$levels) {
+    tryCatch({
+      sub_design <- subset(design, get(sg$var) == lev)
+      n_sub <- nrow(sub_design$variables)
+      n_events_sub <- sum(sub_design$variables$outcome == 1)
+
+      if (n_sub >= 30 && n_events_sub >= 5) {
+        # Reduced model for subgroups (fewer covariates to avoid convergence issues)
+        sg_covars <- setdiff(COVARIATES, sg$var)
+        sg_formula <- as.formula(paste("outcome ~ exposure +", paste(sg_covars, collapse = " + ")))
+        m_sg <- svyglm(sg_formula, design = sub_design, family = quasibinomial())
+        r_sg <- extract_or(m_sg)
+
+        subgroup_results[[length(subgroup_results) + 1]] <- data.frame(
+          combo_id  = COMBO_ID,
+          exposure  = "{{EXPOSURE_LABEL}}",
+          outcome   = "{{OUTCOME_LABEL}}",
+          subgroup  = sg_name,
+          level     = as.character(lev),
+          N         = n_sub,
+          events    = n_events_sub,
+          OR        = r_sg["OR"],
+          lower     = r_sg["lower"],
+          upper     = r_sg["upper"],
+          p_value   = r_sg["p"],
+          row.names = NULL
+        )
+      }
+    }, error = function(e) {
+      message(sprintf("[%s] Subgroup %s=%s failed: %s", COMBO_ID, sg_name, lev, e$message))
+    })
+  }
+}
+
+if (length(subgroup_results) > 0) {
+  subgroup_df <- do.call(rbind, subgroup_results)
+  write.csv(subgroup_df, file.path(RESULTS_DIR, "subgroup_results.csv"), row.names = FALSE)
+}
+
+cat(sprintf("[%s] Complete. Fully adjusted wOR: %.2f (%.2f–%.2f), p=%.3f\n",
+            COMBO_ID,
+            main_df$OR[3], main_df$lower[3], main_df$upper[3], main_df$p_value[3]))