SyntheticDID

Synthetic difference-in-differences with complete or missing outcomes

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.

On complete panels both simplex problems use the active-set quadratic solver, allowing exact zero 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. Complete panels retain the simplex quadratic solver; incomplete panels use the normalized available-case objective described in missing panel outcomes.

1. 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.
2. 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.
3. 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.
4. On complete data, centering profiles out the intercept and produces a simplex quadratic problem. On incomplete data, each average divides by its available weight mass. The intercept is profiled out and projected gradient descent with backtracking starts at uniform weights. It must reach a scaled projected-gradient residual below 10^{-8} or the fit fails. The masked objective is nonlinear and may have multiple local minima; this criterion establishes stationarity, not a global optimum.
5. 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.
6. On complete panels, 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. With missing outcomes, the ATT instead uses observed-treated-count-weighted post gaps minus the available-case time-weighted pre-gap; cohort weights are observed treated post-cell counts.
7. 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.
8. 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 weight fits, each using its observed control/pre-treatment data. 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. Both solvers can return exact zero weights. The masked solver rejects zero available-weight denominators.

6 Python API

Constructor: cm.SyntheticDID

Use SyntheticDID(zeta_omega=None, zeta_lambda=None, max_iterations=1000). fit(y, w, observed=None) infers cohorts and donors. NaNs or an explicit Boolean mask specify missing outcomes; W must remain known and absorbing. ATT uses observed treated cells. Masked-fit diagnostics are in missing_diagnostics, alongside observation counts. The diagnostic counterfactual/event path retains the unit-fit intercept; ATT separately subtracts the time-weighted pre-gap. 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
SyntheticDID(zeta_omega=None, zeta_lambda=None, max_iterations=1000)
fit(self, /, y, w, *, observed=None)
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.341684611362706
(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(1)
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=1000)
model.fit(y, w)
summary = model.summary()
display(HTML(html_table(["summary() key", "shape"], summary_shape_rows(summary))))

summary() key	shape
n_observed	()
n_missing	()
n_untreated_observed	()
n_treated_observed	()
att_target	()
missing_diagnostics	(0,)
missing_method	()
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	()