---
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 |
|---------|--------|-----|
| Look-ahead bias | Creates false predictability or overstated alpha | Construct signals using only information available at portfolio formation |
| Survivorship bias | Overstates returns and weakens external validity | Include delisted, failed, or missing firms when the research question requires them |
| Weak benchmark model | Mislabels risk compensation as abnormal performance | Test alternative factor models and report risk-adjusted sensitivity |
| Overlapping returns | Understates standard errors | Use Newey-West, block bootstrap, or design-appropriate corrections |
| Event-date leakage | Confounds CAR interpretation | Audit announcement timing, anticipation, and nearby events |
| Stale prices or microstructure noise | Creates spurious short-window returns | Add liquidity screens, trade timing checks, or lower-frequency robustness |
| Fama-MacBeth used mechanically | Cross-sectional inference may not match design | State pricing test, risk premia logic, and time-series correction |
| Causal overclaiming in corporate finance | Reviewer rejects interpretation despite strong association | Add identification evidence or narrow to association/risk-adjusted result |
## 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

- [ ] Asset pricing claims define test assets, factor model, return frequency, sample window, portfolio formation date, rebalancing rule, and risk-adjusted benchmark; the report must explicitly label the asset pricing evidence standard being used.
- [ ] Return construction handles delisting returns, dividends, splits, stale prices, survivorship bias, microstructure filters, and look-ahead bias.
- [ ] Event studies define event dates, estimation windows, event windows, expected-return model, confounding-event filters, CAR/BHAR tests, and announcement leakage checks.
- [ ] Corporate finance panels document fixed effects, clustering, timing, treatment definition, comparison group, and identification threats.
- [ ] Inference matches the data structure: Fama-MacBeth, Newey-West, two-way clustering, portfolio-sort tests, bootstrap, or event-time corrections.
- [ ] Factor exposure, benchmark sensitivity, and alternative risk models are reported for abnormal return, alpha, or risk-adjusted claims.
- [ ] Overlapping observations, repeated events, cross-sectional dependence, and calendar-time clustering are handled explicitly.
- [ ] Causal corporate policy claims separate identification evidence from risk-adjusted association.
- [ ] Every finance result states whether it supports alpha, risk compensation, mispricing, liquidity, corporate policy, or descriptive market behavior.
