mlsynth

mlsynth is a Python framework for synthetic control causal inference and synthetic-control-based experimental design. It bundles 46 modern estimators under a single typed Config / .fit() / typed-results interface, so swapping between, say, Forward DiD, TASC, and SPCD is a one-line change.

Documentation · Which estimator should I use? (decision tree)

Install

pip install -U git+https://github.com/jgreathouse9/mlsynth.git

mlsynth supports Python 3.9 and later. The base install pulls in every core dependency and runs every estimator except two that lean on heavier, specialised backends. Those two backends are packaged as optional extras, so you only install the weight you actually use:

Request an extra with the usual bracket syntax (quote it so the shell does not glob the brackets):

# SCIP solver for SYNDES / MAREX
pip install -U "mlsynth[design] @ git+https://github.com/jgreathouse9/mlsynth.git"

# NumPyro for SPOTSYNTH's Bayesian mode
pip install -U "mlsynth[bayes] @ git+https://github.com/jgreathouse9/mlsynth.git"

# everything
pip install -U "mlsynth[all] @ git+https://github.com/jgreathouse9/mlsynth.git"

A few nuances worth knowing:

• The two extra backends are imported lazily, so import mlsynth and importing any estimator class always works on the base install. The extra is consulted only when you actually call the design optimiser (SYNDES / MAREX) or SPOTSYNTH's Bayesian path; without it those raise a clear error pointing you at the missing package, while everything else runs unchanged.
• pyscipopt ships prebuilt wheels (bundling SCIP) for the common platforms, so mlsynth[design] is normally a plain pip install with no separate SCIP system install.
• The test suite is a development artifact and is not shipped in the installed package — clone the repository if you want to run pytest.

Quickstart

import numpy as np
import pandas as pd
from mlsynth import FDID

rng = np.random.default_rng(0)
N, T1, T2 = 60, 24, 12            # 60 controls, 24 pre, 12 post
T = T1 + T2

def factors(T, rng, burn=200):    # f1: AR(1); f2: ARMA(1,1); f3: MA(2)
    Tt = T + burn; v = rng.standard_normal((Tt, 3)); f = np.zeros((Tt, 3))
    for t in range(1, Tt): f[t, 0] = 0.8 * f[t-1, 0] + v[t, 0]
    for t in range(1, Tt): f[t, 1] = -0.6 * f[t-1, 1] + v[t, 1] + 0.8 * v[t-1, 1]
    f[1, 2] = v[1, 2] + 0.9 * v[0, 2]
    for t in range(2, Tt): f[t, 2] = v[t, 2] + 0.9 * v[t-1, 2] + 0.4 * v[t-2, 2]
    f[0, 2] = v[0, 2]
    return f[burn:]

sf = factors(T, rng).sum(1)                        # common factor path
y_tr = 1 + sf + rng.standard_normal(T)             # treated: loading 1, true ATT = 0
loads = np.where(np.arange(N) < N // 2, 1.0, 2.0)  # first 30 match, last 30 mismatch
Y = 1 + np.outer(sf, loads) + rng.standard_normal((T, N))

rows = [{"unit": "treated", "time": t, "gdp": y_tr[t], "treat": int(t >= T1)}
        for t in range(T)]
for j in range(N):
    rows += [{"unit": f"c{j}", "time": t, "gdp": Y[t, j], "treat": 0} for t in range(T)]
df = pd.DataFrame(rows)

res = FDID({"df": df, "outcome": "gdp", "treat": "treat",
            "unitid": "unit", "time": "time", "display_graphs": False}).fit()

sel = res.fdid.selected_names
matching = sum(int(s[1:]) < N // 2 for s in sel)
print(f"FDID: ATT={res.fdid.att:+.3f}  R2={res.fdid.r_squared:.3f}  "
      f"selected {len(sel)} donors, {matching} from the matching group")
print(f"DID : ATT={res.did.att:+.3f}  R2={res.did.r_squared:.3f}  (all {N} donors)")

The same five df/outcome/unitid/time/treat fields work for every estimator. Swap FDID for TASC, CLUSTERSC, BVSS, or any other class in the table below; only the class name and any estimator-specific hyperparameters change.

Estimators

mlsynth implements 46 estimator classes spanning the full synthetic-control landscape. Several classes expose multiple methods through one configuration (e.g. PDA covers four donor-selection / relaxation variants; RESCM covers relaxed- and $L_\infty$-balanced variants; PROXIMAL dispatches several proximal estimators). Each Class below links to its documentation page; the estimator name links to the source paper. Not sure which one fits your problem? Walk the decision tree.

Canonical & convex-hull

Donor selection / forward

High-dimensional / robust / relaxed-hull

Factor / time-series / Bayesian

SDID family / staggered adoption

Spillover / interference (SUTVA)

Multiple outcomes / interventions / proximal

Matrix completion / missing data

Distributional / nonlinear / continuous / IV / micro

Experimental design & geo-testing

Contributing

Fixes are always welcome. For new estimators, inference tests, or larger changes, please email Jared first. Estimators currently on the development list include continuous-treatment synthetic controls, Bayesian factor SCMs, random-forest-based SCMs, simplex-weight inference, and prediction-interval refinements.

Whatever change is proposed, it must reproduce either a canonical benchmark application from the SCM literature (Basque Country, California Proposition 99, or West Germany reunification) or the empirical findings reported in the originating methodological paper. Continuous integration runs the unit test suite, a fresh-install smoke check, and coverage reporting on every pull request.

In addition to code, you can also develop tutorials, presentations, and educational materials using mlsynth, promote it on LinkedIn or in the classroom, and help with outreach and onboarding new contributors.

License

mlsynth is open source and distributed under the MIT License.