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 Implementation walkthrough

The simplex objective and softmax gradient are native; Argmin supplies only the generic L-BFGS state machine and line search.

fit() validates finite donor and treated arrays, aligned pre-period rows, at least one period and donor, and a positive iteration budget. A single donor is an explicit shortcut returning weight one without optimization.
With multiple donors, the unconstrained vector \(\theta\) starts at zero, so the first weight vector is uniform. Stable softmax subtracts \(\max_j\theta_j\) before exponentiating and normalizing.
The cost callback forms \(r=Dw-y\) and returns \(r'r/(2T_0)\). The derivative with respect to simplex weights is \(g_w=D'r/T_0\). Rather than materializing a \(J\times J\) softmax Jacobian, the code applies it as

\[ \nabla_\theta Q=w\odot\{g_w-(w'g_w)\mathbf1\}. \]
Seven-pair L-BFGS uses a More-Thuente line search, gradient tolerance \(10^{-8}\), and cost tolerance \(10^{-12}\). The wrapper rejects any termination status other than solver convergence or target cost; reaching max_iterations does not return the current weights.
The accepted best \(\theta\) is transformed to weights once more and stored with owned fitting data. predict() checks only the donor-column count and performs a dense matrix-vector product, so the same weights can be applied to post-period donor rows.
summary() recomputes pre-period RMSE from stored data. The bootstrap samples pre-period row indices with replacement, copies donor and treated rows together, and reruns the complete simplex fit; it returns raw weight draws and aborts on a failed replicate.

Softmax makes feasibility automatic and the chain-rule gradient concise. Its common-shift redundancy and inability to represent exact boundary weights are the price; a projected or active-set simplex solver would expose sparse donor solutions more directly.

4 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.

5 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.

6 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, /)`

7 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]

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(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`	`()`