bacondecomp

Bacon Decomposition of Two-Way Fixed Effects Difference-in-Differences

A Python implementation of the Goodman-Bacon (2021) decomposition, which expresses any two-way fixed effects (TWFE) DiD estimator as a weighted average of all possible 2×2 DiD comparisons. Supports uncontrolled, ddetail, and controlled (FWL) decompositions with optional multi-core parallelism via joblib.

Installation

pip install pybacondecomp

Dependencies: numpy, pandas, pyfixest ≥ 0.25
Optional: joblib (parallel execution), tqdm (progress bars), matplotlib (plots)

Background

In staggered adoption designs, the TWFE estimator is a weighted average of all 2×2 DiD comparisons between pairs of timing groups. Some of these comparisons use already-treated units as the "control" group, which can produce negative weights when treatment effects are heterogeneous across groups or over time.

The decomposition identifies three types of comparisons:

ddetail mode further splits timing-group comparisons into:

• Early vs. Late — earlier-adopting group treated, later-adopting group as not-yet-treated control
• Late vs. Early — later-adopting group treated, earlier-adopting group as already-treated control

Citation

This package is a Python port of the Stata command bacondecomp (v1.0.5, Goodman-Bacon, Goldring & Nichols, 2022). Please cite the original paper when using this package:

Goodman-Bacon, Andrew. "Difference-in-differences with variation in treatment timing." Journal of Econometrics 225, no. 2 (2021): 254–277. https://doi.org/10.1016/j.jeconom.2021.03.014

The original working paper version:

Goodman-Bacon, Andrew. "Difference-in-differences with variation in treatment timing." NBER Working Paper No. 25018, 2018. https://www.nber.org/papers/w25018

BibTeX:

@article{goodman-bacon2021,
  author  = {Goodman-Bacon, Andrew},
  title   = {Difference-in-differences with variation in treatment timing},
  journal = {Journal of Econometrics},
  volume  = {225},
  number  = {2},
  pages   = {254--277},
  year    = {2021},
  doi     = {10.1016/j.jeconom.2021.03.014}
}

The Stata implementation this port is based on:

Goodman-Bacon, Andrew, Thomas Goldring, and Austin Nichols. bacondecomp: Stata module to perform Bacon decomposition of difference-in-differences estimation. Statistical Software Components S458676, Boston College Department of Economics, 2022. https://ideas.repec.org/c/boc/bocode/s458676.html

Usage

Basic (no controls)

import pandas as pd
from pybacondecomp import bacondecomp

result = bacondecomp(
    df,
    y     = "outcome",      # outcome variable
    tr    = "treat",        # binary treatment (0/1, weakly increasing)
    unit  = "state",        # panel unit identifier
    time  = "year",         # time variable
)

print(result.dd_estimate)   # overall TWFE estimate
print(result.summary)       # weighted average by comparison type
print(result.two_by_two)    # every 2×2 DiD comparison

ddetail mode — split Early vs. Late

from pybacondecomp import bacondecomp

result = bacondecomp(df, y="outcome", tr="treat",
                     unit="state", time="year",
                     ddetail=True)

Controlled decomposition (FWL)

from pybacondecomp import bacondecomp

result = bacondecomp(df, y="outcome", tr="treat",
                     unit="state", time="year",
                     x=["log_income", "unemp_rate"])

Parallel execution

from pybacondecomp import bacondecomp

result = bacondecomp(df, y="outcome", tr="treat",
                     unit="state", time="year",
                     n_jobs=-1)   # use all cores

Plot

from pybacondecomp import bacon_plot

fig = bacon_plot(result)
fig.savefig("bacon.png", dpi=150)

Stata-style interface

from pybacondecomp import bacondecomp_stata

result = bacondecomp_stata(df, "outcome treat log_income unemp_rate",
                           unit="state", time="year")

API Reference

bacondecomp(df, y, tr, unit, time, x=None, weights=None, ddetail=False, n_jobs=1, verbose=True)

Returns: BaconResult dataclass with fields:

bacon_plot(result, figsize=(8,5), show_dd_line=True, title=..., ax=None)

Scatter plot of 2×2 estimates vs. weights, by comparison type.

Data Requirements

• Strongly balanced panel: every unit observed at every time period.
• Binary treatment: tr ∈ {0, 1} in all periods.
• Weakly increasing: once treated, units remain treated (no reversals).
• No missing values on y, tr, unit, time, or any x variables.

Stata Correspondence

Validation Against Stata

The following results were produced on a synthetic staggered DiD panel (50 states × 9 years, 4 treatment cohorts: 2001/2003/2005/2007, 14 never-treated states; seed = 42) and cross-validated against Stata's bacondecomp v1.0.5.

The data and Stata do-file are available in tests/stata_verify/.

Branch 1 — no controls, no ddetail

Overall DD: Python = 0.165726 | Stata = 0.16572565

Branch 2 — ddetail (no controls)

Overall DD: Python = 0.165726 | Stata = 0.16572565

All 12 timing-group 2×2 comparisons match to 6 decimal places. Summary:

* Stata reports individual dyad rows; Python summary aggregates identically.

Branch 3 — controlled (FWL, x = log income + unemployment rate)

Overall DD: Python = 0.163864 | Stata = 0.163864

All three branches replicate Stata output to at least 5 significant figures.

License

MIT — see LICENSE.