gsynth – User Manual

Welcome

This manual serves as a user guide for the gsynth package in R.

Starting from v1.3.0, gsynth becomes a wrapper of fect. We recommend users consult the fect User Manual for the most up-to-date features. We maintain gsynth for backward compatibility. For the technical details of the GSC estimator, see Xu (2017).

TipWhat’s new in v1.5.0

• fect 2.4.x catch-up.
  • new rolling-window cross-validation defaults (cv.method = "rolling", k = 20);
  • new ci.method argument for the confidence intervals reported in est.* slots;
  • new placeboTest and placebo.period arguments for placebo testing;
  • new legacy.style, highlight, and highlight.fill arguments on plot.gsynth();
  • loading-overlap plot type available via plot(fit, type = "loading.overlap").
• Soft-deprecated paths.
  • estimator = "ife" (IFE-EM), estimator = "mc" (matrix completion), EM = TRUE, and effect(). Each emits a one-time-per-session deprecation message.
  • For IFE-EM, matrix completion, and post-hoc estimands (cumulative ATT, APTT, log-ATT), use fect::fect() and fect::estimand() directly.
• Breaking change. inference = "parametric" with estimator = "ife" or "mc" now errors instead of silently coercing to bootstrap. See Chapter 2  IFE-EM & MC.

Installation

gsynth v1.5.0 requires fect >= 2.4.2. Until fect v2.4.2 is on CRAN, install both the fect development branch and gsynth from GitHub:

# Up-to-date fect from the dev branch (>= 2.4.2)
devtools::install_github("xuyiqing/fect", ref = "dev")

# gsynth development version
devtools::install_github("xuyiqing/gsynth")

Once fect v2.4.2 is on CRAN, the standard install will suffice:

install.packages("gsynth")

# Check version
installed.packages()["gsynth", "Version"]
#> [1] "1.5.0"

# Load package
library(gsynth)
#> ## gsynth v1.5.0 (requires fect >= 2.4.2).
#> ## *gsynth* is a wrapper of the *fect* package; see ?gsynth.
#> ## NOTE: estimator='ife' and estimator='mc' are soft-deprecated in v1.5.0;
#> ##   for IFE-EM or matrix completion, use fect::fect() directly.
#> ##   See vignette('02-ife-mc', package='gsynth').

Quick reference

gsynth has one main function, gsynth(), which estimates causal effects using interactive fixed-effect models. Three estimation methods are nominally available, but only the GSC path is recommended in v1.5.0+:

estimator =	Status	Method	Reference
"gsynth" (default)	recommended	Generalized Synthetic Control	Xu (2017)
"ife"	soft-deprecated; use fect::fect(method = "ife", ...)	IFE-EM	Gobillon and Magnac (2016)
"mc"	soft-deprecated; use fect::fect(method = "mc", ...)	Matrix completion	Athey et al. (2021)

The legacy EM = TRUE parameter is also soft-deprecated and equivalent to estimator = "ife".

Key arguments

Argument	Type	Description
formula	formula	Y ~ D + X1 + X2; first RHS variable is the treatment
data	data.frame	Long-format panel data
index	character(2)	c("unit_var", "time_var")
estimator	character	"gsynth" (recommended); "ife" / "mc" soft-deprecated
force	character	"none" / "unit" / "time" / "two-way"
r	integer(2)	Range for number of factors, e.g. c(0, 5)
CV	logical	Cross-validation to select number of factors
cv.method	character	"rolling" (default) or "block"
cv.prop	numeric	Per-fold unit-sampling fraction (default 0.1)
cv.buffer	integer	Past-side buffer for rolling CV (default 1)
k	integer	CV folds (default 20 in v1.5.0+)
time.component.from	character	"nevertreated" (GSC) or "notyettreated" (IFE-EM/MC)
se	logical	Compute uncertainty estimates
inference	character	"parametric" / "nonparametric" / "jackknife"
ci.method	character	"normal" (default; Wald) or "basic" (reflected pivot). New in v1.5.0.
nboots	integer	Number of bootstrap runs (default 200; bump to 1000+ for tail-quantile CIs)
placeboTest	logical	Hold out pre-treatment periods as placebo. New in v1.5.0.
placebo.period	integer	Event-time periods used for the placebo block, e.g. c(-2, 0)
weight, W.est, W.agg	character	Weight column(s); per-role variants for outcome fit / aggregation
parallel	logical	Enable parallel computing
cores	integer	Number of cores (default: auto-detect)
min.T0	integer	Minimum pre-treatment periods for treated units

Organization

• Chapter 1  Gsynth — Generalized Synthetic Control: block DID, inference, placebo test, loading-overlap diagnostic, staggered DID, unbalanced panels
• Chapter 2  IFE-EM & MC — IFE-EM and matrix completion (soft-deprecated); placebo test for these methods; migration to fect::fect()
• Chapter 3  Plot customization — Plot customization, modern theme, highlight API, plot types (counterfactual, factors, loadings, loading-overlap, raw, missing)

Contributors

• Yiqing Xu
• Licheng Liu
• Ziyi Liu
• Shiyun Hu

How to Cite

To cite the gsynth package, please use:

Xu, Yiqing. 2017. “Generalized Synthetic Control Method: Causal Inference with Interactive Fixed Effects Models.” Political Analysis 25 (1): 57–76.

@article{Xu2017,
  title = {Generalized Synthetic Control Method: Causal Inference with Interactive Fixed Effects Models},
  author = {Xu, Yiqing},
  journal = {Political Analysis},
  volume = {25},
  number = {1},
  pages = {57--76},
  year = {2017}
}

For technical background on the v2.0–v2.4 changes in fect (which gsynth v1.5.0 inherits), see the fect User Manual.

Report Bugs

Please report bugs to yiqingxu [at] stanford.edu or open an issue on GitHub.

Athey, Susan, Mohsen Bayati, Nikolay Doudchenko, Guido Imbens, and Khashayar Khosravi. 2021. “Matrix Completion Methods for Causal Panel Data Models.” Journal of the American Statistical Association forthcoming.

Chen, Jiafeng, and Jonathan Roth. 2024. “Logs with Zeros? Some Problems and Solutions.” Quarterly Journal of Economics.

Davison, A. C., and D. V. Hinkley. 1997. Bootstrap Methods and Their Application. Cambridge Series in Statistical and Probabilistic Mathematics. Cambridge University Press.

Gobillon, Laurent, and Thierry Magnac. 2016. “Regional Policy Evaluation: Interactive Fixed Effects and Synthetic Controls.” Review of Economics and Statistics 98 (3): 535–51.

Xu, Yiqing. 2017. “Generalized Synthetic Control Method: Causal Inference with Interactive Fixed Effects Models.” Political Analysis 25 (1): 57–76.