Package 'fect' reference manual

Package 'fect'

Title:	Fixed Effects Counterfactuals
Description:	Estimates causal effects with panel data using the counterfactual methods. It is suitable for panel or time-series cross-sectional analysis with binary treatments under (hypothetically) baseline randomization.It allows a treatment to switch on and off and limited carryover effects. It supports linear factor models, a generalization of gsynth and the matrix completion method. Implementation details can be found in Liu, Wang and Xu (2022) <arXiv:2107.00856>.
Authors:	Licheng Liu [aut], Ziyi Liu [aut, cre], Ye Wang [aut], Yiqing Xu [aut]
Maintainer:	Ziyi Liu <[email protected]>
License:	MIT + file LICENSE
Version:	1.0.0
Built:	2024-11-04 06:44:00 UTC
Source:	CRAN

Title:

Fixed Effects Counterfactuals

Description:

Estimates causal effects with panel data using the counterfactual methods. It is suitable for panel or time-series cross-sectional analysis with binary treatments under (hypothetically) baseline randomization.It allows a treatment to switch on and off and limited carryover effects. It supports linear factor models, a generalization of gsynth and the matrix completion method. Implementation details can be found in Liu, Wang and Xu (2022) <arXiv:2107.00856>.

Authors:

Licheng Liu [aut], Ziyi Liu [aut, cre], Ye Wang [aut], Yiqing Xu [aut]

Maintainer:

Ziyi Liu <[email protected]>

License:

MIT + file LICENSE

Version:

1.0.0

Built:

2024-11-04 06:44:00 UTC

Source:

CRAN

Help Index

Fixed Effects Counterfactual Estimators

Description

The package implements counterfactual estimators in TSCS data analysis and statistical tools to test their identification assumptions.

Details

It implements counterfactual estimators in TSCS data analysis. These estimators first impute counterfactuals for each treated observation in a TSCS dataset by fitting an outcome model (fixed effects model, interactive fixed effects model, or matrix completion) using the untreated observations. They then estimate the individualistic treatment effect for each treated observatio n by subtracting the predicted counterfactual outcome from its observed outcome. Finally, the average treatment effect on the treated (ATT) or period-specific ATTs are calculated. A placebo test and an equivalence test are included to evaluate the validity of identification assumptions behind these estimators.

See fect for details.

Author(s)

Licheng Liu <[email protected]>, MIT

Ye Wang <[email protected]>, New York University

Yiqing Xu <[email protected] >, Stanford University

Ziyi Liu <[email protected]>, University of Chicago

References

Jushan Bai. 2009. "Panel Data Models with Interactive Fixed Effects." Econometrica.

Yiqing Xu. 2017. "Generalized Synthetic Control Method: Causal Inference with Interactive Fixed Effects Models." Political Analysis.

Athey, Susan, et al. 2021 "Matrix completion methods for causal panel data models." Journal of the American Statistical Association.

Licheng Liu, et al. 2022. "A Practical Guide to Counterfactual Estimators for Causal Inference with Time-Series Cross-Sectional Data." American Journal of Political Science.

Calculate Cumulative Treatment Effects

Description

Calculate cumulative treatment effects

Usage

att.cumu(x, period = NULL, weighted = TRUE, alpha = 0.05, type = "on", plot = FALSE)att.cumu(x, period = NULL, weighted = TRUE, alpha = 0.05, type = "on", plot = FALSE)

Arguments

`x`	a `fect` object.
`period`	a two-element numeric vector specifying the range of term during which treatment effects are to be accumulated. e.g. `period = c(-1,1)`.
`weighted`	a logical flag specifying whether to calculate weigthed cumulative treatment effects based on counts at each period. Default is `weighted = TRUE`.
`alpha`	a numerical value that specfies significant level.
`type`	a string that specifies the type. Must be one of the following: "on" (switch-on treatment effect); "off" (switch-off treatment effect). Default is `type = "on"`.
`plot`	A logical flag indicating whether to plot cumulative effects. Default is `plot = FALSE`.

Author(s)

Licheng Liu; Ye Wang; Yiqing Xu

References

Jushan Bai. 2009. "Panel Data Models with Interactive Fixed Effects." Econometrica.

Yiqing Xu. 2017. "Generalized Synthetic Control Method: Causal Inference with Interactive Fixed Effects Models." Political Analysis.

Athey, Susan, et al. 2021 "Matrix completion methods for causal panel data models." Journal of the American Statistical Association.

Licheng Liu, et al. 2022. "A Practical Guide to Counterfactual Estimators for Causal Inference with Time-Series Cross-Sectional Data." American Journal of Political Science.

For more details about the matrix completion method, see https://github.com/susanathey/MCPanel.

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, 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", nboots = 200, alpha = 0.05,
            parallel = TRUE, cores = NULL, tol = 0.001, 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)  
fect(formula = NULL, data, Y, D, X = 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", nboots = 200, alpha = 0.05,
            parallel = TRUE, cores = NULL, tol = 0.001, 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.
`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`. These removed observations will not be used to fit the data nor be in the validation set for the cross-validation, e.g, if `cv.nobs=3` and `cv.donut = 1`, the first and the last observation in each triplet will not be included in the test set. Default is `cv.donut = 0`.
`criterion`	criterion used for model selection. Default is "mspe". `"mspe"` for the mean squared prediction error, `"gmspe"` for the geometric-mean squared prediction errors, if `criterion="moment"`, we average the residuals in test sets by their relative periods to treatments and then average the squares of these period-wise deviations weighted by the number of observations at each period, it yields a better pre-trend fitting on test sets rather than a better prediction ability. `"pc"` for the information criterion of interactive fixed effects or generalized synthetic control model.
`binary`	This version doesn't support this option. a logical flag indicating whether a probit link function will be used.
`QR`	This version doesn't support this option. a logical flag indicating whether QR decomposition will be used for factor analysis in probit model.
`method`	a string specifying which imputation algorithm will be used. `"fe"` for fixed effects model, `"ife"` for interactive fixed effects model, `"mc"` for matrix copletion method, `"polynomial"` for polynomial trend terms, `"bspline"` for regression splines, `"gsynth"` for generalized synthetic control method, and `"cfe"` for complex fixed effects method Default is `method = "fe"`.
`se`	a logical flag indicating whether uncertainty estimates will be produced.
`vartype`	a string specifying the type of variance estimator. Choose from `vartype = c("bootstrap", "jackknife", "parametric")`. Default value is `"bootstrap"`.
`nboots`	an integer specifying the number of bootstrap runs. Ignored if `se = FALSE`.
`alpha`	significant level for hypothesis test and CIs. Default value is `alpha = 0.05`.
`parallel`	a logical flag indicating whether parallel computing will be used in bootstrapping and/or cross-validation. Ignored if `se = FALSE`.
`cores`	an integer indicating the number of cores to be used in parallel computing. If not specified, the algorithm will use the maximum number of logical cores of your computer (warning: this could prevent you from multi-tasking on your computer).
`tol`	a positive number indicating the tolerance level.
`seed`	an integer that sets the seed in random number generation. Ignored if `se = FALSE` and `r` is specified.
`min.T0`	an integer specifying the minimum value of observed periods that a unit is under control.
`max.missing`	an integer. Units with number of missing values greater than it will be removed. Ignored if this parameter is set "NULL"(i.e. `max.missing = NULL`, the default setting).
`proportion`	a numeric value specifying pre-treatment periods that have observations larger than the proportion of observations at period 0. These pre-treatment periods are used used for goodness-of-fit test. Ignore if `se = FALSE`. Deafult is `proportion = 0.3`.
`pre.periods`	a vector specifying the range of pre-treatment period used for goodness-of-fit test. If left blank, all pre-treatment periods specified by `proportion` will be used. Ignore if `se = FALSE`.
`f.threshold`	a numeric value specifying the threshold for the F-statistic in the equivalent test. Ignore if `se = FALSE`. Deafult is `f.threshold = 0.5`.
`tost.threshold`	a numeric value specifying the threshold for the two-one-sided t-test. If `alpha=0.05`, TOST checks whether the 90 The default value is 0.36 times the standard deviation of the outcome variable after two-way fixed effects are partialed out.
`knots`	a numeric vector speicfying the knots for b-spline curve trend term.
`degree`	an integer speifcying the order of either the b-spline or the polynomial trend term.
`sfe`	a vector specifying other fixed effects in addition to unit or time fixed effects that is used when `method="cfe"`.
`cfe`	a vector of lists specifying interactive fixed effects when `method="cfe"`. For each list, the value of the first element is the name of the group variable for which fixed effects are to be estimated. The value of the second element is the name of a regressor (e.g., a time trend).
`balance.period`	a vector of length 2 specifying the range of periods for a balanced sample which has no missing observation in the specified range.
`fill.missing`	a logical flag indicating whether to allow missing observations in this balanced sample. The default is FALSE.
`placeboTest`	a logic flag indicating whether to perform placebo test.
`placebo.period`	an integer or a two-element numeric vector specifying the range of pre-treatment periods that will be assigned as pseudo treatment periods.
`carryoverTest`	a logic flag indicating whether to perform (no) carryover test.
`carryover.period`	an integer or a two-element numeric vector specifying the range of post-treatment periods that will be assigned as pseudo treatment periods.
`carryover.rm`	an integer specifying the range of post-treatment periods that will be assigned as pseudo treatment periods.
`loo`	a logic flag indicating whether to perform the leave-one-period-out goodness-of-fit test, which is very time-consuming.
`permute`	a logic flag indicating whether to perform permutation test.
`m`	an integer specifying the block length in permutation test. Default value is `m = 2`.
`normalize`	a logic flag indicating whether to scale outcome and covariates. Useful for accelerating computing speed when magnitude of data is large. The default is `normalize=FALSE`.

Details

fect implements counterfactual estimators in TSCS data analysis. These estimators first impute counterfactuals for each treated observation in a TSCS dataset by fitting an outcome model (fixed effects model, interactive fixed effects model, or matrix completion) using the untreated observations. They then estimate the individualistic treatment effect for each treated observation by subtracting the predicted counterfactual outcome from its observed outcome. Finally, the average treatment effect on the treated (ATT) or period-specific ATTs are calculated. A placebo test and an equivalence test are included to evaluate the validity of identification assumptions behind these estimators. Data must be with a dichotomous treatment.

Value

`Y.dat`	a T-by-N matrix storing data of the outcome variable.
`D.dat`	a T-by-N matrix storing data of the treatment variable.
`I.dat`	a T-by-N matrix storing data of the indicator for whether is observed or missing.
`Y`	name of the outcome variable.
`D`	name of the treatment variable.
`X`	name of the time-varying control variables.
`index`	name of the unit and time indicators.
`force`	user specified `force` option.
`T`	the number of time periods.
`N`	the total number of units.
`p`	the number of time-varying observables.
`r.cv`	the number of factors included in the model – either supplied by users or automatically chosen via cross-validation.
`lambda.cv`	the optimal hyper-parameter in matrix completion method chosen via cross-validation.
`beta`	coefficients of time-varying observables from the interactive fixed effect model.
`sigma2`	the mean squared error of interactive fixed effect model.
`IC`	the information criterion.
`est`	result of the interactive fixed effect model based on observed values.
`MSPE`	mean squared prediction error of the cross-validated model.
`CV.out`	result of the cross-validation procedure.
`niter`	the number of iterations in the estimation of the interactive fixed effect model.
`factor`	estimated time-varying factors.
`lambda`	estimated loadings.
`lambda.tr`	estimated loadings for treated units.
`lambda.co`	estimated loadings for control units.
`mu`	estimated ground 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`	a logic value indicating if multicollinearity exists.
`validF`	a logic value indicating if factor exists.
`id`	a vector of unit IDs.
`rawtime`	a vector of time periods.
`obs.missing`	a matrix stroing status of each unit at each time point.
`Y.ct`	a T-by-N matrix storing the predicted Y(0).
`eff`	a T-by-N matrix storing the difference between actual outcome and predicted Y(0).
`res`	residuals for observed values.
`eff.pre`	difference between actual outcome and predicted Y(0) for observations of treated units under control.
`eff.pre.equiv`	difference between actual outcome and predicted Y(0) for observations of treated units under control based on baseline (two-way fixed effects) model.
`pre.sd`	by period residual standard deviation for estimated pre-treatment average treatment effects.
`att.avg`	average treatment effect on the treated.
`att.avg.unit`	by unit average treatment effect on the treated.
`time`	term for switch-on treatment effect.
`count`	count of each term for switch-on treatment effect.
`att`	switch-on treatment effect.
`time.off`	term for switch-off treatment effect.
`att.off`	switch-off treatment effect.
`count.off`	count of each term for switch-off treatment effect.
`att.placebo`	average treatment effect for placebo period.
`att.carryover`	average treatment effect for carryover period.
`eff.calendar`	average treatment effect for each calendar period.
`eff.calendar.fit`	loess fitted values of average treatment effect for each calendar period.
`N.calandar`	number of treated observations at each calendar period.
`balance.avg.att`	average treatment effect for the balance sample.
`balance.att`	switch-on treatment effect for the balance sample.
`balance.time`	term of switch-on treatment effect for the balance sample.
`balance.count`	count of each term for switch-on treatment effect for the balance sample.
`balance.att.placebo`	average treatment effect for placebo period of the balance sample.
`group.att`	average treatment effect for different groups.
`group.output`	a list saving the switch-on treatment effects for different groups.
`est.att.avg`	inference for `att.avg`.
`est.att.avg.unit`	inference for `att.avg.unit`.
`est.att`	inference for `att.on`.
`est.att.off`	inference for `att.off`.
`est.placebo`	inference for `att.placebo`.
`est.carryover`	inference for `att.carryover`.
`est.eff.calendar`	inference for `eff.calendar`.
`est.eff.calendar.fit`	inference for `eff.calendar.fit`.
`est.balance.att`	inference for `balance.att`.
`est.balance.avg`	inference for `balance.avg.att`.
`est.balance.placebo`	inference for `balance.att.placebo`.
`est.beta`	inference for `beta`.
`est.group.att`	inference for `group.att`.
`est.group.output`	inference for `group.output`.
`att.avg.boot`	bootstrap results for `att.avg`.
`att.avg.unit.boot`	bootstrap results for `att.avg.unit`.
`att.count.boot`	bootstrap results for `count`.
`att.off.boot`	bootstrap results for `att.avg.off`.
`att.off.count.boot`	bootstrap results for `count.off`.
`att.placebo.boot`	bootstrap results for `att.placebo`.
`att.carryover.boot`	bootstrap results for `att.carryover`.
`balance.att.boot`	bootstrap results for `balance.att`.
`att.bound`	equivalence confidence interval for equivalence test.
`att.off.bound`	equivalence confidence interval for equivalence test for switch-off effect.
`beta.boot`	bootstrap results for `beta`.
`test.out`	goodness-of-fit test and equivalent test results for pre-treatment fitting check.
`loo.test.out`	leave-one-period-out goodness-of-fit test and equivalent test results for pre-treatment fitting check.
`permute`	permutation test results for sharp null hypothesis.

Author(s)

Licheng Liu; Ye Wang; Yiqing Xu; Ziyi Liu

References

Jushan Bai. 2009. "Panel Data Models with Interactive Fixed Effects." Econometrica.

Yiqing Xu. 2017. "Generalized Synthetic Control Method: Causal Inference with Interactive Fixed Effects Models." Political Analysis.

Athey, Susan, et al. 2021 "Matrix completion methods for causal panel data models." Journal of the American Statistical Association.

Licheng Liu, et al. 2022. "A Practical Guide to Counterfactual Estimators for Causal Inference with Time-Series Cross-Sectional Data." American Journal of Political Science.

For more details about the matrix completion method, see https://github.com/susanathey/MCPanel.

Examples

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

Internal FEct Functions

Description

Internal fect functions

Details

These are not to be called by the user (or in some cases are just waiting for proper documentation to be written :).

Get the Cohort Index

Description

Gets the cohort index given a panel data.

Usage

get.cohort(data, D, index, 
                  varname = NULL, entry.time = NULL)
get.cohort(data, D, index, 
                  varname = NULL, entry.time = NULL)

Arguments

`data`	a data frame, can be a balanced or unbalanced panel data.
`D`	the treatment indicator. The treatment should be binary (0 and 1).
`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.
`varname`	a string specifying the name for the generated cohort index.
`entry.time`	a list of intervals for first get-treated time.

Details

get.cohort pre-processes the data and generates the index for different cohorts..

Value

data

a new data frame containing the cohort index.

Author(s)

Licheng Liu; Ye Wang; Yiqing Xu, Ziyi Liu

References

Jushan Bai. 2009. "Panel Data Models with Interactive Fixed Effects." Econometrica.

Yiqing Xu. 2017. "Generalized Synthetic Control Method: Causal Inference with Interactive Fixed Effects Models." Political Analysis.

Athey, Susan, et al. 2021 "Matrix completion methods for causal panel data models." Journal of the American Statistical Association.

Licheng Liu, et al. 2022. "A Practical Guide to Counterfactual Estimators for Causal Inference with Time-Series Cross-Sectional Data." American Journal of Political Science.

For more details about the matrix completion method, see https://github.com/susanathey/MCPanel.

Examples

library(fect)
data(fect)
simdata.cohort <- get.cohort(data = simdata,D = 'D',index = c("id","time"))
library(fect)
data(fect)
simdata.cohort <- get.cohort(data = simdata,D = 'D',index = c("id","time"))

Interactive Fixed Effects Models

Description

Estimating interactive fixed effect models.

Usage

interFE(formula = NULL, data, Y, X, index, r = 0, force = "none",
         se = TRUE, nboots = 500, seed = NULL, 
         tol = 1e-3, binary = FALSE, QR = FALSE, normalize = FALSE)
interFE(formula = NULL, data, Y, X, index, r = 0, force = "none",
         se = TRUE, nboots = 500, seed = NULL, 
         tol = 1e-3, binary = FALSE, QR = FALSE, normalize = FALSE)

Arguments

`formula`	an object of class "formula": a symbolic description of the model to be fitted.
`data`	a data frame (must be with a dichotomous treatment but balanced is not required).
`Y`	outcome.
`X`	time-varying covariates.
`index`	a two-element string vector specifying the unit (group) and time indicators. Must be of length 2.
`r`	an integer specifying the number of factors.
`force`	a string indicating whether unit or time fixed effects will be imposed. Must be one of the following, "none", "unit", "time", or "two-way". The default is "unit".
`se`	a logical flag indicating whether uncertainty estimates will be produced via bootstrapping.
`nboots`	an integer specifying the number of bootstrap runs. Ignored if `se = FALSE`.
`seed`	an integer that sets the seed in random number generation. Ignored if `se = FALSE` and `r` is specified.
`tol`	a numeric value that specifies tolerate level.
`binary`	a logical flag indicating whether a probit link function will be used.
`QR`	a logical flag indicating whether QR decomposition will be used for factor analysis in probit model.
`normalize`	a logic flag indicating whether to scale outcome and covariates. Useful for accelerating computing speed when magnitude of data is large.The default is `normalize=FALSE`.

Details

interFE estimates interactive fixed effect models proposed by Bai (2009).

Value

`beta`	estimated coefficients.
`mu`	estimated grand mean.
`factor`	estimated factors.
`lambda`	estimated factor loadings.
`VNT`	a diagonal matrix that consists of the r eigenvalues.
`niter`	the number of iteration before convergence.
`alpha`	estimated unit fixed effect (if `force` is "unit" or "two-way").
`xi`	estimated time fixed effect (if `force` is "time" or "two-way").
`residuals`	residuals of the estimated interactive fixed effect model.
`sigma2`	mean squared error of the residuals.
`IC`	the information criterion.
`ValidX`	a logical flag specifying whether there are valid covariates.
`dat.Y`	a matrix storing data of the outcome variable.
`dat.X`	an array storing data of the independent variables.
`Y`	name of the outcome variable.
`X`	name of the time-varying control variables.
`index`	name of the unit and time indicators.
`est.table`	a table of the estimation results.
`est.boot`	a matrix storing results from bootstraps.

Author(s)

Licheng Liu; Ye Wang; Yiqing Xu

References

Jushan Bai. 2009. "Panel Data Models with Interactive Fixed Effects." Econometrica 77:1229–1279.

Examples

library(fect)
data(fect)
d <- simdata1[-(1:150),] # remove the treated units
out <- interFE(Y ~ X1 + X2, data = d, index=c("id","time"),
               r = 2, force = "two-way", nboots = 50)
library(fect)
data(fect)
d <- simdata1[-(1:150),] # remove the treated units
out <- interFE(Y ~ X1 + X2, data = d, index=c("id","time"),
               r = 2, force = "two-way", nboots = 50)

Plotting

Description

Visualizes estimation results of the matrix completion method.

Usage

## S3 method for class 'fect'
plot(x, type = NULL, loo = "FALSE", 
            highlight = NULL, plot.ci = NULL, show.points = NULL,
            show.group = NULL, bound = NULL, vis = NULL,
            count = TRUE, proportion = 0.3, pre.periods = NULL,
            f.threshold = NULL, tost.threshold = NULL,
            effect.bound.ratio = FALSE, 
            stats = NULL, stats.labs = NULL, 
            main = NULL, 
            xlim = NULL, ylim = NULL, xlab = NULL, ylab = NULL, 
            gridOff = FALSE, legendOff = FALSE, legend.pos = NULL, legend.nrow = NULL,
            legend.labs = NULL, stats.pos = NULL, theme.bw = TRUE,
            nfactors = NULL, include.FE = TRUE,
            id = NULL,
            cex.main = NULL, cex.main.sub = NULL, cex.axis = NULL,
            cex.lab = NULL, cex.legend = NULL, cex.text = NULL,
            axis.adjust = FALSE, axis.lab = "both", axis.lab.gap = c(0, 0),
            start0 = FALSE,
            return.test = FALSE,
            balance = NULL,...)
## S3 method for class 'fect'
plot(x, type = NULL, loo = "FALSE", 
            highlight = NULL, plot.ci = NULL, show.points = NULL,
            show.group = NULL, bound = NULL, vis = NULL,
            count = TRUE, proportion = 0.3, pre.periods = NULL,
            f.threshold = NULL, tost.threshold = NULL,
            effect.bound.ratio = FALSE, 
            stats = NULL, stats.labs = NULL, 
            main = NULL, 
            xlim = NULL, ylim = NULL, xlab = NULL, ylab = NULL, 
            gridOff = FALSE, legendOff = FALSE, legend.pos = NULL, legend.nrow = NULL,
            legend.labs = NULL, stats.pos = NULL, theme.bw = TRUE,
            nfactors = NULL, include.FE = TRUE,
            id = NULL,
            cex.main = NULL, cex.main.sub = NULL, cex.axis = NULL,
            cex.lab = NULL, cex.legend = NULL, cex.text = NULL,
            axis.adjust = FALSE, axis.lab = "both", axis.lab.gap = c(0, 0),
            start0 = FALSE,
            return.test = FALSE,
            balance = NULL,...)

Arguments

`x`	a `fect` object.
`type`	a string specifying the type of the plot. `"gap"` plots the estimated period-wise ATT (dynamic treatment effects), `"equiv"` shows the visualization of the equivalence test, `"exit"` plots the estimated period-wise switch-off effects, `"status"` shows the treatment status of all observations, `"factors"` plots the estimated factor and time fixed effects, `"loadings"` plots the estimated factor loadings and unit fixed effects, `"calendar"` plots the estimated treatment effects for each calendar period, and `"box"` visualizes the estimated individualistic treatment effects of observations.
`loo`	a logical flag indicating whether to use the leave-one-period-out pre-treatment effects for the visualization and tests.
`highlight`	a logical flag indicating whether to highlight the periods for the carryover and placebo test.
`plot.ci`	a string specifying the confidence interval. Choose from: "0.9", "0.95", or "none".
`show.points`	a logical flag indicating whether to represent treatment effects by points or point-ranges. Default to TRUE.
`show.group`	a string indicating the group to be visualized.
`bound`	a string that specifies the bounds to be plotted for equivalence test for pre-treatment fit checking. Choose from: "both", "equiv", "min" and "none".
`vis`	A string specifying whether to plot the dots for placebo plots.
`count`	a logical flag controlling whether to show the count of each term for gap plot.
`proportion`	a positive value specifying periods at which observations equal to or greater than the proporation of the largest number of observations at a certain period. Default to 0.3.
`pre.periods`	a vector specifying the range of pre-treatment period used for goodness-of-fit test. If left blank, all pre-treatment periods specified by `proportion` will be used. Ignore if `se = FALSE`.
`f.threshold`	a numeric value specifying the threshold for the F-statistic in the equivalent test. Ignore if `se = FALSE`. Deafult is `f.threshold = 0.5`.
`tost.threshold`	a numeric value specifying the threshold for the two-one-sided t-test. If `alpha=0.05`, TOST checks whether the 90 The default value is 0.36 times the standard deviation of the outcome variable after two-way fixed effects are partialed out.
`effect.bound.ratio`	a logical value specifiying whether to annotate the ratio of estimated average treatment effects / minimun bound.
`stats`	a string that specifices what statistics to be shown. For `"gap"` plot, choose from `c("none", "F.p", "equiv.p", "F.equiv.p",)`, for `"placebo"` plot, choose from `c("none", "placebo.p", "equiv.placebo.p")`, and for "carryover" plot, choose from `c("none", "carryover.p")`.
`stats.labs`	a string specifying the label for the statistics specified by `stats`.
`main`	a string that controls the title of the plot. If not supplied, no title will be shown.
`xlim`	a two-element numeric vector specifying the range of x-axis. When class of time varible is string, must specify not original value but a counting number e.g. `xlim=c(1,30)`.
`ylim`	a two-element numeric vector specifying the range of y-axis.
`xlab`	a string indicating the label of the x-axis.
`ylab`	a string indicating the label of the y-axis.
`gridOff`	a logical flag indicating whether to remove the grid lines for the status plot.
`legendOff`	a logical flag controlling whether to show the legend.
`legend.pos`	a string specifying the position of legend. If left blank, legend will be setted at the bottom.
`legend.nrow`	an integer speficying rows of legend.
`legend.labs`	a string vector for user-defined legends.
`stats.pos`	a numeric vector of length 2 specifying the postion for labels of test statistic value.
`theme.bw`	a logical flag specifying whether to use the black and white theme.
`nfactors`	a integer controlling the number of factors to be shown when `type='factors'`.
`include.FE`	a loical flag indicating whether to keep the fixed effects when `type='factors'` or `type='loadings'`.
`id`	a string vector specifying a sub-group of units that are to be plotted for treatment status(`type = "status"`).
`cex.main`	a numeric value (pt) specifying the fontsize of the main title.
`cex.main.sub`	a numeric value (pt) specifying the fontsize of the subtitles.
`cex.axis`	a numeric value (pt) specifying the fontsize of the texts on the axes.
`cex.lab`	a numeric value (pt) specifying the fontsize of the axis titles.
`cex.legend`	a numeric value (pt) specifying the fontsize of the legend.
`cex.text`	a numeric value (pt) specifying the fontsize of the annotations.
`axis.adjust`	a logic flag indicating whether to adjust labels on x-axis. Useful when class of time variable is string and data magnitude is large.
`axis.lab`	a string indicating whether labels on the x- and y-axis will be shown. There are four options: `"both"` (default): labels on both axes will be shown; `"unit"`: only labels on y-axis will be shown; `"time"`: only labels on the x-axis will be shown; "none": no labels will be shown.
`axis.lab.gap`	a numeric vector setting the gaps between labels on the x- or y-axis for `"missing"` plot. Default is `axis.lab.gap = c(0, 0)`, which means that all labels will be shown. Useful for datasets with large N or T.
`start0`	a logical flag indicating whether to index the start of the treatment as period 0 rather than period 1. Default to FALSE.
`return.test`	a logical flag indicating whether to return the results of statistical tests.
`balance`	a logical flag indicating whether to plot the dynamic treatment effects for the balance sample.
`...`	other argv.

Details

plot.fect visualizes the estimation results obtained by fect.

Value

`p`	a ggplot2 object saving the graph.
`test.out`	a list storing the results of statistical tests if `return.test=TRUE`.

Author(s)

Licheng Liu; Ye Wang; Yiqing Xu, Ziyi Liu

References

Jushan Bai. 2009. "Panel Data Models with Interactive Fixed Effects." Econometrica.

Yiqing Xu. 2017. "Generalized Synthetic Control Method: Causal Inference with Interactive Fixed Effects Models." Political Analysis.

Athey, Susan, et al. 2021 "Matrix completion methods for causal panel data models." Journal of the American Statistical Association.

Licheng Liu, et al. 2022. "A Practical Guide to Counterfactual Estimators for Causal Inference with Time-Series Cross-Sectional Data." American Journal of Political Science.

For more details about the matrix completion method, see https://github.com/susanathey/MCPanel.

Examples

library(fect)
data(fect)
out <- fect(Y ~ D + X1 + X2, data = simdata1, 
            index = c("id","time"), force = "two-way",
            CV = TRUE, r = c(0, 5), se = 0, parallel = FALSE) 
plot(out)
plot(out,type='status')
plot(out,show.points = FALSE)
library(fect)
data(fect)
out <- fect(Y ~ D + X1 + X2, data = simdata1, 
            index = c("id","time"), force = "two-way",
            CV = TRUE, r = c(0, 5), se = 0, parallel = FALSE) 
plot(out)
plot(out,type='status')
plot(out,show.points = FALSE)

Print Results

Description

Print results of the matrix completion method.

Usage

## S3 method for class 'fect'
print(x, switch.on = TRUE,
       switch.off = FALSE,time.on.lim = NULL, time.off.lim = NULL, ...)## S3 method for class 'fect'
print(x, switch.on = TRUE,
       switch.off = FALSE,time.on.lim = NULL, time.off.lim = NULL, ...)

Arguments

`x`	a `fect` object.
`switch.on`	a logical value that specifies whether to print switch.on effect.
`switch.off`	a logical value that specifies whether to print switch.off effect.
`time.on.lim`	a two-element numeric vector specifying the range of term of switch-on treatment effects. e.g. `time.on.lim = c(-1,1)`.
`time.off.lim`	a two-element numeric vector specifying the range of term of switch-off treatment effects. e.g. `time.off.lim = c(-1,1)`.
`...`	other argv.

Value

No return value.

Author(s)

Licheng Liu; Ye Wang; Yiqing Xu; Ziyi Liu

References

Jushan Bai. 2009. "Panel Data Models with Interactive Fixed Effects." Econometrica.

Yiqing Xu. 2017. "Generalized Synthetic Control Method: Causal Inference with Interactive Fixed Effects Models." Political Analysis.

Athey, Susan, et al. 2021 "Matrix completion methods for causal panel data models." Journal of the American Statistical Association.

Licheng Liu, et al. 2022. "A Practical Guide to Counterfactual Estimators for Causal Inference with Time-Series Cross-Sectional Data." American Journal of Political Science.

For more details about the matrix completion method, see https://github.com/susanathey/MCPanel.

Examples

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

Print Results

Description

Print results of interactive fixed effects estimation.

Usage

## S3 method for class 'interFE'
print(x, ...)## S3 method for class 'interFE'
print(x, ...)

Arguments

`x`	an `interFE` object.
`...`	other argv.

Value

No return value.

Author(s)

Licheng Liu; Ye Wang; Yiqing Xu

References

Jushan Bai. 2009. "Panel Data Models with Interactive Fixed Effects." Econometrica 77:1229–1279.

Examples

library(fect)
data(fect)
d <- simdata1[-(1:150),] # remove the treated units
out <- interFE(Y ~ X1 + X2, data = d, index=c("id","time"),
               r = 2, force = "two-way", nboots = 50)
print(out)
library(fect)
data(fect)
d <- simdata1[-(1:150),] # remove the treated units
out <- interFE(Y ~ X1 + X2, data = d, index=c("id","time"),
               r = 2, force = "two-way", nboots = 50)
print(out)

Simulated data

Description

A simulated dataset with continuous outcomes.

Format

dataframe

References

Liu, Licheng, Ye Wang, and Yiqing Xu. 2022. “A Practical Guide to Counterfactual Estimators for Causal Inference with Time-Series Cross-Sectional Data.” American Journal of Political Science, forthcoming.

Simulated data

Description

A simulated dataset with continuous outcomes.

Format

dataframe

References

EDR and voter turnout in the US

Description

State-level voter turnout data.

Format

dataframe

References

Melanie Jean Springer. 2014. How the States Shaped the Nation: American Electoral Institutions and Voter Turnout, 1920-2000. University of Chicago Press.

Yiqing Xu. 2017. "Generalized Synthetic Control Method: Causal Inference with Interactive Fixed Effects Models." Political Analysis.

Package 'fect'

Help Index

Fixed Effects Counterfactual Estimators

Description

Details

Author(s)

References

Calculate Cumulative Treatment Effects

Description

Usage

Arguments

Author(s)

References

See Also

Fixed Effects Counterfactual Estimators

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

Examples

Internal FEct Functions

Description

Details

Get the Cohort Index

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

Examples

Interactive Fixed Effects Models

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

Examples

Plotting

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

Examples

Print Results

Description

Usage

Arguments

Value

Author(s)

References

See Also

Examples

Print Results

Description

Usage

Arguments

Value

Author(s)

References

See Also

Examples

Simulated data

Description

Format

References

Simulated data