prettyPanelMatch: 'ggplot2'-Based Visualization for 'PanelMatch' (Imai, Kim, Wang 2023) Results

Description

Provides 'ggplot2'-based plotting functions for 'PanelMatch' (Imai, Kim, Wang (2023) doi:10.1111/ajps.12685) results. Tidy-and-plot function pairs for three 'PanelMatch' outputs: treatment effect estimates (PanelEstimate()), placebo test diagnostics (placebo_test()), and covariate balance checks (get_covariate_balance()). Supports multiple models, significance indicators, faceted balance grids, and full 'ggplot2' extensibility.

Provides tidy-and-plot function pairs for three types of PanelMatch output: treatment effect estimates, placebo test estimates, and covariate balance diagnostics. All plotting functions return standard ggplot objects that can be extended with additional ggplot2 layers.

Panel Estimate functions

tidy_panel_estimate

Convert one or more PanelEstimate summaries to a tidy data frame

ggplot_panel_estimate

Create a coefficient plot with significance-coded shapes

Placebo Test functions

pretty_placebo_test

Convert one or more placebo_test() results to a tidy data frame

gg_placebo_test

Create a coefficient plot for placebo test estimates

Covariate Balance functions

pretty_covariate_balance

Convert get_covariate_balance() matrices to a tidy data frame

gg_covariate_balance

Create a faceted balance plot (models as rows, matching stages as columns)

Author(s)

Maintainer: Jihye Park Jihye.Park@unige.ch

See Also

Useful links:

• https://github.com/jacqpark/prettyPanelMatch

• Report bugs at https://github.com/jacqpark/prettyPanelMatch/issues

Create a ggplot2 Covariate Balance Plot

Description

Produces a faceted covariate balance plot showing standardized mean differences across matching stages. Dependent variables are drawn as black solid lines; covariates as grey lines with distinct linetypes.

Usage

gg_covariate_balance(
  data,
  dv_color = "black",
  cov_color = "grey70",
  dv_linetype = "solid",
  cov_linetypes = NULL,
  hline = 0,
  ylim = c(-2, 2),
  xlab = "Time",
  ylab = "SD",
  title = NULL,
  subtitle = NULL,
  show_legend = FALSE,
  strip_text_y_size = 8.5,
  theme_fn = ggplot2::theme_bw
)

## S3 method for class 'ppm_cov_tidy'
autoplot(object, ...)

Arguments

Details

The default layout uses facet_grid(model ~ stage), where models (different DVs / subsamples) form the rows and matching stages form the columns, reproducing the standard PanelMatch covariate-balance diagnostic.

Value

A ggplot object that can be further customized with standard ggplot2 syntax.

See Also

pretty_covariate_balance to prepare the input data, ggplot_panel_estimate for treatment effect plots, gg_placebo_test for placebo test plots.

Examples

# Toy example (runs without PanelMatch)
toy <- data.frame(
  model    = factor("Model A", ordered = TRUE),
  stage    = factor("Before matching", ordered = TRUE),
  time     = factor(rep(paste0("t-", 3:1), 2),
                    levels = paste0("t-", 3:1), ordered = TRUE),
  variable = factor(rep(c("outcome", "covar1"), each = 3), ordered = TRUE),
  estimate = c(0.3, 0.5, 0.8, -0.1, 0.2, 0.1),
  is_dv    = rep(c(TRUE, FALSE), each = 3),
  stringsAsFactors = FALSE
)
class(toy) <- c("ppm_cov_tidy", "data.frame")
gg_covariate_balance(toy)

Create a ggplot2 Coefficient Plot from Placebo Test Results

Description

Produces a customizable ggplot2 coefficient plot for placebo test estimates from the PanelMatch package. This is a convenience wrapper around ggplot_panel_estimate with defaults tailored for placebo tests (e.g., y-axis label set to "Placebo estimate").

Usage

gg_placebo_test(data, ylab = "Placebo estimate", ...)

## S3 method for class 'ppm_placebo_tidy'
autoplot(object, ...)

Arguments

Details

All arguments are passed through to ggplot_panel_estimate(), so the full range of customization (shapes, dodging, significance coding, faceting, themes) is available.

Value

A ggplot object.

See Also

pretty_placebo_test to prepare the input data, ggplot_panel_estimate for treatment effect plots.

Examples

# Toy example (runs without PanelMatch)
toy <- data.frame(
  term      = factor(paste0("t-", 3:1), levels = paste0("t-", 3:1), ordered = TRUE),
  estimate  = c(0.1, -0.05, 0.02),
  std.error = c(0.15, 0.12, 0.10),
  conf.low  = c(-0.19, -0.29, -0.18),
  conf.high = c(0.39, 0.19, 0.22),
  label     = factor("Model", ordered = TRUE),
  signif    = c("Non-signif", "Non-signif", "Non-signif"),
  stringsAsFactors = FALSE
)
class(toy) <- c("ppm_placebo_tidy", "data.frame")
gg_placebo_test(toy)

Create a ggplot2 Coefficient Plot from PanelEstimate Results

Description

Produces a customizable ggplot2 coefficient plot showing point estimates and confidence intervals across lead periods. Supports multiple models with dodged positions and significance-based shape coding (hollow = not significant, filled = significant). A footnote is added by default.

Usage

ggplot_panel_estimate(
  data,
  dodge_width = 0.5,
  point_size = 2.2,
  errorbar_alpha = 0.5,
  errorbar_width = 0,
  shapes = NULL,
  show_signif_shapes = TRUE,
  legend_labels = NULL,
  footnote = "Filled markers denote statistical significance (CI excludes zero).",
  footnote_size = NULL,
  xlab = "Time",
  ylab = "ATT",
  title = NULL,
  subtitle = NULL,
  hline = 0,
  facet_by = NULL,
  theme_fn = ggplot2::theme_minimal
)

## S3 method for class 'ppm_tidy'
autoplot(object, ...)

Arguments

Details

The returned object is a standard ggplot object, so you can add any ggplot2 layers, scales, or themes on top of it.

Value

A ggplot object that can be further customized with standard ggplot2 syntax.

See Also

tidy_panel_estimate to prepare the input data, gg_placebo_test for placebo test plots, gg_covariate_balance for covariate balance plots.

Examples

# Toy example (runs without PanelMatch)
toy <- data.frame(
  term      = factor(paste0("t+", 0:2), levels = paste0("t+", 0:2), ordered = TRUE),
  estimate  = c(0.5, 0.8, 1.2),
  std.error = c(0.2, 0.3, 0.25),
  conf.low  = c(0.1, 0.2, 0.7),
  conf.high = c(0.9, 1.4, 1.7),
  label     = factor("Model", ordered = TRUE),
  signif    = c("Non-signif", "Signif", "Signif"),
  stringsAsFactors = FALSE
)
class(toy) <- c("ppm_tidy", "data.frame")
ggplot_panel_estimate(toy)

Tidy Covariate Balance Matrices into a Data Frame

Description

Converts get_covariate_balance() matrices from the PanelMatch package into a single tidy data frame suitable for ggplot2 plotting.

Usage

pretty_covariate_balance(
  ...,
  stage_labels = c("Before matching", "Matched, pre-refinement", "Post-refinement"),
  dv = NULL
)

Arguments

Details

Each named argument should be a list of 1–3 matrices (one per matching stage, e.g., before matching, after matching pre-refinement, post-refinement). The argument names become model/row facet labels.

Value

A data frame (with class "ppm_cov_tidy") containing:

model

Model label (ordered factor, row facet)

stage

Matching stage label (ordered factor, column facet)

time

Pre-treatment period label (ordered factor, e.g., "t-3")

variable

Covariate or DV name (ordered factor)

estimate

Standardized mean difference

is_dv

Logical; TRUE for dependent variables

See Also

gg_covariate_balance to plot the result, tidy_panel_estimate for treatment effect estimates, pretty_placebo_test for placebo test results.

Examples

# Create a mock covariate balance matrix (rows = time, cols = variables)
mat <- matrix(
  c(0.3, -0.1, 0.5, 0.2, 0.8, 0.1),
  nrow = 3,
  dimnames = list(NULL, c("outcome", "covar1"))
)
pretty_covariate_balance(
  "My Model" = mat,
  stage_labels = "Before matching",
  dv = "outcome"
)

Tidy placebo_test Results into a Data Frame

Description

Converts one or more placebo_test() results from the PanelMatch package into a single tidy data frame suitable for ggplot2 plotting.

Usage

pretty_placebo_test(..., labels = NULL, confidence_level = 0.95)

Arguments

Value

A data frame (with class "ppm_placebo_tidy") containing:

term

Lag period label (e.g., "t-3", "t-2")

estimate

Point estimate

std.error

Standard error

conf.low

Lower confidence bound

conf.high

Upper confidence bound

label

Model label (ordered factor preserving input order)

signif

Whether the CI excludes zero ("Signif" or "Non-signif")

See Also

gg_placebo_test to plot the result, tidy_panel_estimate for treatment effect estimates, pretty_covariate_balance for covariate balance.

Examples

# Create a mock placebo_test result
pt <- list(
  estimates = c("t-3" = 0.10, "t-2" = -0.05, "t-1" = 0.02),
  standard.errors = c("t-3" = 0.15, "t-2" = 0.12, "t-1" = 0.10)
)
pretty_placebo_test(pt, labels = "My Model")

# Custom confidence level
pretty_placebo_test(pt, confidence_level = 0.90)

Tidy PanelEstimate Summaries into a Data Frame

Description

Converts one or more summary(PanelEstimate(...)) objects into a single tidy data frame suitable for ggplot2 plotting.

Usage

tidy_panel_estimate(..., labels = NULL)

Arguments

Value

A data frame (with class "ppm_tidy") containing columns:

term

Lead period label (e.g., "t+0", "t+1", ...)

estimate

Point estimate (ATT)

std.error

Standard error

conf.low

Lower confidence bound

conf.high

Upper confidence bound

label

Model label (ordered factor preserving input order)

signif

Whether the CI excludes zero ("Signif" or "Non-signif")

See Also

ggplot_panel_estimate to plot the result, pretty_placebo_test for placebo test results, pretty_covariate_balance for covariate balance.

Examples

# Create a mock PanelEstimate summary (matrix with 4 columns)
pe_sum <- matrix(
  c(0.5, 0.2, 0.1, 0.9,
    0.8, 0.3, 0.2, 1.4,
    1.2, 0.25, 0.7, 1.7),
  nrow = 3, byrow = TRUE,
  dimnames = list(NULL, c("Estimate", "Std.Error", "lower", "upper"))
)
tidy_panel_estimate(pe_sum, labels = "My Model")

# Multiple models with named arguments
pe_sum2 <- matrix(
  c(0.3, 0.15, 0.0, 0.6,
    0.6, 0.20, 0.2, 1.0,
    0.9, 0.18, 0.5, 1.3),
  nrow = 3, byrow = TRUE,
  dimnames = list(NULL, c("Estimate", "Std.Error", "lower", "upper"))
)
tidy_panel_estimate("Model A" = pe_sum, "Model B" = pe_sum2)