Balance constraints — balance

balance_terms() records the set of covariate functions a balancing method should equate across exposure groups. It is passed to balance() through constraints. The specification is data-free: the covariate expansion it describes is applied at fit time.

Usage

balance_terms(
  moments = NULL,
  interactions = FALSE,
  quantiles = NULL,
  tolerance = 0,
  ...
)

Arguments

moments: The highest covariate power to balance. A single whole number or a named integer vector; NULL (the default) resolves to first moments.
interactions: Whether to add pairwise interactions of the base columns. These expand the constraint set the weights must balance, adding the pairwise products of the base columns to the covariate functions a fit constrains: equated across the exposure groups of a discrete exposure, and driven to zero correlation with a continuous one. They say nothing about causal interaction between two exposures, which is an effect rather than a constraint and is reported for a joint exposure by ipw().
quantiles: Quantile probabilities in (0, 1): a numeric vector applied to every continuous covariate, a named list of probabilities per covariate, or NULL for none.
tolerance: The per-constraint tolerance: a single non-negative number, or a named vector giving the tolerance per source covariate.
...: Reserved for future extensions; must be empty.

Value

A balance_terms object.

Details

The constraint set is built from four ingredients:

moments: the highest power of each numeric covariate to balance. A scalar applies to every covariate; a named integer vector sets powers per covariate, with unnamed covariates defaulting to 1. Powers above 1 are ignored for binary indicator columns.
interactions: when TRUE, all pairwise products of distinct base columns are added, excluding products of two indicators of the same factor.
quantiles: probabilities in (0, 1). Each probability adds an indicator column so that mean balance on the indicator is quantile balance on the covariate. A single probability vector applies to every continuous covariate; a named list sets probabilities per covariate. Quantile constraints apply to discrete exposures only.
tolerance: the largest absolute standardized mean difference (discrete exposures) or exposure-covariate correlation (continuous exposures) permitted per constraint. A scalar applies to every covariate; a named vector sets tolerances per source covariate, and derived columns inherit their source covariate's tolerance. 0 requests exact balance. A positive value selects the inexact problem for entropy balancing and is the central tuning parameter for stable balancing weights.

Examples

# Balance means and variances of every numeric covariate.
balance_terms(moments = 2)
#> <balancing::balance_terms>
#>  @ moments     : int 2
#>  @ interactions: logi FALSE
#>  @ quantiles   : NULL
#>  @ tolerance   : num 0

# Balance means with a relaxed tolerance.
balance_terms(tolerance = 0.05)
#> <balancing::balance_terms>
#>  @ moments     : NULL
#>  @ interactions: logi FALSE
#>  @ quantiles   : NULL
#>  @ tolerance   : num 0.05