medsci-skills 4.1.0

package/skills/clean-data/scripts/check_structural_zero.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+"""Categorical-implied-zero (structural-zero) detector for clean-data Stage 2.
+
+A dose/duration variable anchored to a categorical exposure has a known zero at
+the reference level: a never-smoker's pack-years is 0 *by definition*, not
+missing. When that implied zero is instead stored as NULL/blank, two downstream
+failures follow — a complete-case model silently drops the whole unexposed
+stratum, or MICE imputes a non-zero dose for people who have no exposure — both
+of which corrupt the exposure contrast. This script finds those contradiction
+rows so they are fixed at cleaning time (set 0 at the reference level; impute
+only the residual missingness among the exposed).
+
+INPUTS
+  --data            CSV with one row per subject.
+  --category-col    categorical exposure column (e.g. smoking_status).
+  --reference-level value of the category that implies a zero dose (e.g. never).
+  --dose-col        dose/duration column that should be 0 at the reference level
+                    (e.g. pack_years). Repeatable for several dose columns.
+
+OUTPUT
+  Per (reference-level, dose) pair: counts of
+    - implied_zero_missing : category == reference AND dose is NULL/blank   (FIX)
+    - implied_zero_nonzero : category == reference AND dose > 0  (mislabeled — review)
+    - implied_zero_ok      : category == reference AND dose == 0
+  Exit 1 (with --strict) if any implied_zero_missing rows exist.
+
+Stdlib-only (csv / json / argparse). Exit codes: 0 clean (or report-only),
+1 contradiction rows found (with --strict), 2 input/usage error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import sys
+from pathlib import Path
+
+NULLISH = {"", "na", "n/a", "nan", "null", "none", ".", "missing"}
+
+
+def _is_null(v: str) -> bool:
+    return v.strip().lower() in NULLISH
+
+
+def _to_float(v: str):
+    try:
+        return float(v.strip())
+    except (ValueError, AttributeError):
+        return None
+
+
+def _norm(s: str) -> str:
+    return s.strip().lower()
+
+
+def analyze(data: str, category_col: str, reference: str, dose_cols: list[str]) -> dict:
+    p = Path(data)
+    if not p.is_file():
+        sys.stderr.write(f"ERROR: data file not found: {data}\n")
+        sys.exit(2)
+    with p.open(encoding="utf-8-sig", newline="") as f:
+        reader = csv.DictReader(f)
+        if reader.fieldnames is None:
+            sys.stderr.write("ERROR: empty CSV\n")
+            sys.exit(2)
+        fields = {_norm(c): c for c in reader.fieldnames}
+        cat_key = fields.get(_norm(category_col))
+        if cat_key is None:
+            sys.stderr.write(f"ERROR: category column '{category_col}' not in {reader.fieldnames}\n")
+            sys.exit(2)
+        dose_keys = {}
+        for d in dose_cols:
+            k = fields.get(_norm(d))
+            if k is None:
+                sys.stderr.write(f"ERROR: dose column '{d}' not in {reader.fieldnames}\n")
+                sys.exit(2)
+            dose_keys[d] = k
+        rows = list(reader)
+
+    ref = _norm(reference)
+    results = []
+    total_missing = 0
+    for d, dkey in dose_keys.items():
+        miss = nonzero = ok = ref_n = 0
+        for r in rows:
+            if _norm(r.get(cat_key, "")) != ref:
+                continue
+            ref_n += 1
+            raw = r.get(dkey, "")
+            if _is_null(raw):
+                miss += 1
+            else:
+                val = _to_float(raw)
+                if val is None:
+                    continue            # non-numeric, not our concern here
+                if val > 0:
+                    nonzero += 1
+                else:
+                    ok += 1
+        total_missing += miss
+        results.append({
+            "dose_col": d,
+            "reference_level": reference,
+            "reference_n": ref_n,
+            "implied_zero_missing": miss,
+            "implied_zero_nonzero": nonzero,
+            "implied_zero_ok": ok,
+            "verdict": "FIX_STRUCTURAL_ZERO" if miss else ("REVIEW_MISLABEL" if nonzero else "OK"),
+        })
+
+    return {
+        "data": str(p),
+        "category_col": category_col,
+        "n_rows": len(rows),
+        "results": results,
+        "total_implied_zero_missing": total_missing,
+        "suggested_fix": (
+            f"Set dose = 0 where {category_col} == '{reference}' (structural zero), "
+            "then impute only the residual missingness among the exposed."
+        ) if total_missing else None,
+    }
+
+
+def render(result: dict) -> str:
+    lines = [
+        "| Dose col | ref n | implied-zero MISSING | nonzero (mislabel) | zero (ok) | Verdict |",
+        "|---|---|---|---|---|---|",
+    ]
+    for r in result["results"]:
+        mark = {"FIX_STRUCTURAL_ZERO": "✗ Fix", "REVIEW_MISLABEL": "△ Review", "OK": "✓"}[r["verdict"]]
+        lines.append(
+            f"| {r['dose_col']} | {r['reference_n']} | {r['implied_zero_missing']} | "
+            f"{r['implied_zero_nonzero']} | {r['implied_zero_ok']} | {mark} |"
+        )
+    return "\n".join(lines)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Categorical-implied-zero (structural-zero) detector.")
+    ap.add_argument("--data", required=True, help="subject-level CSV")
+    ap.add_argument("--category-col", required=True, help="categorical exposure column")
+    ap.add_argument("--reference-level", required=True, help="category value implying a zero dose")
+    ap.add_argument("--dose-col", required=True, action="append",
+                    help="dose/duration column (repeatable)")
+    ap.add_argument("--out", help="write JSON artifact to this path")
+    ap.add_argument("--strict", action="store_true", help="exit 1 if any implied-zero-missing rows")
+    args = ap.parse_args()
+
+    result = analyze(args.data, args.category_col, args.reference_level, args.dose_col)
+
+    print("=" * 41)
+    print(" Categorical-Implied-Zero (structural zero)")
+    print("=" * 41)
+    print(f"category: {args.category_col} == '{args.reference_level}'")
+    print(render(result))
+    print()
+    if result["total_implied_zero_missing"]:
+        print(f"FIX: {result['total_implied_zero_missing']} reference-level row(s) store the implied "
+              f"zero as missing.")
+        print(result["suggested_fix"])
+    else:
+        print("OK: no categorical-implied-zero stored as missing.")
+
+    if args.out:
+        Path(args.out).parent.mkdir(parents=True, exist_ok=True)
+        Path(args.out).write_text(json.dumps(result, indent=2), encoding="utf-8")
+        print(f"\nwrote {args.out}")
+
+    return 1 if (args.strict and result["total_implied_zero_missing"]) else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/clean-data/skill.yml

@@ -0,0 +1,35 @@
+schema_version: 2
+name: clean-data
+layer: B
+owner_domain: data_preparation
+
+when_to_use: "Profile and clean clinical CSV/Excel data through a three-stage workflow with user approval at each gate."
+when_NOT_to_use: "Removing PHI (use deidentify); statistical analysis (use analyze-stats)."
+
+inputs:
+  - "raw analysis dataset (CSV/Excel)"
+outputs:
+  - "data profile report"
+  - "cleaning code"
+  - "cleaned dataset"
+side_effects:
+  - writes_project_artifacts
+downstream_consumers:
+  - analyze-stats
+  - version-dataset
+forbidden_actions:
+  - auto_clean_without_user_approval
+  - drop_rows_or_impute_silently
+
+# v2.1 quality card
+purpose: "Profile, flag, and code-generate cleaning steps for clinical tabular data, with a researcher approval gate at every stage."
+safety_boundaries:
+  - "Never auto-cleans; every decision (missing values, outliers, dups, types) requires user confirmation."
+  - "All transforms are emitted as reviewable code, not applied silently."
+known_limitations:
+  - "Heuristic flags need clinical judgement; the skill does not decide what is a true outlier."
+  - "No standalone demo; correctness depends on user approvals."
+validation_commands:
+  - "re-run the emitted cleaning code and re-profile"
+  - "/version-dataset for a manifest"
+evidence_surface: manual_workflow

package/skills/clean-data/tests/fixtures/smoking.csv

@@ -0,0 +1,8 @@
+id,smoking_status,pack_years
+1,never,
+2,never,
+3,never,0
+4,former,20
+5,current,30
+6,never,5
+7,current,

package/skills/clean-data/tests/test_structural_zero.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Regression test for the categorical-implied-zero (structural-zero) detector.
+# Synthetic fixture: never-smokers with NULL pack-years (the bug), one with an
+# explicit 0 (ok), one mislabeled with a positive dose. Stdlib-only (python3).
+set -u
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SCRIPT="$HERE/../scripts/check_structural_zero.py"
+FIXTURE="$HERE/fixtures/smoking.csv"
+OUT="$(mktemp -t sz_XXXX).json"
+trap 'rm -f "$OUT"' EXIT
+
+fail=0
+check() { local label="$1"; shift
+    if "$@" >/dev/null 2>&1; then printf '  PASS  %s\n' "$label"
+    else printf '  FAIL  %s\n' "$label"; fail=$((fail+1)); fi
+}
+
+[[ -f "$SCRIPT" ]]  || { echo "ENV-ERR: script missing"  >&2; exit 2; }
+[[ -f "$FIXTURE" ]] || { echo "ENV-ERR: fixture missing" >&2; exit 2; }
+
+python3 "$SCRIPT" --data "$FIXTURE" --category-col smoking_status \
+    --reference-level never --dose-col pack_years --out "$OUT" --strict >/dev/null 2>&1
+check "exit 1 under --strict (implied-zero missing present)" test "$?" -eq 1
+check "JSON artifact written" test -s "$OUT"
+
+check "implied_zero_missing == 2" python3 -c "
+import json; d=json.load(open('$OUT'))
+assert d['total_implied_zero_missing']==2, d['total_implied_zero_missing']"
+check "implied_zero_nonzero (mislabel) == 1" python3 -c "
+import json; d=json.load(open('$OUT'))
+assert d['results'][0]['implied_zero_nonzero']==1"
+check "implied_zero_ok == 1" python3 -c "
+import json; d=json.load(open('$OUT'))
+assert d['results'][0]['implied_zero_ok']==1"
+check "reference_n == 4 (never-smokers)" python3 -c "
+import json; d=json.load(open('$OUT'))
+assert d['results'][0]['reference_n']==4"
+check "verdict FIX_STRUCTURAL_ZERO" python3 -c "
+import json; d=json.load(open('$OUT'))
+assert d['results'][0]['verdict']=='FIX_STRUCTURAL_ZERO'"
+
+# Clean case: a reference level with no missing dose -> exit 0 under --strict.
+python3 "$SCRIPT" --data "$FIXTURE" --category-col smoking_status \
+    --reference-level former --dose-col pack_years --strict >/dev/null 2>&1
+check "exit 0 when reference level has no missing dose" test "$?" -eq 0
+
+echo "fail=$fail"; [[ "$fail" -eq 0 ]] && echo "ALL PASS" || echo "FAILURES: $fail"
+exit "$fail"

package/skills/cross-national/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: cross-national
+description: End-to-end cross-national comparison study using KNHANES + NHANES + CHNS (or other parallel surveys). Variable harmonization, parallel weighted analysis, and comparison tables. Supports 2-country (KR+US) and 3-country (KR+US+CN) designs.
+triggers: cross-national, 한미 비교, Korea US comparison, KNHANES NHANES, 양국 비교, binational, cross-country, 비교연구, 3국 비교, CHNS, 한미중
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: opus
+---
+
+# Cross-National Comparison Study Skill
+
+You are assisting a medical researcher in conducting a cross-national comparison study
+using parallel nationally representative surveys (e.g., KNHANES for Korea, NHANES for the US, CHNS for China).
+
+## When to Use
+
+- Researcher has a clinical question to compare across two countries
+- KNHANES + NHANES data available (or other parallel survey pairs)
+- Goal: produce a complete analysis with country-stratified results + comparison table
+
+## Inputs
+
+1. **Research question**: exposure → outcome association to compare across countries
+2. **Korean data path**: KNHANES CSV file
+3. **US data path**: NHANES CSV directory (multiple tables to merge)
+4. **Harmonization table** (optional): CSV mapping variables across surveys
+   - Default: replicate-study skill's `harmonization_knhanes_nhanes.csv`
+
+## Reference Files
+
+- Harmonization table: `medsci-skills/skills/replicate-study/references/harmonization_knhanes_nhanes.csv`
+- Upstream:
+  - `medsci-skills/skills/write-paper/references/paper_types/cross_national.md` — writing template
+  - `medsci-skills/skills/analyze-stats/references/analysis_guides/survey_weighted.md`
+
+## Workflow
+
+### Phase 1: Study Definition
+
+1. Confirm research question: Exposure → Outcome
+2. Define variable coding for both countries:
+   - Exposure: PHQ-9, BMI category, smoking, etc.
+   - Outcome: diabetes, hypertension, mortality, etc.
+   - Covariates: age, sex, education, income, smoking, alcohol, obesity, CVD
+3. Check harmonization table for variable availability
+4. Output: study protocol summary for user approval
+
+### Phase 2: Data Preparation
+
+**KNHANES (single CSV)**:
+1. Load CSV, filter age ≥20 (or per protocol)
+2. Derive variables using KNHANES coding:
+   - Smoking: BS3_1 (1,2=current, 3=former, 8=never)
+   - Alcohol: BD1_11 (2-6=frequent, 1=occasional, 8=never)
+   - Obesity: HE_obe (≥4=obesity for BMI≥25 Asian cutoff)
+   - PHQ-9: BP_PHQ_1~9, sum score, ≥10=depression
+   - Diabetes: HE_glu≥126 | HE_HbA1c≥6.5 | DE1_dg=1
+   - CVD: DI4_dg=1 | DI5_dg=1 | DI6_dg=1
+3. Set survey design: svydesign(id=~psu, strata=~kstrata, weights=~wt_itvex, nest=TRUE)
+
+**NHANES (multiple CSVs)**:
+1. Load and merge tables by SEQN (DEMO_J, DPQ_J, GHB_J, BIOPRO_J, BMX_J, SMQ_J, ALQ_J, DIQ_J, MCQ_J, BPQ_J)
+2. Derive variables using NHANES coding:
+   - Smoking: SMQ020 + SMQ040 (100 cigs + now smoke)
+   - Alcohol: ALQ121 (past 12 mo frequency → categories)
+   - Obesity: BMXBMI ≥30 (WHO cutoff, NOT Asian)
+   - PHQ-9: DPQ010~DPQ090, sum score, ≥10=depression
+   - Diabetes: LBXSGL≥126 | LBXGH≥6.5 | DIQ010=="Yes" (CRITICAL: LBXSGL not LBXSGLU)
+   - CVD: MCQ160B=="Yes" (CHF) | MCQ160C=="Yes" (CHD) | MCQ160D=="Yes" (angina) | MCQ160E=="Yes" (MI)
+   - HTN: BPXOSY3≥140 | BPXODI3≥90 | BPQ020=="Yes"
+3. Set survey design: svydesign(id=~SDMVPSU, strata=~SDMVSTRA, weights=~WTMECPRP, nest=TRUE)
+
+### Phase 3: Parallel Analysis
+
+For EACH country independently:
+1. **Table 1**: Baseline characteristics by exposure (weighted counts + percentages)
+2. **Main analysis**: Sequential logistic regression models
+   - Model 1 (unadjusted)
+   - Model 2 (age + sex)
+   - Model 3 (fully adjusted: + education, income, smoking, alcohol, obesity, CVD)
+3. **Subgroup analyses**: By sex, age group, education, income, alcohol, smoking, CVD, obesity
+4. **Dose-response** (if applicable): RCS with 3 knots
+
+### Phase 4: Cross-National Comparison Table
+
+Generate a side-by-side comparison:
+
+| Analysis | Korea wOR (95% CI) | US wOR (95% CI) | Direction Agreement |
+|----------|-------------------|-----------------|---------------------|
+| Overall (fully adjusted) | ... | ... | ✓/✗ |
+| Male | ... | ... | |
+| Female | ... | ... | |
+| ... | ... | ... | |
+
+### Phase 5: Output Files
+
+```
+{working_dir}/
+├── cross_national_report.md    — Study summary + comparison tables
+├── variable_mapping.csv        — Variable mapping with match status
+├── analysis_korea.R            — KNHANES analysis (self-contained)
+├── analysis_us.R               — NHANES analysis (self-contained)
+├── results/
+│   ├── table1_korea.csv
+│   ├── table1_us.csv
+│   ├── main_results_comparison.csv
+│   └── subgroup_comparison.csv
+└── manuscript_draft/           — Optional: Methods + Results draft
+    ├── methods_draft.md
+    └── results_draft.md
+```
+
+## Critical Rules
+
+1. **NEVER pool data across countries**. Each country analyzed with its own survey design.
+2. **Country-specific BMI cutoffs**: Korea ≥25 (Asian), US ≥30 (WHO).
+3. **Country-specific income**: KNHANES quartile, NHANES PIR → harmonize to binary.
+4. **Weighted analysis mandatory**: Both KNHANES and NHANES are complex surveys.
+5. **Document all harmonization decisions**: What matches, what needed recoding, what differs.
+6. **Same analytic approach**: Identical model specifications for both countries for fair comparison.
+
+## KNHANES Variable Coding Reference (validated via Joo 2026 replication)
+
+| Variable | Raw Var | Coding |
+|----------|---------|--------|
+| Smoking | BS3_1 | 1,2=Current; 3=Former; 8=Never |
+| Alcohol | BD1_11 | 2-6=Frequent (current drinker); 1=Occasional (past-year abstainer); 8=Never |
+| Obesity | HE_obe | 1-3=Normal; 4-6=Obesity (BMI≥25) |
+| Depression | BP_PHQ_1~9 | Sum ≥10 = depression |
+| Diabetes | HE_glu, HE_HbA1c, DE1_dg | FPG≥126 or HbA1c≥6.5 or DE1_dg=1 |
+| CVD | DI4_dg, DI5_dg, DI6_dg | Any = 1 → CVD yes |
+| Education | edu | 1-3=Non-college; 4=College |
+| Income | incm | 1-3=Bottom 80%; 4=Top 20% |
+| Survey design | kstrata, psu, wt_itvex | strata, cluster, weight |
+
+## NHANES Variable Coding Reference (validated via Joo 2026 cross-national)
+
+**CRITICAL**: NHANES data downloaded via R `nhanesA` package uses TEXT LABELS, not numeric codes.
+
+| Variable | Raw Var | Text Labels → Numeric |
+|----------|---------|----------------------|
+| PHQ-9 items | DPQ010~DPQ090 | "Not at all"→0, "Several days"→1, "More than half the days"→2, "Nearly every day"→3 |
+| Sex | RIAGENDR | "Male" / "Female" (NOT 1/2) |
+| Smoking (100 cigs) | SMQ020 | "Yes" / "No" |
+| Smoking (now) | SMQ040 | "Every day" / "Some days" / "Not at all" |
+| Alcohol freq | ALQ121 | Text labels (see below) |
+| Alcohol ever | ALQ111 | "Yes" / "No" |
+| Education | DMDEDUC2 | 5 text levels (see SKILL.md Phase 2) |
+| Diabetes dx | DIQ010 | "Yes" / "No" / "Borderline" |
+| CVD (CHF) | MCQ160B | "Yes" / "No" / "Don't know" |
+| CVD (CHD) | MCQ160C | "Yes" / "No" / "Don't know" |
+| CVD (angina) | MCQ160D | "Yes" / "No" / "Don't know" |
+| Fasting glucose | LBXSGL (BIOPRO_J) | Numeric (mg/dL) — note: NOT LBXSGLU |
+| HbA1c | LBXGH (GHB_J) | Numeric (%) |
+| BMI | BMXBMI (BMX_J) | Numeric (kg/m²) |
+| Weight | WTMEC2YR (single-cycle) or WTMECPRP (pre-pandemic pooled) | Numeric |
+| Strata | SDMVSTRA | Numeric |
+| PSU | SDMVPSU | Numeric |
+
+### ALQ121 Text Label Mapping (Alcohol Frequency)
+- Frequent (current drinker): Any specific frequency except "Never in the last year"
+- Occasional (past-year abstainer): "Never in the last year"
+- Never (lifetime non-drinker): ALQ111 == "No" (ALQ121 will be NA)
+
+### Additional KNHANES Variables (validated via LE8-Asthma replication)
+
+| Variable | Raw Var | Coding |
+|----------|---------|--------|
+| Asthma | DJ2_dg | 0=No, 1=Yes (physician dx), 9=Don't know → exclude |
+| Asthma treatment | DJ2_pt | 0=No, 1=Yes, 8=N/A, 9=Don't know |
+| Sleep (2017-18) | BP16_11/12/13/14 | **Clock times, NOT hours!** 11=bed hour, 12=bed min, 13=wake hour, 14=wake min. Calculate: duration = wake_time - bed_time (handle midnight crossing). 99=Don't know→NA |
+| Sleep (2017-18 weekend) | BP16_21/22/23/24 | Same format as weekday |
+| Sleep (2019-20) | BP16_1/2 | Direct sleep hours (weekday/weekend). 99=Don't know→NA |
+| PA aerobic | pa_aerobic | 0=Doesn't meet, 1=Meets guidelines. **Note: values are 0/1, NOT 1/2** |
+| HTN treatment | DI1_pr | 1=Yes, 0=No (currently treating hypertension) |
+| Dyslipidemia tx | DI3_pr | 1=Yes, 0=No (if available) |
+| Non-HDL chol | HE_chol - HE_HDL_st2 | Derived: total cholesterol minus HDL |
+
+### Additional NHANES Variables (validated via LE8-Asthma replication)
+
+| Variable | Raw Var | Coding |
+|----------|---------|--------|
+| Asthma | MCQ010 | "Yes" / "No" (ever told by doctor) |
+| Sleep hours | SLD012 | Numeric (hours/night on weekdays) |
+| BP treatment | BPQ020 | "Yes" / "No" (told by doctor, high BP) |
+| Cholesterol treatment | BPQ100D | "Yes" / "No" (taking cholesterol Rx) |
+| PA vigorous work | PAQ605/PAQ610/PAD615 | Yes/No, days/week, min/day |
+| PA moderate work | PAQ620/PAQ625/PAD630 | Yes/No, days/week, min/day |
+| PA walk/bike | PAQ635/PAQ640/PAD645 | Yes/No, days/week, min/day |
+| PA vigorous rec | PAQ665/PAQ670/PAD675 | Yes/No, days/week, min/day |
+| PA moderate rec | PAQ650/PAQ655/PAD660 | Yes/No, days/week, min/day |
+| Dietary fiber | DR1TFIBE (DR1TOT_J) | Numeric (grams, day 1 recall) |
+| Dietary sodium | DR1TSODI (DR1TOT_J) | Numeric (mg) |
+| Dietary sat fat | DR1TSFAT (DR1TOT_J) | Numeric (grams) |
+| Total energy | DR1TKCAL (DR1TOT_J) | Numeric (kcal) |
+| Total sugars | DR1TSUGR (DR1TOT_J) | Numeric (grams) |
+| Non-HDL chol | LBXTC - LBDHDD | Derived: TCHOL_J minus HDL_J |
+
+## CHNS Variable Coding Reference (validated via 3-country batch)
+
+**Data source**: cpc.unc.edu/projects/china (free registration)
+**Biomarker wave**: 2009 only (N=9,549). Other variables available 1989-2015.
+**Survey design**: No formal weights. Use `svydesign(id=~COMMID, weights=~1)` or cluster-robust SE.
+
+### Key Files and Merge Strategy
+
+| File | Key Variables | Join Key |
+|------|--------------|----------|
+| mast_pub_12 | IDind, GENDER (1=M/2=F), WEST_DOB_Y (birth year) | IDind |
+| pexam_00 | HEIGHT, WEIGHT, U10 (waist), SYSTOL1-3, DIASTOL1-3, U22 (HBP dx), U24 (HBP meds), U24A (DM dx), U25 (ever smoked), U27 (still smokes), U40 (alcohol), U41 (freq), U48A (self-health), COMMID | IDind + filter WAVE==2009 |
+| biomarker_09 | GLUCOSE_MG, HbA1c, TC_MG, TG_MG, HDL_C_MG, LDL_C_MG, HS_CRP, HGB, WBC, ALT, CRE_MG | IDind |
+| educ_12 | A12 (education 0-6) | IDind + filter WAVE==2009 |
+| indinc_10 | indwage (yuan, continuous → quartiles) | IDind + filter wave==2009 |
+
+### Variable Coding
+
+| Variable | Raw Var | Coding | Notes |
+|----------|---------|--------|-------|
+| Sex | GENDER | 1=Male, 2=Female | Same as KNHANES/NHANES |
+| Age | WEST_DOB_Y | age = wave_year - WEST_DOB_Y | Integer truncation |
+| BMI | HEIGHT, WEIGHT | WEIGHT / (HEIGHT/100)^2 | **Obesity: BMI ≥ 28 (WGOC, NOT 25 or 30)** |
+| Waist | U10 | cm, direct measurement | **Central obesity: ≥90M / ≥80F (IDF-Asian)** |
+| SBP | SYSTOL1-3 | mean(SYSTOL1, SYSTOL2, SYSTOL3) | 3 readings averaged |
+| DBP | DIASTOL1-3 | mean(DIASTOL1, DIASTOL2, DIASTOL3) | 3 readings averaged |
+| HBP diagnosed | U22 | 0=No, 1=Yes, 9=Don't know (→NA) | |
+| HBP medication | U24 | 0=No, 1=Yes | |
+| DM diagnosed | U24A | 0=No, 1=Yes, 9=Don't know (→NA) | |
+| Smoking | U25 + U27 | never(U25==0) / former(U25==1 & U27==0) / current(U25==1 & U27==1) | |
+| Alcohol | U40 + U41 | never(U40==0) / occasional(U41≥4) / frequent(U41≤3, ≥1x/week) | U41: 1=daily, 2=3-4x/wk, 3=1-2x/wk, 4=1-2x/mo, 5=<1x/mo |
+| Education | A12 | 0=none, 1=primary, 2=lower-mid, 3=upper-mid, 4=technical, 5=university, 6=master+. Recode: 0-2→low, 3-4→mid, 5-6→high | |
+| Income | indwage | Continuous yuan → quartiles within wave | |
+| Glucose | GLUCOSE_MG | mg/dL (also GLUCOSE in mmol/L) | 2009 only |
+| HbA1c | HbA1c | % (direct) | 2009 only |
+| TC | TC_MG | mg/dL | 2009 only |
+| TG | TG_MG | mg/dL | 2009 only |
+| HDL | HDL_C_MG | mg/dL | 2009 only |
+| hsCRP | HS_CRP | mg/L | 2009 only |
+| Hemoglobin | HGB | **g/L (divide by 10 for g/dL)** | Unit differs from KR/US |
+| Self-health | U48A | Self-reported health status | 2004-2011 |
+| Depression | — | **NOT AVAILABLE** in standard download. CES-D exists but needs separate dataset. | Cannot directly compare with PHQ-9 |
+
+### CHNS-Specific Warnings
+
+1. **No survey weights**: CHNS is NOT a formally weighted survey. Use unweighted analysis with cluster-robust SE by COMMID. Report as limitation.
+2. **Biomarker = 2009 only**: Glucose, HbA1c, lipids, hsCRP available only in 2009 wave. Other waves lack lab data.
+3. **CES-D not in standard download**: Depression comparison requires separate dataset download from cpc.unc.edu.
+4. **BMI cutoff ≠ KR ≠ US**: China=28, Korea=25, US=30. Use country-specific cutoffs AND sensitivity analysis with WHO cutoff=25.
+5. **SES-health gradient may reverse**: Low education and low income are NOT always risk factors in China (null/protective). This is the "developing country health transition" — do NOT treat as a bug.
+6. **Hemoglobin unit**: CHNS reports g/L (KR/US report g/dL). Divide by 10 when comparing.
+7. **Education scale**: 7-level (0-6) vs KR 4-level vs US 5-level. Harmonize to 3-level for comparison.
+
+### Composite Score Replication Warnings (learned from LE8 replication)
+
+1. **BMI cutoff mismatch**: LE8 uses WHO <25 which classifies most Koreans as "ideal" → Factor subscore loses BMI discriminatory power in Asian populations. Report this limitation.
+2. **KNHANES sleep = clock times**: BP16_11-14 are bedtime/waketime (hour:min), NOT sleep duration. Must compute `wake_time - bed_time` with midnight crossing.
+3. **pa_aerobic codes**: Values are 0/1 (not 1/2). Binary → MET-hours approximation is coarse.
+4. **Diet quality scoring**: AHEI-2010 requires detailed food group data; nutrient-based proxy gives different distribution. Recommend downloading NHANES DR1TOT_J for dietary recall nutrients.
+5. **LE8 sensitivity to implementation**: Small scoring differences compound across 8 components → overall score can diverge substantially, especially in the "moderate" range where most people cluster.
+
+## 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/cross-national/skill.yml

@@ -0,0 +1,37 @@
+schema_version: 2
+name: cross-national
+layer: B
+owner_domain: cross_national_comparison
+
+when_to_use: "Run a cross-national comparison (KNHANES + NHANES + CHNS or similar) with harmonized variables and parallel weighted analysis."
+when_NOT_to_use: "Single-cohort analysis (use analyze-stats); replicating one study on one DB (use replicate-study)."
+
+inputs:
+  - "parallel survey datasets"
+  - "variable harmonization plan"
+outputs:
+  - "harmonization table"
+  - "parallel weighted analysis"
+  - "comparison tables"
+side_effects:
+  - writes_project_artifacts
+  - executes_analysis_code
+downstream_consumers:
+  - analyze-stats
+  - self-review
+forbidden_actions:
+  - harmonize_variables_without_documented_mapping
+  - ignore_survey_weights
+
+# v2.1 quality card
+purpose: "Harmonize and analyze parallel national surveys (2- or 3-country) with correct complex-survey weighting."
+safety_boundaries:
+  - "Variable harmonization is documented in an explicit mapping; survey weights are always applied."
+  - "Numbers come from executed weighted analysis on real survey data."
+known_limitations:
+  - "Cross-survey comparability is limited by instrument differences; residual non-comparability remains."
+  - "No standalone demo; depends on a sound harmonization plan."
+validation_commands:
+  - "re-run weighted analysis per country and reconcile"
+  - "/self-review"
+evidence_surface: manual_workflow