Skip to content

README.md

Latest commit

 

History

History
145 lines (108 loc) · 3.31 KB

README.md

File metadata and controls

145 lines (108 loc) · 3.31 KB

synthlearners: Scalable Synthetic Control Methods in Python

Fast synthetic control tooling with two estimator families:

  • PenguinSynth: lean, adelie-backed regularized estimators for long-format panel data
  • Synth: full, pyensmallen-backed estimators for matrix-format workflows and inference

Check the notebooks/ directory for synthetic and real-data examples.

Features

Features are indicated by:

  • pending
  • implemented

Weights

  • unit weights
  • simplex
  • lasso
  • ridge
  • matching
  • intercept support
  • entropy weights
  • multiple treated units with aggregate or granular matching
  • time weights for SDID
  • time-distance penalized weights
  • matrix completion augmentation
  • latent factor models
  • two-way kernel ridge weights

Inference

  • jackknife confidence intervals
  • permutation tests
  • conformal inference

Visualizations

  • treated versus synthetic trajectories
  • treatment-effect event studies
  • weight plots

Installation

For local development:

git clone https://github.com/apoorvalal/synthlearners.git
cd synthlearners
uv sync --extra full --extra test --extra docs

Lean Installation

For the adelie-backed API:

uv add synthlearners

Lean installs expose:

  • PenguinSynth
  • PenguinResults
  • PenguinSynth(method="synth")
  • PenguinSynth(method="sdid")
  • PenguinSynth(method="did")

Full Installation

For the traditional synthetic-control stack and auxiliary utilities:

uv sync --extra full

If you are adding the package to another project instead of working from source:

uv add "synthlearners[full]"

Full installs add:

  • Synth
  • SynthResults
  • DynamicBalance
  • DynamicBalanceResults
  • Synth(method="simplex")
  • Synth(method="linear")
  • Synth(method="lp_norm")
  • Synth(method="matching")
  • Synth(method="matrix_completion")
  • Synth(method="sdid")
  • DynamicBalance.fit(...) for exact treatment-history contrasts
  • PanelCrossValidator and related cross-validation utilities

MatrixCompletionEstimator is available from synthlearners.mcnnm; it is not exported from the package root.

Documentation

Static API docs are generated with pdoc into docs/.

uv sync --extra full --extra docs
./scripts/build_docs.sh

Quick Start

Lean API

from synthlearners import PenguinSynth

estimator = PenguinSynth(method="synth", l1_ratio=0.0)
result = estimator.fit(df, "unit", "time", "treatment", "outcome")
print(f"Treatment effect: {result.att:.3f}")

Full API

from synthlearners import DynamicBalance, Synth, PenguinSynth

synth = Synth(method="simplex")
result = synth.fit(Y, treated_units=15, T_pre=10)

penguin = PenguinSynth(method="synth", l1_ratio=0.5)
result = penguin.fit(df, "unit", "time", "treatment", "outcome")

dynbal = DynamicBalance(l1_ratio=0.0)
res = dynbal.fit(
    df=df,
    unit_id="unit",
    time_id="time",
    treatment="treatment",
    outcome="outcome",
    covariates=["x", "lag_outcome"],
    target_history=[1, 1],
    reference_history=[0, 0],
)

Performance

PenguinSynth is the faster default path for regularized estimation.

Synth carries the broader constrained-optimization toolbox, matrix completion support, and inference utilities that rely on the full dependency set.