---
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 |
|---------|--------|-----|
| Treating a noisy accounting proxy as the latent construct | Coefficients are overinterpreted as reporting behavior | Add construct-proxy mapping and alternative measures |
| Hidden fiscal timing mismatch | Reverse timing or look-ahead undermines inference | Align fiscal years, announcement dates, and outcome windows explicitly |
| Undocumented winsorization | Researcher discretion changes effect size | Report thresholds and sensitivity to scaling or trimming |
| Missing Compustat/CRSP or database link rules | Sample cannot be replicated | State merge keys, coverage, duplicate handling, and dropped observations |
| Unjustified fixed effects | Variation is absorbed or interpretation changes | Explain what each fixed effect controls and what variation remains |
| Wrong clustering level | Precision is misleading in firm-year panels | Cluster by the assignment/reporting channel and test robustness |
| Event-window confounding | Disclosure or market reaction is mixed with other news | Define windows and exclude or flag confounding disclosures |
| Measurement robustness omitted | Reviewers doubt construct validity | Add alternate proxies, validation checks, or sensitivity tables |
## 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

- [ ] Model choices match the accounting construct, empirical proxy, sample structure, and identifying variation.
- [ ] Accrual, disclosure, audit, governance, tax, and capital-market measures document source items, transformations, fiscal timing, scaling, and missingness.
- [ ] Standard errors reflect firm, year, industry, auditor, office, state, market, or event-level dependence when the design requires it.
- [ ] Fixed effects are justified by the reporting setting and do not absorb the relevant variation without explanation.
- [ ] Winsorization, trimming, restatement handling, and sample screens are reported with observation-loss counts and selection-risk notes.
- [ ] Accrual models and residual-based proxies include distribution checks, influential-observation diagnostics, and alternative proxy robustness.
- [ ] Disclosure or market-reaction designs define event windows, confounding disclosures, fiscal/calendar alignment, and information-availability timing.
- [ ] Construct-validity checks are separated from identification checks before interpreting coefficients.
- [ ] Central tables include at least one measurement robustness check and one sample-construction sensitivity check.
