diff-diff

A Python library for Difference-in-Differences (DiD) causal inference - sklearn-like estimators with statsmodels-style outputs, built for econometricians, marketing analysts, and data scientists running campaign-lift, policy, and staggered-rollout analyses.

Installation

pip install diff-diff

For development:

git clone https://github.com/igerber/diff-diff.git
cd diff-diff
pip install -e ".[dev]"

Quick Start

import pandas as pd
from diff_diff import DifferenceInDifferences  # or: DiD

data = pd.DataFrame({
    'outcome': [10, 11, 15, 18, 9, 10, 12, 13],
    'treated': [1, 1, 1, 1, 0, 0, 0, 0],
    'post': [0, 0, 1, 1, 0, 0, 1, 1],
})

did = DifferenceInDifferences()
results = did.fit(data, outcome='outcome', treatment='treated', post='post')
print(results)              # DiDResults(ATT=3.0000, SE=1.7321, p=0.1583)
results.print_summary()     # full statsmodels-style table

Documentation

• Quickstart - basic 2x2 DiD with column-name and formula interfaces, covariates, fixed effects, cluster-robust SEs
• Choosing an Estimator - decision flowchart for picking the right estimator
• Tutorials - hands-on Jupyter notebooks covering every estimator and design pattern
• Troubleshooting - common issues and solutions
• R Comparison | Python Comparison | Benchmarks - validation results vs did, synthdid, fixest
• API Reference - full API for all estimators, results classes, diagnostics, utilities

For AI Agents

If you are an AI agent or LLM using this library, call diff_diff.get_llm_guide() for a concise API reference with an 8-step practitioner workflow (based on Baker et al. 2025). The workflow ensures rigorous DiD analysis - testing assumptions, running sensitivity analysis, and checking robustness, not just calling fit().

from diff_diff import get_llm_guide

get_llm_guide()                 # concise API reference
get_llm_guide("practitioner")   # 8-step workflow (Baker et al. 2025)
get_llm_guide("full")           # comprehensive documentation
get_llm_guide("autonomous")     # autonomous-agent variant

The guides are bundled in the wheel - accessible from a pip install with no network access. After estimation, call practitioner_next_steps(results) for context-aware guidance on remaining diagnostic steps.

For Data Scientists

Measuring campaign lift? Evaluating a product launch? Rolling out a policy in waves? diff-diff handles the causal inference so you can focus on the business question.

• Which method fits my problem? - start from your business scenario (campaign in some markets, staggered rollout, survey data) and find the right estimator
• Getting started for practitioners - end-to-end walkthrough from marketing campaign to causal estimate to stakeholder-ready result
• Brand awareness survey tutorial - full example with complex survey design, brand funnel analysis, and staggered rollouts
• Have BRFSS/ACS/CPS individual records? Use aggregate_survey() to roll respondent-level microdata into a geographic-period panel with inverse-variance precision weights for second-stage DiD

BusinessReport and DiagnosticReport are experimental preview classes that produce plain-English output and a structured to_dict() schema from any fitted estimator result except the two rejected by type (EventStudyResults surfaces and DurationDiDResults) - wording and schema will evolve. See docs/methodology/REPORTING.md for usage and stability notes.

Practitioner Workflow (Baker et al. 2025)

For rigorous DiD analysis, follow these 8 steps. Skipping diagnostic steps produces unreliable results.

1. Define target parameter - ATT, group-time ATT(g,t), or event-study ATT_es(e). State whether weighted or unweighted.
2. State identification assumptions - which parallel trends variant (unconditional, conditional, PT-GT-Nev, PT-GT-NYT), no-anticipation, overlap.
3. Test parallel trends - simple 2x2: check_parallel_trends(), equivalence_test_trends(); staggered: inspect CS event-study pre-period coefficients (generic PT tests are invalid for staggered designs). Insignificant pre-trends do NOT prove PT holds.
4. Choose estimator - staggered adoption -> CS/SA/BJS (NOT plain TWFE); few treated units -> SDiD; factor confounding -> TROP; simple 2x2 -> DiD. Run BaconDecomposition to diagnose TWFE bias.
5. Estimate - estimator.fit(data, ...). Always print the cluster count first and choose inference method based on the result (cluster-robust if >= 50 clusters, wild bootstrap if fewer - for DifferenceInDifferences pass cluster=; TwoWayFixedEffects auto-clusters at unit level).
6. Sensitivity analysis - compute_honest_did(results) for bounds under PT violations (the TwoWayFixedEffects event_study=True surface, CS, or dCDH natively; a StackedDiD results.aggregate('event_study') container also admits - Stacked needs kappa_pre >= 2), run_all_placebo_tests() for 2x2 falsification, specification comparisons for staggered designs.
7. Heterogeneity - CS: results.aggregate('group')/'event_study' (post-fit, no refit); SA: results.event_study_effects / to_dataframe(level='cohort'); Stacked: results.aggregate('event_study')/'simple' post-fit views (surface always computed since 3.9); EDiD: results.aggregate(...) post-fit from retained EIFs (3.9); ImputationDiD/TwoStageDiD: results.aggregate(...) post-fit from panel-backed kits (3.9); ContinuousDiD: results.aggregate('dose'/'simple'/'event_study') post-fit (3.9; dose/simple are views, event_study recomputes); subgroup re-estimation.
8. Robustness - compare 2-3 estimators (CS vs SA vs BJS), report with and without covariates (shows whether conditioning drives identification), present pre-trends and sensitivity bounds.

Full guide: diff_diff.get_llm_guide("practitioner").

Estimators

• DifferenceInDifferences - basic 2x2 DiD with robust/cluster-robust SEs, wild bootstrap, formula interface, and fixed effects
• TwoWayFixedEffects - panel data DiD with unit and time fixed effects via within-transformation or dummies; event-study mode (event_study=True) for period-specific treatment effects
• CallawaySantAnna - Callaway & Sant'Anna (2021) group-time ATT estimator for staggered adoption
• ChaisemartinDHaultfoeuille - de Chaisemartin & D'Haultfœuille (2020/2022) for reversible (non-absorbing) treatments with multi-horizon event study, normalized effects, cost-benefit delta, sup-t bands, and dynamic placebos. The most general option for treatments that switch on AND off (see also LPDiD/TROP non_absorbing). Alias DCDH.
• SunAbraham - Sun & Abraham (2021) interaction-weighted estimator for heterogeneity-robust event studies
• ImputationDiD - Borusyak, Jaravel & Spiess (2024) imputation estimator, most efficient under homogeneous effects
• TwoStageDiD - Gardner (2022) two-stage estimator with GMM sandwich variance
• SpilloverDiD - Butts (2021) ring-indicator spillover-aware DiD identifying direct effect on treated + per-ring spillover on near-control units; handles non-staggered and staggered timing; supports survey-design variance under survey_design= for HC1 / CR1 (Wave E.1 Binder TSL) and Conley (Wave E.2 panel-aware stratified-Conley sandwich on per-period PSU totals; extended in Wave E.2 follow-up to conley_lag_cutoff > 0 via panel-block composition with within-PSU serial Bartlett HAC — lag>0 requires an effective PSU via explicit survey_design.psu or injected cluster=<col>); SurveyDesign.subpopulation() preserves full-design n_psu / df_survey via zero-padded scores (Wave E.3, R svyrecvar(subset()) form)
• SyntheticDiD - Synthetic DiD combining standard DiD and synthetic control for few treated units
• SyntheticControl - Abadie, Diamond & Hainmueller (2010) classic synthetic control for a single treated unit (donor-weight counterfactual, nested/cv/inverse-variance/custom V; in-space placebo permutation inference via in_space_placebo(), plus ADH-2015 leave_one_out() + in_time_placebo() robustness, Firpo-Possebom (2018) test-inversion confidence sets, and Chernozhukov-Wüthrich-Zhu (2021) conformal inference)
• TripleDifference - triple difference (DDD) estimator for designs requiring two criteria for treatment eligibility; serves both the 2x2x2 and the staggered-adoption design (Ortiz-Villavicencio & Sant'Anna (2025) staggered DDD with group-time ATT) from one signature (fit(..., first_treat=) selects the staggered engine)
• ContinuousDiD - Callaway, Goodman-Bacon & Sant'Anna (2024) continuous treatment DiD with dose-response curves
• HeterogeneousAdoptionDiD - de Chaisemartin, Ciccia, D'Haultfœuille & Knau (2026) for designs where no unit remains untreated; local-linear estimator at the dose support boundary returning Weighted Average Slope (WAS) on Design 1' (d̲ = 0 / QUG) or WAS_{d̲} on Design 1 (d̲ > 0, continuous-near-d̲ or mass-point), with a multi-period event-study extension (last-treatment cohort, pointwise CIs). Panel-only in this release - repeated cross-sections rejected by the validator. Alias HAD.
• RegressionDiscontinuity - Calonico, Cattaneo & Titiunik (2014) sharp, fuzzy, AND covariate-adjusted regression discontinuity with robust bias-corrected inference and rdrobust-parity bandwidth selection (all 10 selectors, mass-point handling; fuzzy via takeup= with a first-stage block and weak-identification warning; covariates via covariates= - CCFT 2019, same estimand, covariate-aware bandwidths). Canonical att is the bias-corrected estimate with a coherent robust CI (rdrobust's printed headline is att_conventional). Alias RDD.
• StackedDiD - Wing, Freedman & Hollingsworth (2024) stacked DiD with Q-weights and sub-experiments; optional covariate balancing (Ustyuzhanin 2026)
• EfficientDiD - Chen, Sant'Anna & Xie (2025) efficient DiD with optimal weighting for tighter SEs
• TROP - Triply Robust Panel estimator (Athey et al. 2025) with nuclear norm factor adjustment
• WooldridgeDiD - Wooldridge (2023, 2025) ETWFE: saturated OLS, logit/Poisson QMLE (ASF-based ATT). Alias ETWFE.
• LPDiD - Dube, Girardi, Jorda & Taylor (2025) Local Projections DiD: per-horizon long-difference event study on clean controls (no negative weighting), variance- or equally-weighted ATT, for absorbing or non-absorbing (reversible) treatment
• ChangesInChanges - Athey & Imbens (2006) nonlinear/distributional DiD for the 2x2 design: full counterfactual distribution and quantile treatment effects via CDF transformation, plus the QDiD comparison estimator via method="qdid"; bootstrap inference; R qte parity. Alias CiC
• LWDiD - Lee & Wooldridge (2025, 2026) rolling-transformation DiD: unit-specific demean/detrend converts panel to cross-section, staggered adoption, estimation_method in reg/ipw/dr/psm (the papers' RA/IPW/IPWRA plus propensity-score matching), exact small-N inference on the classical collapsed regression
• DMLDiD - Chang (2020) double/debiased machine learning DiD: staggered ATT(g,t) with cross-fitted ML nuisance learners (DML2) and Neyman-orthogonal scores, for flexible/high-dimensional covariate adjustment under conditional parallel trends; panel or declared repeated cross sections (panel=False); survey/cluster support on both lanes (bad-control lane: panel only, cluster= only); Caetano, Callaway, Payne & Sant'Anna (2026) bad-control score via fit(bad_control=, bad_control_covariates=)
• DurationDiD - Deaner & Ku (2026) causal duration DiD for a binary absorbing outcome (spell ended) in a two-group common-timing design: restricts the groups' untreated hazards (method="cd" additive gap or method="ph" ratio) instead of outcome levels, imputes the treated counterfactual survival, reports the per-date absorption ATT with whole-individual bootstrap pointwise and simultaneous bands plus a fixed-anchor pre-treatment specification test

Diagnostics & Sensitivity

• Bad-control pre-test - Caetano, Callaway, Payne & Sant'Anna (2026) Remark 6 ATT_X(g,t): the effect of treatment on a suspected bad control itself, per (g,t) cell (DMLDiDResults.bad_control_summary(); analytical SE; pre-period rows pre-test the identifying assumptions MP-5 / MP-8 and should be zero, post-period rows are the Condition-2 check that treatment affects the covariate)
• RD Plots - Calonico, Cattaneo & Titiunik (2015) optimal data-driven RD plots (RDPlot): all 8 rdrobust binselect bin selectors, implied-scale/WIMSE-weight reporting, optional matplotlib rendering
• Manipulation Testing - Cattaneo, Jansson & Ma (2020) density-discontinuity test (RDDensityTest): rddensity 3.0 parity, robust bias-corrected inference, unrestricted/restricted models, mass-point adjustment
• Parallel Trends Testing - simple and Wasserstein-robust parallel trends tests, equivalence testing (TOST)
• Placebo Tests - placebo timing, group, permutation, leave-one-out
• TWFE Weight Diagnostics - Baker et al. (2025) implicit weights a TWFE regression places on each ATT(g,t), against the ATT^O / ATT^simple targets, with the pre-period contribution. Ports Callaway's twfeweights (MIT)
• Bacon Decomposition - Goodman-Bacon (2021) decomposition of the TWFE estimate into its 2x2 comparisons and weights, for diagnosing TWFE bias in staggered settings (BaconDecomposition, alias Bacon)
• Honest DiD - Rambachan & Roth (2023) sensitivity analysis: robust CI under PT violations, breakdown values
• Pre-Trends Power Analysis - Roth (2022) minimum detectable violation and power curves
• Power Analysis - analytical and simulation-based MDE, sample size, power curves for study design
• MMM Calibration Export - convert experiment results into MMM calibration inputs: PyMC-Marketing lift-test frames and Google Meridian lognormal ROI priors
• Conley spatial HAC SE (vcov_type="conley") on cross-sectional LinearRegression / compute_robust_vcov plus panel DifferenceInDifferences / TwoWayFixedEffects (with conley_lag_cutoff for within-unit Bartlett temporal HAC) - Conley (1999) spatial-correlation-aware SEs with parity vs R conleyreg on cross-sectional + panel fixtures, optional combined spatial + cluster product kernel via explicit cluster=, auto-activating sparse k-d-tree fast path for n > 5_000

Survey Support

Most estimators accept an optional survey_design parameter (or survey= / weights= for HeterogeneousAdoptionDiD) for design-based variance estimation. Coverage and supported weight types vary by estimator - see the Survey Design Support compatibility matrix for the per-estimator support table.

• Design elements available across the supported set: strata, PSU, FPC, lonely PSU handling, nest. Weight types vary by estimator: some surfaces (e.g. CallawaySantAnna, StackedDiD, the HAD continuous path) accept pweight only; others accept pweight / fweight / aweight.
• Variance methods: Taylor Series Linearization (TSL via Binder 1983), replicate weights (BRR / Fay / JK1 / JKn / SDR), survey-aware bootstrap
• Diagnostics: DEFF per coefficient, effective n, subpopulation analysis, weight trimming, CV on estimates
• Repeated cross-sections: CallawaySantAnna(panel=False) for BRFSS, ACS, CPS
• Weight calibration / raking: upstream by design - pair with Meta's balance package, whose balance.interop.diff_diff adapter hands raked samples straight to diff-diff; see the composition-drift tutorial

No other Python or R DiD package offers design-based variance estimation for modern heterogeneity-robust estimators.

Requirements

• Python 3.9 - 3.15
• numpy >= 1.20
• pandas >= 1.3
• scipy >= 1.10

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black diff_diff tests
ruff check diff_diff tests

References

This library implements methods from a wide body of econometric and causal-inference research. See the full bibliography on Read the Docs for citations spanning DiD foundations, modern staggered estimators, sensitivity analysis, and synthetic controls.

Citing diff-diff

If you use diff-diff in your research, please cite it:

@software{diff_diff,
  title = {diff-diff: Difference-in-Differences Causal Inference for Python},
  author = {Gerber, Isaac},
  year = {2026},
  url = {https://github.com/igerber/diff-diff},
  doi = {10.5281/zenodo.19646175},
  license = {MIT},
}

The DOI above is the Zenodo concept DOI - it always resolves to the latest release. To cite a specific version, look up its versioned DOI on the Zenodo project page.

See CITATION.cff for the full citation metadata.

Note on authorship: academic citation (CITATION.cff, the BibTeX above) lists individual authors with ORCIDs per scholarly convention. Package metadata surfaces (pyproject.toml, Sphinx docs) list "diff-diff contributors" to acknowledge the collective - see CONTRIBUTORS.md for the full list.

License

MIT License