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 Implementation walkthrough
The implementation fits staggered adoption cohort by cohort and reuses one native softmax least-squares solver for both simplex problems.
- The shared panel parser enforces binary absorbing treatment, infers first-treatment periods, and requires never-treated controls plus at least one pre-period for every cohort. For cohort \(g\), rows are reordered as all never-treated controls followed by units first treated at \(g\).
- The default noise scale pools first differences \(Y_{i,t}-Y_{i,t-1}\) over control units and cohort-specific pre-periods and uses their sample standard deviation. This one \(\hat\sigma_g\) generates both default penalties. With fewer than two differences it is zero, so the defaults can become unregularized.
- Time weights use \(Y_{C,\mathrm{pre}}\) as a \(C\times T_0\) design and the control post-period mean by unit as its target. Unit weights use \(Y_{C,\mathrm{pre}}'\) as a \(T_0\times C\) design and the treated-cohort pre-period mean by time as its target.
- In either problem, softmax maps a zero-initialized unconstrained vector to a uniform simplex. The residual is demeaned internally, profiling out an intercept. The gradient adds \(\zeta^2w\) in weight coordinates and applies the softmax Jacobian as \(w\odot(g_w-w'g_w)\). Seven-pair L-BFGS uses More-Thuente search and fixed \(10^{-8}\) gradient and \(10^{-12}\) cost tolerances.
- After weights converge, the profiled intercept is recomputed as the mean target-minus-fit residual. The unit intercept and weights generate the displayed full cohort counterfactual \(a_g+Y_C'\omega_g\). The fitted time intercept is retained for diagnostics but is not used in that path.
- Separately, signed unit weights \((-\omega,1/N_g)\) and signed time weights \((-\lambda,1/T_{\mathrm{post}})\) are multiplied through the reordered cohort panel to obtain \(\hat\tau_g\). Cohort estimates are accumulated with \(N_gT_{\mathrm{post}}\) weights. This is why ATT cannot generally be recovered by averaging the displayed diagnostic effect matrix.
- Weight matrices are stored in original panel coordinates: control-unit columns or pre-period columns receive fitted values and all irrelevant positions remain zero. Event summaries are computed later from displayed counterfactual cells.
- Bootstrap samples whole unit rows and silently skips invalid refits. Placebo shuffles never-treated units, assigns the observed treated timing rows to the last pseudo-treated subset, and also skips failed fits. Both return the sample standard deviation of successful estimates multiplied by \(\sqrt{(R-1)/R}\) using the requested replication count \(R\), even when fewer fits succeeded. Jackknife instead returns NaN at the first invalid leave-one-out panel and uses the usual \(\sqrt{(N-1)\sum(\tau_{-i}-\bar\tau)^2/N}\) formula.
The two fitted simplex problems and the final double difference are cleanly separated in code. That separation is didactically useful, but the permissive skipped-replication inference and its finite-replication multiplier should be treated as implementation conventions, not generic bootstrap theory.
4 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.
5 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.
6 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) |
7 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)8 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 |
() |