Causal Inference: The Mixtape — Code Skill (v3.1)

Practitioner-oriented causal inference: route from the assignment mechanism to
a design, implement it in Python / R / Stata, run the diagnostics that make it
publishable, and write the identification section without over-claiming.

Based on Scott Cunningham's Causal Inference: The Mixtape, extended with 25
Journal of Finance (2021-2024) applications and ML-based causal inference
patterns for DML, causal forests, and heterogeneous treatment effects.

The core Python validation suite runs against the Mixtape's own public
data. python scripts/validate_all.py runs all 13 bundled scripts and asserts
cross-backend agreement — currently 13/13 passing. The DML material in §15 is
reference code and is not part of that 13-script validation suite.

Start here: route the design before writing code

Users describe a setting, not a method. Ask how treatment was assigned, then
route:

How was treatment assigned?
├─ Randomised                          -> diff in means + RI  (09)
├─ Threshold on a running variable     -> RDD / fuzzy / diff-in-disc  (05)
├─ Policy date, one date for all       -> 2x2 DiD -> event study  (02, 03)
├─ Policy date, dates VARY             -> staggered: Bacon -> CS/SA/BJS  (04)
├─ One treated unit, many controls     -> synthetic control  (07)
├─ Self-selected + an instrument       -> IV / 2SLS, identifies a LATE  (06)
├─ Self-selected + rich observables    -> matching / IPW / DML  (08)
└─ None of the above                   -> say so; use associational language

Full tree, estimator choice within each design, and a StatsPAI second opinion
(sp.detect_design, sp.recommend, sp.preflight):
references/design-router.md.

When the design is unsettled, also load references/method-selection.md.
It maps research setting → identifying assumption → method → falsification
check, with Chinese-language explanations and links to worked Stata tutorials.

Python backends: choose by estimator and replication target

import statspai as sp    # pip install statspai

StatsPAI is one supported
Python backend for this skill. It covers a broad Stata/R causal-inference surface
natively — regress, ivregress, reghdfe, csdid, rdrobust, synth,
psmatch2, outreg2 and their R equivalents — plus Bacon decomposition,
Callaway-Sant'Anna, Sun-Abraham, Honest DiD, wild cluster bootstrap, DAG
identification, and Conley SEs.

Do not assume that Python lacks a method; check current implementations first.
Choose StatsPAI, pyfixest, linearmodels, R, or Stata according to estimator
maturity, independent validation, and the replication target. See
references/statspai-guide.md for the StatsPAI API map and cross-backend
checks.

Disclosure: the v3 StatsPAI integration was contributed by StatsPAI's
maintainer. Keep independent cross-checks for headline estimates and do not
treat package choice as an identification argument.

Complementary backends: pyfixest for fast HDFE and an independent wild
bootstrap; linearmodels for deep IV/panel diagnostics; statsmodels for plain
OLS/GLM; and R or Stata when the reference implementation or replication target
requires them.

There is also an MCP server (statspai-mcp): prefer it when the user wants
an answer; prefer generating a script when they want a reproducible artefact.

Methods Covered

Core Workflow

1. Route the design from the assignment mechanism (design-router.md),
   using method-selection.md when the setting or identifying assumption is
   still unclear
2. Load the template from method-patterns.md; use the corresponding
   runnable version in scripts/ when one is listed in the methods table
3. Adapt variable names, FE structure and clustering — cluster at the level
   of treatment assignment (Abadie-Athey-Imbens-Wooldridge 2023)
4. Diagnose with the design's required checks (reporting-checklist.md §3)
5. Report N, cluster count, treated share, baseline mean, and economic
   magnitude — never a t-statistic alone (reporting-checklist.md §1)
6. Write the identification paragraph with a verb the design supports
   (identification-writing-patterns.md §3)

Common Pitfalls

The numbered script references below point to live demonstrations. General
design and DML cautions without a script reference are documentation guidance,
not claims of executed validation.

1. TWFE with staggered treatment. In simulation with effects growing at 1.0
   per period, the true ATT is 6.832 and TWFE reports 3.173 — a 54% understatement.
   Run sp.bacon_decomposition, then report Callaway-Sant'Anna or Sun-Abraham as
   the headline. → sim_twfe_staggered_bias.py
2. Event study with the reference period not actually dropped.
   range(-4, 0) contains −1. Without omitting it the model is collinear and
   there is no normalisation; and endpoints must be binned, not zeroed. → 03
3. Main effects collinear with fixed effects. C(treated)*C(post) alongside
   entity and year FE: statsmodels uses a pseudo-inverse and silently splits the
   coefficient instead of dropping a term. Include the interaction only. → 02
4. "The pre-trends look flat" is not a test. On castle.dta that test has
   power 0.50 individually and 0.14 jointly. Report Honest DiD and the breakdown
   M instead. → 11
5. Too few effective clusters. CRVE is justified as the number of clusters
   grows, but there is no universal safe cutoff: imbalance, leverage, and the
   number of treated clusters matter. Add a small-sample correction when the
   approximation is doubtful. Use randomisation inference only when the
   assignment mechanism justifies the permutations. → 10
6. Clustering finer than assignment. State-year instead of state shrinks the
   SE by 57% on castle.dta. Cluster where treatment was assigned. → 10
7. Manual two-step 2SLS. Reproduces the point estimate exactly and reports
   the wrong standard error; the direction of the error is data-dependent. → 06
8. The forbidden regression. A logit first stage plugged in as a regressor
   is inconsistent — on Card it flips sign versus linear 2SLS. Use it as an
   instrument instead. → 06
9. RDD without a manipulation test. Run sp.rddensity before estimating.
   And put only predetermined variables in the balance table — the treatment
   indicator is supposed to jump. → 05
10. Synthetic control t-ratios. With one treated unit there is no sampling
    distribution. On texas.dta the t-ratio is 7.74 while the permutation
    p-value is 0.18. Report the rank. → 07
11. IPW without checking overlap. Only 30% of CPS controls lie inside the
    treated propensity support. Untrimmed weights put 7% of total weight on one
    observation. And verify whether your library drops or clips — on
    NSW/CPS that is a $9,400 difference. → 08
12. Matching without bias correction or matching-appropriate SEs. With >1
    continuous covariate the Abadie-Imbens bias does not vanish asymptotically,
    and the post-match OLS standard error is wrong. → 08
13. Adding controls is not safer. Colliders and mediators bias you by being
    included. A collider control produces a higher R², a lower residual
    variance, and a t of −78 on a coefficient whose truth is zero. → sim_collider_bias.py
14. Fixed effects absorbing the treatment. county × year FE eats any
    state-level policy. Check what the FE structure consumed.
15. Permutation / bootstrap p-values of exactly 0. The +1 correction is
    not optional; the smallest attainable value is 1/(1+B). → 09
16. Non-causal framing. "Factor X captures the cross-section" is a spanning
    claim. Do not write "causes" without exogenous variation.
    → identification-writing-patterns.md §3
17. Cross-country panels with rich FE. Fixed effects reduce confounds; they
    do not create exogenous variation.
18. Multiple testing. Apply Romano-Wolf or a FDR correction before trusting
    any single α from a scan. → inference-and-standard-errors.md §7
19. DML without cross-fitting. In-sample nuisance predictions reintroduce
    regularisation bias. Use out-of-fold prediction, vary the nuisance learners,
    and remember that DML addresses estimation under high-dimensional controls,
    not identification: an ATE interpretation still requires unconfoundedness.
    → dml-causal-ml.md

Reference Files

Runnable Scripts

scripts/ — 13 validated templates plus _common.py (Mixtape data loader) and
validate_all.py. Run python scripts/validate_all.py --list to see them all,
or --quick to skip the slow one.

Prompt Files

prompts/01-implement-method.md · 02-robustness-checks.md ·
03-finance-application.md · 04-statspai-workflow.md