Package 'cobalt'

Efficiently compute scalar balance statistics

Description

These are functions primarily designed for programmers who want to be able to quickly compute one of several scalar (single number) sample balance statistics, e.g., for use in selecting a tuning parameter when estimating balancing weights. bal.compute() computes a scalar balance statistics from the supplied inputs. bal.init() initializes the input so that when bal.compute() is used on the output along with a set of weights, the computation of the balance statistic is fast. vignette("optimizing-balance") provides an overview and more examples of how to use these functions. available.stats() returns the balance statistics available for the given treatment type.

Usage

bal.compute(x, ...)

## S3 method for class 'bal.init'
bal.compute(x, weights = NULL, ...)

## Default S3 method:
bal.compute(x, treat, stat, s.weights = NULL, weights = NULL, ...)

bal.init(x, treat, stat, s.weights = NULL, ...)

available.stats(treat.type = "binary")

Arguments

x	for bal.compute(), a bal.init object created by bal.init() or a matrix or data frame containing the covariates. For bal.init(), a matrix or data frame containing the covariates.
...	other arguments used to specify options for the balance statistic. See Details for which arguments are allowed with each balance statistic. Ignored for the bal.init method of bal.compute().
weights	a vector of balancing weights to compute the weighted statistics.
treat	a vector containing the treatment variable.
stat	string; the name of the statistic to compute. See Details.
s.weights	optional; a vector of sampling weights.
treat.type	string; the treatment type, either "binary", "multinomial", or "continuous". Abbreviations allowed.

Details

The following list contains the allowable balance statistics that can be supplied to bal.init() or the default method of bal.compute(), the additional arguments that can be used with each one, and the treatment types allowed with each one. For all balance statistics, lower values indicate better balance.

smd.mean, smd.max, smd.rms

The mean, maximum, or root-mean-squared absolute standardized mean difference, computed using col_w_smd(). The other allowable arguments include estimand ("ATE", "ATT", or "ATC") to select the estimand (default is "ATE"), focal to identify the focal treatment group when the ATT is the estimand and the treatment has more than two categories, and pairwise to select whether mean differences should be computed between each pair of treatment groups or between each treatment group and the target group identified by estimand (default TRUE). Can be used with binary and multi-category treatments.

ks.mean, ks.max, ks.rms

The mean, maximum, or root-mean-squared Kolmogorov-Smirnov statistic, computed using col_w_ks(). The other allowable arguments include estimand ("ATE", "ATT", or "ATC") to select the estimand (default is "ATE"), focal to identify the focal treatment group when the ATT is the estimand and the treatment has more than two categories, and pairwise to select whether statistics should be computed between each pair of treatment groups or between each treatment group and the target group identified by estimand (default TRUE). Can be used with binary and multi-category treatments.

ovl.mean, ovl.max, ovl.rms

The mean, maximum, or root-mean-squared overlapping coefficient complement, computed using col_w_ovl(). The other allowable arguments include estimand ("ATE", "ATT", or "ATC") to select the estimand (default is "ATE"), integrate to select whether integration is done using using integrate() (TRUE) or a Riemann sum (FALSE, the default), focal to identify the focal treatment group when the ATT is the estimand and the treatment has more than two categories, pairwise to select whether statistics should be computed between each pair of treatment groups or between each treatment group and the target group identified by estimand (default TRUE). Can be used with binary and multi-category treatments.

mahalanobis

The Mahalanobis distance between the treatment group means. This is similar to smd.rms but the covariates are standardized to remove correlations between them and de-emphasize redundant covariates. The other allowable arguments include estimand ("ATE", "ATT", or "ATC") to select the estimand (default is "ATE") and focal to identify the focal treatment group when the ATT is the estimand. Can only be used with binary treatments.

energy.dist

The total energy distance between each treatment group and the target sample, which is a scalar measure of the similarity between two multivariate distributions. The other allowable arguments include estimand ("ATE", "ATT", "ATC", or NULL) to select the estimand (default is NULL), focal to identify the focal treatment group when the ATT is the estimand and the treatment has more than two categories, and improved to select whether the "improved" energy distance should be used when estimand = "ATE", which emphasizes difference between treatment groups in addition to difference between each treatment group and the target sample (default TRUE). When estimand = NULL, only the energy distance between the treatment groups will be computed (i.e., as opposed to the energy distance between each treatment groups and the target sample). Can be used with binary and multi-category treatments.

kernel.dist

The kernel distance between the treatment groups, which is a scalar measure of the similarity between two multivariate distributions. Can only be used with binary treatments.

l1.med

The median L1 statistic computed across a random selection of possible coarsening of the data. The other allowable arguments include estimand ("ATE", "ATT", or "ATC") to select the estimand (default is "ATE"), focal to identify the focal treatment group when the ATT is the estimand and the treatment has more than two categories, l1.min.bin (default 2) and l1.max.bin default (12) to select the minimum and maximum number of bins with which to bin continuous variables and l1.n (default 101) to select the number of binnings used to select the binning at the median. covs should be supplied without splitting factors into dummies to ensure the binning works correctly; for simplicity, the .covs argument can be supplied, which will override covs but isn't used by other statistics. Can be used with binary and multi-category treatments.

r2, r2.2, r2.3

The post-weighting $R^2$ of a model for the treatment. The other allowable arguments include poly to add polynomial terms of the supplied order to the model and int (default FALSE) to add two-way interaction between covariates into the model. Using r2.2 is a shortcut to requesting squares, and using r2.3 is a shortcut to requesting cubes. Can be used with binary and continuous treatments. For binary treatments, the McKelvey and Zavoina $R^2$ from a logistic regression is used; for continuous treatments, the $R^2$ from a linear regression is used.

p.mean, p.max, p.rms

The mean, maximum, or root-mean-squared absolute Pearson correlation between the treatment and covariates, computed using col_w_corr(). Can only be used with continuous treatments.

s.mean, s.max, s.rms

The mean, maximum, or root-mean-squared absolute Spearman correlation between the treatment and covariates, computed using col_w_corr(). Can only be used with continuous treatments.

distance.cov

The distance covariance between the scaled covariates and treatment, which is a scalar measure of the independence of two possibly multivariate distributions. Can only be used with continuous treatments.

Although statistics can be computed directly using bal.compute() alone, the intended workflow is to use bal.init() to initialize a bal.init object, which can then be passed to bal.compute() many times with different sets of weights, thereby minimizing the processing that bal.init() does because it is only done once. In contrast, using bal.compute() on covariates directly (i.e., using the default method) calls bal.init() internally each time, which can slow down evaluation. When speed isn't of interest or to calculate a balance statistic outside the context of balance optimization, the default method of bal.compute() can be a quick shortcut to avoid having to create a bal.init object first.

Value

For bal.compute(), a single numeric value. For bal.init(), a bal.init object containing the components created in the initialization and the function used to compute the balance statistic. For available.stats(), a character vector of available statistics.

See Also

balance-summary, bal.tab()

See vignette("optimizing-balance") for references and definitions of some of the above quantities.

Examples

# Select the optimal number of subclasses for
# subclassification:
data("lalonde")
covs <- c("age", "educ", "race", "married",
          "nodegree", "re74", "re75")

# Estimate propensity score
p <- glm(reformulate(covs, "treat"),
         data = lalonde, 
         family = "binomial")$fitted.values

# Function to compute subclassification weights
subclass_ATE <- function(treat, p, nsub) {
    m <- MatchIt::matchit(treat ~ 1,
                          data = lalonde,
                          distance = p,
                          method = "subclass",
                          estimand = "ATE",
                          subclass = nsub)
    return(m$weights)
}

# Initialize balance statistic; largest KS statistic
init <- bal.init(lalonde[covs], treat = lalonde$treat, 
                 stat = "ks.max",
                 estimand = "ATE")

# Statistic prior to subclassification:
bal.compute(init)

# Testing 4 to 50 subclasses
nsubs <- 4:50
stats <- vapply(nsubs, function(n) {
    w <- subclass_ATE(lalonde$treat, p, n)
    bal.compute(init, w)
}, numeric(1L))

plot(stats ~ nsubs)

# 6 subclass gives lowest ks.max value (.238)
nsubs[which.min(stats)]
stats[which.min(stats)]

# See which statistics are available
available.stats("binary")
available.stats("multinomial")

---

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
)

Arguments

x	the object for which balance is to be assessed; can be any object for which there is support in bal.tab().
var.name	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 data.frame from 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 bw, adjust, kernel, and n arguments for ggplot2::geom_density() and the bins argument for ggplot2::geom_histogram().
which	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.
which.sub	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.
cluster	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.
which.cluster	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.
imp	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.
which.imp	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.treat	which treatment groups to display. If NULL (the default) or NA, all treatment groups are displayed.
which.time	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.
mirror	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.
type	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.
colors	a vector of colors for the plotted densities/histograms. See 'Color Specification' at graphics::par(). Defaults to the default ggplot2 colors.
grid	logical; whether gridlines should be shown on the plot. Default is TRUE.
sample.names	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 c("Unmatched", "Matched").
position	the position of the legend. This can be any value that would be appropriate as an argument to legend.position in ggplot2::theme().
facet.formula	a formula designating 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, a will be faceted on the rows and b on 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 which, cluster, imp, and (for longitudinal treatments) time. If NULL, bal.plot() will decide what looks best; this argument exists in case you disagree with its choice.
disp.means	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 type is not "density" or "histogram". Default is FALSE.
alpha.weight	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 TRUE.

Details

bal.plot() uses 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 ggplot2::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 ggplot2::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 ggplot2::facet_grid(). Subclassification cannot be used with clusters or multiply imputed data.

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

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).

See Also

bal.tab(), love.plot()

Examples

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"))


#Entropy balancing with a continuous treatment
w.out <- WeightIt::weightit(re75 ~ age + I(age^2) + educ + 
                                race + married + nodegree,
                            data = lalonde, method = "ebal")

bal.plot(w.out, "age", which = "both")
bal.plot(w.out, "married", which = "both")

---

Display Balance Statistics in a Table

Description

Generates balance statistics on covariates in relation to an observed treatment variable. It is a generic function that dispatches to the method corresponding to the class of the first argument.

Usage

bal.tab(x, ...)

## # Arguments common across all input types:
## bal.tab(x,
##         stats,
##         int = FALSE,
##         poly = 1,
##         distance = NULL,
##         addl = NULL,
##         data = NULL,
##         continuous,
##         binary,
##         s.d.denom,
##         thresholds = NULL,
##         weights = NULL,
##         cluster = NULL,
##         imp = NULL,
##         pairwise = TRUE,
##         s.weights = NULL,
##         abs = FALSE,
##         subset = NULL,
##         quick = TRUE,
##         ...)

Arguments

x	an input object on which to assess balance. Can be the output of a call to a balancing function in another package or a formula or data frame. Input to this argument will determine which bal.tab() method is used. Each input type has its own documentation page, which is linked in the See Also section below. Some input types require or allow additional arguments to be specified. For inputs with no dedicated method, the default method will be dispatched. See Details below.
...	for some input types, other arguments that are required or allowed. Otherwise, further arguments to control display of output. See display options for details.
stats	character; which statistic(s) should be reported. See stats for allowable options. For binary and multi-category treatments, "mean.diffs" (i.e., mean differences) is the default. For continuous treatments, "correlations" (i.e., treatment-covariate Pearson correlations) is the default. Multiple options are allowed.
int	logical or numeric; whether or not to include 2-way interactions of covariates included in covs and in addl. If numeric, will be passed to poly as well.
poly	numeric; the highest polynomial of each continuous covariate to display. For example, if 2, squares of each continuous covariate will be displayed (in addition to the covariate itself); if 3, squares and cubes of each continuous covariate will be displayed, etc. If 1, the default, only the base covariate will be displayed. If int is numeric, poly will take on the value of int.
distance	an optional formula or data frame containing distance values (e.g., propensity scores) or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the argument to data, if specified. For longitudinal treatments, can be a list of allowable arguments, one for each time point.
addl	an optional formula or data frame containing additional covariates for which to present balance or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the arguments to the input object, covs, and data, if specified. For longitudinal treatments, can be a list of allowable arguments, one for each time point.
data	an optional data frame containing variables named in other arguments. For some input object types, this is required.
continuous	whether mean differences for continuous variables should be standardized ("std") or raw ("raw"). Default "std". Abbreviations allowed. This option can be set globally using set.cobalt.options().
binary	whether mean differences for binary variables (i.e., difference in proportion) should be standardized ("std") or raw ("raw"). Default "raw". Abbreviations allowed. This option can be set globally using set.cobalt.options().
s.d.denom	character; how the denominator for standardized mean differences should be calculated, if requested. See col_w_smd() for allowable options. If weights are supplied, each set of weights should have a corresponding entry to s.d.denom. Abbreviations allowed. If left blank and weights, subclasses, or matching strata are supplied, bal.tab() will figure out which one is best based on the estimand, if given (for ATT, "treated"; for ATC, "control"; otherwise "pooled") and other clues if not.
thresholds	a named vector of balance thresholds, where the name corresponds to the statistic (i.e., in stats) that the threshold applies to. For example, to request thresholds on mean differences and variance ratios, one can set thresholds = c(m = .05, v = 2). Requesting a threshold automatically requests the display of that statistic. When specified, extra columns are inserted into the Balance table describing whether the requested balance statistics exceeded the threshold or not. Summary tables tallying the number of variables that exceeded and were within the threshold and displaying the variables with the greatest imbalance on that balance measure are added to the output.
weights	a vector, list, or data.frame containing weights for each unit, or a string containing the names of the weights variables in data, or an object with a get.w() method or a list thereof. The weights can be, e.g., inverse probability weights or matching weights resulting from a matching algorithm.
cluster	either a vector containing cluster membership for each unit or a string containing the name of the cluster membership variable in data or the input object. See class-bal.tab.cluster for details.
imp	either a vector containing imputation indices for each unit or a string containing the name of the imputation index variable in data or the input object. See class-bal.tab.imp for details. Not necessary if data is a mids object.
pairwise	whether balance should be computed for pairs of treatments or for each treatment against all groups combined. See bal.tab.multi() for details. This can also be used with a binary treatment to assess balance with respect to the full sample.
s.weights	Optional; either a vector containing sampling weights for each unit or a string containing the name of the sampling weight variable in data. These function like regular weights except that both the adjusted and unadjusted samples will be weighted according to these weights if weights are used.
abs	logical; whether displayed balance statistics should be in absolute value or not.
subset	a logical or numeric vector denoting whether each observation should be included or which observations should be included. If logical, it should have length equal to the number of units. NAs will be treated as FALSE. This can be used as an alternative to cluster to examine balance on subsets of the data.
quick	logical; if TRUE, will not compute any values that will not be displayed. Set to FALSE if computed values not displayed will be used later.

Details

bal.tab() performs various calculations on the the data objects given. This page details the arguments and calculations that are used across bal.tab() methods.

With Binary Point Treatments

Balance statistics can be requested with the stats argument. The default balance statistic for mean differences for continuous variables is the standardized mean difference, which is the difference in the means divided by a measure of spread (i.e., a d-type effect size measure). This is the default because it puts the mean differences on the same scale for comparison with each other and with a given threshold. For binary variables, the default balance statistic is the raw difference in proportion. Although standardized differences in proportion can be computed, raw differences in proportion for binary variables are already on the same scale, and computing the standardized difference in proportion can obscure the true difference in proportion by dividing the difference in proportion by a number that is itself a function of the observed proportions.

Standardized mean differences are calculated using col_w_smd() as follows: the numerator is the mean of the treated group minus the mean of the control group, and the denominator is a measure of spread calculated in accordance with the argument to s.d.denom or the default of the specific method used. Common approaches in the literature include using the standard deviation of the treated group or using the "pooled" standard deviation (i.e., the square root of the mean of the group variances) in calculating standardized mean differences. The computed spread bal.tab() uses is always that of the full, unadjusted sample (i.e., before matching, weighting, or subclassification), as recommended by Stuart (2010).

Prior to computation, all variables are checked for variable type, which allows users to differentiate balance statistic calculations based on type using the arguments to continuous and binary. First, if a given covariate is numeric and has only 2 levels, it is converted into a binary (0,1) variable. If 0 is a value in the original variable, it retains its value and the other value is converted to 1; otherwise, the lower value is converted to 0 and the other to 1. Next, if the covariate is not numeric or logical (i.e., is a character or factor variable), it will be split into new binary variables, named with the original variable and the value, separated by an underscore. Otherwise, the covariate will be used as is and treated as a continuous variable.

When weighting or matching are used, an "effective sample size" is calculated for each group using the following formula: $(\sum w)^2 / \sum w^2$. The effective sample size is "approximately the number of observations from a simple random sample that yields an estimate with sampling variation equal to the sampling variation obtained with the weighted comparison observations" (Ridgeway et al., 2016). The calculated number tends to underestimate the true effective sample size of the weighted samples. The number depends on the variability of the weights, so sometimes trimming units with large weights can actually increase the effective sample size, even though units are being down-weighted. When matching is used, an additional "unweighted" sample size will be displayed indicating the total number of units contributing to the weighted sample.

When subclassification is used, the balance tables for each subclass stored in ⁠$Subclass.Balance⁠ use values calculated as described above. For the aggregate balance table stored in ⁠$Balance.Across.Subclass⁠, the values of each statistic are computed as a weighted average of the statistic across subclasses, weighted by the proportion of units in each subclass. See class-bal.tab.subclass for more details.

With Continuous Point Treatments

When continuous treatment variables are considered, the balance statistic calculated is the Pearson correlation between the covariate and treatment. The correlation after adjustment is computed using col_w_cov() as the weighted covariance between the covariate and treatment divided by the product of the standard deviations of the unweighted covariate and treatment, in an analogous way to how how the weighted standardized mean difference uses an unweighted measure of spread in its denominator, with the purpose of avoiding the analogous paradox (i.e., where the covariance decreases but is accompanied by a change in the standard deviations, thereby distorting the actual resulting balance computed using the weighted standard deviations). This can sometimes yield correlations greater than 1 in absolute value; these usually indicate degenerate cases anyway.

With Multi-Category Point Treatments

For information on using bal.tab() with multi-category treatments, see class-bal.tab.multi. Essentially, bal.tab() compares pairs of treatment groups in a standard way.

With Longitudinal Treatments

For information on using bal.tab() with longitudinal treatments, see class-bal.tab.msm and vignette("longitudinal-treat"). Essentially, bal.tab() summarizes balance at each time point and summarizes across time points.

With Clustered or Multiply Imputed Data

For information on using bal.tab() with clustered data, see class-bal.tab.cluster. For information on using bal.tab() with multiply imputed data, see class-bal.tab.imp.

quick

Calculations can take some time, especially when there are many variables, interactions, or clusters. When certain values are not printed, by default they are not computed. In particular, summary tables are not computed when their display has not been requested. This can speed up the overall production of the output when these values are not to be used later. However, when they are to be used later, such as when output is to be further examined with print() or is to be used in some other way after the original call to bal.tab(), it may be useful to compute them even if they are not to be printed initially. To do so, users can set quick = FALSE, which will cause bal.tab() to calculate all values and components it can. Note that love.plot() is fully functional even when quick = TRUE and values are requested that are otherwise not computed in bal.tab() with quick = TRUE.

Missing Data

If there is missing data in the covariates (i.e., NAs in the covariates provided to bal.tab()), a few additional things happen. A warning will appear mentioning that missing values were present in the data set. The computed balance summaries will be for the variables ignoring the missing values. New variables will be created representing missingness indicators for each variable, named ⁠var: <NA>⁠ (with var replaced by the actual name of the variable). If int = TRUE, balance for the pairwise interactions between the missingness indicators will also be computed. These variables are treated like regular variables once created.

Value

An object of class "bal.tab". The use of continuous treatments, subclasses, clusters, and/or imputations will also cause the object to inherit other classes. The class "bal.tab" has its own print() method (print.bal.tab()), which formats the output nicely and in accordance with print-related options given in the call to bal.tab(), and which can be called with its own options.

For scenarios with binary point treatments and no subclasses, imputations, or clusters, the following are the elements of the bal.tab object:

Balance	A data frame containing balance information for each covariate. Balance contains the following columns, with additional columns present when other balance statistics are requested, and some columns omitted when not requested: Type: Whether the covariate is binary, continuous, or a measure of distance (e.g., the propensity score). M.0.Un: The mean of the control group prior to adjusting. SD.0.Un: The standard deviation of the control group prior to adjusting. M.1.Un: The mean of the treated group prior to adjusting. SD.1.Un: The standard deviation of the treated group prior to adjusting. Diff.Un: The (standardized) difference in means between the two groups prior to adjusting. See the binary and continuous arguments on the bal.tab method pages to determine whether standardized or raw mean differences are being reported. By default, the standardized mean difference is displayed for continuous variables and the raw mean difference (difference in proportion) is displayed for binary variables. M.0.Adj: The mean of the control group after adjusting. SD.0.Adj: The standard deviation of the control group after adjusting. M.1.Adj: The mean of the treated group after adjusting. SD.1.Adj: The standard deviation of the treated group after adjusting. Diff.Adj: The (standardized) difference in means between the two groups after adjusting. See the binary and continuous arguments on the bal.tab method pages to determine whether standardized or raw mean differences are being reported. By default, the standardized mean difference is displayed for continuous variables and the raw mean difference (difference in proportion) is displayed for binary variables. M.Threshold: Whether or not the calculated mean difference after adjusting exceeds or is within the threshold given by thresholds. If a threshold for mean differences is not specified, this column will be NA.
Balanced.Means	If a threshold on mean differences is specified, a table tallying the number of variables that exceed or are within the threshold.
Max.Imbalance.Means	If a threshold on mean differences is specified, a table displaying the variable with the greatest absolute mean difference.
Observations	A table displaying the sample sizes before and after adjusting. Often the effective sample size (ESS) will be displayed. See Details.
call	The original function call, if adjustment was performed by a function in another package.

If the treatment is continuous, instead of producing mean differences, bal.tab() will produce correlations between the covariates and the treatment. The default corresponding entries in the output will be "Corr.Un", "⁠Corr.Adj"⁠, and "R.Threshold" (and accordingly for the balance tally and maximum imbalance tables).

If multiple weights are supplied, "Adj" in Balance will be replaced by the provided names of the sets of weights, and extra columns will be added for each set of weights. Additional columns and rows for other items in the output will be created as well.

For bal.tab output with subclassification, see class-bal.tab.subclass.

References

Ridgeway, G., McCaffrey, D., Morral, A., Burgette, L., & Griffin, B. A. (2016). Toolkit for Weighting and Analysis of Nonequivalent Groups: A tutorial for the twang package. R vignette. RAND.

Stuart, E. A. (2010). Matching Methods for Causal Inference: A Review and a Look Forward. Statistical Science, 25(1), 1-21. doi:10.1214/09-STS313

See Also

For information on the use of bal.tab() with specific types of objects, use the following links:

• bal.tab.matchit() for the method for objects returned by MatchIt.

• bal.tab.weightit() for the method for weightit and weightitMSM objects returned by WeightIt.

• bal.tab.ps() for the method for ps, mnps, and iptw objects returned by twang and for ps.cont objects returned by twangContinuous.

• bal.tab.Match() for the method for objects returned by Matching.

• bal.tab.optmatch() for the method for objects returned by optmatch.

• bal.tab.cem.match() for the method for objects returned by cem.

• bal.tab.CBPS() for the method for objects returned by CBPS.

• bal.tab.ebalance() for the method for objects returned by ebal.

• bal.tab.designmatch() for the method for objects returned by designmatch.

• bal.tab.mimids() for the method for objects returned by MatchThem.

• bal.tab.sbwcau() for the method for objects returned by sbw.

• bal.tab.formula() and bal.tab.data.frame() for the methods for formula and data frame interfaces when the user has covariate values and weights (including matching weights) or subclasses or wants to evaluate balance on an unconditioned data set. For data that corresponds to a longitudinal treatment (i.e., to be analyzed with a marginal structural model), see bal.tab.time.list().

See vignette("faq") for answers to frequently asked questions about bal.tab().

Examples

## See individual pages above for examples with
## different inputs, or see `vignette("cobalt")`

---

Balance Statistics for CBPS Objects

Description

Generates balance statistics for CBPS and CBMSM objects from the CBPS package.

Usage

## S3 method for class 'CBPS'
bal.tab(
  x,
  stats,
  int = FALSE,
  poly = 1,
  distance = NULL,
  addl = NULL,
  data = NULL,
  continuous,
  binary,
  s.d.denom,
  thresholds = NULL,
  weights = NULL,
  cluster = NULL,
  imp = NULL,
  pairwise = TRUE,
  s.weights = NULL,
  abs = FALSE,
  subset = NULL,
  quick = TRUE,
  ...
)

Arguments

x	a CBPS or CBMSM object; the output of a call to CBPS::CBPS() or CBPS::CBMSM().
stats	character; which statistic(s) should be reported. See stats for allowable options. For binary and multi-category treatments, "mean.diffs" (i.e., mean differences) is the default. For continuous treatments, "correlations" (i.e., treatment-covariate Pearson correlations) is the default. Multiple options are allowed.
int	logical or numeric; whether or not to include 2-way interactions of covariates included in covs and in addl. If numeric, will be passed to poly as well.
poly	numeric; the highest polynomial of each continuous covariate to display. For example, if 2, squares of each continuous covariate will be displayed (in addition to the covariate itself); if 3, squares and cubes of each continuous covariate will be displayed, etc. If 1, the default, only the base covariate will be displayed. If int is numeric, poly will take on the value of int.
distance	an optional formula or data frame containing distance values (e.g., propensity scores) or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the argument to data, if specified. Propensity scores generated by CBPS() and CBMSM() are automatically included and named "prop.score". For CBMSM objects, can be a list of allowable arguments, one for each time point, but each dataset in the list supplied to distance must have one row per individual, unlike the data frame in the original call to CBMSM().
addl	an optional formula or data frame containing additional covariates for which to present balance or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the arguments to the input object, covs, and data, if specified. For CBMSM objects, can be a list of allowable arguments, one for each time point, but each dataset in the list supplied to addl must have one row per individual, unlike the data frame in the original call to CBMSM().
data	an optional data frame containing variables named in other arguments. For some input object types, this is required.
continuous	whether mean differences for continuous variables should be standardized ("std") or raw ("raw"). Default "std". Abbreviations allowed. This option can be set globally using set.cobalt.options().
binary	whether mean differences for binary variables (i.e., difference in proportion) should be standardized ("std") or raw ("raw"). Default "raw". Abbreviations allowed. This option can be set globally using set.cobalt.options().
s.d.denom	character; how the denominator for standardized mean differences should be calculated, if requested. See col_w_smd() for allowable options. Abbreviations allowed. If not specified, will be set to "treated" if the estimand of the call to CBPS() is the ATT and "pooled" if the estimand is the ATE.
thresholds	a named vector of balance thresholds, where the name corresponds to the statistic (i.e., in stats) that the threshold applies to. For example, to request thresholds on mean differences and variance ratios, one can set thresholds = c(m = .05, v = 2). Requesting a threshold automatically requests the display of that statistic. When specified, extra columns are inserted into the Balance table describing whether the requested balance statistics exceeded the threshold or not. Summary tables tallying the number of variables that exceeded and were within the threshold and displaying the variables with the greatest imbalance on that balance measure are added to the output.
weights	a vector, list, or data.frame containing weights for each unit, or a string containing the names of the weights variables in data, or an object with a get.w() method or a list thereof. The weights can be, e.g., inverse probability weights or matching weights resulting from a matching algorithm.
cluster	either a vector containing cluster membership for each unit or a string containing the name of the cluster membership variable in data or the input object. See class-bal.tab.cluster for details.
imp	either a vector containing imputation indices for each unit or a string containing the name of the imputation index variable in data or the input object. See class-bal.tab.imp for details. Not necessary if data is a mids object.
pairwise	whether balance should be computed for pairs of treatments or for each treatment against all groups combined. See bal.tab.multi() for details. This can also be used with a binary treatment to assess balance with respect to the full sample.
s.weights	Optional; either a vector containing sampling weights for each unit or a string containing the name of the sampling weight variable in data. These function like regular weights except that both the adjusted and unadjusted samples will be weighted according to these weights if weights are used. If sampling weights are used in CBPS(), it is critical that they are specified in bal.tab() as well using the s.weights argument.
abs	logical; whether displayed balance statistics should be in absolute value or not.
subset	a logical or numeric vector denoting whether each observation should be included or which observations should be included. If logical, it should have length equal to the number of units. NAs will be treated as FALSE. This can be used as an alternative to cluster to examine balance on subsets of the data.
quick	logical; if TRUE, will not compute any values that will not be displayed. Set to FALSE if computed values not displayed will be used later.
...	for some input types, other arguments that are required or allowed. Otherwise, further arguments to control display of output. See display options for details.

Details

bal.tab.CBPS() and bal.tab.CBMSM() generate a list of balance summaries for the CBPS or CBMSM object given and functions similarly to CBPS::balance().

Value

For point treatments, if clusters are not specified, an object of class "bal.tab" containing balance summaries for the CBPS object. See bal.tab() for details.

If clusters are specified, an object of class "bal.tab.cluster" containing balance summaries within each cluster and a summary of balance across clusters. See class-bal.tab.cluster for details.

If CBPS() is used with multi-category treatments, an object of class "bal.tab.multi" containing balance summaries for each pairwise treatment comparison and a summary of balance across pairwise comparisons. See bal.tab.multi() for details.

If CBMSM() is used for longitudinal treatments, an object of class "bal.tab.msm" containing balance summaries for each time period and a summary of balance across time periods. See class-bal.tab.msm for details.

See Also

• bal.tab() for details of calculations.

• class-bal.tab.cluster for more information on clustered data.

• bal.tab.multi() for more information on multi-category treatments.

• class-bal.tab.msm for more information on longitudinal treatments.

Examples

data("lalonde", package = "cobalt")

## Using CBPS() for generating covariate balancing 
## propensity score weights
cbps.out <- CBPS::CBPS(treat ~ age + educ + married + race +
                           nodegree + re74 + re75,
                       data = lalonde)

bal.tab(cbps.out)

---

Balance Statistics for cem Objects

Description

Generates balance statistics for cem.match objects from cem.

Usage

## S3 method for class 'cem.match'
bal.tab(
  x,
  data,
  stats,
  int = FALSE,
  poly = 1,
  distance = NULL,
  addl = NULL,
  continuous,
  binary,
  s.d.denom,
  thresholds = NULL,
  weights = NULL,
  cluster = NULL,
  imp = NULL,
  pairwise = TRUE,
  s.weights = NULL,
  abs = FALSE,
  subset = NULL,
  quick = TRUE,
  ...
)

Arguments

x	a cem.match or cem.match.list object; the output of a call to cem::cem().
data	a data frame containing variables named in other arguments. An argument to data is required. It must be the same data used in the call to cem() or a mids object from which the data supplied to datalist in the cem() call originated.
stats	character; which statistic(s) should be reported. See stats for allowable options. For binary and multi-category treatments, "mean.diffs" (i.e., mean differences) is the default. For continuous treatments, "correlations" (i.e., treatment-covariate Pearson correlations) is the default. Multiple options are allowed.
int	logical or numeric; whether or not to include 2-way interactions of covariates included in covs and in addl. If numeric, will be passed to poly as well.
poly	numeric; the highest polynomial of each continuous covariate to display. For example, if 2, squares of each continuous covariate will be displayed (in addition to the covariate itself); if 3, squares and cubes of each continuous covariate will be displayed, etc. If 1, the default, only the base covariate will be displayed. If int is numeric, poly will take on the value of int.
distance	an optional formula or data frame containing distance values (e.g., propensity scores) or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the argument to data, if specified. For longitudinal treatments, can be a list of allowable arguments, one for each time point.
addl	an optional formula or data frame containing additional covariates for which to present balance or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the arguments to the input object, covs, and data, if specified. For longitudinal treatments, can be a list of allowable arguments, one for each time point.
continuous	whether mean differences for continuous variables should be standardized ("std") or raw ("raw"). Default "std". Abbreviations allowed. This option can be set globally using set.cobalt.options().
binary	whether mean differences for binary variables (i.e., difference in proportion) should be standardized ("std") or raw ("raw"). Default "raw". Abbreviations allowed. This option can be set globally using set.cobalt.options().
s.d.denom	character; how the denominator for standardized mean differences should be calculated, if requested. See col_w_smd() for allowable options. Abbreviations allowed. If not specified, will be set to "treated", where the treated group corresponds to the baseline.group in the call to cem().
thresholds	a named vector of balance thresholds, where the name corresponds to the statistic (i.e., in stats) that the threshold applies to. For example, to request thresholds on mean differences and variance ratios, one can set thresholds = c(m = .05, v = 2). Requesting a threshold automatically requests the display of that statistic. When specified, extra columns are inserted into the Balance table describing whether the requested balance statistics exceeded the threshold or not. Summary tables tallying the number of variables that exceeded and were within the threshold and displaying the variables with the greatest imbalance on that balance measure are added to the output.
weights	a vector, list, or data.frame containing weights for each unit, or a string containing the names of the weights variables in data, or an object with a get.w() method or a list thereof. The weights can be, e.g., inverse probability weights or matching weights resulting from a matching algorithm.
cluster	either a vector containing cluster membership for each unit or a string containing the name of the cluster membership variable in data or the input object. See class-bal.tab.cluster for details.
imp	either a vector containing imputation indices for each unit or a string containing the name of the imputation index variable in data or the input object. See class-bal.tab.imp for details. Not necessary if data is a mids object.
pairwise	whether balance should be computed for pairs of treatments or for each treatment against all groups combined. See bal.tab.multi() for details. This can also be used with a binary treatment to assess balance with respect to the full sample.
s.weights	Optional; either a vector containing sampling weights for each unit or a string containing the name of the sampling weight variable in data. These function like regular weights except that both the adjusted and unadjusted samples will be weighted according to these weights if weights are used.
abs	logical; whether displayed balance statistics should be in absolute value or not.
subset	a logical or numeric vector denoting whether each observation should be included or which observations should be included. If logical, it should have length equal to the number of units. NAs will be treated as FALSE. This can be used as an alternative to cluster to examine balance on subsets of the data.
quick	logical; if TRUE, will not compute any values that will not be displayed. Set to FALSE if computed values not displayed will be used later.
...	for some input types, other arguments that are required or allowed. Otherwise, further arguments to control display of output. See display options for details.

Details

bal.tab.cem.match() generates a list of balance summaries for the cem.match object given, and functions similarly to cem::imbalance().

Value

If clusters and imputations are not specified, an object of class "bal.tab" containing balance summaries for the cem.match object. See bal.tab() for details.

If imputations are specified, an object of class "bal.tab.imp" containing balance summaries for each imputation and a summary of balance across imputations. See class-bal.tab.imp for details.

If cem() is used with multi-category treatments, an object of class "bal.tab.multi" containing balance summaries for each pairwise treatment comparison. See bal.tab.multi() for details.

If clusters are specified, an object of class "bal.tab.cluster" containing balance summaries within each cluster and a summary of balance across clusters. See class-bal.tab.cluster for details.

See Also

bal.tab() for details of calculations.

Examples

data("lalonde", package = "cobalt")

## Coarsened exact matching
cem.out <- cem::cem("treat", data = lalonde, drop = "re78")

bal.tab(cem.out, data = lalonde, un = TRUE, 
        stats = c("m", "k"))

---

Balance Statistics for Other Objects

Description

Generates balance statistics using an object for which there is not a defined method.

Usage

## Default S3 method:
bal.tab(
  x,
  stats,
  int = FALSE,
  poly = 1,
  distance = NULL,
  addl = NULL,
  data = NULL,
  continuous,
  binary,
  s.d.denom,
  thresholds = NULL,
  weights = NULL,
  cluster = NULL,
  imp = NULL,
  pairwise = TRUE,
  s.weights = NULL,
  abs = FALSE,
  subset = NULL,
  quick = TRUE,
  ...
)

Arguments

x	An object containing information about conditioning. See Details.
stats	character; which statistic(s) should be reported. See stats for allowable options. For binary and multi-category treatments, "mean.diffs" (i.e., mean differences) is the default. For continuous treatments, "correlations" (i.e., treatment-covariate Pearson correlations) is the default. Multiple options are allowed.
int	logical or numeric; whether or not to include 2-way interactions of covariates included in covs and in addl. If numeric, will be passed to poly as well.
poly	numeric; the highest polynomial of each continuous covariate to display. For example, if 2, squares of each continuous covariate will be displayed (in addition to the covariate itself); if 3, squares and cubes of each continuous covariate will be displayed, etc. If 1, the default, only the base covariate will be displayed. If int is numeric, poly will take on the value of int.
distance	an optional formula or data frame containing distance values (e.g., propensity scores) or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the argument to data, if specified. For longitudinal treatments, can be a list of allowable arguments, one for each time point.
addl	an optional formula or data frame containing additional covariates for which to present balance or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the arguments to the input object, covs, and data, if specified. For longitudinal treatments, can be a list of allowable arguments, one for each time point.
data	an optional data frame containing variables named in other arguments. For some input object types, this is required.
continuous	whether mean differences for continuous variables should be standardized ("std") or raw ("raw"). Default "std". Abbreviations allowed. This option can be set globally using set.cobalt.options().
binary	whether mean differences for binary variables (i.e., difference in proportion) should be standardized ("std") or raw ("raw"). Default "raw". Abbreviations allowed. This option can be set globally using set.cobalt.options().
s.d.denom	character; how the denominator for standardized mean differences should be calculated, if requested. See col_w_smd() for allowable options. If weights are supplied, each set of weights should have a corresponding entry to s.d.denom. Abbreviations allowed. If left blank and weights, subclasses, or matching strata are supplied, bal.tab() will figure out which one is best based on the estimand, if given (for ATT, "treated"; for ATC, "control"; otherwise "pooled") and other clues if not.
thresholds	a named vector of balance thresholds, where the name corresponds to the statistic (i.e., in stats) that the threshold applies to. For example, to request thresholds on mean differences and variance ratios, one can set thresholds = c(m = .05, v = 2). Requesting a threshold automatically requests the display of that statistic. When specified, extra columns are inserted into the Balance table describing whether the requested balance statistics exceeded the threshold or not. Summary tables tallying the number of variables that exceeded and were within the threshold and displaying the variables with the greatest imbalance on that balance measure are added to the output.
weights	a vector, list, or data.frame containing weights for each unit, or a string containing the names of the weights variables in data, or an object with a get.w() method or a list thereof. The weights can be, e.g., inverse probability weights or matching weights resulting from a matching algorithm.
cluster	either a vector containing cluster membership for each unit or a string containing the name of the cluster membership variable in data or the input object. See class-bal.tab.cluster for details.
imp	either a vector containing imputation indices for each unit or a string containing the name of the imputation index variable in data or the input object. See class-bal.tab.imp for details. Not necessary if data is a mids object.
pairwise	whether balance should be computed for pairs of treatments or for each treatment against all groups combined. See bal.tab.multi() for details. This can also be used with a binary treatment to assess balance with respect to the full sample.
s.weights	Optional; either a vector containing sampling weights for each unit or a string containing the name of the sampling weight variable in data. These function like regular weights except that both the adjusted and unadjusted samples will be weighted according to these weights if weights are used.
abs	logical; whether displayed balance statistics should be in absolute value or not.
subset	a logical or numeric vector denoting whether each observation should be included or which observations should be included. If logical, it should have length equal to the number of units. NAs will be treated as FALSE. This can be used as an alternative to cluster to examine balance on subsets of the data.
quick	logical; if TRUE, will not compute any values that will not be displayed. Set to FALSE if computed values not displayed will be used later.
...	other arguments that would be passed to bal.tab.formula(), bal.tab.data.frame(), or bal.tab.time.list(). See Details.

Details

bal.tab.default() processes its input and attempt to extract enough information from it to display covariate balance for x. The purpose of this method is to allow users who have created their own objects containing conditioning information (i.e., weights, subclasses, treatments, covariates, etc.) to access the capabilities of bal.tab() without having a special method written for them. By including the correct items in x, bal.tab.default() can present balance tables as if the input was the output of one of the specifically supported packages (e.g., MatchIt, twang, etc.).

The function will search x for the following named items and attempt to process them:

treat

A vector (numeric, character, factor) containing the values of the treatment for each unit or the name of the column in data containing them. Essentially the same input to treat in bal.tab.data.frame().

treat.list

A list of vectors (numeric, character, factor) containing, for each time point, the values of the treatment for each unit or the name of the column in data containing them. Essentially the same input to treat.list in bal.tab.time.list().

covs

A data.frame containing the values of the covariates for each unit. Essentially the same input to covs in bal.tab.data.frame().

covs.list

A list of data.frames containing, for each time point, the values of the covariates for each unit. Essentially the same input to covs.list in bal.tab.time.list().

formula

A formula with the treatment variable as the response and the covariates for which balance is to be assessed as the terms. Essentially the same input to formula in bal.tab.formula().

formula.list

A list of formulas with, for each time point, the treatment variable as the response and the covariates for which balance is to be assessed as the terms. Essentially the same input to formula.list in bal.tab.time.list().

data

A data.frame containing variables with the names used in other arguments and components (e.g., formula, weights, etc.). Essentially the same input to data in bal.tab.formula(), bal.tab.data.frame(), or bal.tab.time.list().

weights

A vector, list, or data.frame containing weights for each unit or a string containing the names of the weights variables in data. Essentially the same input to weights in bal.tab.data.frame() or bal.tab.time.list().

distance

A vector, formula, or data frame containing distance values (e.g., propensity scores) or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the argument to data, if specified. Essentially the same input to distance in bal.tab.data.frame().

formula.list

A list of vectors or data.frames containing, for each time point, distance values (e.g., propensity scores) for each unit or a string containing the name of the distance variable in data. Essentially the same input to distance.list in bal.tab.time.list().

subclass

A vector containing subclass membership for each unit or a string containing the name of the subclass variable in data. Essentially the same input to subclass in bal.tab.data.frame().

match.strata

A vector containing matching stratum membership for each unit or a string containing the name of the matching stratum variable in data. Essentially the same input to match.strata in bal.tab.data.frame().

estimand

A character vector; whether the desired estimand is the "ATT", "ATC", or "ATE" for each set of weights. Essentially the same input to estimand in bal.tab.data.frame().

s.weights

A vector containing sampling weights for each unit or a string containing the name of the sampling weight variable in data. Essentially the same input to s.weights in bal.tab.data.frame() or bal.tab.time.list().

focal

The name of the focal treatment when multi-category treatments are used. Essentially the same input to focal in bal.tab.data.frame().

call

A call object containing the function call, usually generated by using match.call() inside the function that created x.

Any of these items can also be supplied directly to bal.tab.default, e.g., bal.tab.default(x, formula = treat ~ x1 + x2). If supplied, it will override the object with the same role in x. In addition, any arguments to bal.tab.formula(), bal.tab.data.frame(), and bal.tab.time.list() are allowed and perform the same function.

At least some inputs containing information to create the treatment and covariates are required (e.g., formula and data or covs and treat). All other arguments are optional and have the same defaults as those in bal.tab.data.frame() or bal.tab.time.list(). If treat.list, covs.list, or formula.list are supplied in x or as an argument to bal.tab.default(), the function will proceed considering a longitudinal treatment. Otherwise, it will proceed considering a point treatment.

bal.tab.default(), like other bal.tab() methods, is just a shortcut to supply arguments to bal.tab.data.frame() or bal.tab.time.list(). Therefore, any matters regarding argument priority or function are described in the documentation for these methods.

Value

For point treatments, if clusters and imputations are not specified, an object of class "bal.tab" containing balance summaries for the specified treatment and covariates. See bal.tab() for details.

If clusters are specified, an object of class "bal.tab.cluster" containing balance summaries within each cluster and a summary of balance across clusters. See class-bal.tab.cluster for details.

If imputations are specified, an object of class "bal.tab.imp" containing balance summaries for each imputation and a summary of balance across imputations, just as with clusters. See class-bal.tab.imp for details.

If multi-category treatments are used, an object of class "bal.tab.multi" containing balance summaries for each pairwise treatment comparison and a summary of balance across pairwise comparisons. See bal.tab.multi() for details.

If longitudinal treatments are used, an object of class "bal.tab.msm" containing balance summaries at each time point. Each balance summary is its own bal.tab object. See class-bal.tab.msm for more details.

See Also

• bal.tab.formula() and bal.tab.time.list() for additional arguments to be supplied.

• bal.tab() for output and details of calculations.

• class-bal.tab.cluster for more information on clustered data.

• class-bal.tab.imp for more information on multiply imputed data.

• bal.tab.multi() for more information on multi-category treatments.

Examples

data("lalonde", package = "cobalt")
covs <- subset(lalonde,  select = -c(treat, re78))

##Writing a function the produces output for direct
##use in bal.tab.default

ate.weights <- function(treat, covs) {
    data <- data.frame(treat, covs)
    formula <- formula(data)
    ps <- glm(formula, data = data, 
              family = "binomial")$fitted.values
    weights <- treat/ps + (1-treat)/(1-ps)
    call <- match.call()
    out <- list(treat = treat,
                covs = covs,
                distance = ps,
                weights = weights,
                estimand = "ATE",
                call = call)
    return(out)
}

out <- ate.weights(lalonde$treat, covs)

bal.tab(out, un = TRUE)

---

Balance Statistics for designmatch Objects

Description

Generates balance statistics for output objects from designmatch.

Usage

## S3 method for class 'designmatch'
bal.tab(
  x,
  formula = NULL,
  data = NULL,
  treat = NULL,
  covs = NULL,
  stats,
  int = FALSE,
  poly = 1,
  distance = NULL,
  addl = NULL,
  continuous,
  binary,
  s.d.denom,
  thresholds = NULL,
  weights = NULL,
  cluster = NULL,
  imp = NULL,
  pairwise = TRUE,
  s.weights = NULL,
  abs = FALSE,
  subset = NULL,
  quick = TRUE,
  ...
)

Arguments

x	the output of a call to designmatch::bmatch() or related wrapper functions from the designmatch package.
formula	a formula with the treatment variable as the response and the covariates for which balance is to be assessed as the predictors. All named variables must be in data. See Details.
data	a data frame containing variables named in formula, if supplied, and other arguments.
treat	a vector of treatment statuses. See Details.
covs	a data frame of covariate values for which to check balance. See Details.
stats	character; which statistic(s) should be reported. See stats for allowable options. For binary and multi-category treatments, "mean.diffs" (i.e., mean differences) is the default. For continuous treatments, "correlations" (i.e., treatment-covariate Pearson correlations) is the default. Multiple options are allowed.
int	logical or numeric; whether or not to include 2-way interactions of covariates included in covs and in addl. If numeric, will be passed to poly as well.
poly	numeric; the highest polynomial of each continuous covariate to display. For example, if 2, squares of each continuous covariate will be displayed (in addition to the covariate itself); if 3, squares and cubes of each continuous covariate will be displayed, etc. If 1, the default, only the base covariate will be displayed. If int is numeric, poly will take on the value of int.
distance	an optional formula or data frame containing distance values (e.g., propensity scores) or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the argument to data, if specified. For longitudinal treatments, can be a list of allowable arguments, one for each time point.
addl	an optional formula or data frame containing additional covariates for which to present balance or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the arguments to the input object, covs, and data, if specified. For longitudinal treatments, can be a list of allowable arguments, one for each time point.
continuous	whether mean differences for continuous variables should be standardized ("std") or raw ("raw"). Default "std". Abbreviations allowed. This option can be set globally using set.cobalt.options().
binary	whether mean differences for binary variables (i.e., difference in proportion) should be standardized ("std") or raw ("raw"). Default "raw". Abbreviations allowed. This option can be set globally using set.cobalt.options().
s.d.denom	character; how the denominator for standardized mean differences should be calculated, if requested. See col_w_smd() for allowable options. Abbreviations allowed. If not specified, will be set to "treated".
thresholds	a named vector of balance thresholds, where the name corresponds to the statistic (i.e., in stats) that the threshold applies to. For example, to request thresholds on mean differences and variance ratios, one can set thresholds = c(m = .05, v = 2). Requesting a threshold automatically requests the display of that statistic. When specified, extra columns are inserted into the Balance table describing whether the requested balance statistics exceeded the threshold or not. Summary tables tallying the number of variables that exceeded and were within the threshold and displaying the variables with the greatest imbalance on that balance measure are added to the output.
weights	a vector, list, or data.frame containing weights for each unit, or a string containing the names of the weights variables in data, or an object with a get.w() method or a list thereof. The weights can be, e.g., inverse probability weights or matching weights resulting from a matching algorithm.
cluster	either a vector containing cluster membership for each unit or a string containing the name of the cluster membership variable in data or the input object. See class-bal.tab.cluster for details.
imp	either a vector containing imputation indices for each unit or a string containing the name of the imputation index variable in data or the input object. See class-bal.tab.imp for details. Not necessary if data is a mids object.
pairwise	whether balance should be computed for pairs of treatments or for each treatment against all groups combined. See bal.tab.multi() for details. This can also be used with a binary treatment to assess balance with respect to the full sample.
s.weights	Optional; either a vector containing sampling weights for each unit or a string containing the name of the sampling weight variable in data. These function like regular weights except that both the adjusted and unadjusted samples will be weighted according to these weights if weights are used.
abs	logical; whether displayed balance statistics should be in absolute value or not.
subset	a logical or numeric vector denoting whether each observation should be included or which observations should be included. If logical, it should have length equal to the number of units. NAs will be treated as FALSE. This can be used as an alternative to cluster to examine balance on subsets of the data.
quick	logical; if TRUE, will not compute any values that will not be displayed. Set to FALSE if computed values not displayed will be used later.
...	for some input types, other arguments that are required or allowed. Otherwise, further arguments to control display of output. See display options for details.

Details

bal.tab() generates a list of balance summaries for the object given, and functions similarly to designmatch::meantab(). Note that output objects from designmatch do not have their own class; bal.tab() first checks whether the object meets the criteria to be treated as a designmatch object before dispatching the correct method. Renaming or removing items from the output object can create unintended consequences.

The input to bal.tab.designmatch() must include either both formula and data or both covs and treat. Using the covs + treat input mirrors how designmatch::meantab() is used (note that to see identical results to meantab(), s.d.denom must be set to "pooled").

Value

If clusters and imputations are not specified, an object of class "bal.tab" containing balance summaries for the given object. See bal.tab() for details.

If clusters are specified, an object of class "bal.tab.cluster" containing balance summaries within each cluster and a summary of balance across clusters. See class-bal.tab.cluster for details.

See Also

bal.tab() for details of calculations.

Examples

data("lalonde", package = "cobalt")

library(designmatch)
covariates <- as.matrix(lalonde[c("age", "educ", "re74", "re75")])
treat <- lalonde$treat
dmout <- bmatch(treat,
                total_groups = sum(treat == 1),
                mom = list(covs = covariates,
                           tols = absstddif(covariates, 
                                            treat, .05))
)

## Using treat and covs
bal.tab(dmout, treat = treat, covs = covariates)

---

Balance Statistics for ebalance Objects

Description

Generates balance statistics for output objects from ebal.

Usage

## S3 method for class 'ebalance'
bal.tab(
  x,
  formula = NULL,
  data = NULL,
  treat = NULL,
  covs = NULL,
  stats,
  int = FALSE,
  poly = 1,
  distance = NULL,
  addl = NULL,
  continuous,
  binary,
  s.d.denom,
  thresholds = NULL,
  weights = NULL,
  cluster = NULL,
  imp = NULL,
  pairwise = TRUE,
  s.weights = NULL,
  abs = FALSE,
  subset = NULL,
  quick = TRUE,
  ...
)

Arguments

x	an ebalance object (the output of a call to ebal::ebalance() or ebal::ebalance.trim()).
formula	a formula with the treatment variable as the response and the covariates for which balance is to be assessed as the predictors. All named variables must be in data. See Details.
data	a data frame containing variables named in formula, if supplied, and other arguments.
treat	a vector of treatment statuses. See Details.
covs	a data frame of covariate values for which to check balance. See Details.
stats	character; which statistic(s) should be reported. See stats for allowable options. For binary and multi-category treatments, "mean.diffs" (i.e., mean differences) is the default. For continuous treatments, "correlations" (i.e., treatment-covariate Pearson correlations) is the default. Multiple options are allowed.
int	logical or numeric; whether or not to include 2-way interactions of covariates included in covs and in addl. If numeric, will be passed to poly as well.
poly	numeric; the highest polynomial of each continuous covariate to display. For example, if 2, squares of each continuous covariate will be displayed (in addition to the covariate itself); if 3, squares and cubes of each continuous covariate will be displayed, etc. If 1, the default, only the base covariate will be displayed. If int is numeric, poly will take on the value of int.
distance	an optional formula or data frame containing distance values (e.g., propensity scores) or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the argument to data, if specified. For longitudinal treatments, can be a list of allowable arguments, one for each time point.
addl	an optional formula or data frame containing additional covariates for which to present balance or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the arguments to the input object, covs, and data, if specified. For longitudinal treatments, can be a list of allowable arguments, one for each time point.
continuous	whether mean differences for continuous variables should be standardized ("std") or raw ("raw"). Default "std". Abbreviations allowed. This option can be set globally using set.cobalt.options().
binary	whether mean differences for binary variables (i.e., difference in proportion) should be standardized ("std") or raw ("raw"). Default "raw". Abbreviations allowed. This option can be set globally using set.cobalt.options().
s.d.denom	character; how the denominator for standardized mean differences should be calculated, if requested. See col_w_smd() for allowable options. Abbreviations allowed. If not specified, will be set to "treated".
thresholds	a named vector of balance thresholds, where the name corresponds to the statistic (i.e., in stats) that the threshold applies to. For example, to request thresholds on mean differences and variance ratios, one can set thresholds = c(m = .05, v = 2). Requesting a threshold automatically requests the display of that statistic. When specified, extra columns are inserted into the Balance table describing whether the requested balance statistics exceeded the threshold or not. Summary tables tallying the number of variables that exceeded and were within the threshold and displaying the variables with the greatest imbalance on that balance measure are added to the output.
weights	a vector, list, or data.frame containing weights for each unit, or a string containing the names of the weights variables in data, or an object with a get.w() method or a list thereof. The weights can be, e.g., inverse probability weights or matching weights resulting from a matching algorithm.
cluster	either a vector containing cluster membership for each unit or a string containing the name of the cluster membership variable in data or the input object. See class-bal.tab.cluster for details.
imp	either a vector containing imputation indices for each unit or a string containing the name of the imputation index variable in data or the input object. See class-bal.tab.imp for details. Not necessary if data is a mids object.
pairwise	whether balance should be computed for pairs of treatments or for each treatment against all groups combined. See bal.tab.multi() for details. This can also be used with a binary treatment to assess balance with respect to the full sample.
s.weights	Optional; either a vector containing sampling weights for each unit or a string containing the name of the sampling weight variable in data. These function like regular weights except that both the adjusted and unadjusted samples will be weighted according to these weights if weights are used.
abs	logical; whether displayed balance statistics should be in absolute value or not.
subset	a logical or numeric vector denoting whether each observation should be included or which observations should be included. If logical, it should have length equal to the number of units. NAs will be treated as FALSE. This can be used as an alternative to cluster to examine balance on subsets of the data.
quick	logical; if TRUE, will not compute any values that will not be displayed. Set to FALSE if computed values not displayed will be used later.
...	for some input types, other arguments that are required or allowed. Otherwise, further arguments to control display of output. See display options for details.

Details

bal.tab() generates a list of balance summaries for the object given. The input to bal.tab.ebalance() must include either both formula and data or both covs and treat.

Value

If clusters and imputations are not specified, an object of class "bal.tab" containing balance summaries for the given object. See bal.tab() for details.

If clusters are specified, an object of class "bal.tab.cluster" containing balance summaries within each cluster and a summary of balance across clusters. See class-bal.tab.cluster for details.

See Also

bal.tab() for details of calculations.

Examples

data("lalonde", package = "cobalt")

covs <- subset(lalonde, select = -c(re78, treat))
covs0 <- splitfactor(covs)

e.out <- ebal::ebalance(lalonde$treat, covs0)

## Using formula and data
bal.tab(e.out, formula = treat ~ age + educ + race +
            married + nodegree + re74 + re75,
        data = lalonde)

## Using treat and covs
bal.tab(e.out, treat = lalonde$treat, covs = covs)

---

Balance Statistics for Data Sets

Description

Generates balance statistics for unadjusted, matched, weighted, or stratified data using either a data.frame or formula interface.

Usage

## S3 method for class 'formula'
bal.tab(
  x,
  data = NULL,
  stats,
  int = FALSE,
  poly = 1,
  distance = NULL,
  addl = NULL,
  continuous,
  binary,
  s.d.denom,
  thresholds = NULL,
  weights = NULL,
  cluster = NULL,
  imp = NULL,
  pairwise = TRUE,
  s.weights = NULL,
  abs = FALSE,
  subset = NULL,
  quick = TRUE,
  subclass = NULL,
  match.strata = NULL,
  method,
  estimand = NULL,
  focal = NULL,
  ...
)

## S3 method for class 'data.frame'
bal.tab(
  x,
  treat,
  stats,
  int = FALSE,
  poly = 1,
  distance = NULL,
  addl = NULL,
  data = NULL,
  continuous,
  binary,
  s.d.denom,
  thresholds = NULL,
  weights = NULL,
  cluster = NULL,
  imp = NULL,
  pairwise = TRUE,
  s.weights = NULL,
  abs = FALSE,
  subset = NULL,
  quick = TRUE,
  subclass = NULL,
  match.strata = NULL,
  method,
  estimand = NULL,
  focal = NULL,
  ...
)

## S3 method for class 'matrix'
bal.tab(
  x,
  treat,
  stats,
  int = FALSE,
  poly = 1,
  distance = NULL,
  addl = NULL,
  data = NULL,
  continuous,
  binary,
  s.d.denom,
  thresholds = NULL,
  weights = NULL,
  cluster = NULL,
  imp = NULL,
  pairwise = TRUE,
  s.weights = NULL,
  abs = FALSE,
  subset = NULL,
  quick = TRUE,
  subclass = NULL,
  match.strata = NULL,
  method,
  estimand = NULL,
  focal = NULL,
  ...
)

Arguments

x	either a data.frame containing covariate values for each unit or a formula with the treatment variable as the response and the covariates for which balance is to be assessed as the terms. If a formula is supplied, all terms must be present as variable names in data or the global environment.
data	an optional data frame containing variables named in other arguments. For some input object types, this is required.
stats	character; which statistic(s) should be reported. See stats for allowable options. For binary and multi-category treatments, "mean.diffs" (i.e., mean differences) is the default. For continuous treatments, "correlations" (i.e., treatment-covariate Pearson correlations) is the default. Multiple options are allowed.
int	logical or numeric; whether or not to include 2-way interactions of covariates included in covs and in addl. If numeric, will be passed to poly as well.
poly	numeric; the highest polynomial of each continuous covariate to display. For example, if 2, squares of each continuous covariate will be displayed (in addition to the covariate itself); if 3, squares and cubes of each continuous covariate will be displayed, etc. If 1, the default, only the base covariate will be displayed. If int is numeric, poly will take on the value of int.
distance	an optional formula or data frame containing distance values (e.g., propensity scores) or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the argument to data, if specified. For longitudinal treatments, can be a list of allowable arguments, one for each time point.
addl	an optional formula or data frame containing additional covariates for which to present balance or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the arguments to the input object, covs, and data, if specified. For longitudinal treatments, can be a list of allowable arguments, one for each time point.
continuous	whether mean differences for continuous variables should be standardized ("std") or raw ("raw"). Default "std". Abbreviations allowed. This option can be set globally using set.cobalt.options().
binary	whether mean differences for binary variables (i.e., difference in proportion) should be standardized ("std") or raw ("raw"). Default "raw". Abbreviations allowed. This option can be set globally using set.cobalt.options().
s.d.denom	character; how the denominator for standardized mean differences should be calculated, if requested. See col_w_smd() for allowable options. Abbreviations allowed. If weights are supplied, each set of weights should have a corresponding entry to s.d.denom; a single entry will be recycled to all sets of weights. If left blank and one of weights, subclass, or match.strata are supplied, bal.tab() will figure out which one is best based on estimand, if given (for ATT, "treated"; for ATC, "control"; otherwise "pooled") and other clues if not.
thresholds	a named vector of balance thresholds, where the name corresponds to the statistic (i.e., in stats) that the threshold applies to. For example, to request thresholds on mean differences and variance ratios, one can set thresholds = c(m = .05, v = 2). Requesting a threshold automatically requests the display of that statistic. When specified, extra columns are inserted into the Balance table describing whether the requested balance statistics exceeded the threshold or not. Summary tables tallying the number of variables that exceeded and were within the threshold and displaying the variables with the greatest imbalance on that balance measure are added to the output.
weights	a vector, list, or data.frame containing weights for each unit, or a string containing the names of the weights variables in data, or an object with a get.w() method or a list thereof. The weights can be, e.g., inverse probability weights or matching weights resulting from a matching algorithm.
cluster	either a vector containing cluster membership for each unit or a string containing the name of the cluster membership variable in data or the input object. See class-bal.tab.cluster for details.
imp	either a vector containing imputation indices for each unit or a string containing the name of the imputation index variable in data or the input object. See class-bal.tab.imp for details. Not necessary if data is a mids object.
pairwise	whether balance should be computed for pairs of treatments or for each treatment against all groups combined. See bal.tab.multi() for details. This can also be used with a binary treatment to assess balance with respect to the full sample.
s.weights	Optional; either a vector containing sampling weights for each unit or a string containing the name of the sampling weight variable in data. These function like regular weights except that both the adjusted and unadjusted samples will be weighted according to these weights if weights are used.
abs	logical; whether displayed balance statistics should be in absolute value or not.
subset	a logical or numeric vector denoting whether each observation should be included or which observations should be included. If logical, it should have length equal to the number of units. NAs will be treated as FALSE. This can be used as an alternative to cluster to examine balance on subsets of the data.
quick	logical; if TRUE, will not compute any values that will not be displayed. Set to FALSE if computed values not displayed will be used later.
subclass	optional; either a vector containing subclass membership for each unit or a string containing the name of the subclass variable in data.
match.strata	optional; either a vector containing matching stratum membership for each unit or a string containing the name of the matching stratum variable in data. See Details.
method	character; the method of adjustment, if any. If weights are specified, the user can specify either "matching" or "weighting"; "weighting" is the default. If multiple sets of weights are used, each must have a corresponding value for method, but if they are all of the same type, only one value is required. If subclass is specified, "subclassification" is the default. Abbreviations allowed. The only distinction between "matching" and "weighting" is how sample sizes are displayed.
estimand	character; whether the desired estimand is the "ATT", "ATC", or "ATE" for each set of weights. This argument can be used in place of s.d.denom to specify how standardized differences are calculated.
focal	the name of the focal treatment when multi-category treatments are used. See bal.tab.multi() for details.
...	for some input types, other arguments that are required or allowed. Otherwise, further arguments to control display of output. See display options for details.
treat	either a vector containing treatment status values for each unit or a string containing the name of the treatment variable in data. Required for the data.frame method.

Details

bal.tab.data.frame() generates a list of balance summaries for the covariates and treatment status values given. bal.tab.formula() does the same but uses a formula interface instead. When the formula interface is used, the formula and data are reshaped into a treatment vector and data.frame of covariates and then simply passed through the data.frame method.

If weights, subclass and match.strata are all NULL, balance information will be presented only for the unadjusted sample.

The argument to match.strata corresponds to a factor vector containing the name or index of each pair/stratum for units conditioned through matching, for example, using the optmatch package. If more than one of weights, subclass, or match.strata are specified, bal.tab() will attempt to figure out which one to apply. Currently only one of these can be applied ta a time. bal.tab() behaves differently depending on whether subclasses are used in conditioning or not. If they are used, bal.tab() creates balance statistics for each subclass and for the sample in aggregate. See class-bal.tab.subclass for more information.

Multiple sets of weights can be supplied simultaneously by entering a data.frame or a character vector containing the names of weight variables found in data or a list of weights vectors or names. The arguments to method, s.d.denom, and estimand, if any, must be either the same length as the number of sets of weights or of length one, where the sole entry is applied to all sets. When standardized differences are computed for the unadjusted group, they are done using the first entry to s.d.denom or estimand. When only one set of weights is supplied, the output for the adjusted group will simply be called "Adj", but otherwise will be named after each corresponding set of weights. Specifying multiple sets of weights will also add components to other outputs of bal.tab().

Value

For point treatments, if clusters and imputations are not specified, an object of class "bal.tab" containing balance summaries for the specified treatment and covariates. See bal.tab() for details.

If imputations are specified, an object of class "bal.tab.imp" containing balance summaries for each imputation and a summary of balance across imputations. See class-bal.tab.imp for details.

If multi-category treatments are used, an object of class "bal.tab.multi" containing balance summaries for each pairwise treatment comparison. See bal.tab.multi() for details.

If clusters are specified, an object of class "bal.tab.cluster" containing balance summaries within each cluster and a summary of balance across clusters. See class-bal.tab.cluster for details.

See Also

• bal.tab() for details of calculations.

• class-bal.tab.cluster for more information on clustered data.

• class-bal.tab.imp for more information on multiply imputed data.

• bal.tab.multi() for more information on multi-category treatments.

Examples

data("lalonde", package = "cobalt")
lalonde$p.score <- glm(treat ~ age + educ + race, data = lalonde, 
                       family = "binomial")$fitted.values
covariates <- subset(lalonde, select = c(age, educ, race))

## Propensity score weighting using IPTW
lalonde$iptw.weights <- ifelse(lalonde$treat==1, 
                               1/lalonde$p.score, 
                               1/(1-lalonde$p.score))

# data frame interface:
bal.tab(covariates, treat = "treat", data = lalonde, 
        weights = "iptw.weights", s.d.denom = "pooled")

# Formula interface:
bal.tab(treat ~ age + educ + race, data = lalonde, 
        weights = "iptw.weights", s.d.denom = "pooled")

## Propensity score subclassification
lalonde$subclass <- findInterval(lalonde$p.score, 
                                 quantile(lalonde$p.score, 
                                          (0:6)/6), all.inside = TRUE)

# data frame interface:
bal.tab(covariates, treat = "treat", data = lalonde, 
        subclass = "subclass", disp.subclass = TRUE, 
        s.d.denom = "pooled")

# Formula interface:
bal.tab(treat ~ age + educ + race, data = lalonde, 
        subclass = "subclass", disp.subclass = TRUE, 
        s.d.denom = "pooled")

---

Balance Statistics for Matching Objects

Description

Generates balance statistics for output objects from Matching.

Usage

## S3 method for class 'Match'
bal.tab(
  x,
  formula = NULL,
  data = NULL,
  treat = NULL,
  covs = NULL,
  stats,
  int = FALSE,
  poly = 1,
  distance = NULL,
  addl = NULL,
  continuous,
  binary,
  s.d.denom,
  thresholds = NULL,
  weights = NULL,
  cluster = NULL,
  imp = NULL,
  pairwise = TRUE,
  s.weights = NULL,
  abs = FALSE,
  subset = NULL,
  quick = TRUE,
  ...
)

Arguments

x	a Match object (the output of a call to Matching::Match() or Matching::Matchby()).
formula	a formula with the treatment variable as the response and the covariates for which balance is to be assessed as the predictors. All named variables must be in data. See Details.
data	a data frame containing variables named in formula, if supplied, and other arguments.
treat	a vector of treatment statuses. See Details.
covs	a data frame of covariate values for which to check balance. See Details.
stats	character; which statistic(s) should be reported. See stats for allowable options. For binary and multi-category treatments, "mean.diffs" (i.e., mean differences) is the default. For continuous treatments, "correlations" (i.e., treatment-covariate Pearson correlations) is the default. Multiple options are allowed.
int	logical or numeric; whether or not to include 2-way interactions of covariates included in covs and in addl. If numeric, will be passed to poly as well.
poly	numeric; the highest polynomial of each continuous covariate to display. For example, if 2, squares of each continuous covariate will be displayed (in addition to the covariate itself); if 3, squares and cubes of each continuous covariate will be displayed, etc. If 1, the default, only the base covariate will be displayed. If int is numeric, poly will take on the value of int.
distance	an optional formula or data frame containing distance values (e.g., propensity scores) or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the argument to data, if specified. For longitudinal treatments, can be a list of allowable arguments, one for each time point.
addl	an optional formula or data frame containing additional covariates for which to present balance or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the arguments to the input object, covs, and data, if specified. For longitudinal treatments, can be a list of allowable arguments, one for each time point.
continuous	whether mean differences for continuous variables should be standardized ("std") or raw ("raw"). Default "std". Abbreviations allowed. This option can be set globally using set.cobalt.options().
binary	whether mean differences for binary variables (i.e., difference in proportion) should be standardized ("std") or raw ("raw"). Default "raw". Abbreviations allowed. This option can be set globally using set.cobalt.options().
s.d.denom	character; how the denominator for standardized mean differences should be calculated, if requested. See col_w_smd() for allowable options. Abbreviations allowed. If not specified, bal.tab() will use "treated" if the estimand of the call to Match() is the ATT, "pooled" if the estimand is the ATE, and "control" if the estimand is the ATC.
thresholds	a named vector of balance thresholds, where the name corresponds to the statistic (i.e., in stats) that the threshold applies to. For example, to request thresholds on mean differences and variance ratios, one can set thresholds = c(m = .05, v = 2). Requesting a threshold automatically requests the display of that statistic. When specified, extra columns are inserted into the Balance table describing whether the requested balance statistics exceeded the threshold or not. Summary tables tallying the number of variables that exceeded and were within the threshold and displaying the variables with the greatest imbalance on that balance measure are added to the output.
weights	a vector, list, or data.frame containing weights for each unit, or a string containing the names of the weights variables in data, or an object with a get.w() method or a list thereof. The weights can be, e.g., inverse probability weights or matching weights resulting from a matching algorithm.
cluster	either a vector containing cluster membership for each unit or a string containing the name of the cluster membership variable in data or the input object. See class-bal.tab.cluster for details.
imp	either a vector containing imputation indices for each unit or a string containing the name of the imputation index variable in data or the input object. See class-bal.tab.imp for details. Not necessary if data is a mids object.
pairwise	whether balance should be computed for pairs of treatments or for each treatment against all groups combined. See bal.tab.multi() for details. This can also be used with a binary treatment to assess balance with respect to the full sample.
s.weights	Optional; either a vector containing sampling weights for each unit or a string containing the name of the sampling weight variable in data. These function like regular weights except that both the adjusted and unadjusted samples will be weighted according to these weights if weights are used.
abs	logical; whether displayed balance statistics should be in absolute value or not.
subset	a logical or numeric vector denoting whether each observation should be included or which observations should be included. If logical, it should have length equal to the number of units. NAs will be treated as FALSE. This can be used as an alternative to cluster to examine balance on subsets of the data.
quick	logical; if TRUE, will not compute any values that will not be displayed. Set to FALSE if computed values not displayed will be used later.
...	for some input types, other arguments that are required or allowed. Otherwise, further arguments to control display of output. See display options for details.

Details

bal.tab() generates a list of balance summaries for the object given, and functions similarly to Matching::MatchBalance(). The input to bal.tab.Match() must include either both formula and data or both covs and treat. Using the formula + data inputs mirrors how Matching::MatchBalance() is used.

cobalt functions do not support Match object with sampling weights, i.e., with an argument passed to the weights argument of Matching::Match().

Value

If clusters and imputations are not specified, an object of class "bal.tab" containing balance summaries for the given object. See bal.tab() for details.

If clusters are specified, an object of class "bal.tab.cluster" containing balance summaries within each cluster and a summary of balance across clusters. See class-bal.tab.cluster for details.

See Also

bal.tab() for details of calculations.

Examples

library(Matching); data("lalonde", package = "cobalt")

p.score <- glm(treat ~ age + educ + race + 
                   married + nodegree + re74 + re75, 
               data = lalonde, family = "binomial")$fitted.values
Match.out <- Match(Tr = lalonde$treat, X = p.score)

## Using formula and data
bal.tab(Match.out, formula = treat ~ age + educ + race + 
            married + nodegree + re74 + re75, data = lalonde)

---

Balance Statistics for MatchIt Objects

Description

Generates balance statistics for matchit objects from MatchIt.

Usage

## S3 method for class 'matchit'
bal.tab(
  x,
  stats,
  int = FALSE,
  poly = 1,
  distance = NULL,
  addl = NULL,
  data = NULL,
  continuous,
  binary,
  s.d.denom,
  thresholds = NULL,
  weights = NULL,
  cluster = NULL,
  imp = NULL,
  pairwise = TRUE,
  s.weights = NULL,
  abs = FALSE,
  subset = NULL,
  quick = TRUE,
  method,
  ...
)

Arguments

x	a matchit object; the output of a call to MatchIt::matchit().
stats	character; which statistic(s) should be reported. See stats for allowable options. For binary and multi-category treatments, "mean.diffs" (i.e., mean differences) is the default. For continuous treatments, "correlations" (i.e., treatment-covariate Pearson correlations) is the default. Multiple options are allowed.
int	logical or numeric; whether or not to include 2-way interactions of covariates included in covs and in addl. If numeric, will be passed to poly as well.
poly	numeric; the highest polynomial of each continuous covariate to display. For example, if 2, squares of each continuous covariate will be displayed (in addition to the covariate itself); if 3, squares and cubes of each continuous covariate will be displayed, etc. If 1, the default, only the base covariate will be displayed. If int is numeric, poly will take on the value of int.
distance	an optional formula or data frame containing distance values (e.g., propensity scores) or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the argument to data, if specified. The distance measure (e.g., propensity score) generated by matchit() is automatically included and named "distance".
addl	an optional formula or data frame containing additional covariates for which to present balance or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the arguments to the input object, covs, and data, if specified. For longitudinal treatments, can be a list of allowable arguments, one for each time point.
data	an optional data frame containing variables named in other arguments. For some input object types, this is required.
continuous	whether mean differences for continuous variables should be standardized ("std") or raw ("raw"). Default "std". Abbreviations allowed. This option can be set globally using set.cobalt.options().
binary	whether mean differences for binary variables (i.e., difference in proportion) should be standardized ("std") or raw ("raw"). Default "raw". Abbreviations allowed. This option can be set globally using set.cobalt.options().
s.d.denom	character; how the denominator for standardized mean differences should be calculated, if requested. See col_w_smd() for allowable options. Abbreviations allowed. If not specified, bal.tab() will figure out which one is best based on the estimand of the matchit object: if ATT, "treated"; if ATC, "control", otherwise "pooled".
thresholds	a named vector of balance thresholds, where the name corresponds to the statistic (i.e., in stats) that the threshold applies to. For example, to request thresholds on mean differences and variance ratios, one can set thresholds = c(m = .05, v = 2). Requesting a threshold automatically requests the display of that statistic. When specified, extra columns are inserted into the Balance table describing whether the requested balance statistics exceeded the threshold or not. Summary tables tallying the number of variables that exceeded and were within the threshold and displaying the variables with the greatest imbalance on that balance measure are added to the output.
weights	a vector, list, or data.frame containing weights for each unit, or a string containing the names of the weights variables in data, or an object with a get.w() method or a list thereof. The weights can be, e.g., inverse probability weights or matching weights resulting from a matching algorithm.
cluster	either a vector containing cluster membership for each unit or a string containing the name of the cluster membership variable in data or the input object. See class-bal.tab.cluster for details.
imp	either a vector containing imputation indices for each unit or a string containing the name of the imputation index variable in data or the input object. See class-bal.tab.imp for details. Not necessary if data is a mids object.
pairwise	whether balance should be computed for pairs of treatments or for each treatment against all groups combined. See bal.tab.multi() for details. This can also be used with a binary treatment to assess balance with respect to the full sample.
s.weights	Optional; either a vector containing sampling weights for each unit or a string containing the name of the sampling weight variable in data. These function like regular weights except that both the adjusted and unadjusted samples will be weighted according to these weights if weights are used. If s.weights was specified in the call to matchit(), they will automatically be included and do not need be specified again (though there is no harm if they are).
abs	logical; whether displayed balance statistics should be in absolute value or not.
subset	a logical or numeric vector denoting whether each observation should be included or which observations should be included. If logical, it should have length equal to the number of units. NAs will be treated as FALSE. This can be used as an alternative to cluster to examine balance on subsets of the data.
quick	logical; if TRUE, will not compute any values that will not be displayed. Set to FALSE if computed values not displayed will be used later.
method	a character vector containing the method of adjustment. Ignored unless subclassification was used in the original call to matchit(). If "weighting", the subclassification weights will be used and subclasses will be ignored. If "subclassification", balance will be assessed using the subclasses (see class-bal.tab.subclass for details). Abbreviations allowed.
...	for some input types, other arguments that are required or allowed. Otherwise, further arguments to control display of output. See display options for details.

Details

bal.tab.matchit() generates a list of balance summaries for the matchit object given, and functions similarly to MatchIt::summary.matchit(). bal.tab() behaves differently depending on whether subclasses are used in conditioning or not. If they are used, bal.tab() creates balance statistics for each subclass and for the sample in aggregate; see class-bal.tab.subclass for more information.

Value

If subclassification is used and method is set to "subclassification", an object of class "bal.tab.subclass" containing balance summaries within and across subclasses. See class-bal.tab.subclass for details.

If matching is used and clusters are not specified, an object of class "bal.tab" containing balance summaries for the matchit object. See bal.tab() for details.

If clusters are specified, an object of class "bal.tab.cluster" containing balance summaries within each cluster and a summary of balance across clusters. See class-bal.tab.cluster for details.

See Also

• bal.tab() for details of calculations.

Examples

library(MatchIt); data("lalonde", package = "cobalt")

## Nearest Neighbor matching
m.out1 <- matchit(treat ~ age + educ + race + 
                      married + nodegree + re74 + re75, 
                  data = lalonde, method = "nearest")

bal.tab(m.out1, un = TRUE, m.threshold = .1, 
        v.threshold = 2)

## Subclassification
m.out2 <- matchit(treat ~ age + educ + race + 
                      married + nodegree + re74 + re75, 
                  data = lalonde, method = "subclass")

bal.tab(m.out2, disp.subclass = TRUE)

---

Balance Statistics for MatchThem Objects

Description

Generates balance statistics for mimids and wimids objects from MatchThem.

Usage

## S3 method for class 'mimids'
bal.tab(
  x,
  stats,
  int = FALSE,
  poly = 1,
  distance = NULL,
  addl = NULL,
  data = NULL,
  continuous,
  binary,
  s.d.denom,
  thresholds = NULL,
  weights = NULL,
  cluster = NULL,
  pairwise = TRUE,
  s.weights = NULL,
  abs = FALSE,
  subset = NULL,
  quick = TRUE,
  ...
)

Arguments

x	a mimids or wimids object; the output of a call to MatchThem::matchthem() or MatchThem::weightthem().
stats	character; which statistic(s) should be reported. See stats for allowable options. For binary and multi-category treatments, "mean.diffs" (i.e., mean differences) is the default. For continuous treatments, "correlations" (i.e., treatment-covariate Pearson correlations) is the default. Multiple options are allowed.
int	logical or numeric; whether or not to include 2-way interactions of covariates included in covs and in addl. If numeric, will be passed to poly as well.
poly	numeric; the highest polynomial of each continuous covariate to display. For example, if 2, squares of each continuous covariate will be displayed (in addition to the covariate itself); if 3, squares and cubes of each continuous covariate will be displayed, etc. If 1, the default, only the base covariate will be displayed. If int is numeric, poly will take on the value of int.
distance	an optional formula or data frame containing distance values (e.g., propensity scores) or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the argument to data, if specified. The distance measure generated by matchthem() or weightthem() is automatically included and named "distance" or "prop.score", respectively.
addl	an optional formula or data frame containing additional covariates for which to present balance or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the arguments to the input object, covs, and data, if specified. For longitudinal treatments, can be a list of allowable arguments, one for each time point.
data	an optional data frame containing variables named in other arguments. For some input object types, this is required.
continuous	whether mean differences for continuous variables should be standardized ("std") or raw ("raw"). Default "std". Abbreviations allowed. This option can be set globally using set.cobalt.options().
binary	whether mean differences for binary variables (i.e., difference in proportion) should be standardized ("std") or raw ("raw"). Default "raw". Abbreviations allowed. This option can be set globally using set.cobalt.options().
s.d.denom	character; how the denominator for standardized mean differences should be calculated, if requested. See col_w_smd() for allowable options. Abbreviations allowed. If not specified, the defaults depend on the options specified in the original function calls; see bal.tab.matchit() and bal.tab.weightit() for details on the defaults.
thresholds	a named vector of balance thresholds, where the name corresponds to the statistic (i.e., in stats) that the threshold applies to. For example, to request thresholds on mean differences and variance ratios, one can set thresholds = c(m = .05, v = 2). Requesting a threshold automatically requests the display of that statistic. When specified, extra columns are inserted into the Balance table describing whether the requested balance statistics exceeded the threshold or not. Summary tables tallying the number of variables that exceeded and were within the threshold and displaying the variables with the greatest imbalance on that balance measure are added to the output.
weights	a vector, list, or data.frame containing weights for each unit, or a string containing the names of the weights variables in data, or an object with a get.w() method or a list thereof. The weights can be, e.g., inverse probability weights or matching weights resulting from a matching algorithm.
cluster	either a vector containing cluster membership for each unit or a string containing the name of the cluster membership variable in data or the input object. See class-bal.tab.cluster for details.
pairwise	whether balance should be computed for pairs of treatments or for each treatment against all groups combined. See bal.tab.multi() for details. This can also be used with a binary treatment to assess balance with respect to the full sample.
s.weights	Optional; either a vector containing sampling weights for each unit or a string containing the name of the sampling weight variable in data. These function like regular weights except that both the adjusted and unadjusted samples will be weighted according to these weights if weights are used.
abs	logical; whether displayed balance statistics should be in absolute value or not.
subset	a logical or numeric vector denoting whether each observation should be included or which observations should be included. If logical, it should have length equal to the number of units. NAs will be treated as FALSE. This can be used as an alternative to cluster to examine balance on subsets of the data.
quick	logical; if TRUE, will not compute any values that will not be displayed. Set to FALSE if computed values not displayed will be used later.
...	for some input types, other arguments that are required or allowed. Otherwise, further arguments to control display of output. See display options for details.

Details

bal.tab.mimids() and bal.tab.wimids() generate a list of balance summaries for the mimids or wimids object given.

Value

If clusters are not specified, an object of class "bal.tab.imp" containing balance summaries for each imputation and a summary of balance across imputations. See class-bal.tab.imp for details.

If clusters are specified, an object of class "bal.tab.imp.cluster" containing summaries between and across all clusters and imputations.

See Also

• bal.tab() for details of calculations

• bal.tab.matchit() and bal.tab.weightit()

Examples

library(mice)
library(MatchThem)

data("lalonde_mis", package = "cobalt")

#Imputing the missing data
imp <- mice(lalonde_mis, m = 5)

#Matching using within-imputation propensity scores
mt.out1 <- matchthem(treat ~ age + educ + race + 
                         married + nodegree + re74 + re75, 
                     data = imp, approach = "within")
bal.tab(mt.out1)

#Matching using across-imputation average propensity scores
mt.out2 <- matchthem(treat ~ age + educ + race + 
                         married + nodegree + re74 + re75, 
                     data = imp, approach = "across")

bal.tab(mt.out2)

#Weighting using within-imputation propensity scores
wt.out <- weightthem(treat ~ age + educ + race + 
                         married + nodegree + re74 + re75, 
                     data = imp, approach = "within",
                     estimand = "ATT")

bal.tab(wt.out)

---

Balance Statistics for optmatch Objects

Description

Generates balance statistics for output objects from optmatch.

Usage

## S3 method for class 'optmatch'
bal.tab(
  x,
  formula = NULL,
  data = NULL,
  treat = NULL,
  covs = NULL,
  estimand = NULL,
  stats,
  int = FALSE,
  poly = 1,
  distance = NULL,
  addl = NULL,
  continuous,
  binary,
  s.d.denom,
  thresholds = NULL,
  weights = NULL,
  cluster = NULL,
  imp = NULL,
  pairwise = TRUE,
  s.weights = NULL,
  abs = FALSE,
  subset = NULL,
  quick = TRUE,
  ...
)

Arguments

x	an optmatch object (the output of a call to optmatch::pairmatch() or optmatch::fullmatch()).
formula	a formula with the treatment variable as the response and the covariates for which balance is to be assessed as the predictors. All named variables must be in data. See Details.
data	a data frame containing variables named in formula, if supplied, and other arguments.
treat	a vector of treatment statuses. See Details.
covs	a data frame of covariate values for which to check balance. See Details.
estimand	character; whether the desired estimand is the "ATT", "ATC", or "ATE". Default is "ATT".
stats	character; which statistic(s) should be reported. See stats for allowable options. For binary and multi-category treatments, "mean.diffs" (i.e., mean differences) is the default. For continuous treatments, "correlations" (i.e., treatment-covariate Pearson correlations) is the default. Multiple options are allowed.
int	logical or numeric; whether or not to include 2-way interactions of covariates included in covs and in addl. If numeric, will be passed to poly as well.
poly	numeric; the highest polynomial of each continuous covariate to display. For example, if 2, squares of each continuous covariate will be displayed (in addition to the covariate itself); if 3, squares and cubes of each continuous covariate will be displayed, etc. If 1, the default, only the base covariate will be displayed. If int is numeric, poly will take on the value of int.
distance	an optional formula or data frame containing distance values (e.g., propensity scores) or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the argument to data, if specified. For longitudinal treatments, can be a list of allowable arguments, one for each time point.
addl	an optional formula or data frame containing additional covariates for which to present balance or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the arguments to the input object, covs, and data, if specified. For longitudinal treatments, can be a list of allowable arguments, one for each time point.
continuous	whether mean differences for continuous variables should be standardized ("std") or raw ("raw"). Default "std". Abbreviations allowed. This option can be set globally using set.cobalt.options().
binary	whether mean differences for binary variables (i.e., difference in proportion) should be standardized ("std") or raw ("raw"). Default "raw". Abbreviations allowed. This option can be set globally using set.cobalt.options().
s.d.denom	character; how the denominator for standardized mean differences should be calculated, if requested. See col_w_smd() for allowable options. Abbreviations allowed. If unspecified, bal.tab() will figure out which one is best based on the estimand, if given (for ATT, "treated"; for ATC, "control"; otherwise "pooled") and other clues if not.
thresholds	a named vector of balance thresholds, where the name corresponds to the statistic (i.e., in stats) that the threshold applies to. For example, to request thresholds on mean differences and variance ratios, one can set thresholds = c(m = .05, v = 2). Requesting a threshold automatically requests the display of that statistic. When specified, extra columns are inserted into the Balance table describing whether the requested balance statistics exceeded the threshold or not. Summary tables tallying the number of variables that exceeded and were within the threshold and displaying the variables with the greatest imbalance on that balance measure are added to the output.
weights	a vector, list, or data.frame containing weights for each unit, or a string containing the names of the weights variables in data, or an object with a get.w() method or a list thereof. The weights can be, e.g., inverse probability weights or matching weights resulting from a matching algorithm.
cluster	either a vector containing cluster membership for each unit or a string containing the name of the cluster membership variable in data or the input object. See class-bal.tab.cluster for details.
imp	either a vector containing imputation indices for each unit or a string containing the name of the imputation index variable in data or the input object. See class-bal.tab.imp for details. Not necessary if data is a mids object.
pairwise	whether balance should be computed for pairs of treatments or for each treatment against all groups combined. See bal.tab.multi() for details. This can also be used with a binary treatment to assess balance with respect to the full sample.
s.weights	Optional; either a vector containing sampling weights for each unit or a string containing the name of the sampling weight variable in data. These function like regular weights except that both the adjusted and unadjusted samples will be weighted according to these weights if weights are used.
abs	logical; whether displayed balance statistics should be in absolute value or not.
subset	a logical or numeric vector denoting whether each observation should be included or which observations should be included. If logical, it should have length equal to the number of units. NAs will be treated as FALSE. This can be used as an alternative to cluster to examine balance on subsets of the data.
quick	logical; if TRUE, will not compute any values that will not be displayed. Set to FALSE if computed values not displayed will be used later.
...	for some input types, other arguments that are required or allowed. Otherwise, further arguments to control display of output. See display options for details.

Details

bal.tab() generates a list of balance summaries for the object given. The input to bal.tab.optmatch() must include either both formula and data or just covs (treat is not necessary).

Value

If clusters and imputations are not specified, an object of class "bal.tab" containing balance summaries for the given object. See bal.tab() for details.

If clusters are specified, an object of class "bal.tab.cluster" containing balance summaries within each cluster and a summary of balance across clusters. See class-bal.tab.cluster for details.

See Also

bal.tab() for details of calculations.

Examples

data("lalonde", package = "cobalt")

lalonde$prop.score <- glm(treat ~ age + educ + race + 
                              married + nodegree + re74 + re75, 
                          data = lalonde, family = binomial)$fitted.values
pm <- optmatch::pairmatch(treat ~ prop.score, data = lalonde)

## Using formula and data; LHS of formula not required
bal.tab(pm, formula = ~ age + educ + race +
            married + nodegree + re74 + re75,
        data = lalonde)

## Using covs
covs <- subset(lalonde, select = -c(re78, treat))
bal.tab(pm, covs = covs)

---

Balance Statistics for twang Objects

Description

Generates balance statistics for ps, mnps, and iptw objects from twang and for ps.cont objects from twangContinuous.

Usage

## S3 method for class 'ps'
bal.tab(
  x,
  stop.method,
  stats,
  int = FALSE,
  poly = 1,
  distance = NULL,
  addl = NULL,
  data = NULL,
  continuous,
  binary,
  s.d.denom,
  thresholds = NULL,
  weights = NULL,
  cluster = NULL,
  imp = NULL,
  pairwise = TRUE,
  s.weights = NULL,
  abs = FALSE,
  subset = NULL,
  quick = TRUE,
  ...
)

Arguments

x	a ps, mnps, iptw, or ps.cont object; the output of a call to twang::ps(), twang::mnps(), twang::iptw() or twangContinuous::ps.cont().
stop.method	a string containing the names of the stopping methods used in the original call to ps(), mnps(), or iptw(). Examples include "es.max" or "ks.mean" for ps and mnps objects. bal.tab() will assess balance for the weights created by those stopping methods. The names can be abbreviated as long as the abbreviations are specific enough. If no stopping methods are provided, bal.tab() will default to displaying balance for all available stopping methods. Ignored for ps.cont objects.
stats	character; which statistic(s) should be reported. See stats for allowable options. For binary and multi-category treatments, "mean.diffs" (i.e., mean differences) is the default. For continuous treatments, "correlations" (i.e., treatment-covariate Pearson correlations) is the default. Multiple options are allowed.
int	logical or numeric; whether or not to include 2-way interactions of covariates included in covs and in addl. If numeric, will be passed to poly as well.
poly	numeric; the highest polynomial of each continuous covariate to display. For example, if 2, squares of each continuous covariate will be displayed (in addition to the covariate itself); if 3, squares and cubes of each continuous covariate will be displayed, etc. If 1, the default, only the base covariate will be displayed. If int is numeric, poly will take on the value of int.
distance	an optional formula or data frame containing distance values (e.g., propensity scores) or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the argument to data, if specified. The propensity scores generated by ps() and iptw() (but not mnps() or ps.cont()) are automatically included and named "prop.score.{stop.method}".
addl	an optional formula or data frame containing additional covariates for which to present balance or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the arguments to the input object, covs, and data, if specified. For longitudinal treatments, can be a list of allowable arguments, one for each time point.
data	an optional data frame containing variables named in other arguments. For some input object types, this is required.
continuous	whether mean differences for continuous variables should be standardized ("std") or raw ("raw"). Default "std". Abbreviations allowed. This option can be set globally using set.cobalt.options().
binary	whether mean differences for binary variables (i.e., difference in proportion) should be standardized ("std") or raw ("raw"). Default "raw". Abbreviations allowed. This option can be set globally using set.cobalt.options().
s.d.denom	character; how the denominator for standardized mean differences should be calculated, if requested. See col_w_smd() for allowable options. Abbreviations allowed. If not specified, for ps objects, bal.tab() will use "treated" if the estimand of the call to ps() is the ATT and "pooled" if the estimand is the ATE; for mnps objects, bal.tab() will use "treated" if treatATT was specified in the original call to mnps and "pooled" otherwise. Use "all" to get the same values computed by bal.table() in twang.
thresholds	a named vector of balance thresholds, where the name corresponds to the statistic (i.e., in stats) that the threshold applies to. For example, to request thresholds on mean differences and variance ratios, one can set thresholds = c(m = .05, v = 2). Requesting a threshold automatically requests the display of that statistic. When specified, extra columns are inserted into the Balance table describing whether the requested balance statistics exceeded the threshold or not. Summary tables tallying the number of variables that exceeded and were within the threshold and displaying the variables with the greatest imbalance on that balance measure are added to the output.
weights	a vector, list, or data.frame containing weights for each unit, or a string containing the names of the weights variables in data, or an object with a get.w() method or a list thereof. The weights can be, e.g., inverse probability weights or matching weights resulting from a matching algorithm.
cluster	either a vector containing cluster membership for each unit or a string containing the name of the cluster membership variable in data or the input object. See class-bal.tab.cluster for details.
imp	either a vector containing imputation indices for each unit or a string containing the name of the imputation index variable in data or the input object. See class-bal.tab.imp for details. Not necessary if data is a mids object.
pairwise	whether balance should be computed for pairs of treatments or for each treatment against all groups combined. See bal.tab.multi() for details. This can also be used with a binary treatment to assess balance with respect to the full sample.
s.weights	Optional; either a vector containing sampling weights for each unit or a string containing the name of the sampling weight variable in data. These function like regular weights except that both the adjusted and unadjusted samples will be weighted according to these weights if weights are used. If sampw was supplied in the call to ps(), mnps(), iptw(), or ps.cont(), they will automatically be supplied to s.weights and do not need be specified again (though there is no harm if they are).
abs	logical; whether displayed balance statistics should be in absolute value or not.
subset	a logical or numeric vector denoting whether each observation should be included or which observations should be included. If logical, it should have length equal to the number of units. NAs will be treated as FALSE. This can be used as an alternative to cluster to examine balance on subsets of the data.
quick	logical; if TRUE, will not compute any values that will not be displayed. Set to FALSE if computed values not displayed will be used later.
...	for some input types, other arguments that are required or allowed. Otherwise, further arguments to control display of output. See display options for details.

Details

bal.tab.ps() generates a list of balance summaries for the input object given, and functions similarly to twang::bal.table(). The variances used in the denominator of the standardized mean differences computed in twang::bal.table() are weighted and computed using survey::svyvar() and are unweighted here (except when s.weights are specified, in which case col_w_sd() is used). twang also uses "all" as the default s.d.denom when the estimand is the ATE; the default here is "pooled". For these reasons, results may differ slightly between the two packages.

Value

For binary or continuous point treatments, if clusters are not specified, an object of class "bal.tab" containing balance summaries for the ps object. See bal.tab() for details.

If clusters are specified, an object of class "bal.tab.cluster" containing balance summaries within each cluster and a summary of balance across clusters. See class-bal.tab.cluster for details.

If mnps() is used with multi-category treatments, an object of class "bal.tab.multi" containing balance summaries for each pairwise treatment comparison and a summary of balance across pairwise comparisons. See bal.tab.multi() for details.

See Also

• bal.tab() for details of calculations.

• class-bal.tab.cluster for more information on clustered data.

• bal.tab.multi() for more information on multi-category treatments.

• class-bal.tab.msm for more information on longitudinal treatments.

Examples

library(twang); data("lalonde", package = "cobalt")

## Using ps() for generalized boosted modeling
ps.out <- ps(treat ~ age + educ + married + race +
                 nodegree + re74 + re75, data = lalonde, 
             stop.method = c("ks.mean", "es.mean"), 
             estimand = "ATT", verbose = FALSE)

bal.tab(ps.out, stop.method = "ks.mean", un = TRUE, 
        m.threshold = .1, disp.ks = TRUE)

---

Balance Statistics for sbw Objects

Description

Generates balance statistics for sbwcau objects from sbw.

Usage

## S3 method for class 'sbwcau'
bal.tab(
  x,
  stats,
  int = FALSE,
  poly = 1,
  distance = NULL,
  addl = NULL,
  data = NULL,
  continuous,
  binary,
  s.d.denom,
  thresholds = NULL,
  weights = NULL,
  cluster = NULL,
  imp = NULL,
  pairwise = TRUE,
  s.weights = NULL,
  abs = FALSE,
  subset = NULL,
  quick = TRUE,
  ...
)

Arguments

x	an sbwcau object; the output of a call to sbw::sbw().
stats	character; which statistic(s) should be reported. See stats for allowable options. For binary and multi-category treatments, "mean.diffs" (i.e., mean differences) is the default. For continuous treatments, "correlations" (i.e., treatment-covariate Pearson correlations) is the default. Multiple options are allowed.
int	logical or numeric; whether or not to include 2-way interactions of covariates included in covs and in addl. If numeric, will be passed to poly as well.
poly	numeric; the highest polynomial of each continuous covariate to display. For example, if 2, squares of each continuous covariate will be displayed (in addition to the covariate itself); if 3, squares and cubes of each continuous covariate will be displayed, etc. If 1, the default, only the base covariate will be displayed. If int is numeric, poly will take on the value of int.
distance	an optional formula or data frame containing distance values (e.g., propensity scores) or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the argument to data, if specified. For longitudinal treatments, can be a list of allowable arguments, one for each time point.
addl	an optional formula or data frame containing additional covariates for which to present balance or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the arguments to the input object, covs, and data, if specified. For longitudinal treatments, can be a list of allowable arguments, one for each time point.
data	an optional data frame containing variables named in other arguments. For some input object types, this is required.
continuous	whether mean differences for continuous variables should be standardized ("std") or raw ("raw"). Default "std". Abbreviations allowed. This option can be set globally using set.cobalt.options().
binary	whether mean differences for binary variables (i.e., difference in proportion) should be standardized ("std") or raw ("raw"). Default "raw". Abbreviations allowed. This option can be set globally using set.cobalt.options().
s.d.denom	character; how the denominator for standardized mean differences should be calculated, if requested. See col_w_smd() for allowable options. Abbreviations allowed. If not specified, bal.tab() will figure out which one is best based on the par component of the sbwcau object: if "att", "treated"; if "atc", "control"; otherwise "pooled".
thresholds	a named vector of balance thresholds, where the name corresponds to the statistic (i.e., in stats) that the threshold applies to. For example, to request thresholds on mean differences and variance ratios, one can set thresholds = c(m = .05, v = 2). Requesting a threshold automatically requests the display of that statistic. When specified, extra columns are inserted into the Balance table describing whether the requested balance statistics exceeded the threshold or not. Summary tables tallying the number of variables that exceeded and were within the threshold and displaying the variables with the greatest imbalance on that balance measure are added to the output.
weights	a vector, list, or data.frame containing weights for each unit, or a string containing the names of the weights variables in data, or an object with a get.w() method or a list thereof. The weights can be, e.g., inverse probability weights or matching weights resulting from a matching algorithm.
cluster	either a vector containing cluster membership for each unit or a string containing the name of the cluster membership variable in data or the input object. See class-bal.tab.cluster for details.
imp	either a vector containing imputation indices for each unit or a string containing the name of the imputation index variable in data or the input object. See class-bal.tab.imp for details. Not necessary if data is a mids object.
pairwise	whether balance should be computed for pairs of treatments or for each treatment against all groups combined. See bal.tab.multi() for details. This can also be used with a binary treatment to assess balance with respect to the full sample.
s.weights	Optional; either a vector containing sampling weights for each unit or a string containing the name of the sampling weight variable in data. These function like regular weights except that both the adjusted and unadjusted samples will be weighted according to these weights if weights are used.
abs	logical; whether displayed balance statistics should be in absolute value or not.
subset	a logical or numeric vector denoting whether each observation should be included or which observations should be included. If logical, it should have length equal to the number of units. NAs will be treated as FALSE. This can be used as an alternative to cluster to examine balance on subsets of the data.
quick	logical; if TRUE, will not compute any values that will not be displayed. Set to FALSE if computed values not displayed will be used later.
...	for some input types, other arguments that are required or allowed. Otherwise, further arguments to control display of output. See display options for details.

Details

bal.tab.sbwcau() generates a list of balance summaries for the sbwcau object given, and functions similarly to sbw::summarize().

Value

If clusters are not specified, an object of class "bal.tab" containing balance summaries for the sbwcau object. See bal.tab() for details.

If clusters are specified, an object of class "bal.tab.cluster" containing balance summaries within each cluster and a summary of balance across clusters. See class-bal.tab.cluster for details.

See Also

• bal.tab() for details of calculations.

Examples

library(sbw); data("lalonde", package = "cobalt")

## Stable balancing weights for the ATT
sbw.out <- sbw(splitfactor(lalonde, drop.first = "if2"),
               ind = "treat",
               bal = list(bal_cov = c("age", "educ", "race_black", 
                                      "race_hispan", "race_white", 
                                      "married", "nodegree", 
                                      "re74", "re75"),
                          bal_alg = FALSE, 
                          bal_tol = .001),
               par = list(par_est = "att"))

bal.tab(sbw.out, un = TRUE, poly = 2)

---

Balance Statistics for Longitudinal Datasets

Description

Generates balance statistics for data coming from a longitudinal treatment scenario. The primary input is in the form of a list of formulas or data.frames contain the covariates at each time point. bal.tab() automatically classifies this list as either a data.frame.list or formula.list, respectively.

Usage

## S3 method for class 'formula.list'
bal.tab(
  x,
  stats,
  int = FALSE,
  poly = 1,
  distance = NULL,
  addl = NULL,
  data = NULL,
  continuous,
  binary,
  s.d.denom,
  thresholds = NULL,
  weights = NULL,
  cluster = NULL,
  imp = NULL,
  pairwise = TRUE,
  s.weights = NULL,
  abs = FALSE,
  subset = NULL,
  quick = TRUE,
  ...
)

## S3 method for class 'data.frame.list'
bal.tab(
  x,
  treat.list,
  stats,
  int = FALSE,
  poly = 1,
  distance = NULL,
  addl = NULL,
  data = NULL,
  continuous,
  binary,
  s.d.denom,
  thresholds = NULL,
  weights = NULL,
  cluster = NULL,
  imp = NULL,
  pairwise = TRUE,
  s.weights = NULL,
  abs = FALSE,
  subset = NULL,
  quick = TRUE,
  ...
)

Arguments

x	either a list of data frames containing all the covariates to be assessed at each time point or a list of formulas with the treatment for each time period on the left and the covariates for which balance is to be displayed on the right. Covariates to be assessed at multiple points must be included in the entries for each time point. Data must be in the "wide" format, with one row per unit. If a formula list is supplied, an argument to data is required unless all objects in the formulas exist in the environment.
stats	character; which statistic(s) should be reported. See stats for allowable options. For binary and multi-category treatments, "mean.diffs" (i.e., mean differences) is the default. For continuous treatments, "correlations" (i.e., treatment-covariate Pearson correlations) is the default. Multiple options are allowed.
int	logical or numeric; whether or not to include 2-way interactions of covariates included in covs and in addl. If numeric, will be passed to poly as well.
poly	numeric; the highest polynomial of each continuous covariate to display. For example, if 2, squares of each continuous covariate will be displayed (in addition to the covariate itself); if 3, squares and cubes of each continuous covariate will be displayed, etc. If 1, the default, only the base covariate will be displayed. If int is numeric, poly will take on the value of int.
distance	an optional formula or data frame containing distance values (e.g., propensity scores) or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the argument to data, if specified. For longitudinal treatments, can be a list of allowable arguments, one for each time point.
addl	an optional formula or data frame containing additional covariates for which to present balance or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the arguments to the input object, covs, and data, if specified. For longitudinal treatments, can be a list of allowable arguments, one for each time point.
data	an optional data frame containing variables named in other arguments. For some input object types, this is required.
continuous	whether mean differences for continuous variables should be standardized ("std") or raw ("raw"). Default "std". Abbreviations allowed. This option can be set globally using set.cobalt.options().
binary	whether mean differences for binary variables (i.e., difference in proportion) should be standardized ("std") or raw ("raw"). Default "raw". Abbreviations allowed. This option can be set globally using set.cobalt.options().
s.d.denom	character; how the denominator for standardized mean differences should be calculated, if requested. See col_w_smd() for allowable options. Abbreviations allowed. It is recommended not to set this argument for longitudinal treatments.
thresholds	a named vector of balance thresholds, where the name corresponds to the statistic (i.e., in stats) that the threshold applies to. For example, to request thresholds on mean differences and variance ratios, one can set thresholds = c(m = .05, v = 2). Requesting a threshold automatically requests the display of that statistic. When specified, extra columns are inserted into the Balance table describing whether the requested balance statistics exceeded the threshold or not. Summary tables tallying the number of variables that exceeded and were within the threshold and displaying the variables with the greatest imbalance on that balance measure are added to the output.
weights	a vector, list, or data.frame containing weights for each unit, or a string containing the names of the weights variables in data, or an object with a get.w() method or a list thereof. The weights can be, e.g., inverse probability weights or matching weights resulting from a matching algorithm.
cluster	either a vector containing cluster membership for each unit or a string containing the name of the cluster membership variable in data or the input object. See class-bal.tab.cluster for details.
imp	either a vector containing imputation indices for each unit or a string containing the name of the imputation index variable in data or the input object. See class-bal.tab.imp for details. Not necessary if data is a mids object.
pairwise	whether balance should be computed for pairs of treatments or for each treatment against all groups combined. See bal.tab.multi() for details. This can also be used with a binary treatment to assess balance with respect to the full sample.
s.weights	Optional; either a vector containing sampling weights for each unit or a string containing the name of the sampling weight variable in data. These function like regular weights except that both the adjusted and unadjusted samples will be weighted according to these weights if weights are used.
abs	logical; whether displayed balance statistics should be in absolute value or not.
subset	a logical or numeric vector denoting whether each observation should be included or which observations should be included. If logical, it should have length equal to the number of units. NAs will be treated as FALSE. This can be used as an alternative to cluster to examine balance on subsets of the data.
quick	logical; if TRUE, will not compute any values that will not be displayed. Set to FALSE if computed values not displayed will be used later.
...	for some input types, other arguments that are required or allowed. Otherwise, further arguments to control display of output. See display options for details.
treat.list	treatment status for each unit at each time point. This can be specified as a list or data frame of vectors, each of which contains the treatment status of each individual at each time point, or a list or vector of the names of variables in data that contain treatment at each time point. Required for the data.frame.list method.

Details

bal.tab.formula.list() and bal.tab.data.frame.list() generate a list of balance summaries for each time point based on the treatments and covariates provided. All data must be in the "wide" format, with exactly one row per unit and columns representing variables at different time points. See the WeightIt::weightitMSM() documentation for an example of how to transform long data into wide data using reshape().

Multiple sets of weights can be supplied simultaneously by including entering a data frame or a character vector containing the names of weight variables found in data or a list thereof. When only one set of weights is supplied, the output for the adjusted group will simply be called "Adj", but otherwise will be named after each corresponding set of weights. Specifying multiple sets of weights will also add components to other outputs of bal.tab().

Value

An object of class bal.tab.msm containing balance summaries at each time point. Each balance summary is its own bal.tab object. See class-bal.tab.msm for more details.

See bal.tab() base methods() for more detailed information on the value of the bal.tab objects produced for each time point.

See Also

• bal.tab() for details of calculations.

• class-bal.tab.msm for output and related options.

• class-bal.tab.cluster for more information on clustered data.

• class-bal.tab.imp for more information on multiply imputed data.

• bal.tab.multi() for more information on multi-category treatments.

Examples

data("msmdata", package = "WeightIt")

## Estimating longitudinal propensity scores and weights
ps1 <- glm(A_1 ~ X1_0 + X2_0,
           data = msmdata, 
           family = "binomial")$fitted.values
w1 <- ifelse(msmdata$A_1 == 1, 1 / ps1, 1 / (1 - ps1))

ps2 <- glm(A_2 ~ X1_1 + X2_1 +
               A_1 + X1_0 + X2_0,
           data = msmdata, 
           family = "binomial")$fitted.values
w2 <- ifelse(msmdata$A_2 == 1, 1 / ps2, 1 / (1 - ps2))

ps3 <- glm(A_3 ~ X1_2 + X2_2 +
               A_2 + X1_1 + X2_1 +
               A_1 + X1_0 + X2_0,
           data = msmdata, 
           family = "binomial")$fitted.values
w3 <- ifelse(msmdata$A_3 == 1, 1 / ps3, 1 / (1 - ps3))

w <- w1 * w2 * w3

# Formula interface plus addl:
bal.tab(list(A_1 ~ X1_0 + X2_0,
             A_2 ~ X1_1 + X2_1 +
                 A_1 + X1_0 + X2_0,
             A_3 ~ X1_2 + X2_2 +
                 A_2 + X1_1 + X2_1 +
                 A_1 + X1_0 + X2_0),
        data = msmdata, 
        weights = w,
        distance = list(~ps1, ~ps2, ~ps3),
        addl = ~X1_0 * X2_0,
        un = TRUE)

# data frame interface:
bal.tab(list(msmdata[c("X1_0", "X2_0")],
             msmdata[c("X1_1", "X2_1", "A_1", "X1_0", "X2_0")],
             msmdata[c("X1_2", "X2_2", "A_2", "X1_1", "X2_1",
                       "A_1", "X1_0", "X2_0")]),
        treat.list = msmdata[c("A_1", "A_2", "A_3")], 
        weights = w,
        distance = list(~ps1, ~ps2, ~ps3),
        un = TRUE)

---

Balance Statistics for WeightIt Objects

Description

Generates balance statistics for weightit and weightitMSM objects from WeightIt.

Usage

## S3 method for class 'weightit'
bal.tab(
  x,
  stats,
  int = FALSE,
  poly = 1,
  distance = NULL,
  addl = NULL,
  data = NULL,
  continuous,
  binary,
  s.d.denom,
  thresholds = NULL,
  weights = NULL,
  cluster = NULL,
  imp = NULL,
  pairwise = TRUE,
  s.weights = NULL,
  abs = FALSE,
  subset = NULL,
  quick = TRUE,
  ...
)

Arguments

x	a weightit or weightitMSM object; the output of a call to WeightIt::weightit() or WeightIt::weightitMSM().
stats	character; which statistic(s) should be reported. See stats for allowable options. For binary and multi-category treatments, "mean.diffs" (i.e., mean differences) is the default. For continuous treatments, "correlations" (i.e., treatment-covariate Pearson correlations) is the default. Multiple options are allowed.
int	logical or numeric; whether or not to include 2-way interactions of covariates included in covs and in addl. If numeric, will be passed to poly as well.
poly	numeric; the highest polynomial of each continuous covariate to display. For example, if 2, squares of each continuous covariate will be displayed (in addition to the covariate itself); if 3, squares and cubes of each continuous covariate will be displayed, etc. If 1, the default, only the base covariate will be displayed. If int is numeric, poly will take on the value of int.
distance	an optional formula or data frame containing distance values (e.g., propensity scores) or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the argument to data, if specified. Propensity scores generated by weightit() and weightitMSM() are automatically included and named "prop.score".
addl	an optional formula or data frame containing additional covariates for which to present balance or a character vector containing their names. If a formula or variable names are specified, bal.tab() will look in the arguments to the input object, covs, and data, if specified. For longitudinal treatments, can be a list of allowable arguments, one for each time point.
data	an optional data frame containing variables named in other arguments. For some input object types, this is required.
continuous	whether mean differences for continuous variables should be standardized ("std") or raw ("raw"). Default "std". Abbreviations allowed. This option can be set globally using set.cobalt.options().
binary	whether mean differences for binary variables (i.e., difference in proportion) should be standardized ("std") or raw ("raw"). Default "raw". Abbreviations allowed. This option can be set globally using set.cobalt.options().
s.d.denom	character; how the denominator for standardized mean differences should be calculated, if requested. See col_w_smd() for allowable options. Abbreviations allowed. If not specified, bal.tab() will figure out which one is best based on the estimand of the weightit object: if ATT, "treated"; if ATC, "control"; otherwise "pooled".
thresholds	a named vector of balance thresholds, where the name corresponds to the statistic (i.e., in stats) that the threshold applies to. For example, to request thresholds on mean differences and variance ratios, one can set thresholds = c(m = .05, v = 2). Requesting a threshold automatically requests the display of that statistic. When specified, extra columns are inserted into the Balance table describing whether the requested balance statistics exceeded the threshold or not. Summary tables tallying the number of variables that exceeded and were within the threshold and displaying the variables with the greatest imbalance on that balance measure are added to the output.
weights	a vector, list, or data.frame containing weights for each unit, or a string containing the names of the weights variables in data, or an object with a get.w() method or a list thereof. The weights can be, e.g., inverse probability weights or matching weights resulting from a matching algorithm.
cluster	either a vector containing cluster membership for each unit or a string containing the name of the cluster membership variable in data or the input object. See class-bal.tab.cluster for details.
imp	either a vector containing imputation indices for each unit or a string containing the name of the imputation index variable in data or the input object. See class-bal.tab.imp for details. Not necessary if data is a mids object.
pairwise	whether balance should be computed for pairs of treatments or for each treatment against all groups combined. See bal.tab.multi() for details. This can also be used with a binary treatment to assess balance with respect to the full sample.
s.weights	Optional; either a vector containing sampling weights for each unit or a string containing the name of the sampling weight variable in data. These function like regular weights except that both the adjusted and unadjusted samples will be weighted according to these weights if weights are used. If s.weights was supplied in the call to weightit() or weightitMSM(), they will automatically be included and do not need be specified again (though there is no harm if they are).
abs	logical; whether displayed balance statistics should be in absolute value or not.
subset	a logical or numeric vector denoting whether each observation should be included or which observations should be included. If logical, it should have length equal to the number of units. NAs will be treated as FALSE. This can be used as an alternative to cluster to examine balance on subsets of the data.
quick	logical; if TRUE, will not compute any values that will not be displayed. Set to FALSE if computed values not displayed will be used later.
...	for some input types, other arguments that are required or allowed. Otherwise, further arguments to control display of output. See display options for details.

Details

bal.tab.weightit() generates a list of balance summaries for the weightit object given.

Value

For point treatments, if clusters and imputations are not specified, an object of class "bal.tab" containing balance summaries for the weightit object. See bal.tab() for details.

If imputations are specified, an object of class "bal.tab.imp" containing balance summaries for each imputation and a summary of balance across imputations. See class-bal.tab.imp for details.

If weightit() is used with multi-category treatments, an object of class "bal.tab.multi" containing balance summaries for each pairwise treatment comparison. See bal.tab.multi() for details.

If weightitMSM() is used for longitudinal treatments, an object of class "bal.tab.msm" containing balance summaries for each time period. See class-bal.tab.msm for details.

If clusters are specified, an object of class "bal.tab.cluster" containing balance summaries within each cluster and a summary of balance across clusters. See class-bal.tab.cluster for details.

See Also

• bal.tab() for details of calculations.

Examples

library(WeightIt)
data("lalonde", package = "cobalt")

## Basic propensity score weighting
w.out1 <- weightit(treat ~ age + educ + race + 
                       married + nodegree + re74 + re75, 
                   data = lalonde, method = "glm")
bal.tab(w.out1, un = TRUE, m.threshold = .1, 
        v.threshold = 2)

## Weighting with a multi-category treatment
w.out2 <- weightit(race ~ age + educ + married + 
                       nodegree + re74 + re75, 
                   data = lalonde, method = "glm",
                   estimand = "ATE")
bal.tab(w.out2, un = TRUE)
bal.tab(w.out2, un = TRUE, pairwise = FALSE)

## IPW for longitudinal treatments
data("msmdata", package = "WeightIt")

wmsm.out <- weightitMSM(list(A_1 ~ X1_0 + X2_0,
                        A_2 ~ X1_1 + X2_1 +
                            A_1 + X1_0 + X2_0,
                        A_3 ~ X1_2 + X2_2 +
                            A_2 + X1_1 + X2_1 +
                            A_1 + X1_0 + X2_0),
                   data = msmdata,
                   method = "glm")
bal.tab(wmsm.out)

---

Balance Statistics in bal.tab and love.plot

Description

bal.tab() and love.plot() display balance statistics for the included covariates. The stats argument in each of these functions controls which balance statistics are to be displayed. The argument to stats should be a character vector with the names of the desired balance statistics.

This page describes all of the available balance statistics and how to request them. Abbreviations are allowed, so you can use the first few letters of each balance statistics to request it instead of typing out its whole name. That convention is used throughout the documentation. For example, to request mean differences and variance ratios in bal.tab() or love.plot(), you could include stats = c("m", "v"). In addition, the thresholds argument uses the same naming conventions and can be used to request balance thresholds on each statistic. For example, to request a balance threshold of .1 for mean differences, you could include thresholds = c(m = .1).

Below, each allowable entry to stats and thresholds are described, along with other details or option that accompany them.

Binary/Multi-Category Treatments

"mean.diffs"

Mean differences as computed by col_w_smd(). Can be abbreviated as "m". Setting the arguments continuous and binary to either "std" or "raw" will determine whether standardized mean differences or raw mean differences are calculated for continuous and categorical variables, respectively. When standardized mean differences are requested, the s.d.denom argument controls how the standardization occurs. When abs = TRUE, negative values become positive. Mean differences are requested by default when no entry to stats is provided.

"variance.ratios"

Variance ratios as computed by col_w_vr(). Can be abbreviated as "v". Will not be computed for binary variables. When abs = TRUE, values less than 1 will have their inverse taken. When used with love.plot, the x-axis scaled will be logged so that, e.g., .5 is as far away from 1 as 2 is.

"ks.statistics"

Kolmogorov-Smirnov (KS) statistics as computed by col_w_ks().

"ovl.coefficients"

Overlapping (OVL) statistics as computed by col_w_ovl(). Can be abbreviated as "ovl". Additional arguments passed to col_w_ovl(), such as integrate or bw, can be supplied to bal.tab() or love.plot().

Continuous Treatments

"correlations"

Pearson correlations as computed by col_w_cov(). Can be abbreviated as "cor". Setting the arguments continuous and binary to either "std" or "raw" will determine whether correlations or covariances are calculated for continuous and categorical variables, respectively (they are both "std" by default). When correlations are requested, the s.d.denom argument controls how the standardization occurs. When abs = TRUE, negative values become positive. Pearson correlations are requested by default when no entry to stats is provided.

"spearman.correlations"

Spearman correlations as computed by col_w_cov(). Can be abbreviated as "sp". All arguments are the same as those for "correlations". When abs = TRUE, negative values become positive.

"mean.diffs.target"

Mean differences computed between the weighted and unweighted sample to ensure the weighted sample is representative of the original population. Can be abbreviated as "m". Setting the arguments continuous and binary to either "std" or "raw" will determine whether standardized mean differences or raw mean differences are calculated for continuous and categorical variables, respectively. The standardization factor will be computed in the unweighted sample. When abs = TRUE, negative values become positive. This statistic is only computed for the adjusted samples.

"ks.statistics.target"

KS-statistics computed between the weighted and unweighted sample to ensure the weighted sample is representative of the original population. Can be abbreviated as "ks". This statistic is only computed for the adjusted samples.

If a statistic is requested in thresholds, it will automatically be placed in stats. For example, bal.tab(..., stats = "m", thresholds = c(v = 2)) will display both mean differences and variance ratios, and the variance ratios will have a balance threshold set to 2.

Examples

data(lalonde)

#Binary treatments
bal.tab(treat ~ age + educ + married + re74, data = lalonde,
        stats = c("m", "v", "ks"))
love.plot(treat ~ age + educ + married + re74, data = lalonde,
          stats = c("m", "v", "ks"), binary = "std",
          thresholds = c(m = .1, v = 2))

#Continuous treatments
bal.tab(re75 ~ age + educ + married + re74, data = lalonde,
        stats = c("cor", "sp"))
love.plot(re75 ~ age + educ + married + re74, data = lalonde,
          thresholds = c(cor = .1, sp = .1))

---

Compute Balance and Summary Statistics for Covariates

Description

These functions quickly compute balance statistics for the given covariates. These functions are used in bal.tab(), but they are available for use in programming without having to call bal.tab() to get them.

• col_w_mean() computes the (weighted) means for a set of covariates and weights and is essentially a weighted version of colMeans().

• col_w_sd() computes the (weighted) standard deviations for a set of covariates and weights.

• col_w_smd() computes the (weighted) (absolute) (standardized) difference in means for a set of covariates, a binary treatment, and weights.

• col_w_vr() computes the (weighted) variance ratio for a set of covariates, a binary treatment, and weights.

• col_w_ks() computes the (weighted) Kolmogorov-Smirnov (KS) statistic for a set of covariates, a binary treatment, and weights.

• col_w_ovl() computes the complement of the (weighted) overlapping coefficient compliment for a set of covariates, a binary treatment, and weights (based on Franklin et al, 2014).

• col_w_cov() and col_w_corr() compute the (weighted) (absolute) treatment-covariate covariance or correlation for a set of covariates, a continuous treatment, and weights.

Usage

col_w_mean(
  mat,
  weights = NULL,
  s.weights = NULL,
  subset = NULL,
  na.rm = TRUE,
  ...
)

col_w_sd(
  mat,
  weights = NULL,
  s.weights = NULL,
  bin.vars,
  subset = NULL,
  na.rm = TRUE,
  ...
)

col_w_smd(
  mat,
  treat,
  weights = NULL,
  std = TRUE,
  s.d.denom = "pooled",
  abs = FALSE,
  s.weights = NULL,
  bin.vars,
  subset = NULL,
  weighted.weights = weights,
  na.rm = TRUE,
  ...
)

col_w_vr(
  mat,
  treat,
  weights = NULL,
  abs = FALSE,
  s.weights = NULL,
  bin.vars,
  subset = NULL,
  na.rm = TRUE,
  ...
)

col_w_ks(
  mat,
  treat,
  weights = NULL,
  s.weights = NULL,
  bin.vars,
  subset = NULL,
  na.rm = TRUE,
  ...
)

col_w_ovl(
  mat,
  treat,
  weights = NULL,
  s.weights = NULL,
  bin.vars,
  integrate = FALSE,
  subset = NULL,
  na.rm = TRUE,
  ...
)

col_w_cov(
  mat,
  treat,
  weights = NULL,
  type = "pearson",
  std = FALSE,
  s.d.denom = "all",
  abs = FALSE,
  s.weights = NULL,
  bin.vars,
  subset = NULL,
  weighted.weights = weights,
  na.rm = TRUE,
  ...
)

col_w_corr(
  mat,
  treat,
  weights = NULL,
  type = "pearson",
  s.d.denom = "all",
  abs = FALSE,
  s.weights = NULL,
  bin.vars,
  subset = NULL,
  weighted.weights = weights,
  na.rm = TRUE,
  ...
)

Arguments

mat	a numeric matrix or a data frame containing the covariates for which the statistic is to be computed. If a data frame, splitfactor() with drop.first = "if2" will be called if any character or factor variables are present. This can slow down the function, so it's generally best to supply a numeric matrix. If a numeric vector is supplied, it will be converted to a 1-column matrix first.
weights	numeric; an optional set of weights used to compute the weighted statistics. If sampling weights are supplied through s.weights, the weights should not incorporate these weights, as weights and s.weights will be multiplied together prior to computing the weighted statistics.
s.weights	numeric; an optional set of sampling weights used to compute the weighted statistics. If weights are supplied through weights, weights and s.weights will be multiplied together prior to computing the weighted statistics. Some functions use s.weights in a particular way; for others, supplying weights and s.weights is equivalent to supplying their product to either weights or s.weights. See Details.
subset	a logical vector with length equal to the number of rows of mat used to subset the data. See Details for notes on its use with col_w_smd(), col_w_cov(), and col_w_corr().
na.rm	logical; whether NAs should be ignored or not. If FALSE, any variable with any NAs will have its corresponding statistic returned as NA. If TRUE, any variable with any NAs will have its corresponding statistic computed as if the missing value were not there.
...	for all functions, additional arguments supplied to splitfactor() when mat is a data.frame. data, var.name, drop.first, and drop.level are ignored; drop.first is automatically set to "if2". For col_w_ovl() and col_w_ent(), other arguments passed to density() besides x and weights. Note that the default value for bw when unspecified is "nrd" rather than the default in density(), which is "nrd0".
bin.vars	a vector used to denote whether each variable is binary or not. Can be a logical vector with length equal to the number of columns of mat or a vector of numeric indices or character names of the binary variables. If missing (the default), the function will figure out which covariates are binary or not, which can increase computation time. If NULL, it will be assumed no variables are binary. All functions other than col_w_mean() treat binary variables different from continuous variables. If a factor or character variable is in mat, all the dummies created will automatically be marked as binary, but it should still receive an entry when bin.vars is supplied as logical.
treat	a vector of treatment status for each individual. For col_w_smd(), col_w_vr(), col_w_ks(), and col_w_ovl(), treat should have exactly two unique values. For col_w_cov() and col_w_corr(), treat should be a many-valued numeric vector.
std	logical; for col_w_smd(), whether the computed mean differences for each variable should be standardized; for col_w_cov(), whether treatment-covariate correlations should be computed (TRUE) rather than covariances (FALSE). Can be either length 1, whereby all variables will be standardized or not, or length equal to the number of columns of mat, whereby only variables with a value of TRUE will be standardized. See Details.
s.d.denom	for col_w_smd() and col_w_cov() when std is TRUE for some variables, and for col_w_corr(), how the standardization factor should be computed. For col_w_smd() (i.e., when computing standardized mean differences), allowable options include "treated" - uses the standard deviation of the variable in the treated group "control" - uses the standard deviation of the variable in the control group "pooled" - uses the square root of the average of the variances of the variable in the treated and control groups "all" - uses the standard deviation of the variable in the full sample "weighted" - uses the standard deviation of the variable in the full sample weighted by weighted.weights "hedges" - uses the small-sample corrected version of Hedge's G described in the WWC Procedures Handbook (see References) the name of one of the treatment values - uses the standard deviation of the variable in that treatment group. For col_w_cov() and col_w_corr(), only "all" and "weighted" are allowed. Abbreviations allowed. This can also be supplied as a numeric vector of standard deviations with length equal to the number of columns of mat; the values will be used as the standardization factors.
abs	logical; for col_w_smd(), col_w_cov(), and col_w_corr(), whether the returned statistics should be in absolute value (TRUE) or not. For col_w_vr(), whether the ratio should always include the larger variance in the numerator, so that the ratio is always greater than or equal to 1. Default is FALSE.
weighted.weights	for col_w_smd(), col_w_cov(), and col_w_corr(), when std = TRUE and s.d.denom = "weighted", a vector of weights to be applied to the computation of the denominator standard deviation. If not specified, will use the argument to weights. When s.d.denom is not "weighted", this is ignored. The main purpose of this is to allow weights to be NULL while weighting the denominator standard deviations for assessing balance in the unweighted sample but using the standard deviations of the weighted sample.
integrate	logical; for col_w_ovl(), whether to use integrate() to calculate the area of overlap or the distance between the densities, respectively. If FALSE, a midpoint Riemann sum with 1000 partitions will be used instead. The Riemann sum is a little slower and very slightly imprecise (unnoticibly in most contexts), but the integral can fail sometimes and thus is less stable. The default is to use the Riemann sum.
type	for col_w_cov() and col_w_corr(), the type of covariance/correlation to be computed. Allowable options include "pearson" and "spearman". When "spearman" is requested, the covariates and treatment are first turned into ranks using rank() with na.last = "keep".

Details

col_w_mean() computes column weighted means for a matrix of variables. It is similar to colMeans() but (optionally) incorporates weights. weights and s.weights are multiplied together prior to being used, and there is no distinction between them. This could be used to compute the weighted means of each covariate in the general population to examine the degree to which a weighting method has left the weighted samples resembling the original population.

col_w_sd() computes column weighted standard deviations for a matrix of variables. weights and s.weights are multiplied together prior to being used, and there is no distinction between them. The variance of binary variables is computed as $p(1-p)$, where $p$ is the (weighted) proportion of 1s, while the variance of continuous variables is computed using the standard formula; the standard deviation is the square root of this variance.

col_w_smd() computes the mean difference for each covariate between treatment groups defined by treat. These mean differences can optionally be weighted, standardized, and/or in absolute value. The standardization factor is computed using the unweighted standard deviation or variance when s.weights are absent, and is computed using the s.weights-weighted standard deviation or variance when s.weights are present, except when s.d.denom = "weighted", in which case the product of weighted.weights and s.weights (if present) are used to weight the standardization factor. The standardization factor is computed using the whole sample even when subset is used. Note that unlike bal.tab(), col_w_smd() requires the user to specify whether each individual variable should be standardized using std rather than relying on continuous or binary. The weighted mean difference is computed using the product of weights and s.weights, if specified. The variance of binary variables is computed as $p(1-p)$, where $p$ is the (weighted) proportion of 1s, while the variance of continuous variables is computed using the standard formula.

col_w_vr() computes the variance ratio for each covariate between treatment groups defined by treat. When abs = TRUE, pmax(out, 1/out) is applied to the output so that the ratio is always greater than or equal to 1. For binary variables, the variance is computed as $p(1-p)$, where $p$ is the (weighted) proportion of 1s, while the variance of continuous variables is computed using the standard formula. Note that in bal.tab(), variance ratios are not computed for binary variables, while here, they are (but likely should not be interpreted). weights and s.weights are multiplied together prior to being used, and there is no distinction between them. Because of how the weighted variance is computed, exactly balanced groups may have variance ratios that differ slightly from 1.

col_w_ks() computes the KS statistic for each covariate using the method implemented in twang. The KS statistics can optionally be weighted. For binary variables, the KS statistic is just the difference in proportions. weights and s.weights are multiplied together prior to being used, and there is no distinction between them.

col_w_ovl() computes the complement of the overlapping coefficient as described by Franklin et al. (2014). It does so by computing the density of the covariate in the treated and control groups, then finding the area where those density overlap, and subtracting that number from 1, yielding a value between 0 and 1 where 1 indicates complete imbalance, and 0 indicates perfect balance. density() is used to model the density in each group. The bandwidth of the covariate in the smaller treatment group is used for both groups. The area of overlap can be computed using integrate, which quickly and accurately computes the integral, or using a midpoint Riemann sum with 1000 partitions, which approximates the area more slowly. A reason to prefer the Riemann sum is that integrate can fail for unknown reasons, though Riemann sums will fail with some extreme distributions. When either method fails, the resulting value will be NA. For binary variables, the complement of the overlapping coefficient is just the difference in proportions. weights and s.weights are multiplied together prior to being used, and there is no distinction between them. The weights are used to compute the weighted density by supplying them to the weights argument of density.

col_w_cov() computes the covariance between a continuous treatment and the covariates to assess balance for continuous treatments as recommended in Austin (2019). These covariance can optionally be weighted or in absolute value or can be requested as correlations (i.e., standardized covariances). The correlations are computed as the covariance between the treatment and covariate divided by a standardization factor, which is equal to the square root of the product of the variance of treatment and the variance of the covariate. The standardization factor is computed using the unweighted variances when s.weights are absent, and is computed using the sampling weighted variances when s.weights are present, except when s.d.denom = "weighted", in which case the product of weighted.weights and s.weights (if present) are used to weight the standardization factor. For this reason, the computed correlation can be greater than 1 or less than -1. The standardization factor is always computed using the whole sample even when subset is used. The covariance is computed using the product of weights and s.weights, if specified. The variance of binary variables is computed as $p(1-p)$, where $p$ is the (weighted) proportion of 1s, while the variance of continuous variables is computed using the standard formula.

col_w_corr() is a wrapper for col_w_cov with std set to TRUE.

Value

A vector of balance statistics, one for each variable in mat. If mat has column names, the output will be named as well.

References

Austin, P. C. (2019). Assessing covariate balance when using the generalized propensity score with quantitative or continuous exposures. Statistical Methods in Medical Research, 28(5), 1365–1377. doi:10.1177/0962280218756159

Franklin, J. M., Rassen, J. A., Ackermann, D., Bartels, D. B., & Schneeweiss, S. (2014). Metrics for covariate balance in cohort studies of causal effects. Statistics in Medicine, 33(10), 1685–1699. doi:10.1002/sim.6058

What Works Clearinghouse. (2020). WWC Procedures Handbook (Version 4.1). Retrieved from https://ies.ed.gov/ncee/wwc/Handbooks

See Also

• bal.tab()

• bal.compute()

• balance-statistics

Examples

data("lalonde", package = "cobalt")

treat <- lalonde$treat
covs <- subset(lalonde, select = -c(treat, re78))
covs0 <- splitfactor(covs, drop.first = "if2")
bin.vars <- c(FALSE, FALSE, TRUE, TRUE, TRUE,
              TRUE, TRUE, FALSE, FALSE)
W <- WeightIt::weightit(treat ~ covs, method = "glm", 
                        estimand = "ATE")
weights <- W$weights

round(data.frame(
    m0 = col_w_mean(covs0, weights = weights, subset = treat == 0),
    sd0 = col_w_sd(covs0, weights = weights,
                   bin.vars = bin.vars, subset = treat == 0),
    m1 = col_w_mean(covs0, weights = weights, subset = treat == 1),
    sd1 = col_w_sd(covs0, weights = weights,
                   bin.vars = bin.vars, subset = treat == 1),
    smd = col_w_smd(covs0, treat = treat, weights = weights,
                    std = TRUE, bin.vars = bin.vars),
    vr = col_w_vr(covs0, treat = treat, weights = weights,
                  bin.vars = bin.vars),
    ks = col_w_ks(covs0, treat = treat, weights = weights,
                  bin.vars = bin.vars),
    row.names = colnames(covs0)
), 4)

# Compare to bal.tab():
bal.tab(covs, treat = treat, weights = weights,
        disp = c("m", "sd"), stats = c("m", "v", "ks"),
        estimand = "ATE", method = "weighting",
        binary = "std")

---

Using bal.tab() with Clustered Data

Description

When using bal.tab() with clustered data, the output will be different from the case with single-level data, and there are some options that are common across all bal.tab() methods. This page outlines the outputs and options in this case.

There are two main components of the output of bal.tab() with clustered data: the within-cluster balance summaries and the across-cluster balance summary. The within-cluster balance summaries display balance for units within each cluster separately.

The across-cluster balance summary pools information across the within-cluster balance summaries to simplify balance assessment. It provides a combination (e.g., mean or maximum) of each balance statistic for each covariate across all clusters. This allows you to see how bad the worst imbalance is and what balance looks like on average. The balance summary will not be computed if longitudinal treatments, multi-category treatments, or multiply imputed data are used.

Allowable arguments

There are four arguments for each bal.tab() method that can handle clustered data: cluster, which.cluster, cluster.summary, and cluster.fun.

cluster

A vector of cluster membership. This can be factor, character, or numeric vector. This argument is required to let bal.tab() know that the data is clustered. If a data argument is specified, this can also be the name of a variable in data that contains cluster membership.

which.cluster

This is a display option that does not affect computation. If .all (the default), all clusters in cluster will be displayed. If .none, no clusters will be displayed. Otherwise, can be a vector of cluster names or numerical indices for which to display balance. Indices correspond to the alphabetical order of cluster names (or the order of cluster levels if a factor).

cluster.summary

This is a display option that does not affect computation. If TRUE, the balance summary across clusters will be displayed. The default is TRUE, and if which.cluster is .none, it will automatically be set to TRUE.

cluster.fun

This is a display option that does not affect computation. Can be "min", "mean", or "max" and corresponds to which function is used in the across-cluster summary to combine results across clusters. For example, if cluster.fun = "mean" the mean balance statistic across clusters will be displayed. The default when abs = FALSE in the bal.tab() call is to display all three. The default when abs = FALSE in the bal.tab() call is to display just the mean and max balance statistic.

Output

The output is a bal.tab.cluster object, which inherits from bal.tab. It has the following elements:

• Cluster.Balance: For each cluster, a regular bal.tab object containing a balance table, a sample size summary, and other balance assessment tools, depending on which options are specified.

• Cluster.Summary: The balance summary across clusters. This will include the combination of each balance statistic for each covariate across all clusters according to the value of cluster.fun.

• Observations: A table of sample sizes or effective sample sizes for each cluster before and after adjustment.

As with other methods, multiple weights can be specified, and values for all weights will appear in all tables.

See Also

• bal.tab()

• bal.tab.data.frame()

• print.bal.tab()

• vignette("segmented-data") for examples

---