Synthetic Difference-in-Differences (SDID)
English
A Python implementation of Synthetic Difference-in-Differences for causal inference.
Overview
SDID combines synthetic control methods with difference-in-differences to provide robust causal effect estimates. It automatically finds optimal weights for:
- Control units: Creates a synthetic comparison group
- Time periods: Balances pre/post treatment comparisons
Mathematical Formulation
SDID estimates the Average Treatment Effect on the Treated (ATT) through a weighted two-way fixed effects regression.
Unit Weights Optimization
We find optimal unit weights $\hat{\omega}$ by solving:
$$\hat{\omega}, \hat{\alpha} = \underset{\omega, \alpha}{\arg\min} \sum_{t=1}^{T_{pre}} \left( \sum_{i \in \mathcal{C}} \omega_i Y_{it} + \alpha - \bar{Y}{treated,t} \right)^2 + \zeta{unit}^2 |\omega|_2^2$$
subject to $\omega_i \geq 0$ and $\sum_{i \in \mathcal{C}} \omega_i = 1$
where:
- $\mathcal{C}$ is the set of control units
- $Y_{it}$ is the outcome for unit $i$ at time $t$
- $\alpha$ is an intercept term (allows level differences)
- $\zeta_{unit}$ is the regularization parameter
Time Weights Optimization
Time weights $\hat{\lambda}$ are chosen so that, for the control units, a weighted average of pre-treatment outcomes predicts their average post-treatment outcome:
$$\hat{\lambda}, \hat{\beta} = \underset{\lambda, \beta}{\arg\min} \sum_{i \in \mathcal{C}} \left( \beta + \sum_{t=1}^{T_{pre}} \lambda_t Y_{it} - \frac{1}{T_{post}} \sum_{t > T_0} Y_{it} \right)^2 + \zeta_{time} |\lambda|_2^2$$
subject to $\lambda_t \geq 0$ and $\sum_{t=1}^{T_{pre}} \lambda_t = 1$
Treatment Effect Estimation
The ATT is estimated via weighted two-way fixed effects regression:
$$Y_{it} = \alpha_i + \gamma_t + \tau \cdot D_{it} + \varepsilon_{it}$$
where:
- $\alpha_i$ are unit fixed effects
- $\gamma_t$ are time fixed effects
- $D_{it} = \mathbf{1}{i \in treated} \cdot \mathbf{1}{t \geq T_0}$ is the treatment indicator
- $\tau$ is the treatment effect (our target parameter)
Observations are weighted by $w_{it} = \hat{\omega}_i \cdot \hat{\lambda}_t$.
Installation
From PyPI (Recommended)
pip install sdid
From Source
git clone https://github.com/AluminumShark/Synthetic_Difference_in_Difference.git
cd Synthetic_Difference_in_Difference
pip install .
Development Installation
git clone https://github.com/AluminumShark/Synthetic_Difference_in_Difference.git
cd Synthetic_Difference_in_Difference
uv sync
Examples
See it in action:
examples/example.ipynb
Complete walkthrough: model fitting, bootstrap SE, event study analysis, and visualization.
Run the notebook locally
git clone https://github.com/AluminumShark/Synthetic_Difference_in_Difference.git
cd Synthetic_Difference_in_Difference
uv sync
uv run --with jupyter jupyter lab examples/example.ipynb
Quick Start
import pandas as pd
from sdid import SyntheticDiffInDiff
# Load your panel data
data = pd.read_csv("your_data.csv")
# Initialize and fit
sdid = SyntheticDiffInDiff(
data=data,
outcome_col="outcome",
times_col="year",
units_col="state",
treat_col="treated",
post_col="post"
)
# Estimate treatment effect
effect = sdid.fit()
print(f"Treatment Effect: {effect:.4f}")
# Estimate standard error
sdid.estimate_se(n_bootstrap=200, n_jobs=4)
print(sdid.summary())
Data Format
Your data should be in long format (one row per unit-time observation):
| Column | Description | Example |
|---|---|---|
outcome |
Outcome variable | Sales, GDP |
times |
Time period | 2018, 2019, 2020 |
units |
Unit identifier | "CA", "TX", "NY" |
treat |
Treatment indicator | 0 = control, 1 = treated |
post |
Post-treatment period | 0 = before, 1 = after |
Example:
unit year outcome treated post
CA 2018 100.5 0 0
CA 2019 102.3 0 0
CA 2020 105.1 0 1
TX 2018 98.2 1 0
TX 2019 99.8 1 0
TX 2020 108.7 1 1
API Reference
| Method | Description |
|---|---|
fit(verbose=False) |
Fit model and return treatment effect |
estimate_se(n_bootstrap, seed, n_jobs) |
Estimate standard error via placebo bootstrap |
summary(confidence_level=0.95) |
Return formatted results with customizable CI |
run_event_study(times) |
Estimate effects for multiple periods |
plot_event_study(times, ...) |
Create event study plot with confidence intervals |
plot_raw_trends(...) |
Plot raw trends for treated vs control units |
plot_synthetic_control(...) |
Plot treated unit vs synthetic control |
get_weights_summary() |
Return unit and time weights |
is_fitted |
Property to check if model is fitted |
Visualization
# Plot raw trends: treated unit vs all control units
sdid.plot_raw_trends(
title="Raw Data: Treated vs Controls",
treated_color="red",
control_color="gray"
)
# Plot synthetic control comparison
sdid.plot_synthetic_control(
title="SDID: Actual vs Synthetic",
treated_color="blue",
synthetic_color="orange"
)
Customizable Confidence Interval
# Default 95% confidence interval
print(sdid.summary())
# Custom 90% confidence interval
print(sdid.summary(confidence_level=0.90))
# Custom 99% confidence interval
print(sdid.summary(confidence_level=0.99))
Event Study
# Estimate dynamic treatment effects
effects = sdid.run_event_study([2020, 2021, 2022])
# Plot with confidence intervals
fig = sdid.plot_event_study(
times=[2020, 2021, 2022],
n_bootstrap=200,
confidence_level=0.95,
n_jobs=4
)
fig.savefig("event_study.png", dpi=300)
Assumptions
SDID relies on these key assumptions:
- No anticipation: Units don't change behavior before treatment
- SUTVA: No spillover effects between units
- Overlap: Control units can approximate treated units
Reference
@article{arkhangelsky2021synthetic,
title={Synthetic difference-in-differences},
author={Arkhangelsky, Dmitry and Athey, Susan and Hirshberg, David A and Imbens, Guido W and Wager, Stefan},
journal={American Economic Review},
volume={111},
number={12},
pages={4088--4118},
year={2021}
}
Development
# Install dev dependencies
uv sync
# Run tests
uv run pytest tests/ -v
# Run linter
uv run ruff check .
# Format code
uv run ruff format .
# Build package
uv build
# Upload to PyPI (requires API token)
uv publish
License
MIT License - see LICENSE for details.
繁體中文
合成雙重差分法 (SDID) 的 Python 實現,用於因果推論。
概述
SDID 結合了合成控制法與雙重差分法的優點,提供穩健的因果效應估計。它自動計算最佳權重:
- 控制單位權重:建立合成對照組
- 時間期間權重:平衡處理前後的比較
數學公式
SDID 透過加權雙向固定效應迴歸估計處理組的平均處理效果 (ATT)。
單位權重優化
我們通過求解以下問題找到最佳單位權重 $\hat{\omega}$:
$$\hat{\omega}, \hat{\alpha} = \underset{\omega, \alpha}{\arg\min} \sum_{t=1}^{T_{pre}} \left( \sum_{i \in \mathcal{C}} \omega_i Y_{it} + \alpha - \bar{Y}{treated,t} \right)^2 + \zeta{unit}^2 |\omega|_2^2$$
限制條件:$\omega_i \geq 0$ 且 $\sum_{i \in \mathcal{C}} \omega_i = 1$
其中:
- $\mathcal{C}$ 為控制單位集合
- $Y_{it}$ 為單位 $i$ 在時間 $t$ 的結果
- $\alpha$ 為截距項(允許水平差異)
- $\zeta_{unit}$ 為正則化參數
時間權重優化
時間權重 $\hat{\lambda}$ 的選取,是讓控制單位的處理前結果加權平均能預測其處理後的平均結果:
$$\hat{\lambda}, \hat{\beta} = \underset{\lambda, \beta}{\arg\min} \sum_{i \in \mathcal{C}} \left( \beta + \sum_{t=1}^{T_{pre}} \lambda_t Y_{it} - \frac{1}{T_{post}} \sum_{t > T_0} Y_{it} \right)^2 + \zeta_{time} |\lambda|_2^2$$
限制條件:$\lambda_t \geq 0$ 且 $\sum_{t=1}^{T_{pre}} \lambda_t = 1$
處理效果估計
ATT 透過加權雙向固定效應迴歸估計:
$$Y_{it} = \alpha_i + \gamma_t + \tau \cdot D_{it} + \varepsilon_{it}$$
其中:
- $\alpha_i$ 為單位固定效應
- $\gamma_t$ 為時間固定效應
- $D_{it} = \mathbf{1}{i \in treated} \cdot \mathbf{1}{t \geq T_0}$ 為處理指標
- $\tau$ 為處理效果(目標參數)
觀測值權重為 $w_{it} = \hat{\omega}_i \cdot \hat{\lambda}_t$。
安裝
從 PyPI 安裝(推薦)
pip install sdid
從原始碼安裝
git clone https://github.com/AluminumShark/Synthetic_Difference_in_Difference.git
cd Synthetic_Difference_in_Difference
pip install .
開發安裝
git clone https://github.com/AluminumShark/Synthetic_Difference_in_Difference.git
cd Synthetic_Difference_in_Difference
uv sync
範例
實際操作範例:
examples/example.ipynb
完整教學:模型擬合、bootstrap 標準誤、事件研究分析、視覺化。
在本機執行 notebook
git clone https://github.com/AluminumShark/Synthetic_Difference_in_Difference.git
cd Synthetic_Difference_in_Difference
uv sync
uv run --with jupyter jupyter lab examples/example.ipynb
快速開始
import pandas as pd
from sdid import SyntheticDiffInDiff
# 載入面板資料
data = pd.read_csv("your_data.csv")
# 初始化並擬合
sdid = SyntheticDiffInDiff(
data=data,
outcome_col="outcome", # 結果變數
times_col="year", # 時間
units_col="state", # 單位識別
treat_col="treated", # 處理指標
post_col="post" # 處理後指標
)
# 估計處理效果
effect = sdid.fit()
print(f"處理效果: {effect:.4f}")
# 估計標準誤
sdid.estimate_se(n_bootstrap=200, n_jobs=4)
print(sdid.summary())
資料格式
資料須為長格式(每個單位-時間組合一列):
| 欄位 | 說明 | 範例 |
|---|---|---|
outcome |
結果變數 | 銷售額、GDP |
times |
時間期間 | 2018, 2019, 2020 |
units |
單位識別 | "CA", "TX", "NY" |
treat |
處理指標 | 0 = 控制組, 1 = 處理組 |
post |
處理後期間 | 0 = 處理前, 1 = 處理後 |
範例:
unit year outcome treated post
CA 2018 100.5 0 0
CA 2019 102.3 0 0
CA 2020 105.1 0 1
TX 2018 98.2 1 0
TX 2019 99.8 1 0
TX 2020 108.7 1 1
API 參考
| 方法 | 說明 |
|---|---|
fit(verbose=False) |
擬合模型並回傳處理效果 |
estimate_se(n_bootstrap, seed, n_jobs) |
透過安慰劑 bootstrap 估計標準誤 |
summary(confidence_level=0.95) |
回傳格式化結果,可自訂信賴區間 |
run_event_study(times) |
估計多個時間點的效果 |
plot_event_study(times, ...) |
繪製帶信賴區間的事件研究圖 |
plot_raw_trends(...) |
繪製處理組與控制組的原始趨勢 |
plot_synthetic_control(...) |
繪製處理單位與合成控制的比較 |
get_weights_summary() |
回傳單位和時間權重 |
is_fitted |
檢查模型是否已擬合的屬性 |
視覺化
# 繪製原始趨勢:處理單位 vs 所有控制單位
sdid.plot_raw_trends(
title="原始資料:處理組 vs 控制組",
treated_color="red",
control_color="gray"
)
# 繪製合成控制比較圖
sdid.plot_synthetic_control(
title="SDID:實際值 vs 合成控制",
treated_color="blue",
synthetic_color="orange"
)
自訂信賴區間
# 預設 95% 信賴區間
print(sdid.summary())
# 自訂 90% 信賴區間
print(sdid.summary(confidence_level=0.90))
# 自訂 99% 信賴區間
print(sdid.summary(confidence_level=0.99))
事件研究
# 估計動態處理效果
effects = sdid.run_event_study([2020, 2021, 2022])
# 繪製帶信賴區間的圖表
fig = sdid.plot_event_study(
times=[2020, 2021, 2022],
n_bootstrap=200,
confidence_level=0.95,
n_jobs=4
)
fig.savefig("event_study.png", dpi=300)
假設條件
SDID 依賴以下關鍵假設:
- 無預期效應:單位不會在處理前改變行為
- SUTVA:單位間無外溢效應
- 重疊性:控制單位能近似處理單位
參考文獻
@article{arkhangelsky2021synthetic,
title={Synthetic difference-in-differences},
author={Arkhangelsky, Dmitry and Athey, Susan and Hirshberg, David A and Imbens, Guido W and Wager, Stefan},
journal={American Economic Review},
volume={111},
number={12},
pages={4088--4118},
year={2021}
}
開發
# 安裝開發相依套件
uv sync
# 執行測試
uv run pytest tests/ -v
# 執行 linter
uv run ruff check .
# 格式化程式碼
uv run ruff format .
# 建置套件
uv build
# 上傳到 PyPI(需要 API token)
uv publish
授權
MIT 授權 - 詳見 LICENSE。
Metadata
Release files for sdid 0.4.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sdid-0.4.1.tar.gz | 179.6 kB | With provenance | Details for sdid-0.4.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sdid-0.4.1-py3-none-any.whl | Python 3 | none | any | Details for sdid-0.4.1-py3-none-any.whl |
Total release size: 196.8 kB
Release files / sdid-0.4.1.tar.gz
| Download URL | sdid-0.4.1.tar.gz |
|---|---|
| Size | 179.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2ae4bfb2864351e9bd13f1fb9e0042d637168a14889d9b6d2ebb1f1619aa122e
|
|
BLAKE2b-256 checksum How to use checksums |
5dc02eb0d5c7f1ac42ce4f40df54077d27002b17e4a0c331d594abb9ebca31e7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.
Transparency logRelease files / sdid-0.4.1-py3-none-any.whl
| Download URL | sdid-0.4.1-py3-none-any.whl |
|---|---|
| Size | 17.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d4785f5ecc23db191d34af7acdb61b1564a45cc7fe479a7f656caf679ae19edf
|
|
BLAKE2b-256 checksum How to use checksums |
c5dd8bed604f5dec0d43c946adec8703e498332fa6146651cf067c63d71bb4a4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.
Transparency logSecurity for sdid 0.4.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for sdid-0.4.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.