fect: Fixed Effects Counterfactual Estimators

In xuyiqing/fect: Fixed Effects Counterfactual Estimators

Fixed Effects Counterfactual Estimators

Description

Implements counterfactual estimators in TSCS data analysis and statistical tools to test their identification assumptions.

Usage

fect(formula = NULL, data, Y, D, X = NULL, 
            W = NULL, group = NULL,
            na.rm = FALSE, 
            index, force = "two-way", r = 0, lambda = NULL, nlambda = 10,
            CV = NULL, k = 10, cv.prop = 0.1, cv.treat = FALSE, 
            cv.nobs = 3, cv.donut = 0, criterion = "mspe",
            binary = FALSE, QR = FALSE,
            method = "fe",  se = FALSE, vartype = "bootstrap", cl = NULL,
            quantile.CI = FALSE, nboots = 200, alpha = 0.05, 
            parallel = TRUE, cores = NULL, tol = 1e-3, 
            max.iteration = 1000, seed = NULL, 
            min.T0 = NULL, max.missing = NULL, 
            proportion = 0.3, pre.periods = NULL, 
            f.threshold = 0.5, tost.threshold = NULL,
            knots = NULL, degree = 2, 
            sfe = NULL, cfe = NULL,
            balance.period = NULL, fill.missing = FALSE,
            placeboTest = FALSE, placebo.period = NULL,
            carryoverTest = FALSE, carryover.period = NULL, carryover.rm = NULL,
            loo = FALSE, permute = FALSE, m = 2, normalize = FALSE)

Arguments

formula	an object of class "formula": a symbolic description of the model to be fitted, e.g, Y~D+X1+X2
data	a data frame, can be a balanced or unbalanced panel data.
Y	the outcome indicator.
D	the treatment indicator. The treatment should be binary (0 and 1).
X	time-varying covariates. Covariates that have perfect collinearity with specified fixed effects are dropped automatically.
W	the weight indicator. If specified, the program will fit the data with a weighted outcome model and calculate weighted average and dynamic treatment effect.
group	the group indicator. If specified, the group-wise ATT will be estimated.
na.rm	a logical flag indicating whether to list-wise delete missing observations. Default to FALSE. If na.rm = FALSE, it allows the situation when Y is missing but D is not missing for some observations. If na.rm = TRUE, it will list-wise delete observations whose Y, D, or X is missing.
index	a two-element string vector specifying the unit and time indicators. Must be of length 2. Every observation should be uniquely defined by the pair of the unit and time indicator.
force	a string indicating whether unit or time or both fixed effects will be imposed. Must be one of the following, "none", "unit", "time", or "two-way". The default is "two-way".
r	an integer specifying the number of factors. If CV = TRUE, the cross validation procedure will select the optimal number of factors from r to 5.
lambda	a single or sequence of positive numbers specifying the hyper-parameter sequence for matrix completion method. If lambda is a sequence and CV = 1, cross-validation will be performed.
nlambda	an integer specifying the length of hyper-parameter sequence for matrix completion method. Default is nlambda = 10.
CV	a logical flag indicating whether cross-validation will be performed to select the optimal number of factors or hyper-parameter in matrix completion algorithm. If r is not specified, the procedure will search through r = 0 to 5.
k	an integer specifying number of cross-validation rounds. Default is k = 10.
cv.prop	a numerical value specifying the proportion of testing set compared to sample size during the cross-validation procedure.
cv.treat	a logical flag speficying whether to only use observations of treated units as testing set.
cv.nobs	an integer specifying the length of continuous observations within a unit in the testing set. Default is cv.nobs = 3.
cv.donut	an integer specifying the length of removed observations at the head and tail of the continuous observations specified by cv.nobs.
criterion	criterion used for model selection. Default is "mspe". "mspe" for the mean squared prediction error, "gmspe" for the geometric-mean squared prediction errors, "moment" for period-weighted residuals in test sets, "pc" for an information criterion method.
binary	This version doesn't support this option.
QR	This version doesn't support this option.
method	a string specifying which imputation algorithm will be used. "fe", "ife", "mc", "polynomial", "bspline", "gsynth", or "cfe". Default is "fe".
se	a logical flag indicating whether uncertainty estimates will be produced.
vartype	a string specifying the type of variance estimator, e.g. "bootstrap".
cl	a string specifying the cluster for cluster bootstrapping.
quantile.CI	a logical flag indicating whether to use quantile confidence intervals when bootstrapping.
nboots	an integer specifying the number of bootstrap runs. Ignored if se=FALSE.
alpha	the significance level for hypothesis tests and confidence intervals. Default 0.05.
parallel	a logical flag indicating whether parallel computing will be used in bootstrapping or cross-validation.
cores	an integer indicating the number of cores for parallel computing.
tol	a positive number indicating the tolerance level for EM updates.
max.iteration	the maximal number of iterations for the EM algorithm.
seed	an integer seed for random number generation.
min.T0	an integer specifying the minimum number of pre-treatment periods for each treated unit.
max.missing	an integer specifying the maximum number of missing observations allowed per unit.
proportion	a numeric value specifying which pre-treatment periods are used for goodness-of-fit tests.
pre.periods	a vector specifying the range of pre-treatment periods used for the goodness-of-fit test.
f.threshold	a numeric threshold for an F-test in equivalence testing. Default 0.5.
tost.threshold	a numeric threshold for two-one-sided t-tests.
knots	a numeric vector specifying knots for the b-spline.
degree	an integer specifying the polynomial or b-spline degree.
sfe	vector specifying other fixed effects for method="cfe".
cfe	a vector of lists specifying interactive fixed effects for method="cfe".
balance.period	a length-2 vector specifying a time range for a balanced sample.
fill.missing	a logical flag indicating whether to allow missing observations in a balanced sample.
placeboTest	a logical flag indicating whether to perform a placebo test.
placebo.period	an integer or 2-element numeric vector specifying pseudo-treatment periods.
carryoverTest	a logical flag for carryover tests.
carryover.period	an integer or 2-element numeric vector specifying pseudo-carryover periods.
carryover.rm	an integer specifying the range of post-treatment periods to treat as carryover.
loo	a logical flag for leave-one-period-out goodness-of-fit tests.
permute	a logical flag indicating whether to run a permutation test.
m	an integer specifying the block length for permutation tests. Default 2.
normalize	a logical flag indicating whether to scale outcome and covariates.

Details

fect implements counterfactual estimators for TSCS data. It first imputes counterfactuals by fitting an outcome model using untreated observations, then estimates the individual treatment effect as the difference between observed and predicted outcomes. Finally, it computes average treatment effects on the treated (ATT) and period-specific ATTs. Placebo and equivalence tests help evaluate identification assumptions.

Value

Y.dat	T-by-N matrix of the outcome variable.
D.dat	T-by-N matrix of the treatment variable.
I.dat	T-by-N matrix of observation indicators (observed/missing).
Y	name of the outcome variable.
D	name of the treatment variable.
X	name of any time-varying covariates.
W	name of the weight variable.
index	name of the unit and time indicators.
force	specified fixed effects option.
T	number of time periods.
N	number of units.
p	number of time-varying observables.
r.cv	number of factors (selected by cross-validation if needed).
lambda.cv	optimal hyper-parameter for matrix completion, if applicable.
beta	coefficients for any covariates in an interactive fixed effects model.
sigma2	mean squared error.
IC	information criterion.
est	results of the fitted model.
MSPE	mean squared prediction error from cross-validation.
CV.out	results of the cross-validation procedure.
niter	number of iterations.
factor	estimated time-varying factors.
lambda	estimated loadings.
lambda.tr	estimated loadings for treated units.
lambda.co	estimated loadings for control units.
mu	estimated grand mean.
xi	estimated time fixed effects.
alpha	estimated unit fixed effects.
alpha.tr	estimated unit fixed effects for treated units.
alpha.co	estimated unit fixed effects for control units.
validX	logical indicating if valid covariates exist.
validF	logical indicating if factors exist.
id	vector of unit IDs.
rawtime	vector of time periods.
obs.missing	matrix indicating missingness patterns.
Y.ct	T-by-N matrix of predicted outcomes under no treatment.
eff	T-by-N matrix of estimated individual treatment effects.
res	residuals for observed values.
eff.pre	effects for treated units in pre-treatment periods.
eff.pre.equiv	pre-treatment effects under baseline (two-way FE) model.
pre.sd	by-period residual standard deviations for pre-treatment ATT.
att.avg	overall average treatment effect on the treated.
att.avg.W	weighted ATT.
att.avg.unit	by-unit average treatment effect on the treated.
time	time index for switch-on treatment effect.
count	count of observations for each switch-on effect time.
att	switch-on treatment effect.
att.on.W	weighted switch-on effect.
time.off	time index for switch-off treatment effect.
att.off	switch-off treatment effect.
att.off.W	weighted switch-off effect.
count.off	count for each switch-off period.
att.placebo	ATT for placebo periods.
att.carryover	ATT for carryover periods.
eff.calendar	ATT by calendar time.
eff.calendar.fit	loess-fitted ATT by calendar time.
N.calandar	number of treated observations each calendar period.
balance.avg.att	ATT for balanced sample.
balance.att	switch-on ATT for balanced sample.
balance.time	time index for balanced sample.
balance.count	count for each time in balanced sample.
balance.att.placebo	ATT for placebo period in balanced sample.
group.att	ATT for different groups.
group.output	list of switch-on treatment effects by group.
est.att.avg	inference for att.avg.
est.att.avg.unit	inference for att.avg.unit.
est.att	inference for att.
est.att.W	inference for weighted att.
est.att.off	inference for switch-off.
est.att.off.W	inference for weighted switch-off.
est.placebo	inference for placebo ATT.
est.carryover	inference for carryover ATT.
est.eff.calendar	inference for eff.calendar.
est.eff.calendar.fit	inference for eff.calendar.fit.
est.balance.att	inference for balanced sample switch-on.
est.balance.avg	inference for balanced sample average ATT.
est.balance.placebo	inference for balanced sample placebo.
est.avg.W	inference for att.avg.W.
est.beta	inference for beta.
est.group.att	inference for group-specific ATT.
est.group.output	inference for group output.
att.avg.boot	bootstrap draws for att.avg.
att.avg.unit.boot	bootstrap draws for att.avg.unit.
att.count.boot	bootstrap draws for count.
att.off.boot	bootstrap draws for att.off.
att.off.count.boot	bootstrap draws for count.off.
att.placebo.boot	bootstrap draws for att.placebo.
att.carryover.boot	bootstrap draws for att.carryover.
balance.att.boot	bootstrap draws for balance.att.
att.bound	equivalence confidence interval for pre-trend.
att.off.bound	equivalence confidence interval for switch-off.
beta.boot	bootstrap draws for beta.
test.out	F-test and equivalence test results for pre-treatment fit.
loo.test.out	leave-one-period-out test results.
permute	permutation test results.

Author(s)

Licheng Liu; Ye Wang; Yiqing Xu; Ziyi Liu

References

Athey, S., Bayati, M., Doudchenko, N., Imbens, G., and Khosravi, K. (2021). Matrix completion methods for causal panel data models. Journal of the American Statistical Association, 116(536), 1716-1730.

Bai, J. (2009). Panel data models with interactive fixed effects. Econometrica, 77(4), 1229-1279.

Liu, L., Wang, Y., and Xu, Y. (2022). A Practical Guide to Counterfactual Estimators for Causal Inference with Time-Series Cross-Sectional Data. American Journal of Political Science, 68(1), 160-176.

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

See Also

plot.fect, print.fect

Examples

library(fect)
data(fect)
out <- fect(Y ~ D + X1 + X2, data = simdata, 
            index = c("id","time"), force = "two-way",
            CV = TRUE, r = c(0, 5), se = 0, parallel = FALSE) 

xuyiqing/fect documentation built on April 12, 2025, 9:50 p.m.