extract.bal.tab: Extract a Balance Table for Further Use

Description

as.data.frame() extracts the balance statistics computed by bal.tab() as a tidy data frame, one row per covariate, sample, and statistic. format() returns the balance table exactly as print.bal.tab() displays it, as a data frame of formatted strings, ready to be passed to a table-rendering function.

Together they are meant to remove the need to pick apart a bal.tab object by hand when reporting balance in a document.

Usage

# S3 method for bal.tab
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  ...,
  var.names = NULL,
  wide = FALSE
)
# S3 method for bal.tab
format(
  x,
  ...,
  var.names = NULL,
  digits = max(3L, getOption("digits") - 3L),
  component = "balance"
)

Value

as.data.frame() returns a data frame with one row per covariate, sample, and statistic, and these columns:

variable: the covariate name, as it appears in the row names of the balance table.
type: the covariate type: "Binary", "Contin.", or "Distance".
sample: "Unadjusted", or the name of the set of weights.
stat: the name of the statistic, using the same names as bal.tab()'s stats argument (e.g., "mean.diffs"), with "mean" and "sd" for the distribution summary statistics.
group: for "mean" and "sd", the name of the treatment group the value describes, as bal.tab() names it: the two group names for a binary treatment, the level for a multi-category one, "Uncensored" or "Full" for a censoring indicator, and "All" for a continuous treatment, which has no groups, or for the full sample when pairwise = FALSE. NA for a statistic that contrasts two groups, which belongs to neither of them.
estimate: the value of the statistic.
threshold: the balance verdict, e.g. "Balanced, <0.1", when a threshold was requested for that statistic; NA for a row it does not cover, such as a mean.
threshold.value: the numeric threshold, on the same rows.

The two threshold columns are present only when a threshold is on display for at least one statistic; when none is, they would be empty throughout and are omitted. The rest of the columns are always present.

When the data are segmented -- by cluster, imputation, treatment pair, time point, or subclass -- one further column per level of segmentation identifies it. Segmentation is always a column, never a nested list, so the result is a single rectangle whatever the shape of the input.

A multi-category treatment is reported one pair of groups at a time, but a mean or a standard deviation belongs to a group rather than to a comparison, and is the same in every pair that group appears in. Such a row therefore appears once, with pair set to NA; only the statistics that contrast two groups carry a pair. The same applies to the full sample's own means when pairwise = FALSE, which would otherwise be repeated against every group.

With wide = TRUE, the columns are those print() displays, with the covariate names moved from the row names into a variable column and any segmentation columns retained.

format() returns a data frame of character vectors with the covariate names as row names, formatted exactly as print() displays them: rounded to digits, padded to a common number of decimal places, with NA shown as ".".

Arguments

x: a bal.tab object; the output of a call to bal.tab().
row.names, optional: ignored; present for consistency with the as.data.frame() generic.
...: arguments passed to print.bal.tab() to control which statistics, samples, and covariates are included, e.g. stats, disp, un, imbalanced.only, or disp.thresholds. The .all and .none shorthands are accepted as they are by print(). Arguments that were not computed in the original call to bal.tab() cannot be requested here, for the same reason they cannot be requested in print().
var.names: an optional object providing alternate names for the variables, which will otherwise be returned as they are stored. Entries given here add to those given in the original call to bal.tab() and replace any entry they name. See display-options for how to specify it.
wide: logical; for as.data.frame(), whether to return the table in the layout print() uses, with one column per sample and statistic, rather than the default tidy layout. Default is FALSE.
digits: for format(), the number of significant digits to display. Default is the same as for print().
component: for format(), which table to return: "balance" (the default) for the balance table, or "observations" for the sample size table.

Details

Both functions accept every argument print() accepts, and resolve them the same way, so the same warnings are raised when a requested value was not computed because quick = TRUE in the original call to bal.tab().

The variable column and the row names carry the covariates' display names, so var.names -- given here or in the original call to bal.tab() -- changes them. What the covariates are stored under is unaffected. See display-options.

as.data.frame() returns the balance statistics themselves, from each innermost balance table. It does not return the summaries across clusters, imputations, treatment pairs, or time points, which are aggregates of those statistics; format() returns the summary when that is what print() displays.

Examples

Run this code

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

b <- bal.tab(treat ~ age + educ + race + re74, data = lalonde,
             s.d.denom = "pooled", stats = c("m", "ks"),
             thresholds = c(m = .1), un = TRUE)

#Tidy: one row per covariate, sample, and statistic
head(as.data.frame(b))

#The layout print() shows
as.data.frame(b, wide = TRUE)

#Ready for knitr::kable() or any other table renderer
format(b)

format(b, component = "observations")

#print()'s arguments work here too
as.data.frame(b, stats = "ks", un = FALSE)