from _api_doc_utils import *SyntheticDID
Synthetic difference-in-differences for balanced panels
1 Where it fits
Group: Causal inference
SyntheticDID combines donor-unit weights and pre-period time weights. It estimates counterfactual treated outcomes by reweighting both units and periods, then reports ATT and event-time summaries under the common fit(Y, W) panel contract.
2 Cohort weights and ATT
For each adoption cohort \(g\), the estimator uses only never-treated controls. Let \(Y_{C,\mathrm{pre}}\) be the control-by-pre-period matrix, \(\bar Y_{g,\mathrm{pre}}\) the treated-cohort pre-period mean, and \(\bar Y_{C,\mathrm{post}}\) each control unit’s post-period mean. Unit and time weights solve
\[ \min_{a,\ \omega\in\Delta_C} \frac{1}{2T_{\mathrm{pre}}} \|\bar Y_{g,\mathrm{pre}}-a\mathbf1-Y_{C,\mathrm{pre}}'\omega\|_2^2 +\frac{\zeta_\omega^2}{2}\|\omega\|_2^2, \]
\[ \min_{b,\ \lambda\in\Delta_{T_{\mathrm{pre}}}} \frac{1}{2C} \|\bar Y_{C,\mathrm{post}}-b\mathbf1-Y_{C,\mathrm{pre}}\lambda\|_2^2 +\frac{\zeta_\lambda^2}{2}\|\lambda\|_2^2. \]
Both simplex problems use softmax L-BFGS, so finite solutions have strictly positive weights. If penalties are omitted, \(\hat\sigma\) is the sample standard deviation of first differences among control pre-period outcomes and
\[ \zeta_\omega=(N_gT_{\mathrm{post}})^{1/4}\hat\sigma, \qquad \zeta_\lambda=10^{-6}\hat\sigma. \]
Define \(u_g=(-\omega',\,\mathbf1_{N_g}'/N_g)'\) across controls and cohort units and \(v_g=(-\lambda',\,\mathbf1_{T_{\mathrm{post}}}'/T_{\mathrm{post}})'\) across time. The cohort estimate is
\[ \hat\tau_g=u_g'Y_gv_g, \]
and the overall ATT averages cohort estimates with weights \(N_gT_{\mathrm{post}}\). The displayed counterfactual path instead uses the unit-weight fit \(a+Y_C'\omega\) at every time; its cell effects and event-study summaries are useful diagnostics but are not the same time-weighted decomposition used for \(\hat\tau_g\).
3 Inference
There is no analytic covariance. Bootstrap resamples panel units with replacement, carrying each unit’s entire outcome and treatment path, and refits the estimator. Jackknife drops each unit in turn. Placebo inference samples only never-treated units, assigns the observed treated timing patterns to a pseudo-treated subset, and requires more controls than treated units. Failed bootstrap and placebo fits are skipped; too few successful estimates return NaN. A jackknife failure returns NaN immediately. The returned covariance is the square of the resulting scalar standard error.
These procedures address sampling variability under different resampling stories, but none repairs a poor pre-treatment match or violations of the never-treated comparison design. With one treated unit, bootstrap and jackknife standard errors are returned as NaN.
4 Performance and numerical behavior
Every cohort requires two simplex L-BFGS fits, each with dense panel multiplications. Resampling multiplies the entire cohort-fitting cost by the requested replications; jackknife performs one full fit per unit. The class stores cohort-by-unit and cohort-by-time weight matrices plus panel-sized counterfactual and effect matrices. Softmax can represent very small but not exact zero weights, and weakly identified weight vectors may vary substantially even when ATT is stable.
5 Python API
Constructor: cm.SyntheticDID
Use SyntheticDID(zeta_omega=None, zeta_lambda=None, max_iterations=1000). fit(y, w) infers cohorts and donors. predict(), treatment_effect(), summary(), vcov(), and se() expose fitted counterfactuals and uncertainty helpers.
print(inspect.signature(cm.SyntheticDID))(zeta_omega=None, zeta_lambda=None, max_iterations=1000)cls = cm.SyntheticDID
display(HTML(html_table(["Public method"], public_methods(cls))))| Public method |
|---|
fit(self, /, y, w) |
predict(self, /) |
se(self, /, method='bootstrap', replications=200, seed=None) |
summary(self, /) |
treatment_effect(self, /) |
vcov(self, /, method='bootstrap', replications=200, seed=None) |
6 Minimal example
rng = np.random.default_rng(17)
y = rng.normal(size=(9, 13))
w = np.zeros_like(y)
w[6:, 8:] = 1
y[6:, 8:] += 0.7
model = cm.SyntheticDID(max_iterations=500)
model.fit(y, w)
print(model.summary()['att'])
print(model.treatment_effect().shape)1.3416850436864332
(9, 13)7 summary() contract
The table below is generated by fitting the live class in this repository and then inspecting summary(). Shapes are shown because most values are plain NumPy arrays or scalars.
rng = np.random.default_rng(117)
y = rng.normal(size=(8, 12))
w = np.zeros_like(y)
w[6:, 8:] = 1
y[6:, 8:] += 0.7
model = cm.SyntheticDID(max_iterations=300)
model.fit(y, w)
summary = model.summary()
display(HTML(html_table(["summary() key", "shape"], summary_shape_rows(summary))))| summary() key | shape |
|---|---|
att |
() |
unit_weights |
(1, 8) |
time_weights |
(1, 12) |
counterfactual |
(8, 12) |
synthetic_outcome |
(8, 12) |
treatment_effect |
(8, 12) |
event_study |
() |
group_means |
() |
pre_rmse |
() |
unit_intercept |
(1,) |
time_intercept |
(1,) |
zeta_omega |
(1,) |
zeta_lambda |
(1,) |
control_units |
(6,) |
treated_units |
(2,) |
cohorts |
(1,) |
converged |
() |