fect – User Manual

Welcome!

This Quarto book serves as a user manual for the fect package in R, which implements counterfactual (imputation) estimators for causal inference with panel data—without feedback—and performs diagnostic tests.

fect covers a series of counterfactual estimators, including the five estimators from the last version and integrating the latest version of the gsynth package (User Manual) for the generalized synthetic control method (Gsynth). This Quarto book also facilitates the application of various new difference-in-differences (DID) estimators. For details of these methods, see

Xu (2017) for Gsynth [Paper]
Liu, Wang, and Xu (2024) for counterfactual estimators [Paper]
Chiu et al. (2026) for a survey of the new DID estimators [Paper]

Source Code and Version

For those interested in exploring the algorithms used in fect for calculating estimates, please visit the source GitHub Repo for further details.

This manual was rendered against fect 2.4.5 on 2026-05-30.

Why Counterfactual Estimators?

There are several reasons why you might consider using counterfactual estimators for your panel data applications:

Because “causal inference is a missing data problem” (Holland 1986), it is natural to impute treated counterfactuals when the ATT, if well defined, is the primary quantity of interest.
Counterfactual estimators help avoid the (negative) weighting problem, which has been highlighted in recent applied econometrics literature regarding TWFE models, e.g., Chaisemartin and D’Haultfœuille (2020); Goodman-Bacon (2021).
Among the newer estimators that accommodate heterogeneous treatment effects, the fixed effect counterfactual estimator (imputation based on TWFE) is the most efficient under homoskedasticity (Borusyak, Jaravel, and Spiess 2024).
Counterfactual estimators enable the use of more complex modeling strategies, such as linear factor models and matrix completion methods, which naturally connect to the synthetic control setting.

However, these counterfactual estimators come with important limitations:

Most rely on some form of the parallel trends assumption or a low-rank structure.
They generally do not accommodate dynamic treatment assignment given past outcomes or covariates—i.e., “feedback”—based on sequential ignorability.
Methods for continuous treatments are still underdeveloped and are not currently covered by fect.

Chiu et al. (2026) reanalyze 49 published studies in political science and offer justifications for adopting these estimators.

Why the Merge?

I have decided to merge the two packages, gsynth and fect, as gsynth is fundamentally a counterfactual estimator based on ife. The two packages increasingly share similar code modules and features, including core algorithms (the ife and mc methods in both packages are essentially identical), tuning methods, and visualization tools. This merge will greatly simplify package maintenance moving forward.

Moving forward, I will discontinue maintaining gsynth and focus on adding more functionalities to fect.

Two Research Settings

The differences between gsynth and fect reflect a broader distinction in panel data methods. We separate two research settings.

The Synth (synthetic control) setting learns time components from never-treated units, optionally via dimension reduction (e.g., factor models), and projects counterfactuals for treated units through vertical regression. This is the setting of gsynth (Xu 2017). Designed for block or staggered adoption without treatment reversal, it is well suited for a small number of treated units (including $N_{tr} = 1$). The estimand is SATT.

The DID/TWFE setting imputes treated counterfactuals using all not-yet-treated observations, including both never-treated units and pre-treatment periods of treated units. This accommodates treatment reversal and uses more data. The estimand is PATT.

Inference differs across the two settings. The Synth setting conditions on fixed pre-treatment information $X$ and uses predictive uncertainty, implemented via a two-stage parametric bootstrap (vartype = "parametric"). The DID/TWFE setting relies on super-population inference, for which nonparametric bootstrap (vartype = "bootstrap") or jackknife (vartype = "jackknife") are appropriate.

Estimation and Inference

Starting from v2.2.0, time.component.from determines which setting governs estimation. It specifies how time components, such as time fixed effects, latent factors, and temporal dynamics, are learned from the data. The table summarizes compatibility.

Method	Description	`time.component.from`
`"fe"`	Two-way fixed effects ($r = 0$)	Both
`"ife"`	Interactive fixed effects ($r \geq 0$)	Both
`"cfe"`	Complex fixed effects	Both
`"mc"`	Matrix completion	`"notyettreated"` only
`"gsynth"`	Equivalent to `"ife"` with `time.component.from = "nevertreated"`	`"nevertreated"`

The two values correspond to the two settings. "notyettreated" (default) uses all not-yet-treated observations to learn components. "nevertreated" uses only never-treated controls.

How Should I Choose?

Choose based on estimand and inference. If the target is unit-specific and conditions on $X$, use the Synth setting. If the target is a population parameter, use the DID framework. The table below gives recommendations based on feasibility in common scenarios.

Scenario	Recommended Settings
Treatment switches on and off	`time.component.from = "notyettreated"` (default)
No reversal, many treated units	Either setting
No reversal, few treated units	`time.component.from = "nevertreated"`, `vartype = "parametric"`
Reproduce gsynth	`method = "gsynth"` or `method = "ife"`, `time.component.from = "nevertreated"`

Organization

The user guide is structured into four parts. Most users only need the Basics part to perform a complete analysis with the fixed effects counterfactual estimator; the remaining parts are referenced as needed.

Basics

Chapter 1 Get Started
Installation instructions and datasets.
Chapter 2 The Imputation Estimator
The fixed effects counterfactual estimator (FEct), including estimation, basic inference, and the group.fe argument for sub-group treatment (e.g., counties nested in states with a state-level policy).
Chapter 3 Alternative Estimands
Alternative estimands and the unified post-hoc estimand interface: cumulative ATT, APTT, log-scale ATT, window-restricted ATT, and the long-form accessor for custom estimands.

Advanced estimators and inference

Chapter 4 Factor-Based Methods
Interactive fixed effects (IFE) and matrix completion (MC) methods, cross-validation, and diagnostic tests.
Chapter 5 Complex Fixed Effects
The complex fixed effects (CFE) estimator: multi-level fixed effects, time-invariant covariates with time-varying coefficients, unit-specific time trends, in addition to interactive fixed effects.
Chapter 6 Gsynth Program
The Gsynth program — the synthetic control setting using time.component.from = "nevertreated" — originally developed in the gsynth package, with CFE extensions.
Chapter 7 Inference
Bootstrap inference internals: the vartype × ci.method × para.error matrix, parametric bootstrap mechanics, and the decision tree for choosing an inference path. Most relevant after Chapter 6 Gsynth Program where parametric bootstrap is the default.

Diagnostics and extensions

Chapter 8 Effect Heterogeneity
Effect heterogeneity: box plots, calendar-time trends, and covariate-based HTE. Triple difference-in-differences designs (in development).
Chapter 9 Modern DID Methods
Application of various “modern” DID estimators.
Chapter 10 Sensitivity Analysis
Sensitivity analysis for the counterfactual estimators.

Reference

Chapter 11 Plot Options
Detailed reference for plot options and customization, with examples for factor diagnostics, HTE, and modern-DID visualizations.
Chapter 12 Cheatsheet
Quick reference for methods, parameters, plotting, and diagnostics.

Contributors

The following individuals (and AI) have contributed to gsynth and fect, listed in the order of their involvement in the project:

Yiqing Xu
Licheng Liu
Ye Wang
Ziyi Liu (PhD Student at Berkeley Haas)
Shijian Liu (PhD Student at NYU Stern)
Tianzhu Qin (PhD Student at Cambridge University)
Jinwen Wu (Predoc at Stanford PoliSci)
Rivka Lipkovitz (Undergraduate at MIT)
StatsClaw (Agentic System for Statistical Software Development)

How to Cite

To cite the fect package or this user manual, please use:

Xu, Yiqing, Licheng Liu, Ye Wang, Ziyi Liu, Shijian Liu, Tianzhu Qin, Jinwen Wu, and Rivka Lipkovitz. 2026. fect: Fixed Effects Counterfactual Estimators — User Manual (v2.4.5). https://yiqingxu.org/packages/fect/

@manual{fect2026,
  title = {fect: Fixed Effects Counterfactual Estimators --- User Manual},
  author = {Xu, Yiqing and Liu, Licheng and Wang, Ye and Liu, Ziyi and Liu, Shijian and Qin, Tianzhu and Wu, Jinwen and Lipkovitz, Rivka},
  year = {2026},
  note = {R package version 2.4.5},
  url = {https://yiqingxu.org/packages/fect/}
}

Report Bugs

Please report any bugs by submitting an issue on GitHub or emailing me (yiqingxu [at] stanford.edu). We’d really appreciate it if you can include your minimally replicable code & data file and a panelView treatment status plot. Your feedback is highly valued!

fect:

gsynth (wrapper):

panelView:

# Welcome! {.unnumbered} ```{r} #| include: false source("_common.R") ``` This Quarto book serves as a user manual for the **fect** package in R, which implements counterfactual (imputation) estimators for causal inference with panel data---without feedback---and performs diagnostic tests. **fect** covers a series of counterfactual estimators, including the five estimators from the last version and integrating the latest version of the **gsynth** package ([User Manual](https://yiqingxu.org/packages/gsynth/)) for the generalized synthetic control method (Gsynth). This Quarto book also facilitates the application of various new difference-in-differences (DID) estimators. For details of these methods, see - @Xu2017 for Gsynth \[<a href="https://www.cambridge.org/core/journals/political-analysis/article/generalized-synthetic-control-method-causal-inference-with-interactive-fixed-effects-models/B63A8BD7C239DD4141C67DA10CD0E4F3" target="_blank">Paper</a>\] - @LWX2024 for counterfactual estimators \[<a href="https://onlinelibrary.wiley.com/doi/full/10.1111/ajps.12723" target="_blank">Paper</a>\] - @CLLX2026 for a survey of the new DID estimators \[<a href="https://www.cambridge.org/core/journals/american-political-science-review/article/causal-panel-analysis-under-parallel-trends-lessons-from-a-large-reanalysis-study/219275E0CE901F099F2CFFBA07079243" target="_blank">Paper</a>\] ::: {.callout-note appearance="simple"} ### Source Code and Version For those interested in exploring the algorithms used in **fect** for calculating estimates, please visit the source [GitHub Repo](https://github.com/xuyiqing/fect) for further details. This manual was rendered against **fect** `r read.dcf("../DESCRIPTION")[,"Version"]` on `r format(Sys.Date(), "%Y-%m-%d")`. ::: ## Why Counterfactual Estimators? There are several reasons why you might consider using counterfactual estimators for your panel data applications: - Because "causal inference is a missing data problem" [@holland1986statistics], it is natural to impute treated counterfactuals when the ATT, if well defined, is the primary quantity of interest. - Counterfactual estimators help avoid the (negative) weighting problem, which has been highlighted in recent applied econometrics literature regarding TWFE models, e.g., @CDH2020; @goodman2021difference.\ - Among the newer estimators that accommodate heterogeneous treatment effects, the fixed effect counterfactual estimator (imputation based on TWFE) is the most efficient under homoskedasticity [@BJS2024].\ - Counterfactual estimators enable the use of more complex modeling strategies, such as linear factor models and matrix completion methods, which naturally connect to the synthetic control setting. However, these counterfactual estimators come with important limitations: - Most rely on some form of the parallel trends assumption or a low-rank structure.\ - They generally do not accommodate dynamic treatment assignment given past outcomes or covariates---i.e., "feedback"---based on sequential ignorability.\ - Methods for continuous treatments are still underdeveloped and are not currently covered by **fect**. @CLLX2026 reanalyze 49 published studies in political science and offer justifications for adopting these estimators. ## Why the Merge? I have decided to merge the two packages, **gsynth** and **fect**, as **gsynth** is fundamentally a counterfactual estimator based on `ife`. The two packages increasingly share similar code modules and features, including core algorithms (the `ife` and `mc` methods in both packages are essentially identical), tuning methods, and visualization tools. This merge will greatly simplify package maintenance moving forward. Moving forward, I will discontinue maintaining **gsynth** and focus on adding more functionalities to **fect**. ## Two Research Settings The differences between **gsynth** and **fect** reflect a broader distinction in panel data methods. We separate two research settings. The **Synth** (synthetic control) setting learns time components from never-treated units, optionally via dimension reduction (e.g., factor models), and projects counterfactuals for treated units through vertical regression. This is the setting of **gsynth** [@Xu2017]. Designed for block or staggered adoption without treatment reversal, it is well suited for a small number of treated units (including $N_{tr} = 1$). The estimand is SATT. The **DID/TWFE** setting imputes treated counterfactuals using all not-yet-treated observations, including both never-treated units and pre-treatment periods of treated units. This accommodates treatment reversal and uses more data. The estimand is PATT. Inference differs across the two settings. The Synth setting conditions on fixed pre-treatment information $X$ and uses predictive uncertainty, implemented via a two-stage parametric bootstrap (`vartype = "parametric"`). The DID/TWFE setting relies on super-population inference, for which nonparametric bootstrap (`vartype = "bootstrap"`) or jackknife (`vartype = "jackknife"`) are appropriate. ### Estimation and Inference Starting from `v2.2.0`, `time.component.from` determines which setting governs estimation. It specifies how time components, such as time fixed effects, latent factors, and temporal dynamics, are learned from the data. The table summarizes compatibility. | Method | Description | `time.component.from` | |:------------------|:-----------------------|:----------------------------| | `"fe"` | Two-way fixed effects ($r = 0$) | Both | | `"ife"` | Interactive fixed effects ($r \geq 0$) | Both | | `"cfe"` | Complex fixed effects | Both | | `"mc"` | Matrix completion | `"notyettreated"` only | | `"gsynth"` | Equivalent to `"ife"` with `time.component.from = "nevertreated"` | `"nevertreated"` | The two values correspond to the two settings. `"notyettreated"` (default) uses all not-yet-treated observations to learn components. `"nevertreated"` uses only never-treated controls. ### How Should I Choose? Choose based on estimand and inference. If the target is unit-specific and conditions on $X$, use the Synth setting. If the target is a population parameter, use the DID framework. The table below gives recommendations based on feasibility in common scenarios. | Scenario | Recommended Settings | |:-----------------------|:-----------------------------------------------| | Treatment switches on and off | `time.component.from = "notyettreated"` (default) | | No reversal, many treated units | Either setting | | No reversal, few treated units | `time.component.from = "nevertreated"`, `vartype = "parametric"` | | Reproduce **gsynth** | `method = "gsynth"` or `method = "ife"`, `time.component.from = "nevertreated"` | ## Organization The user guide is structured into four parts. Most users only need the **Basics** part to perform a complete analysis with the fixed effects counterfactual estimator; the remaining parts are referenced as needed. ### Basics - [Chapter @sec-start]\ Installation instructions and datasets. - [Chapter @sec-fect]\ The fixed effects counterfactual estimator (FEct), including estimation, basic inference, and the `group.fe` argument for sub-group treatment (e.g., counties nested in states with a state-level policy). - [Chapter @sec-estimands]\ Alternative estimands and the unified post-hoc estimand interface: cumulative ATT, APTT, log-scale ATT, window-restricted ATT, and the long-form accessor for custom estimands. ### Advanced estimators and inference - [Chapter @sec-ife-mc]\ Interactive fixed effects (IFE) and matrix completion (MC) methods, cross-validation, and diagnostic tests. - [Chapter @sec-cfe]\ The complex fixed effects (CFE) estimator: multi-level fixed effects, time-invariant covariates with time-varying coefficients, unit-specific time trends, in addition to interactive fixed effects. - [Chapter @sec-gsynth]\ The Gsynth program --- the synthetic control setting using `time.component.from = "nevertreated"` --- originally developed in the **gsynth** package, with CFE extensions. - [Chapter @sec-inference]\ Bootstrap inference internals: the `vartype` × `ci.method` × `para.error` matrix, parametric bootstrap mechanics, and the decision tree for choosing an inference path. Most relevant after Chapter @sec-gsynth where parametric bootstrap is the default. ### Diagnostics and extensions - [Chapter @sec-hte]\ Effect heterogeneity: box plots, calendar-time trends, and covariate-based HTE. Triple difference-in-differences designs (in development). - [Chapter @sec-panel]\ Application of various "modern" DID estimators. - [Chapter @sec-panel-sens]\ Sensitivity analysis for the counterfactual estimators. ### Reference - [Chapter @sec-plots]\ Detailed reference for plot options and customization, with examples for factor diagnostics, HTE, and modern-DID visualizations. - [Chapter @sec-cheatsheet]\ Quick reference for methods, parameters, plotting, and diagnostics. ## Contributors The following individuals (and AI) have contributed to **gsynth** and **fect**, listed in the order of their involvement in the project: - [Yiqing Xu](https://yiqingxu.org/)\ - [Licheng Liu](https://liulch.github.io/)\ - [Ye Wang](https://www.yewang-polisci.com/)\ - Ziyi Liu (PhD Student at Berkeley Haas) - Shijian Liu (PhD Student at NYU Stern) - [Tianzhu Qin](https://tianzhuqin.github.io/) (PhD Student at Cambridge University) - Jinwen Wu (Predoc at Stanford PoliSci) - [Rivka Lipkovitz](https://rivka.me/) (Undergraduate at MIT) - [StatsClaw](https://statsclaw.ai/) (Agentic System for Statistical Software Development) ## How to Cite To cite the **fect** package or this user manual, please use: > Xu, Yiqing, Licheng Liu, Ye Wang, Ziyi Liu, Shijian Liu, Tianzhu Qin, Jinwen Wu, and Rivka Lipkovitz. 2026. *fect: Fixed Effects Counterfactual Estimators --- User Manual (v2.4.5).* <https://yiqingxu.org/packages/fect/> ``` bibtex @manual{fect2026, title = {fect: Fixed Effects Counterfactual Estimators --- User Manual}, author = {Xu, Yiqing and Liu, Licheng and Wang, Ye and Liu, Ziyi and Liu, Shijian and Qin, Tianzhu and Wu, Jinwen and Lipkovitz, Rivka}, year = {2026}, note = {R package version 2.4.5}, url = {https://yiqingxu.org/packages/fect/} } ``` ## Report Bugs Please report any bugs by submitting an issue on [GitHub](https://github.com/xuyiqing/fect/issues) or emailing me (yiqingxu \[at\] stanford.edu). We'd really appreciate it if you can include your minimally replicable code & data file and a **panelView** treatment status plot. Your feedback is highly valued!  **fect**: [![Lifecycle: stable](https://lifecycle.r-lib.org/articles/figures/lifecycle-stable.svg)](https://www.tidyverse.org/lifecycle/#stable) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [<img src="https://www.r-pkg.org/badges/version/fect" alt="CRAN status"/>](https://CRAN.R-project.org/package=fect) [<img src="https://cranlogs.r-pkg.org/badges/grand-total/fect" alt="CRAN downloads"/>](https://cran.r-project.org/web/packages/fect/index.html) ```{=html}  ``` [**gsynth**](https://yiqingxu.org/packages/gsynth/) (wrapper): [![Lifecycle: stable](https://lifecycle.r-lib.org/articles/figures/lifecycle-stable.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [<img src="https://www.r-pkg.org/badges/version/gsynth" alt="CRAN status"/>](https://CRAN.R-project.org/package=gsynth) [<img src="https://cranlogs.r-pkg.org/badges/grand-total/gsynth" alt="downloads: CRAN"/>](https://cran.r-project.org/web/packages/gsynth/index.html) [**panelView**](https://yiqingxu.org/packages/panelview/): [![Lifecycle: stable](https://lifecycle.r-lib.org/articles/figures/lifecycle-stable.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [<img src="https://www.r-pkg.org/badges/version/panelView" alt="CRAN status"/>](https://CRAN.R-project.org/package=panelView) [<img src="https://cranlogs.r-pkg.org/badges/grand-total/panelView" alt="downloads: CRAN"/>](https://cran.r-project.org/package=panelView)