Create mirror distribution plots

Create mirror distribution plots (histograms or density plots) to compare the distribution of variables between treatment groups before and after weighting. This function helps assess covariate balance by visualizing the distributions side-by-side with one group mirrored below the axis.

Usage

plot_mirror_distributions(
  .data,
  .var,
  .group,
  .wts = NULL,
  type = c("histogram", "density"),
  mirror_axis = "y",
  bins = NULL,
  binwidth = NULL,
  bw = "nrd0",
  adjust = 1,
  include_unweighted = TRUE,
  alpha = 0.6,
  na.rm = FALSE
)

Arguments

.data

A data frame containing the variables.

.var

The variable to plot. Supports tidyselect syntax. Can be unquoted.

.group

Column name of treatment/group variable. Supports tidyselect syntax. Can be unquoted. Must have exactly 2 levels.

.wts

Optional weighting variable(s). Can be unquoted variable names, tidyselect syntax, a character vector, or NULL. Multiple weights can be provided to compare different weighting schemes. Default is NULL (unweighted).

type

Character; type of plot - "histogram" or "density". Default is "histogram".

mirror_axis

Character; which axis to mirror - "y" (default) or "x".

bins

Integer; number of bins for histogram. Only used when type = "histogram".

binwidth

Numeric; width of bins for histogram. Only used when type = "histogram". If both bins and binwidth are specified, binwidth takes precedence.

bw

Bandwidth for density estimation. Only used when type = "density". Can be numeric or character (e.g., "nrd0", "sj").

adjust

Numeric; bandwidth adjustment factor for density. Only used when type = "density". Default is 1.

include_unweighted

Logical. If using .wts, also show unweighted distribution? Defaults to TRUE.

alpha

Numeric; transparency level for fills. Default is 0.6.

na.rm

Logical; if TRUE, drop NA values before plotting.

Value

A ggplot2 object.

Details

Mirror distribution plots display the distribution of one group above the x-axis and the other group below (mirrored). This makes it easy to compare distributions and assess balance. The function supports both histogram and density plot types.

When using weights, the function can display both weighted and unweighted distributions for comparison. Multiple weighting schemes can be compared by providing multiple weight variables.

See also

• geom_mirror_histogram() for the underlying histogram geom

• geom_mirror_density() for the underlying density geom

• plot_qq() for QQ plots, another distributional comparison

• geom_ecdf() for ECDF plots

Examples

library(ggplot2)

# Basic histogram (unweighted)
plot_mirror_distributions(nhefs_weights, age, qsmk)
#> `stat_mirror_count()` using `bins = 30`. Pick better value with `binwidth`.


# Density plot instead of histogram
plot_mirror_distributions(nhefs_weights, age, qsmk, type = "density")


# With weighting
plot_mirror_distributions(nhefs_weights, age, qsmk, .wts = w_ate)
#> `stat_mirror_count()` using `bins = 30`. Pick better value with `binwidth`.


# Compare multiple weighting schemes
plot_mirror_distributions(nhefs_weights, age, qsmk, .wts = c(w_ate, w_att))
#> `stat_mirror_count()` using `bins = 30`. Pick better value with `binwidth`.


# Customize appearance
plot_mirror_distributions(
  nhefs_weights, age, qsmk,
  .wts = w_ate,
  type = "density",
  alpha = 0.7
)


# Without unweighted comparison
plot_mirror_distributions(
  nhefs_weights, age, qsmk,
  .wts = w_ate,
  include_unweighted = FALSE
)
#> `stat_mirror_count()` using `bins = 30`. Pick better value with `binwidth`.