panelmed

What it does

A treatment often changes an outcome through an intermediate variable. Employment raises local income partly because it raises wages. panelmed splits the total effect into the part that goes through the mediator and the part that does not, using repeated observations of the same units to remove any time-invariant confounder.

Installation

pip install panelmed

With interactive 3-D surfaces:

pip install "panelmed[plotly]"

Requirements: Python 3.10 or later, with numpy, scipy, pandas, matplotlib, scikit-learn and joblib (installed automatically).

Theory

Step → equation map

Every block of code is tied to a numbered equation of the paper. The full map is in docs/methods.md.

Check against the paper

Monte Carlo design of the paper's Table 1 (\(N = 1600\), \(T = 10\)); 300 replications here, 1,000 in the paper.

API and syntax

Complete example with real data

The application of the paper (Section 6): 3,058 U.S. counties, 2001–2019. Treatment: workplace employment rate. Outcome: log personal income per capita. Mediator: log average wage per job. Eight lagged county characteristics are the covariates. All variables are winsorised and standardised, so effects are in standard deviations.

Step 1 — load the data

from panelmed import PanelMediation, compare_effects, load_us_counties
from panelmed.datasets import US_COUNTIES_COVARIATES as X

df = load_us_counties()          # 3,058 counties x 19 years, prepared as in the paper

Step 2 — two specifications

common = dict(data=df, unit="county_id", time="year", basis_degree=3, basis_max_vars=2)

# I: the same effect in every county
spec1 = PanelMediation("y", "m", "d", X, outcome=["d", "m"], mediator=["d"], **common)
res1 = spec1.fit(n_folds=5, max_lags=2, seed=2026)

# II: effects vary with county characteristics
inter = [f"d*{c}" for c in X]
spec2 = PanelMediation("y", "m", "d", X, outcome=["d", "m"] + inter,
                       mediator=["d"] + inter, **common)
res2 = spec2.fit(n_folds=5, max_lags=2, seed=2026)

Specification I uses 99 moment conditions for 3 parameters and Specification II 627 for 19, the same counts as in the paper.

Step 3 — effects averaged over 2001–2019

eff1 = res1.derivatives(d=0, period="average")
eff2 = res2.derivatives(d=0, period="average")
print(eff1.summary())
print(eff2.summary())

*** p<0.01, ** p<0.05. Analytical standard errors from influence functions (Eq. 21).

Step 4 — does the decomposition change?

print(compare_effects(eff1, eff2))

The total effect is the same in both specifications. The share going through wages falls from about two thirds to about 40%.

Step 5 — figures

eff2.plot()
res2.derivatives(d=0, period="all").plot_profile()
res2.plot_dose_response()
res2.plot_surface()
res1.plot_moments()

Interpreting the output

Beyond the paper

These are additions to the original method.

References

1. Wu, P. and Xiao, Z. (2026). Causal Mediation Analysis for Panel Data with Double/Debiased Machine Learning. arXiv:2610.21339. doi:10.48550/arXiv.2610.21339
2. Wu, P. and Xiao, Z. (2026). Double/Debiased Machine Learning for Treatment Effects in Dynamic Panels. Journal of the American Statistical Association. doi:10.1080/01621459.2026.2696607
3. Chernozhukov, V., Chetverikov, D., Demirer, M., Duflo, E., Hansen, C., Newey, W. and Robins, J. (2018). Double/debiased machine learning for treatment and structural parameters. The Econometrics Journal, 21(1), C1–C68. doi:10.1111/ectj.12097
4. Kapetanios, G. (2008). A bootstrap procedure for panel data sets with many cross-sectional units. The Econometrics Journal, 11(2), 377–395. doi:10.1111/j.1368-423X.2008.00243.x
5. Hansen, L. P. (1982). Large sample properties of generalized method of moments estimators. Econometrica, 50(4), 1029–1054. doi:10.2307/1912775
6. Cerqua, A., Letta, M. and Pinto, G. (2026). On the (mis)use of machine learning with panel data. Oxford Bulletin of Economics and Statistics, 88(3), 506–518. doi:10.1111/obes.70019

Author and citation

Copy@software{roudane_panelmed,
  author  = {Roudane, Merwan},
  title   = {{panelmed}: causal mediation analysis
             for panel data with double/debiased
             machine learning},
  year    = {2026},
  url     = {https://github.com/merwanroudane/panelmed},
  version = {0.1.1}
}