SyntheticControl

Single-treated-unit donor weighting

from _api_doc_utils import *

1 Where it fits

Group: Causal inference

SyntheticControl fits nonnegative donor weights that sum to one, minimizing pre-treatment imbalance between the treated path and a convex combination of donor paths:

\[ \min_{w\ge 0,\;1'w=1}\|y_{\mathrm{treated,pre}} - Y_{\mathrm{donor,pre}}w\|_2^2. \]

It is the lower-level single-path API; the panel estimators use the newer fit(Y, W) contract.

2 Weight objective

For pre-treatment donor matrix \(D\in\mathbb R^{T_0\times J}\) and treated path \(y\), the class solves

\[ \hat w = \arg\min_{w\in\Delta_J} \frac{1}{2T_0}\|Dw-y\|_2^2, \qquad \Delta_J=\{w:w_j\geq0,\ \mathbf1'w=1\}. \]

It parameterizes \(w=\operatorname{softmax}(\theta)\) and uses seven-vector-memory L-BFGS with fixed gradient and cost tolerances. This guarantees an interior simplex vector at every finite \(\theta\); exact zero donor weights are not attainable except through numerical underflow. There is no intercept, predictor weighting, or pre-period weighting.

3 Inference and diagnostics

The summary reports the weights and in-sample pre-treatment RMSE. The class itself receives only donor and treated fitting paths, so it does not calculate a post-treatment effect or ATT. The bootstrap resamples time rows as iid pairs and refits the weights. Those draws are useful as a sensitivity diagnostic, but they do not preserve time-series dependence and are not converted into a formal covariance or confidence interval.

4 Performance and numerical behavior

Each objective and gradient evaluation is \(O(T_0J)\) and stores the dense donor matrix. Runtime depends on L-BFGS iterations and is multiplied by the number of bootstrap draws. A single donor bypasses optimization with weight one. Collinear donors make weights weakly identified even when the synthetic path is stable; softmax parameter redundancy also leaves \(\theta\) unidentified up to a common shift, though the weights remain identified by the optimization target.

5 Python API

Constructor: cm.SyntheticControl

Call fit(donors, treated) where donors is (n_periods, n_donors) and treated is the treated pre-period vector. predict(donors) applies the learned weights to a donor matrix. summary() reports weights and pre-fit RMSE.

print(inspect.signature(cm.SyntheticControl))

(max_iterations=500)

cls = cm.SyntheticControl
display(HTML(html_table(["Public method"], public_methods(cls))))

Public method
bootstrap(self, /, n_bootstrap, seed=None)
fit(self, /, donors, treated)
predict(self, /, donors)
summary(self, /)

6 Minimal example

rng = np.random.default_rng(15)
donors = rng.normal(size=(40, 4))
w_true = np.array([0.45, 0.25, 0.2, 0.1])
treated = donors @ w_true + rng.normal(scale=0.02, size=40)
model = cm.SyntheticControl(max_iterations=500)
model.fit(donors, treated)
print(model.summary()['weights'])
print(model.predict(donors[-3:]))

[0.45260904 0.25299333 0.19448108 0.09991655]
[ 0.54589872  0.43772007 -0.93213339]

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(115)
donors = rng.normal(size=(30, 4))
treated = donors @ np.array([0.45, 0.25, 0.2, 0.1])
model = cm.SyntheticControl(max_iterations=300)
model.fit(donors, treated)
summary = model.summary()
display(HTML(html_table(["summary() key", "shape"], summary_shape_rows(summary))))

summary() key	shape
weights	(4,)
pre_rmse	()
converged	()