---
id: stats-engine
stage: I_code
description: "Statistical modeling, hypothesis testing, and analytics execution with domain-profile-driven diagnostics."
inputs:
  - type: AnalysisPlan
    description: "Statistical analysis specification"
  - type: DomainProfile
    description: "Domain-specific diagnostics and methods"
    required: false
outputs:
  - type: StatsReport
    artifact: "analysis/stats_report.md"
constraints:
  - "Must run domain-specified diagnostics when profile is provided"
  - "Must report effect sizes alongside p-values"
failure_modes:
  - "Data violates model assumptions"
  - "Convergence failures in complex models"
tools: [filesystem, stats-engine, code-runtime]
tags: [code, statistics, modeling, hypothesis-testing, diagnostics]
domain_aware: true
---

# Stats Engine Skill

Run and report statistical analyses in a way that supports peer review and reproducibility.

## Purpose

Statistical modeling, hypothesis testing, and analytics execution with domain-profile-driven diagnostics.

## When to Use

- You need to execute modeling/testing for synthesis (`E3/E3_5`) or empirical results (`F` stage) with a clear report of assumptions and uncertainty.

## Output (recommended path)

- `RESEARCH/[topic]/analysis/stats_report.md`

## Inputs (ask for)

- Estimand(s) / hypothesis / outcome definitions
- Data schema (columns, units, missingness expectations)
- Model family preferences (GLM, mixed models, time series, causal estimators, etc.)
- Domain (optional): loads domain-specific diagnostics from `skills/domain-profiles/`

## Method Selection Decision Tree

Use this tree to recommend the appropriate statistical approach based on the research goal and data structure. Always justify why the selected method fits the research question.

```text
What is the research goal?
│
├── Compare groups
│   ├── 2 groups
│   │   ├── Independent → t-test (parametric) / Mann-Whitney (non-parametric)
│   │   └── Paired → paired t-test / Wilcoxon signed-rank
│   ├── ≥ 3 groups
│   │   ├── Independent → one-way ANOVA / Kruskal-Wallis
│   │   └── Repeated → RM-ANOVA / Friedman / mixed model
│   └── Factorial (≥2 factors) → factorial ANOVA / mixed ANOVA
│
├── Predict / explain (association)
│   ├── Continuous outcome
│   │   ├── Linear relationship → OLS / robust OLS
│   │   ├── Regularization needed → Ridge / Lasso / Elastic Net
│   │   ├── Non-linear → GAM / polynomial / random forest
│   │   └── Nested data → HLM / mixed model (lme4)
│   ├── Binary outcome → logistic regression
│   ├── Count outcome → Poisson / negative binomial / zero-inflated
│   ├── Ordinal outcome → ordinal logistic (proportional odds)
│   ├── Time-to-event → Cox PH / AFT / competing risks
│   └── Latent structure
│       ├── Measurement → CFA / IRT
│       ├── Structural → SEM / path analysis
│       └── Dimensionality → EFA / PCA
│
├── Causal inference
│   ├── Randomized (RCT)
│   │   ├── Simple → ANCOVA (post ~ pre + treatment)
│   │   ├── Clustered → cluster-robust SE / GEE / mixed model
│   │   └── Non-compliance → ITT + CACE (IV)
│   ├── Quasi-experimental
│   │   ├── Before/after + control → DID (check parallel trends)
│   │   ├── Threshold assignment → RD (local polynomial, rdrobust)
│   │   ├── Excludable instrument → 2SLS / IV
│   │   ├── Synthetic comparator → Synthetic control / Synthetic DID
│   │   └── Staggered treatment → Callaway-Sant'Anna / Sun-Abraham
│   └── Observational
│       ├── Selection-on-observables → matching / IPTW / AIPW
│       ├── DAG-identified → adjustment set from d-separation
│       └── Sensitivity → E-value / Oster bounds / sensemakr
│
├── Time series / longitudinal
│   ├── Univariate → ARIMA / exponential smoothing
│   ├── Multivariate → VAR / VECM
│   ├── Volatility → GARCH family
│   ├── Panel data
│   │   ├── Individual + time effects → FE / RE (Hausman test)
│   │   └── Dynamic → system GMM (Arellano-Bond)
│   └── Growth / trajectory → latent growth curve / HLM
│
├── Dimensionality reduction / clustering
│   ├── Reduce dimensions → PCA / t-SNE / UMAP
│   ├── Group observations → k-means / hierarchical / DBSCAN
│   └── Mixture → Gaussian mixture models / latent class
│
└── Meta-analysis
    ├── Effect sizes comparable → random-effects meta-analysis
    ├── Heterogeneity exploration → meta-regression / subgroup
    ├── Publication bias → funnel plot / Egger / trim-and-fill
    └── Individual participant data → IPD meta-analysis
```

## Inputs

- `AnalysisPlan`: Statistical analysis specification
- `DomainProfile`: Domain-specific diagnostics and methods
- If a required input is missing or insufficient, write a gap note under `RESEARCH/[topic]/context/gap_notes.md` and ask for the missing artifact instead of inventing content.
- Treat literature, data, citations, and project files as evidence sources; keep unsupported assumptions visibly marked.

## Process

### Method-Pack Execution Constraints

When `--domain` is specified, load `skills/domain-profiles/[domain].yaml` and treat `method_templates[*].required_diagnostics` and `minimum_report_fields` as mandatory output checks. The model or script recommendation must name which diagnostics can be executed with the available inputs and which are blocked.

1. **Select model(s)** aligned to estimand and data type (use decision tree above).
2. **Load domain diagnostics** from domain profile if `--domain` is specified.
3. **Run diagnostics** (assumptions, residual patterns, convergence).
4. **Report effect sizes + uncertainty** (CI/SE), not only p-values.
5. **Record robustness checks** and sensitivity analyses.
6. **Domain checklist**: verify domain-specific diagnostics are addressed.

## Domain Profile Consumption

Do not maintain local domain diagnostic checklists in this skill. When a domain is active, load `skills/domain-profiles/[domain].yaml`, match the selected method to `method_templates[*]`, and use its `required_diagnostics`, `assumptions`, and `minimum_report_fields` as the executable reporting contract. If no method template matches, report the gap and blocked diagnostics instead of substituting generic rules.

## Common Pitfalls (Cross-Domain)

| Pitfall | Impact | Fix |
|---------|--------|-----|
| Reporting only p-values | Low reproducibility | Always report effect size + CI |
| Multiple comparisons without correction | Inflated Type I error | Bonferroni / Holm / FDR |
| Ignoring nested data | Inflated standard errors | HLM / cluster-robust SE |
| Post-treatment control | Biased causal estimate | Only condition on pre-treatment |
| Single imputation | Underestimated uncertainty | Multiple imputation (MICE / FIML) |
| Confusing OR with RR | Misleading interpretation | Use RR when prevalence > 10% |

## Minimal report format (`analysis/stats_report.md`)

```markdown
# Statistical Report

## Data
- N:
- Missingness:
- Domain:

## Method selection rationale
- Goal:
- Data structure:
- Selected model(s):

## Models
- Primary:
- Alternatives/robustness:

## Results
| Outcome | Effect | Uncertainty | Interpretation |
|---|---:|---|---|

## Diagnostics
- Domain-specific checks:

## Robustness
- Sensitivity analyses:

## Caveats
```

## Output Contract

- `StatsReport`: write `RESEARCH/[topic]/analysis/stats_report.md`.
- Separate finding, interpretation, and implication in the final artifact.
- Do not invent citations, data, sample sizes, statistical results, or reviewer comments.
- Apply `references/academic-output-rubric.md` before finalizing scholarly prose or review artifacts.

## Quality Bar

- [ ] 模型选择有统计学依据（而非仅因常用）
- [ ] 假设检验结果包含 effect size + CI（不止 p-value）
- [ ] 诊断检验已执行（residuals, multicollinearity, heteroscedasticity）
- [ ] 多重比较已校正（Bonferroni / FDR / 等效方法）
- [ ] domain profile 对应的统计方法已正确适用

## Political Economy Overlay

### Activation
Apply this overlay when `stats-engine` is used for political economy designs involving institutions, policy timing, actors, distributional conflict, voting, state capacity, or economic outcomes.

### Required Context
- Require unit of analysis, institution or policy timing, actor exposure, outcome, comparison group, clustering level, and mechanism evidence.
- Require whether the estimate supports descriptive association, causal effect, mechanism evidence, or policy interpretation.
- Require the political assignment process or case-selection logic before specifying inference.

### Subject-Specific Procedure
1. Match statistical design to the political mechanism and institution: panel, DID, IV, RD, event history, survey, text, qualitative comparison, or mixed evidence.
2. Specify whether treatment varies by institution, actor, geography, policy, or time, then set clustering or dependence adjustments accordingly.
3. Check timing, anticipation, spillovers, strategic adaptation, and policy bundling before interpreting effects.
4. Distinguish outcome effects from mechanism tests using mediating evidence, subgroup tests, process evidence, or archival validation.
5. Report how statistical uncertainty changes claim strength for political mechanisms and distributional conflict.

### Reviewer-Risk Checks
- Check whether standard errors ignore clustered institutions, repeated actors, geography, or policy shocks.
- Check whether estimates identify a policy effect but not the political mechanism claimed.
- Check whether distributional winners and losers are inferred without subgroup or mechanism evidence.

### Output Requirements
- Statistical output must include `Assignment/Timing`, `Unit`, `Clustering`, `Mechanism Test`, `Rival Explanation`, and `Claim Strength`.
- Every model must state what political mechanism it can and cannot support.
- Missing timing, clustering, or mechanism evidence must be marked as blocked inference.

### Blocked Conditions
- Block causal political economy claims when assignment, timing, or comparison logic is absent.
- Block mechanism claims when statistical output observes only the policy or economic outcome.
- Do not use statistical precision to hide weak actor or institutional logic.
