---
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

| Pitfall | Impact | Fix |
|---------|--------|-----|
| Accounting proxy treated as construct | Measurement risk is hidden behind causal language | Add construct-proxy map and alternative measures |
| Naive TWFE under staggered disclosure mandates | Treatment effects are biased under heterogeneous timing | Add cohort/event-time diagnostics or heterogeneity-robust estimator |
| Fiscal/calendar mismatch | Treatment, reporting, and market response windows do not align | Document fiscal-year and event-date alignment rules |
| Wrong clustering level | Precision ignores mandate, auditor, industry, or market dependence | Cluster at the assignment/reporting channel and test sensitivity |
| Capital-market mechanism assumed | Disclosure effects are interpreted without outcome-channel evidence | Separate price, liquidity, analyst, financing, and governance channels |
| Sample filters undocumented | Archival results are hard to replicate and may be selected | Report observation loss and selection-risk checks |
| Measurement robustness omitted | Accounting reviewers doubt construct validity | Add alternate proxies, source-item checks, or model residual sensitivity |
| Identification robustness omitted | Economics reviewers doubt causal interpretation | Add pretrends, placebo timing, falsification outcomes, or sensitivity analysis |
## 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

- [ ] The causal estimand, identifying variation, accounting construct, empirical proxy, and disclosure or reporting institution are stated before estimator choice.
- [ ] Panel, event-study, DID, IV, or RD models align treatment timing with fiscal-year reporting windows and capital-market outcome windows.
- [ ] Standard errors are justified for firm, industry, auditor, market, state, mandate, or event-level dependence; cluster choice matches assignment and reporting channels.
- [ ] Archival accounting designs report sample filters, winsorization, missingness handling, source items, fiscal timing, and alternative proxy checks; the output must explicitly describe archival accounting measurement risk.
- [ ] Robustness includes at least one construct-validity check and one identification-threat check when causal language is used.
- [ ] Disclosure event studies define announcement dates, event windows, confounding news, information availability, and abnormal return benchmarks.
- [ ] Capital-market outcomes distinguish price reaction, liquidity, cost of capital, analyst behavior, and financing channels.
- [ ] Matched samples, policy comparisons, and staggered mandates state comparison group, timing, pretrend, and selection-risk diagnostics.
- [ ] Result interpretation says which standard is being satisfied: economics identification, accounting measurement, or both.
