esplot: Event Study Visualization

In fect: Fixed Effects Counterfactual Estimators

Event Study Visualization

Description

Visualize dynamic treatment effects and create an event study plot. This function offers flexibility in displaying estimates, confidence intervals, and various annotations. It can handle data directly or from 'did_wrapper' objects, calculate confidence intervals from standard errors if needed, and allows for connected (line/ribbon) or point-range style plots.

Usage

esplot(data, Period = NULL, Estimate = "ATT", SE = NULL,
       CI.lower = "CI.lower", CI.upper = "CI.upper", Count = NULL,
       proportion = 0.3, est.lwidth = NULL, est.pointsize = NULL,
       show.points = TRUE, fill.gap = TRUE, start0 = FALSE,
       only.pre = FALSE, only.post = FALSE, show.count = TRUE,
       stats = NULL, stats.labs = NULL, highlight.periods = NULL,
       highlight.colors = NULL, highlight.shapes = NULL,
       highlight.fill = FALSE,
       lcolor = NULL, lwidth = NULL,
       ltype = NULL, connected = FALSE, ci.outline = FALSE,
       main = NULL, xlim = NULL, ylim = NULL, xlab = NULL, ylab = NULL,
       gridOff = FALSE, stats.pos = NULL, theme.bw = TRUE,
       legacy.style = FALSE,
       cex.main = NULL, cex.axis = NULL, cex.lab = NULL,
       cex.text = NULL, axis.adjust = FALSE, color = "#000000",
       pre.color = NULL, post.color = NULL,
       count.color = "gray70", count.alpha = 0.4,
       count.outline.color = "grey69",
       xangle = NULL, yangle = NULL,
       xbreaks = NULL, ybreaks = NULL,
       legendOff = FALSE, cex.legend = NULL,
       pre.label = "Pre-treatment", post.label = "Post-treatment")

Arguments

data	The input data for the event study plot. Can be a data.frame or an object of class did_wrapper (in which case, the est.att component will be used).
Period	The name of the column in data representing the relative time period. If NULL (the default), the function will attempt to automatically identify the period column from common names (e.g., 'time', 'Time', 'period', 'Period', 'event.time', 'event_time', 'rel_time') or use numeric rownames if available.
Estimate	The name of the column in data containing the point estimates (e.g., Average Treatment Effect on the Treated). Default is "ATT".
SE	The name of the column in data containing the standard errors. If columns for CI.lower and CI.upper (as specified by their respective arguments, defaulting to "CI.lower" and "CI.upper") are not found in data, and an SE column is provided and found, 95% confidence intervals will be calculated using Estimate +/- 1.96 * SE. Default is NULL.
CI.lower	The name of the column in data for the lower bound of the confidence interval. Default is "CI.lower". If this column is not found, it may be calculated from Estimate and SE (if SE is provided and found in data).
CI.upper	The name of the column in data for the upper bound of the confidence interval. Default is "CI.upper". If this column is not found, it may be calculated from Estimate and SE (if SE is provided and found in data).
Count	Optional. The name of the column in data indicating a count measure (e.g., number of observations) for each time period. Used if show.count = TRUE or for xlim determination based on proportion. Default is NULL.
proportion	Numeric, between 0 and 1. If Count is specified and xlim is not, this proportion is used to determine the default x-axis limits. Periods where the count is below proportion * max(Count) might be excluded from the default view. Default is 0.3.
est.lwidth	Numeric. The line width for the estimate line (if connected = TRUE) or the main vertical line of the point-range (if connected = FALSE). Default is NULL, which resolves to 0.6 if connected = FALSE (the default for connected), 1.2 if connected = TRUE and show.points = FALSE (the default for show.points), and 0.7 if connected = TRUE and show.points = TRUE.
est.pointsize	Numeric. The size of the points. If connected = TRUE and show.points = TRUE, this is the size of points at integer time periods. If connected = FALSE, this controls the size of the central point in the point-range (via fatten aesthetic). Default is NULL, which resolves to 2 if connected = FALSE (the default for connected), 3 if connected = TRUE and show.points = FALSE (the default for show.points), and 1.2 if connected = TRUE and show.points = TRUE.
show.points	Logical. If connected = TRUE, whether to display points at integer time periods on top of the line and ribbon. Default is TRUE.
fill.gap	Logical. If connected = FALSE, whether to fill gaps in the sequence of time periods with an estimate and confidence interval of 0. This is useful when some integer time periods are missing from the input data. Default is TRUE.
start0	Logical. If TRUE, the vertical line separating pre- and post-treatment periods is drawn at x = -0.5, implying period 0 is the first post-treatment period. If FALSE (default), the line is at x = 0.5, implying period 0 is the last pre-treatment period.
only.pre	Logical. If TRUE, the plot will only display pre-treatment periods. The vertical separator line will be omitted. Default is FALSE.
only.post	Logical. If TRUE, the plot will only display post-treatment periods. The vertical separator line will be omitted. Default is FALSE.
show.count	Logical. Whether to display a bar plot of the values from the Count column at the bottom of the main plot. Default is TRUE.
stats	Optional. A numeric vector of statistics (e.g., p-values) to be printed on the plot.
stats.labs	Optional. A character vector of labels corresponding to the stats values. Must be the same length as stats.
highlight.periods	Optional. A numeric vector of time periods to highlight with different colors. For connected = TRUE, these define intervals from period - 0.5 to period + 0.5. For connected = FALSE, individual points at these periods are highlighted.
highlight.colors	Optional. A character vector of colors corresponding to highlight.periods. If NULL and highlight.periods is provided, default rainbow colors are used. Must be the same length as highlight.periods.
highlight.shapes	Optional. An integer vector of point shapes corresponding to highlight.periods (e.g., 17 = triangle, 18 = diamond). Must be the same length as highlight.periods. Default is NULL.
highlight.fill	Logical. If TRUE, draws a lightened-tone background rectangle behind each highlighted period (auto-derived from highlight.colors). If FALSE (the default), only the colored glyph at each highlight period is drawn. The colored glyph alone is usually sufficient signal that a period belongs to a test window, and the glyph-only look survives grayscale printing without surprise. Set TRUE for slide / talk figures where the rectangle helps a remote audience locate the window.
lcolor	Optional. Color(s) for the reference lines. Can be a single color (applied to both horizontal y=0 line and vertical pre/post separator line) or a vector of two colors (first for horizontal, second for vertical). If NULL, defaults to "#aaaaaa" if theme.bw = TRUE, otherwise "white". Default is NULL.
lwidth	Optional. Line width(s) for the reference lines. Can be a single width or a vector of two widths (similar to lcolor). If NULL, defaults to 1.5 if theme.bw = TRUE, otherwise 2. Default is NULL.
ltype	Optional. Linetype(s) for the reference lines. Can be a single linetype (applied to both horizontal y=0 line and vertical pre/post separator line) or a vector of two linetypes (first for horizontal, second for vertical). Default is NULL, which resolves to c("solid", "dashed") under the modern recipe (theme.bw = TRUE with legacy.style = FALSE) and to c("solid", "solid") otherwise.
connected	Logical. If TRUE, estimates and confidence intervals are plotted as a connected line with a ribbon. This involves interpolating values between observed time points (at 0.5 steps by default) to create a smoother appearance. If FALSE (default), geom_pointrange is used, showing individual estimates and their CIs as points with ranges for each observed time period.
ci.outline	Logical. If connected = TRUE, whether to draw an outline around the confidence interval ribbon. The outline color is a slightly darker version of the fill color. Default is FALSE.
main	Optional. The main title for the plot. If NULL (default), a default title "Estimated Dynamic Treatment Effects" is used. If an empty string "" is provided, no title is displayed.
xlim	Optional. A numeric vector of length 2 specifying the x-axis limits (c(min, max)). If NULL (default), limits are determined automatically based on the data range, potentially filtered by proportion if Count is used.
ylim	Optional. A numeric vector of length 2 specifying the y-axis limits (c(min, max)). If NULL (default), limits are determined automatically to encompass all estimates and confidence intervals, with potential expansion if show.count = TRUE.
xlab	Optional. The label for the x-axis. If NULL (default), "Time Relative to Treatment" is used. If an empty string "" is provided, no label is displayed.
ylab	Optional. The label for the y-axis. If NULL (default), "Effect on Y" is used. If an empty string "" is provided, no label is displayed.
gridOff	Logical. Whether to turn off major and minor grid lines. Default is TRUE.
stats.pos	Optional. A numeric vector of length 2 (c(x, y)) specifying the coordinates for the top-left position of the stats text block. If NULL (default), the position is automatically determined.
theme.bw	Logical. Whether to use ggplot2::theme_bw(). Default is TRUE.
legacy.style	Logical. If TRUE, reproduces the pre-2.3.1 visual defaults (bold centered title, larger axis text, solid vline, blue placebo triangles, no peach highlight rectangle) regardless of the value of theme.bw. If FALSE (the default) and theme.bw = TRUE, the modern v2.3.1 visual recipe is used. Pass legacy.style = TRUE to byte-identical-reproduce figures rendered under earlier fect versions.
cex.main	Optional. Numeric scaling factor for the plot title font size. The base size used by ggplot is 16. Default is NULL (uses base size 16).
cex.axis	Optional. Numeric scaling factor for the axis tick mark labels font size. The base size used by ggplot is 15. Default is NULL (uses base size 15).
cex.lab	Optional. Numeric scaling factor for the axis title (x and y labels) font size. The base size used by ggplot is 15. Default is NULL (uses base size 15).
cex.text	Optional. Numeric scaling factor for annotated text elements (e.g., stats text, count label). The base size used by ggplot for annotation is 5. Default is NULL (uses base size 5).
axis.adjust	Logical. If TRUE, x-axis tick labels are rotated 45 degrees for better readability with many labels. Default is FALSE.
color	Character. The primary color for plotting estimates, points, lines, and confidence interval fills/lines (unless overridden by highlight.colors for specific periods). Default is "#000000" (black).
pre.color	Optional. Character. Color for pre-treatment period estimates. If NULL (default), uses the value of color.
post.color	Optional. Character. Color for post-treatment period estimates. If NULL (default), uses the value of color.
count.color	Character. The fill color for the bars if show.count = TRUE. Default is "gray70".
count.alpha	Numeric. Alpha transparency for the count bars if show.count = TRUE. Default is 0.4.
count.outline.color	Character. The color for the outline of count bars if show.count = TRUE. Default is "grey69".
xangle	Optional. Numeric. Rotation angle (in degrees) for x-axis tick labels. Default is NULL (no rotation).
yangle	Optional. Numeric. Rotation angle (in degrees) for y-axis tick labels. Default is NULL (no rotation).
xbreaks	Optional. A numeric vector of break points for the x-axis. If NULL (default), breaks are determined automatically.
ybreaks	Optional. A numeric vector of break points for the y-axis. If NULL (default), breaks are determined automatically.
legendOff	Logical. If TRUE, the legend is suppressed. Default is FALSE.
cex.legend	Optional. Numeric scaling factor for the legend text size. Default is NULL (uses ggplot2 defaults).
pre.label	Character. Label for the pre-treatment period in the legend. Default is "Pre-treatment".
post.label	Character. Label for the post-treatment period in the legend. Default is "Post-treatment".

Value

p	A ggplot object representing the event study plot.

Author(s)

Licheng Liu, Yiqing Xu, Ziyi Liu, Zhongyu Yin, Rivka Lipkovitz

Examples

# Basic example with simulated data
set.seed(123)
event_data <- data.frame(
  time = -5:5,
  ATT = cumsum(rnorm(11, 0, 0.2)) + c(rep(0,5), 0, 0.5, 1, 1.2, 1.5, 1.3),
  SE = runif(11, 0.1, 0.3)
)
event_data$CI.lower <- event_data$ATT - 1.96 * event_data$SE
event_data$CI.upper <- event_data$ATT + 1.96 * event_data$SE
event_data$count <- sample(50:150, 11, replace = TRUE)
event_data$count[event_data$time == -5 | event_data$time == 5] <- 20 # for proportion demo

# Default plot (point-range)
esplot(event_data, Period = "time", Estimate = "ATT",
       CI.lower = "CI.lower", CI.upper = "CI.upper")

# # Connected plot with ribbon
# esplot(event_data, Period = "time", Estimate = "ATT",
#        CI.lower = "CI.lower", CI.upper = "CI.upper",
#        connected = TRUE, show.points = TRUE)

# # Connected plot using SE for CI calculation
# event_data_no_ci <- event_data[, c("time", "ATT", "SE", "count")]
# esplot(event_data_no_ci, Period = "time", Estimate = "ATT", SE = "SE",
#        connected = TRUE, ci.outline = TRUE, color = "blue")

# # Show count bars and stats
# esplot(event_data, Period = "time", Estimate = "ATT",
#        CI.lower = "CI.lower", CI.upper = "CI.upper", Count = "count",
#        show.count = TRUE, stats = c(0.03, 0.12), stats.labs = c("P-val Pre", "P-val Post"),
#        main = "Event Study with Counts and Stats", proportion = 0.2)

# # Highlight specific periods (connected)
# esplot(event_data, Period = "time", Estimate = "ATT", SE = "SE",
#        connected = TRUE, highlight.periods = c(-1, 2),
#        highlight.colors = c("orange", "green"),
#        main = "Highlighted Periods (Connected)")

# # Highlight specific periods (point-range)
# esplot(event_data, Period = "time", Estimate = "ATT", SE = "SE",
#        connected = FALSE, highlight.periods = c(-1, 2),
#        highlight.colors = c("orange", "green"),
#        main = "Highlighted Periods (Point-Range)")

# # Only post-treatment period, custom labels
# esplot(event_data, Period = "time", Estimate = "ATT", SE = "SE",
#        only.post = TRUE, xlab = "Years Post-Intervention", ylab = "Impact Metric",
#        start0 = TRUE, color = "darkred", est.lwidth = 1.5)

# Using did_wrapper object (conceptual example, requires `did` package and setup)
# if (requireNamespace("did", quietly = TRUE)) {
#   # Assume `did_out` is an output from `did::att_gt` or similar
#   # and `did_wrapper_obj` is created, e.g.,
#   # did_wrapper_obj <- list(est.att = event_data) # Simplified for example
#   # class(did_wrapper_obj) <- "did_wrapper"
#   # esplot(did_wrapper_obj) # Would use defaults: Period="time", Estimate="ATT"
# }

fect documentation built on April 30, 2026, 9:06 a.m.