medsci-skills 4.1.0

package/skills/analyze-stats/references/analysis_guides/missing_data.md

@@ -0,0 +1,109 @@
+# Missing Data Guide
+
+Strategies for handling missing data in medical research analyses.
+This is a preprocessing step, not an independent analysis type.
+
+---
+
+## Missing Data Mechanisms
+
+| Mechanism | Definition | Example | Implication |
+|-----------|-----------|---------|-------------|
+| **MCAR** | Missing completely at random | Specimen lost in transit | Complete case analysis OK |
+| **MAR** | Missingness depends on observed data | Older patients more likely to drop out | **Multiple imputation needed** |
+| **MNAR** | Missingness depends on unobserved value | Sicker patients miss follow-up | Sensitivity analysis required |
+
+MNAR cannot be verified statistically — always consider as a possibility.
+
+---
+
+## Decision by Missing Rate
+
+| Missing % | Action |
+|-----------|--------|
+| < 5% | Complete case analysis generally acceptable |
+| 5-20% | **Multiple imputation recommended** |
+| 20-40% | MI + sensitivity analysis mandatory |
+| > 40% | Consider excluding the variable from analysis |
+
+---
+
+## Multiple Imputation via Chained Equations (MICE)
+
+### Procedure
+1. Specify imputation model for each variable with missing data
+2. Generate m imputed datasets (m = 5 minimum; m = 20 if missing > 20%)
+3. Analyze each dataset independently (same analysis model)
+4. Pool results using **Rubin's rules**: estimate = mean of m estimates; variance = within + between variance
+
+### Imputation Model Rules
+- Include ALL variables from the analysis model in the imputation model
+- Include the outcome variable (in imputation model only)
+- Match variable type to method:
+  - Continuous → predictive mean matching (PMM) or regression
+  - Binary → logistic regression
+  - Multinomial → polytomous regression
+  - Ordinal → proportional odds
+
+### Methods NOT Recommended
+- **Mean imputation**: underestimates variance — never use
+- **LOCF (Last Observation Carried Forward)**: biased in most settings — avoid
+- **Single imputation**: does not account for imputation uncertainty
+
+---
+
+## Reporting Template
+
+"Missing data ranged from X% (variable A) to Y% (variable B). Little's MCAR test suggested data were not MCAR (P = 0.003). Multiple imputation using chained equations (MICE) was performed with m = 20 imputed datasets. Results were pooled using Rubin's rules. Sensitivity analyses using complete case analysis yielded consistent results (Supplementary Table X)."
+
+---
+
+## When to Trigger in analyze-stats
+
+During Phase 1 (Data Assessment), if any analysis variable has > 5% missing:
+1. Report missing counts and percentages
+2. Suggest MICE before proceeding
+3. Generate imputation code as a preprocessing step
+4. Run the primary analysis on imputed data
+5. Run complete case analysis as sensitivity analysis
+
+---
+
+## Python Implementation
+
+```python
+from sklearn.experimental import enable_iterative_imputer
+from sklearn.impute import IterativeImputer
+import numpy as np
+import pandas as pd
+
+m = 20  # number of imputations
+results = []
+for i in range(m):
+    imputer = IterativeImputer(max_iter=10, random_state=i, sample_posterior=True)
+    df_imputed = pd.DataFrame(imputer.fit_transform(df), columns=df.columns)
+    # Run analysis on each imputed dataset
+    # ... append results
+# Pool using Rubin's rules
+pooled_estimate = np.mean(results, axis=0)
+```
+
+## R Implementation
+
+```r
+library(mice)
+imp <- mice(df, m = 20, method = 'pmm', seed = 42)
+fit <- with(imp, lm(y ~ x1 + x2))
+pooled <- pool(fit)
+summary(pooled)
+```
+
+---
+
+## Common Reviewer Flags
+
+1. Not reporting missing data counts per variable
+2. Using listwise deletion without justification
+3. Mean imputation or LOCF without acknowledging limitations
+4. Not performing sensitivity analysis (complete case vs MI comparison)
+5. Not stating the assumed missing mechanism (MCAR/MAR/MNAR)

package/skills/analyze-stats/references/analysis_guides/nhis_icd10_mapping.md

@@ -0,0 +1,247 @@
+# NHIS Claims-Based Disease Definition Guide
+
+Methodological patterns for defining exposures, outcomes, and comorbidities
+using ICD-10 codes in Korean NHIS claims data. This guide covers the validated
+algorithm patterns -- NOT specific code lists for individual diseases.
+
+---
+
+## When to Use
+
+- Defining study populations, exposures, or outcomes in NHIS cohort studies
+- Building claims-based algorithms for disease ascertainment
+- Validating disease definitions using multiple data sources within NHIS
+- NOT for: survey data (KNHANES/NHANES), clinical registry data
+
+---
+
+## Core Principle: Claims-Based Algorithms
+
+A single ICD-10 claim is insufficient for disease ascertainment due to rule-out
+diagnoses, coding errors, and provisional codes. Validated algorithms combine
+multiple data elements to improve positive predictive value.
+
+### Algorithm Components
+
+| Component | Source in NHIS | Purpose |
+|-----------|---------------|---------|
+| **ICD-10 diagnostic codes** | Inpatient + outpatient claims | Primary disease identification |
+| **Medication prescriptions** | Pharmacy dispensing records | Confirms active treatment |
+| **Procedure codes** | Claims procedure fields | Confirms diagnostic workup or treatment |
+| **Health examination results** | National health exam data | Objective measurement (lab values, vitals) |
+| **Visit frequency** | Claim count within time window | Distinguishes incident from rule-out |
+
+---
+
+## Validated Algorithm Patterns
+
+### Pattern 1: N-Claim Rule (Most Common)
+
+Require N or more claims with the target ICD-10 code within a defined time
+window to establish a diagnosis.
+
+```
+Disease = (ICD-10 code X appears >= N times within T months)
+```
+
+| Stringency | Claims | Window | PPV | Use case |
+|------------|--------|--------|-----|----------|
+| Lenient | >= 1 claim | Any | Lower | Screening, sensitivity-focused |
+| Standard | >= 2 claims | 12 months | Moderate | Most cohort studies |
+| Strict | >= 3 claims | 12 months | Higher | Sensitivity analysis |
+
+**Reporting template**:
+"[DISEASE] was identified by at least [N] claims with ICD-10 codes [CODE
+RANGE] within [T] months during the observation period."
+
+### Pattern 2: Claim + Medication (Recommended for Chronic Diseases)
+
+Combine diagnostic codes with disease-specific medication prescriptions.
+
+```
+Disease = (ICD-10 code X >= 1 time) AND (related medication dispensed >= 1 time)
+```
+
+**Reporting template**:
+"[DISEASE] was defined as at least one claim with ICD-10 codes [CODE RANGE]
+combined with a prescription for [MEDICATION CLASS] (ATC codes [RANGE])."
+
+**Common medication validation pairs**:
+
+| Disease category | ICD-10 pattern | Medication confirmation |
+|-----------------|----------------|----------------------|
+| Hypertension | I10-I15 | Antihypertensive agents (ATC C02-C09) |
+| Diabetes mellitus | E10-E14 | Antidiabetic agents (ATC A10) |
+| Hyperlipidemia | E78 | Lipid-modifying agents (ATC C10) |
+| Coronary artery disease | I20-I25 | Antiplatelet + statin combination |
+| Depressive disorders | F32-F33 | Antidepressants (ATC N06A) |
+| Asthma | J45 | Inhaled corticosteroids / bronchodilators |
+
+### Pattern 3: Look-Back Period for Incident Cases
+
+To identify **incident** (new-onset) cases, require a disease-free washout
+period before the index date.
+
+```
+Incident case = (ICD-10 code X after index date)
+              AND (NO claims with code X during look-back period)
+```
+
+| Look-back | Strength | Trade-off |
+|-----------|----------|-----------|
+| 1 year | Minimum acceptable | May misclassify prevalent cases as incident |
+| 3 years | Recommended | Better incident case identification |
+| 5+ years | Strongest | Reduces sample size due to data availability |
+
+**Reporting template**:
+"To ensure the identification of incident cases, we applied a minimum [N]-year
+look-back period and excluded individuals with any diagnostic claims for
+[DISEASE] during this period."
+
+### Pattern 4: Outcome Validation with Time Windows
+
+For complications or sequelae, require temporal proximity to the index event.
+
+```
+Complication = (ICD-10 code Y within T1-T2 days after event X)
+```
+
+**Examples of time-window patterns**:
+
+| Complication type | Window | Rationale |
+|------------------|--------|-----------|
+| Post-procedural complication | 0-30 days | Immediate perioperative period |
+| Delayed complication | 30-90 days | Sub-acute period |
+| Chronic sequela | 90 days - 1 year | Excludes acute phase, captures chronicity |
+| Hospital admission for condition | Within 30 days of onset | Links admission to the triggering event |
+
+### Pattern 5: Hierarchical Disease Classification
+
+When exposure or outcome categories overlap, use a hierarchical scheme.
+
+```
+Level 1 (broadest): Any code in ICD-10 block (e.g., E10-E14 for all diabetes)
+Level 2: Specific subcategory (e.g., E11 for type 2 diabetes only)
+Level 3 (strictest): Subcategory + medication + lab confirmation
+```
+
+Sensitivity analyses should test multiple levels to assess robustness.
+
+---
+
+## ICD-10-KM vs ICD-10 Differences
+
+Korean NHIS uses ICD-10-KM (Korean Modification), which is based on ICD-10
+but includes Korea-specific extensions:
+
+| Feature | ICD-10 (WHO) | ICD-10-KM |
+|---------|-------------|-----------|
+| Base structure | Same alphanumeric codes | Same base + Korean extensions |
+| Additional codes | -- | U-codes for Korean-specific conditions |
+| Version alignment | WHO updates | HIRA publishes annual Korean versions |
+| Medication mapping | ATC codes | ATC codes (same international standard) |
+
+For most major disease categories (cardiovascular, metabolic, respiratory,
+neurological), the ICD-10-KM codes are identical to international ICD-10.
+Country-specific extensions primarily affect rare or culture-bound conditions.
+
+---
+
+## Charlson Comorbidity Index in NHIS
+
+The CCI is computed from claims using the Quan adaptation for ICD-10:
+
+| CCI Category | Standard grouping |
+|-------------|-------------------|
+| 0 | No comorbidities |
+| 1 | Single comorbidity point |
+| >= 2 | Multiple comorbidities |
+
+Always specify which CCI adaptation was used (Quan 2005 is standard for
+ICD-10 claims data).
+
+---
+
+## Covariate Definitions from NHIS Data Sources
+
+NHIS integrates three data sources, each providing different covariate types:
+
+### Source 1: Claims Database
+- Comorbidities (via ICD-10 codes)
+- Medication history (via dispensing records)
+- Healthcare utilization (visit counts, hospitalization days)
+
+### Source 2: National Health Examination
+- BMI, blood pressure, fasting glucose, GFR
+- Liver enzymes (AST, ALT, gamma-GTP)
+- Hemoglobin, total cholesterol
+- Urinalysis
+
+### Source 3: Health Interview / Questionnaire
+- Smoking status (never / former / current)
+- Alcohol consumption (frequency categories)
+- Physical activity (MET-based sufficiency)
+- Region of residence, household income level
+
+**Baseline alignment**: Covariates must be anchored to the most recent data
+available **prior to** the index date. Do not use post-index measurements.
+
+---
+
+## Sensitivity Analysis Patterns
+
+### Stricter Disease Definition
+Run the primary analysis with the standard algorithm, then repeat with a
+more stringent definition (e.g., 2-claim → 3-claim, or adding medication
+confirmation).
+
+### Negative Control Outcomes
+Select outcomes with no plausible biological link to the exposure (e.g.,
+neuromuscular junction disorders, self-harm) to detect residual confounding
+or coding artifacts.
+
+### Negative Control Exposures
+Use an exposure with no expected effect on the outcome as a falsification test.
+
+### Multiple Look-Back Periods
+Test 1-year, 3-year, and 5-year look-back periods and compare incidence rates
+to assess the impact of prevalent case misclassification.
+
+---
+
+## Reporting Checklist
+
+When reporting NHIS claims-based definitions in a manuscript:
+
+- [ ] ICD-10 code ranges specified (main text or supplementary table)
+- [ ] Number of claims required (1 vs 2+ vs with medication)
+- [ ] Time window for claims (within 12 months, any time, etc.)
+- [ ] Look-back period for incident case definition
+- [ ] Medication confirmation specified with ATC codes (if used)
+- [ ] Data source specified (claims vs exam vs questionnaire)
+- [ ] CCI adaptation cited (Quan 2005 or other)
+- [ ] Sensitivity analysis with alternative definition included
+
+---
+
+## Common Reviewer Flags
+
+1. Single-claim definition without justification (low PPV concern)
+2. No look-back period for "incident" cases
+3. Mixing ICD-10 and ICD-9 codes without noting transition dates
+4. Not specifying whether inpatient, outpatient, or both claims were used
+5. CCI version not cited
+6. Covariate timing not anchored to index date
+7. Missing sensitivity analysis with stricter/looser definitions
+8. Rule-out diagnoses not addressed (diagnostic codes without treatment)
+
+---
+
+## References (Methodological)
+
+- Quan H et al. Coding algorithms for defining comorbidities in ICD-9-CM
+  and ICD-10 administrative data. Med Care. 2005;43(11):1130-9.
+- Choi JY et al. Validation of administrative data for the identification
+  of chronic diseases in South Korea. J Korean Med Sci. (methodology reference)
+- NHIS data user guide: nhiss.nhis.or.kr (Korean National Health Insurance
+  Sharing Service)

package/skills/analyze-stats/references/analysis_guides/propensity_score.md

@@ -0,0 +1,132 @@
+# Propensity Score Analysis Guide
+
+Methods for estimating causal treatment effects in observational studies by balancing
+confounders between treatment groups.
+
+---
+
+## When to Use
+
+- Observational study comparing treatment vs control (or two interventions)
+- Multiple confounders to adjust for
+- Goal: estimate causal effect analogous to an RCT
+- NOT for: randomized trials (already balanced), single-arm studies
+
+---
+
+## Estimands — Choose Before Analysis
+
+| Estimand | Definition | Target population | Method |
+|----------|-----------|-------------------|--------|
+| **ATE** | Average Treatment Effect | Entire study population | IPTW |
+| **ATT** | Effect on Treated | Treatment group only | PSM, ATT weighting |
+| **ATO** | Effect on Overlap population | PS 0.2-0.8 region | Overlap weighting |
+
+Comparing PSM and IPTW results directly is inappropriate — they estimate different estimands.
+
+---
+
+## Step-by-Step Workflow
+
+### Step 1: PS Estimation
+- Model: logistic regression (standard)
+- Dependent variable: treatment assignment (binary)
+- Covariates: all variables that affect the outcome (confounders)
+- Do NOT include: instrumental variables (affect treatment but not outcome)
+- Individual PS model coefficients have no clinical meaning — only PS distribution matters
+
+### Step 2: Apply PS Method
+
+**Option A — PS Matching (PSM)**
+- Nearest-neighbor matching with caliper = 0.2 x SD(logit PS)
+- 1:1 matching is standard; 1:N or full matching available
+- Estimand: ATT (typically)
+- Drawback: unmatched subjects are excluded → sample size reduction
+
+**Option B — IPTW (Inverse Probability of Treatment Weighting)**
+- Weights: treated = 1/PS, control = 1/(1-PS) for ATE
+- **Always use stabilized weights** to prevent extreme values
+- Stabilized: treated = P(T=1)/PS, control = P(T=0)/(1-PS)
+- All subjects included (no exclusion)
+- Flag extreme weights > 10
+
+**Option C — SIPTW (Stabilized Inverse Probability of Treatment Weighting)**
+- Weights: treated = P(T=1)/PS, control = P(T=0)/(1-PS)
+- Mathematically equivalent to stabilized IPTW (Option B with stabilized=True)
+- Named explicitly as SIPTW in emulated target trial literature
+- Maintains entire cohort sample size (no exclusion)
+- Allows appropriate variance estimation of main effect
+- Estimand: ATE
+- Increasingly used in large-scale NHIS cohort studies
+- Report effective sample size (ESS) alongside raw N
+
+**Option D — Overlap Weighting (Recommended for most cases)**
+- Weights: treated = (1-PS), control = PS
+- Naturally down-weights subjects at PS extremes
+- No extreme weight problem (advantage over IPTW)
+- Estimand: ATO
+- Increasingly recommended in recent guidelines (JAMA 2020, AJE 2024)
+
+### Step 3: Assess Balance
+- **SMD < 0.10** for all covariates (Austin, 2009)
+- SMD < 0.25 is acceptable but suboptimal
+- Use SMD, NOT p-values (SMD is sample-size independent)
+- **Love plot**: pre/post-matching SMD comparison (mandatory figure)
+- Variance ratios: should be within 0.5-2.0
+- PS distribution overlap: histogram comparing treated vs control
+
+### Step 4: Outcome Analysis
+- **After PSM**: paired analysis (paired t-test, conditional logistic, stratified Cox)
+- **After IPTW/OW**: weighted regression using survey methods
+- Always use robust/sandwich standard errors for weighted analyses
+
+### Step 5: Sensitivity Analysis
+- **E-value**: quantifies how strong unmeasured confounding would need to be to explain away the result
+- Report E-value for the point estimate and lower CI bound
+
+---
+
+## Balance Table (Required Output)
+
+| Variable | Before matching | | After matching | |
+|----------|------|------|------|------|
+| | Treated | Control | SMD | Treated | Control | SMD |
+| Age, mean (SD) | 65.2 (12.1) | 58.7 (14.3) | 0.49 | 62.1 (11.8) | 61.8 (12.0) | 0.03 |
+
+---
+
+## Reporting Templates
+
+**PSM**: "Propensity scores were estimated using logistic regression with the following covariates: [list]. PS matching was performed using 1:1 nearest-neighbor matching with a caliper of 0.2 SD of the logit PS. After matching, all SMDs were below 0.10 (Figure X). In the matched cohort (n = X pairs), ..."
+
+**IPTW/OW**: "Inverse probability of treatment weighting (or overlap weighting) was applied using stabilized weights. Covariate balance was assessed using SMDs (all < 0.10; Figure X). The weighted analysis showed ..."
+
+**SIPTW**: "Stabilized inverse probability of treatment weighting was used to balance covariate distributions between the [exposed] and [unexposed] groups. This approach maintains the sample size of the entire cohort and allows for appropriate estimation of the variance of the main effect. Covariate balance was assessed using SMDs (all < 0.10; Figure X)."
+
+---
+
+## Common Reviewer Flags
+
+1. SMD not reported (using p-values instead)
+2. Caliper width not specified
+3. Estimand (ATE/ATT/ATO) not stated
+4. No sensitivity analysis for unmeasured confounding
+5. Number of unmatched subjects not reported (for PSM)
+6. Extreme weights not assessed (for IPTW)
+7. Individual PS model coefficients interpreted clinically
+
+---
+
+## Python Packages
+- `sklearn.linear_model.LogisticRegression` — PS estimation
+- `causalinference` — matching (limited)
+- Manual implementation for IPTW/OW (see template)
+- `statsmodels` — weighted regression
+
+## R Packages
+- `MatchIt` — PS matching
+- `WeightIt` — IPTW, overlap weighting
+- `cobalt` — balance assessment, Love plot
+- `survey` — weighted outcome analysis
+- `tableone` — baseline table with SMD
+- `EValue` — sensitivity analysis

package/skills/analyze-stats/references/analysis_guides/regression.md

@@ -0,0 +1,115 @@
+# Regression Analysis Guide
+
+Covers both logistic regression (binary outcome) and multiple linear regression (continuous outcome).
+
+---
+
+## Logistic Regression
+
+### When to Use
+Binary outcome variable (0/1, event/no event) with one or more predictors.
+Used for risk factor identification and prediction model building.
+
+### Assumptions
+1. Binary outcome
+2. Linear relationship between continuous predictors and log-odds (Box-Tidwell test)
+3. Independent observations (if repeated → GEE or mixed logistic)
+4. No multicollinearity: VIF < 5
+5. Sufficient sample: EPV >= 10 (minimum), >= 20 (recommended)
+
+### Variable Selection
+- **Clinical rationale first** — avoid purely data-driven stepwise selection
+- Include: variables significant at P < 0.10 in univariable analysis + known confounders
+- STROBE/TRIPOD guideline compliance required
+
+### Model Assessment
+
+**Calibration:**
+- Hosmer-Lemeshow test: P > 0.05 = adequate fit (overpowered with large N)
+- Calibration plot: predicted probability vs observed frequency
+
+**Discrimination:**
+- C-statistic (= AUC): 0.7-0.8 acceptable, 0.8-0.9 excellent, > 0.9 outstanding
+
+**Multicollinearity:**
+- VIF > 5 → remove or combine variables
+
+### Required Outputs
+1. OR table: univariable AND multivariable OR (95% CI), P-value per variable
+2. C-statistic with 95% CI
+3. Hosmer-Lemeshow test result
+4. VIF table (supplementary)
+5. Box-Tidwell results for continuous predictors (supplementary)
+
+### OR Table Format
+| Variable | Univariable OR (95% CI) | P | Multivariable OR (95% CI) | P |
+|----------|------------------------|---|--------------------------|---|
+| Age (per 10 yr) | 1.45 (1.12-1.88) | 0.005 | 1.32 (1.01-1.73) | 0.042 |
+
+### Reporting Template
+"Multivariable logistic regression was performed to identify independent predictors of [outcome]. Variables with P < 0.10 in univariable analysis and clinically relevant confounders were included. The model showed good discrimination (C-statistic = 0.82, 95% CI 0.78-0.86) and calibration (Hosmer-Lemeshow P = 0.45). [Variable] was independently associated with [outcome] (adjusted OR = 2.15, 95% CI 1.43-3.24; P < 0.001)."
+
+### Pitfalls
+- OR != RR: when event rate > 10%, OR overestimates RR
+- EPV < 10 → overfitting risk. Consider penalized regression (LASSO/Ridge)
+- Specify reference category for categorical variables
+- Specify units for continuous variables (per 1 year vs per 10 years)
+- Complete separation → use Firth's penalized likelihood
+
+---
+
+## Multiple Linear Regression
+
+### When to Use
+Continuous outcome variable with one or more predictors.
+Used for identifying determinants and estimating adjusted effects.
+
+### Assumptions (LINE + No Multicollinearity)
+1. **L**inearity: residuals vs fitted plot
+2. **I**ndependence: no repeated measures (if repeated → LMM/GEE)
+3. **N**ormality of residuals: Q-Q plot, Shapiro-Wilk on residuals
+4. **E**qual variance (homoscedasticity): residuals vs fitted, Scale-Location plot
+5. No multicollinearity: VIF < 5
+6. No influential outliers: Cook's distance < 4/n
+
+### Assumption Violations → Alternatives
+| Violation | Fix |
+|-----------|-----|
+| Non-linearity | Log transform, polynomial terms, GAM |
+| Heteroscedasticity | Robust SE, WLS |
+| Non-normal residuals | Transform outcome, bootstrap CI |
+| Multicollinearity | Remove variable, combine, Ridge/LASSO |
+
+### Model Evaluation
+- R² (coefficient of determination): proportion of variance explained
+- Adjusted R²: penalized for number of predictors — use for model comparison
+- In medical research, R² = 0.2-0.4 can be meaningful (high biological variability)
+
+### Diagnostic Plots (4-panel, always generate)
+1. Residuals vs Fitted → linearity + homoscedasticity
+2. Q-Q plot → residual normality
+3. Scale-Location → homoscedasticity
+4. Residuals vs Leverage → influential outliers (Cook's distance)
+
+### Required Outputs
+1. Coefficient table: β (95% CI), P-value per variable
+2. R² and adjusted R²
+3. VIF table
+4. 4-panel diagnostic plot
+5. Standardized coefficients (optional, for effect size comparison)
+
+### Coefficient Table Format
+| Variable | β (95% CI) | P |
+|----------|-----------|---|
+| Age (per year) | 0.45 (0.32 to 0.58) | < 0.001 |
+| Model R² | 0.35 | |
+| Adjusted R² | 0.33 | |
+
+### Reporting Template
+"Multiple linear regression was performed with [outcome] as the dependent variable. The model explained X% of the variance (adjusted R² = 0.XX). After adjusting for [covariates], [variable] was significantly associated with [outcome] (β = X.XX, 95% CI X.XX to X.XX; P = exact). Model assumptions were verified using diagnostic plots."
+
+### Pitfalls
+- Always report β units (per 1 year, per 10 kg/m², etc.)
+- Standardized β useful for comparing effect sizes but unstandardized is standard in papers
+- EPV for continuous outcome: N >= 10-20 per predictor
+- Always present diagnostic plots (at minimum in supplementary)