bal.plot: Visualize Distributional Balance

Description

Generates density plots, bar graphs, or scatterplots displaying distributional balance between treatment and covariates using ggplot2.

Usage

bal.plot(x, 
    var.name, 
    ..., 
    which, 
    which.sub = NULL, 
    cluster = NULL,
    which.cluster = NULL, 
    imp = NULL,
    which.imp = NULL, 
    which.treat = NULL,
    which.time = NULL,
    mirror = FALSE, 
    type = "density", 
    colors = NULL,
    grid = FALSE,
    sample.names,
    position = "right", 
    facet.formula = NULL, 
    disp.means = getOption("cobalt_disp.means", FALSE),
    alpha.weight = TRUE)

Value

A "ggplot" object, returned invisibly.

Additional Arguments

bal.plot() works like bal.tab() in that it can take a variety of types of inputs and yield the same output for each. Depending on what kind of input is given, different additional parameters are required in …. For details on what is required and allowed for each additional input and their defaults, see the help file for the bal.tab() method associated with the input. The following are the required additional arguments based on each input type:

For matchit objects: None
For weightit objects: None
For ps, ps.cont, mnps, and iptw objects: (stop.method; see defaults).
For Match objects: formula and data or covs and treat.
For optmatch objects: formula and data or covs (treat is not required).
For CBPS objects: None
For ebalance objects: formula and data or covs and treat.
For formulas: data
For data.frames: treat
For designmatch objects: formula and data or covs and treat.
For sbw objects: None
For mimids and wimids objects: None, but an argument to which.imp should be specified.
For other objects processed through bal.tab()'s default method, whichever arguments are required to identify treatment, variables, and a conditioning method (if any).

Details

bal.plot() uses ggplot() from the ggplot2 package, and (invisibly) returns a "ggplot" object. For categorical treatments with continuous covariates or continuous treatments with categorical covariates, density plots are created using geom_density(), histograms are created using geom_histogram(), and empirical CDF plots are created using geom_step(); for categorical treatments with categorical covariates, bar graphs are created using geom_bar(); for continuous treatments with continuous covariates, scatterplots are created using geom_point().

For continuous treatments with continuous covariates, four additional lines are presented for aid in balance assessment. The red line is the linear fit line. The blue line is a smoothing curve generated with ggplot2's geom_smooth() with method = "auto". The horizontal black line is a horizontal reference line intercepting the (unweighted) treatment mean. The vertical black line is a reference line intercepting the (unweighted) treatment mean. Balance is indicated by the flatness of both fit lines and whether they pass through the intersection of the two black reference lines.

When multiple plots are to be displayed (i.e., when requesting subclass balance, cluster balance, or imputation balance, or when multiple sets of weights are provided or which = "both", or when treatment is longitudinal), the plots will be displayed in a grid using ggplot2's facet_grid(). Subclassification cannot be used with clusters or multiply imputed data.

To change the plot and axis titles, use labs(). Because the output is a ggplot object, other elements can be changed using ggplot2 functions; see here for an example.

Examples

Run this code

# NOT RUN {
data("lalonde", package = "cobalt")

#Nearest Neighbor Matching
library(MatchIt)
m.out <- matchit(treat ~ age + educ + race + 
                 married + nodegree + re74 + re75, 
                 data = lalonde)

bal.plot(m.out, "age", which = "both")
bal.plot(m.out, "re74", which = "both", type = "ecdf")
bal.plot(m.out, "race", which = "both")
bal.plot(m.out, "distance", which = "both", mirror = TRUE,
         type = "histogram", colors = c("white", "black"))
# }
# NOT RUN {
#PS weighting with a continuous treatment
library(WeightIt)
w.out <- weightit(re75 ~ age + I(age^2) + educ + 
                  race + married + nodegree,
                  data = lalonde)
                  
bal.plot(w.out, "age", which = "both")
bal.plot(w.out, "married", which = "both")
# }