Visualize Distributional BalanceSource:
Generates density plots, bar graphs, or scatterplots displaying distributional balance between treatment and covariates using ggplot2.
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 )
the object for which balance is to be assessed; can be any object for which there is support in
character; the name of the variable whose values are to be plotted. To view distributions of the distance measure (e.g., propensity score), if any, use
"distance"as the argument unless the distance variable has been named. If there are duplicate variable names across inputs,
bal.plot()will first look in the covariate
x, followed by
addl, and then
distance, if any. If not specified, will use the first covariate available with a warning.
other arguments to define the variable, treatment, and weights. Some inputs are required depending on the method. See Additional Arguments. Can also be used to supply the
whether to display distributional balance for the adjusted (
"adjusted") or unadjusted sample (
"unadjusted") or both at the same time (
"both"). When multiple weights are present, the names of the weights can be supplied, too. The default is to display balance for the adjusted sample only unless no weights, subclasses, or matching strata are specified. Multiple values and abbreviations allowed.
numeric; if subclassification is used, a vector corresponding to the subclass(es) for which the distributions are to be displayed. If
.all(the default), distributions from all subclasses are displayed in a grid.
optional; a vector of cluster membership, or the name of a variable in an available data set passed to
bal.plot()that contains cluster membership.
if clusters are used, which cluster(s) to display. Can be cluster names or numerical indices for which to display balance. Indices correspond to the alphabetical order of cluster names. If
.all(the default), all clusters are displayed. If
.none, cluster information is ignored and the marginal distribution of the covariates is displayed.
optional; a vector of imputation indices, or the name of a variable in an available data set passed to
bal.plot()that contains imputation indices.
if imputations are used, which imputations(s) to display. Must be numerical indices for which to display balance. If
.all(the default), all imputations are displayed. If
.none, data from all imputations are combined into one distribution.
which treatment groups to display. If
NULL(the default) or
NA, all treatment groups are displayed.
for longitudinal treatments, which time points to display. Can be treatment names or time period indices. If
NULL(the default) or
NA, all time points are displayed.
logical; if the treatment is binary, the covariate is continuous, and densities or histograms are requested, whether to display mirrored densities/histograms or overlapping densities/histograms. Ignored otherwise.
character; for binary and multi-category treatments with a continuous covariate, whether to display densities (
"density"), histograms (
"histogram"), or empirical cumulative density function plots (
"ecdf"). The default is to display densities. Abbreviations are allowed.
a vector of colors for the plotted densities/histograms. See 'Color Specification' at
graphics::par(). Defaults to the default ggplot2 colors.
logical; whether gridlines should be shown on the plot. Default is
character; new names to be given to the samples (i.e., in place of "Unadjusted Sample" and "Adjusted Sample"). For example, when matching it used, it may be useful to enter
the position of the legend. This can be any value that would be appropriate as an argument to
formuladesignating which facets should be on the rows and columns. This should be of the "historical" formula interface to
ggplot2::facet_grid(). If of the form
a ~ b,
awill be faceted on the rows and
bon the columns. To only facet on the rows, provide a one-sided formula with an empty left-hand side. To only facet on the columns, the formula should be of the form
a ~ .(i.e., with only
.on the right-hand side). The allowable facets depend on which arguments have been supplied to
bal.plot(); possible values include
imp, and (for longitudinal treatments)
bal.plot()will decide what looks best; this argument exists in case you disagree with its choice.
logical; for a categorical treatment with a continuous covariate, whether a line should be drawn for each treatment level denoting the (weighted) mean of the covariate. Ignored if
typeis not "density" or "histogram". Default is
logical; if both the treatment and the covariate are continuous, whether points should be shaded according to their weight. Fainter points are those that have smaller weights. Default is
ggplot2::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
ggplot2::geom_density(), histograms are created using
ggplot2::geom_histogram(), and empirical CDF plots are created using
ggplot2::geom_step(); for categorical treatments with categorical covariates, bar graphs are created using
ggplot2::geom_bar(); for continuous treatments with continuous covariates, scatterplots are created using
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
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
ggplot2::facet_grid(). Subclassification cannot be used with clusters or multiply imputed data.
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:
stop.method; see defaults).
treatis not required).
wimidsobjects: None, but an argument to
which.impshould 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).
data("lalonde", package = "cobalt") #Nearest Neighbor Matching m.out <- MatchIt::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")) #PS weighting with a continuous treatment w.out <- WeightIt::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")