Visualizes results from a fect estimation.
# S3 method for fect
plot(
x,
type = NULL,
restrict = "rm",
loo = FALSE,
highlight = NULL,
plot.ci = NULL,
show.points = TRUE,
show.group = NULL,
bound = NULL,
show.count = TRUE,
proportion = 0.3,
pre.periods = NULL,
f.threshold = NULL,
tost.threshold = NULL,
effect.bound.ratio = FALSE,
stats = NULL,
stats.labs = NULL,
raw = "none",
vis = NULL,
main = NULL,
xlim = NULL,
ylim = NULL,
xlab = NULL,
ylab = NULL,
xangle = NULL,
yangle = NULL,
xbreaks = NULL,
ybreaks = NULL,
xticklabels = NULL,
yticklabels = NULL,
gridOff = NULL,
legendOff = FALSE,
legend.pos = NULL,
legend.nrow = NULL,
legend.labs = NULL,
stats.pos = NULL,
show.stats = TRUE,
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),
shade.post = FALSE,
start0 = FALSE,
return.test = FALSE,
balance = NULL,
weight = NULL,
lcolor = NULL,
lwidth = NULL,
ltype = NULL,
line.color = NULL,
line.width = NULL,
count = NULL,
preset = NULL,
connected = NULL,
ci.outline = FALSE,
color = NULL,
est.lwidth = NULL,
est.pointsize = NULL,
count.color = NULL,
count.alpha = NULL,
count.outline.color = NULL,
placebo.color = NULL,
carryover.color = NULL,
carryover.rm.color = NULL,
sens.original.color = NULL,
sens.colors = NULL,
counterfactual.color = NULL,
counterfactual.raw.controls.color = NULL,
counterfactual.raw.treated.color = NULL,
counterfactual.linetype = NULL,
box.control = NULL,
box.treat = NULL,
calendar.color = NULL,
calendar.lcolor = NULL,
calendar.cicolor = NULL,
heterogeneous.color = NULL,
heterogeneous.lcolor = NULL,
heterogeneous.cicolor = NULL,
equiv.color = NULL,
status.treat.color = NULL,
status.control.color = NULL,
status.missing.color = NULL,
status.removed.color = NULL,
status.placebo.color = NULL,
status.carryover.color = NULL,
status.carryover.rm.color = NULL,
status.balanced.post.color = NULL,
status.balanced.pre.color = NULL,
status.background.color = NULL,
covariate = NULL,
covariate.labels = NULL,
...
)A ggplot2 object representing the plot. If return.test=TRUE, a list containing:
The ggplot2 object.
A list or data frame containing relevant test statistics (such as F-tests, equivalence p-values, placebo test p-values, etc.), if applicable to the plot type and options chosen.
A fitted fect object.
Plot type. Options include: "gap", "equiv" (equivalence test), "status" (treatment status), "exit" (exiting treatment effects),
"factors", "loadings", "calendar" (ATT by calendar time), "box" (individual effects distribution), "counterfactual",
"sens" (sensitivity analysis plot, e.g., for Rambachan & Roth bounds), "sens_es" (event-study style sensitivity plot),
or "cumul" (cumulative effect plot). Default is context-dependent (e.g., "gap", or "equiv" if loo=TRUE).
For sensitivity plots (type = "sens" or type = "sens_es"). Specifies the type of restriction: "rm" (restriction on M, for relative magnitude bounds) or "sm" (smoothness restriction, for bounds based on second differences). Default is "rm".
Logical; if TRUE (default is FALSE), use leave-one-out estimates for pre-treatment periods in equivalence tests or gap plots.
Logical or NULL (default). If TRUE, highlights specific periods such as placebo or carryover periods in relevant tests. If NULL, defaults to TRUE if a placebo or carryover test is being plotted, and FALSE otherwise.
Specifies the confidence interval to be plotted. Options include:
"0.9", "0.95", or "none". Default is NULL, which is context-dependent (e.g., "0.95" for gap plots, "0.9" for equivalence plots, "none" if no CIs are available in the fect object).
Logical; if TRUE (default), shows point estimates on event study style plots (e.g., gap, equiv, exit plots).
Optional character string or NULL (default); if specified, plots results for a particular subgroup defined in the fect call.
Which bounds to display in bounding/equivalence tests:
"none" (default for most plots), "min" (minimal effect bound), "equiv" (equivalence range), or "both" (default for type="equiv").
Logical; if TRUE (default), shows a histogram of observation counts (number of treated units) in relevant plots like gap, calendar, or box plots.
Numeric (0 to 1); for event study plots, restricts plotted time points to those where the number of treated units is at least this fraction of the maximum number of treated units observed across all periods. Default is 0.3.
Optional numeric vector; specifies pre-treatment periods to be used for bounding and equivalence tests. Default is NULL, which uses the pre-treatment periods defined in the fect object.
Numeric or NULL (default); F-test threshold for equivalence checks. If NULL, uses the value from the fect object.
Numeric or NULL (default); threshold for TOST-based equivalence checks (e.g., for pre-trend, placebo, or carryover tests). If NULL, uses the value from the fect object.
Logical; if TRUE (default is FALSE), shows the ratio of ATT to the minimal bound in equivalence plots.
Character vector or NULL (default); specifies which test statistics to display on the plot (e.g., "F.p", "equiv.p", "placebo.p"). Default is context-dependent based on plot type and tests performed.
Character vector or NULL (default); custom labels for the displayed statistics. Must match the length of stats.
For type = "counterfactual" plot: "none" (default; shows average treated and counterfactual lines), "band" (shows 5-95% quantile band for raw control/treated data), or "all" (shows all raw control/treated unit trajectories).
(Deprecated) Formerly controlled line display for placebo/carryover tests. This is now handled by highlight and internal logic.
Character string or NULL (default); main plot title. If NULL, a default title is used based on the plot type.
Numeric vector of length 2 or NULL (default); specifies x-axis limits.
Numeric vector of length 2 or NULL (default); specifies y-axis limits.
Character string or NULL (default); x-axis label. If NULL, a default label is used based on the plot type.
Character string or NULL (default); y-axis label. If NULL, a default label is used based on the plot type.
Numeric or NULL (default); angle (in degrees) for x-axis tick labels.
Numeric or NULL (default); angle (in degrees) for y-axis tick labels.
Numeric vector or NULL (default); positions of major ticks on the x-axis.
Numeric vector or NULL (default); positions of major ticks on the y-axis.
Character vector or NULL (default); custom labels for the x-axis ticks. Primarily used in status plots.
Character vector or NULL (default); custom labels for the y-axis ticks. Primarily used in status plots.
Logical or NULL (default). If TRUE, removes major and minor grid lines. If NULL (which defaults to FALSE internally for this argument), the grid is off for most plots but on for type = "status" (where it forms tile outlines).
Logical; if TRUE (default is FALSE), hides the legend.
Character string or NULL (default); position of the legend (e.g., "bottom", "top", "right", "left", "none", or c(x,y) coordinates). Default is typically "bottom".
Integer or NULL (default); number of rows in the legend.
Character vector or NULL (default); custom legend labels.
Numeric vector of length 2 or NULL (default); (x,y) coordinates for displaying the text of test statistics on the plot.
Logical; if TRUE (default), displays test statistics on the plot if stats is not "none".
Logical; if TRUE (default), uses a black-and-white ggplot2 theme (theme_bw()). If FALSE and no preset is specified, uses theme_grey().
Integer or NULL (default); number of factors to plot when type is "factors" or "loadings". Defaults to min(r.cv, 4), where r.cv is the number of estimated factors.
Logical; if TRUE (default), includes fixed effects as additional "factors" in factor/loading plots if applicable (i.e., if unit or time fixed effects were estimated as part of the factor model).
Character vector or NULL (default); when specified, plots only the chosen unit(s). For counterfactual plots (type="counterfactual"), only one ID is typically supported for individual unit display; otherwise, averages are shown.
Numeric or NULL (default); font size multiplier for the main plot title. Base size is 16pt.
Numeric or NULL (default); font size multiplier for a possible subtitle. Base size is 16pt.
Numeric or NULL (default); font size multiplier for axis tick labels. Base size is 15pt.
Numeric or NULL (default); font size multiplier for axis labels. Base size is 15pt.
Numeric or NULL (default); font size multiplier for legend text. Base size is 15pt.
Numeric or NULL (default); font size multiplier for text annotations on the plot (e.g., statistics values). Base size is 5pt.
Logical; if TRUE (default is FALSE), attempts to adjust axis labels for plots with many time points (e.g., by rotating x-axis labels).
Controls axis labeling in type="status" plots. Options: "both" (default), "time", "unit", or "off".
Numeric vector of length 1 or 2; gap spacing for axis labels in type="status" plots (sets frequency of labels). Default is c(0, 0) (label every tick).
Logical; if FALSE (default). If TRUE, shades post-treatment periods in certain plots. For counterfactual plots, if NULL (the default for the argument is FALSE), it effectively becomes TRUE internally unless explicitly set to FALSE.
Logical; if TRUE (default is FALSE), re-indexes the first post-treatment period as 0 in event-time plots (gap, equiv, exit). The period before treatment becomes -1.
Logical; if TRUE (default is FALSE), returns a list containing the plot object and relevant test statistics instead of just the plot.
Logical or NULL (default); if TRUE, uses a "balance sample" (if available from the fect object, e.g., from setting balanced.sample = TRUE in fect) for plotting.
Logical or NULL (default); if TRUE, applies weighting (if available from the fect object, e.g., from providing weights in fect) to the estimates being plotted.
Character vector of length 1 or 2, or NULL (default). If NULL, uses a default color (e.g., "#AAAAAA70" if theme.bw=TRUE, else "white" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Numeric vector of length 1 or 2, or NULL (default). If NULL, uses a default width (e.g., 1.5 if theme.bw=TRUE, else 2 for the base style). The preset argument may define a different width. Specifying this argument directly overrides any preset or base style setting.
Character vector of length 1 or 2, or NULL (default). If NULL, uses a default linetype (e.g., c("solid", "solid") for the base style). The preset argument may define a different linetype (e.g., preset="vibrant" uses c("solid", "dashed")). Specifying this argument directly overrides any preset or base style setting.
(Deprecated) Use color for main estimate lines or lcolor for reference lines instead.
(Deprecated) Use est.lwidth for main estimate lines or lwidth for reference lines instead.
(Deprecated) Use show.count to control visibility and count.color, count.alpha, count.outline.color for appearance.
A character string specifying a color and style preset: NULL (default, uses a base style, often with theme_bw if theme.bw=TRUE), "vibrant", or "grayscale". This sets a group of defaults for many plot elements. Individual appearance arguments (like color, lcolor, etc.) can override settings from a preset or the base style.
Logical or NULL (default). For event study type plots (e.g., type="gap"), if TRUE, connects points with lines; if FALSE, shows point-ranges. If NULL, defaults to FALSE for the base style, and TRUE if preset = "vibrant".
Logical; if FALSE (default). For event study plots where CIs are shown as ribbons, if TRUE, adds an outline to the CI ribbon.
Character string or NULL (default). If NULL, uses a default color for main plot lines/points (e.g., "black" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Numeric or NULL; line width for the main estimate line in event study plots. If NULL (default), the width is determined based on connected and show.points (e.g., `0.6` for point-ranges with the base style, `0.7` for connected points with markers with the base style). The preset argument may influence this default. Specifying a numeric value directly overrides any other setting.
Numeric or NULL; size of points for the main estimate in event study plots. If NULL (default), the size is determined based on connected and show.points (e.g., `2` for point-ranges with the base style, `1.2` for connected points with markers with the base style). The preset argument may influence this default. Specifying a numeric value directly overrides any other setting.
Character string or NULL (default). If NULL, uses a default color for count bars (e.g., "grey70" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Numeric (0-1) or NULL (default). If NULL, uses a default alpha for count bars (e.g., 0.4 for the base style). The preset argument may define a different alpha. Specifying this argument directly overrides any preset or base style setting.
Character string or NULL (default). If NULL, uses a default outline color for count bars (e.g., "grey69" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Character string or NULL (default). If NULL, uses a default color for placebo elements (e.g., "blue" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Character string or NULL (default). If NULL, uses a default color for carryover elements (e.g., "red" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Character string or NULL (default). If NULL, uses a default color for removed carryover elements (e.g., "blue" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Character string or NULL (default). If NULL, uses a default color for original estimates in sensitivity plots (e.g., "darkblue" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Vector of colors or NULL (default). If NULL, uses a default palette for sensitivity bounds (e.g., c("#218C23","#FF34B4","#FF521B","#2B59C3") for the base style). The preset argument may define a different palette. Specifying this argument directly overrides any preset or base style setting.
Character string or NULL (default). If NULL, uses a default color for counterfactual lines (e.g., "steelblue" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Character string or NULL (default). If NULL, uses a default color for raw control lines (e.g., "#4682B420" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Character string or NULL (default). If NULL, uses a default color for raw treated lines (e.g., "#77777750" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Character string or NULL (default). If NULL, uses a default linetype for counterfactual lines (e.g., "longdash" for the base style). The preset argument may define a different linetype. Specifying this argument directly overrides any preset or base style setting.
Character string or NULL (default). If NULL, uses a default fill color for control boxplots (e.g., "skyblue" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Character string or NULL (default). If NULL, uses a default fill color for treated boxplots (e.g., "pink" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Character string or NULL (default). If NULL, uses a default color for fitted lines in calendar plots (e.g., "skyblue" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Character string or NULL (default). If NULL, uses a default color for average ATT lines in calendar plots (e.g., "red" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Character string or NULL (default). If NULL, uses a default color for CI in calendar plots (e.g., "red" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Character string or NULL (default). If NULL, uses a default color for fitted lines in heterogeneous plots (e.g., "red" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Character string or NULL (default). If NULL, uses a default color for average ATT lines in heterogeneous plots (e.g., "red" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Character string or NULL (default). If NULL, uses a default color for CI in heterogeneous plots (e.g., "red" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Character string or NULL (default). If NULL, uses a default color for equivalence bounds (e.g., "red" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Character string or NULL (default). If NULL, uses a default color for treated status (e.g., "#06266F" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Character string or NULL (default). If NULL, uses a default color for control status (e.g., "#B0C4DE" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Character string or NULL (default). If NULL, uses a default color for missing status (e.g., "#FFFFFF" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Character string or NULL (default). If NULL, uses a default color for removed status (e.g., "#A9A9A9" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Character string or NULL (default). If NULL, uses a default color for placebo status (e.g., "#66C2A5" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Character string or NULL (default). If NULL, uses a default color for carryover status (e.g., "#E78AC3" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Character string or NULL (default). If NULL, uses a default color for removed carryover status (e.g., "#ffc425" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Character string or NULL (default). If NULL, uses a default color for balanced post-treatment status (e.g., "#00852B" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Character string or NULL (default). If NULL, uses a default color for balanced pre-treatment status (e.g., "#A5CA18" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Character string or NULL (default). If NULL, uses a default background color for status plots (e.g., "gray90" for the base style). The preset argument may define a different color. Specifying this argument directly overrides any preset or base style setting.
Character string or NULL (default). If NULL, uses a default covariate for heterogeneous plots (e.g., "X" for the base style). The preset argument may define a different covariate. Specifying this argument directly overrides any preset or base style setting.
Character vector or NULL (default). If NULL, uses a default covariate labels for heterogeneous plots (e.g., "X1" for the base style). The preset argument may define a different covariate labels. Specifying this argument directly overrides any preset or base style setting.
Additional graphical parameters passed to internal plotting routines, primarily those accepted by esplot for event study style plots (gap, equiv, exit, sens_es, cumul).
Licheng Liu, Ye Wang, Yiqing Xu, Ziyi Liu, Rivka Lipkovitz
plot.fect generates various visualizations for objects estimated via fect. Depending on
the selected type, it can show treatment-effect dynamics ("gap", "exit", "cumul"),
equivalence test outcomes ("equiv"), factor/loadings for factor models ("factors", "loadings"),
raw vs. counterfactual trajectories ("counterfactual"), treatment status ("status"),
effects by calendar time ("calendar"), distribution of individual effects ("box"),
or sensitivity analysis results ("sens", "sens_es").
The preset argument allows for quick customization of plot aesthetics using predefined color schemes.
Many individual color and style parameters can be set to further customize the appearance, and these will override any settings from a preset or the base style.
The function heavily relies on ggplot2 for plotting and esplot for event-study style visualizations.
Xu, Y. (2017). Generalized Synthetic Control Method: Causal Inference with Interactive Fixed Effects Models. Political Analysis, 25(1), 57–76.
Liu, L., Wang, Y., & Xu, Y. (2022). A Practical Guide to Counterfactual Estimators for Causal Inference with Time-Series Cross-Sectional Data.
American Journal of Political Science, 66(1), 220-237. (Provides context for esplot which is used internally for many plot types)
Rambachan, A., & Roth, J. (2023). A More Credible Approach to Parallel Trends.
Review of Economic Studies, 90(5), 2555-2591. (Provides context for sensitivity analysis plots like type="sens" and type="sens_es")
library(fect)
# For CRAN checks, use a small number of bootstraps
# In practice, use a larger number (e.g., nboots = 200 or more)
if(requireNamespace("ggplot2") && requireNamespace("ggrepel")) {
data(simdata)
# Estimate with fixed effects method
out.fect <- fect(
Y ~ D + X1 + X2,
data = simdata,
index = c("id","time"),
method = "fe",
force = "two-way",
se = TRUE,
parallel = FALSE,
nboots = 5 # nboots low for example
)
# Default gap plot
plot(out.fect, main = "Estimated ATT (FEct)", ylab = "Effect of D on Y")
# Gap plot with vibrant preset and custom line color
# plot(out.fect, preset = "vibrant", color = "darkgreen",
# main = "Estimated ATT (Vibrant Preset, Custom Line)")
# Counterfactual plot for the first treated unit
# Need to know the ID of a treated unit. Let's find one.
treated_ids <- unique(simdata$id[simdata$D == 1])
if (length(treated_ids) > 0) {
plot(out.fect, type = "counterfactual", id = treated_ids[1],
main = paste("Counterfactual for Unit", treated_ids[1]))
}
# Status plot
plot(out.fect, type = "status")
# Cumulative effect plot (if est.eff is available from fect call)
# This example might not have it by default, but showing how to call
# out.fect.cumul <- fect(Y ~ D, data = simdata, index = c("id","time"), method = "fe",
# cumulative = TRUE, se = TRUE, parallel = FALSE, nboots = 5)
# if (exists("out.fect.cumul")) {
# plot(out.fect.cumul, type = "cumul", main = "Cumulative ATT")
# }
# Example for sensitivity plot (requires IFE/GSYNTH method and sensitivity analysis)
# \donttest{
# out.ife <- fect(Y ~ D, data = simdata, index = c("id","time"),
# method = "ife", se = TRUE, r = 2,
# sensitivity.analysis = TRUE, sensitivity.plot = FALSE, # run analysis
# parallel = FALSE, nboots = 5) # nboots low for example
# if (!is.null(out.ife$sensitivity.rm)) {
# plot(out.ife, type = "sens", restrict = "rm",
# main = "Sensitivity Analysis (Relative Magnitude)")
# plot(out.ife, type = "sens_es", restrict = "rm",
# main = "Event-Study Sensitivity (Relative Magnitude)")
# }
# }
}
Run the code above in your browser using DataLab