balqual: Evaluate Matching Quality

In vecmatch: Generalized Propensity Score Estimation and Matching for Multiple Groups

Evaluate Matching Quality

Description

The balqual() function evaluates the balance quality of a dataset after matching, comparing it to the original unbalanced dataset. It computes various summary statistics and provides an easy interpretation using user-specified cutoff values.

Usage

balqual(
  matched_data = NULL,
  formula = NULL,
  type = c("smd", "r", "var_ratio"),
  statistic = c("mean", "max"),
  cutoffs = NULL,
  round = 3
)

Arguments

matched_data	An object of class matched, generated by the match_gps() function. This object is essential for the balqual() function as it contains the final data.frame and attributes required to compute the quality coefficients.
formula	A valid R formula used to compute generalized propensity scores during the first step of the vector matching algorithm in estimate_gps(). This formula must match the one used in estimate_gps().
type	A character vector specifying the quality metrics to calculate, provided in a vector created by the c(). The values fall into two groups. smd, r and var_ratio are balance metrics summarizing pairwise comparisons between the treatment levels. desc_full and desc_reduced instead describe the marginal distribution of each covariate within every treatment level, which makes it possible to directly compare the covariate distributions of the unmatched and the matched dataset. Note that they describe the covariates as they are given in the formula, whereas the balance metrics are computed on the model matrix: a factor is described once, by its levels, rather than once per dummy-coded column, and interaction terms are not described at all, since they are model terms rather than covariates. The balance metrics still cover them. Neither descriptive metric is part of the default, and both have to be requested explicitly, either on their own or together with the balance metrics, e.g. type = c("smd", "desc_reduced"). As desc_reduced is a subset of desc_full, the two are mutually exclusive. Possible values include: smd - Calculates standardized mean differences (SMD) between groups, defined as the difference in means divided by the standard deviation of the treatment group (Rubin, 2001). r - Computes Pearson's r coefficient using the Z statistic from the U-Mann-Whitney test. var_ratio - Measures the dispersion differences between groups, calculated as the ratio of the larger variance to the smaller one. desc_full - Computes standard descriptive statistics for every balancing variable, separately for each treatment level, before and after matching. Numeric covariates are summarized by the number of observations (N), mean, standard deviation, minimum, first quartile, median, third quartile, maximum, skewness and excess kurtosis, where skewness and excess kurtosis are the classical moment (type 1) estimators. Categorical covariates (factor, character and logical) are instead cross-tabulated, reporting the count and the percentage of every level within each treatment level, as means and quantiles are not meaningful for them. The two are printed as two separate tables. desc_reduced - As desc_full, but the summary of the numeric covariates is restricted to the four most commonly reported statistics: minimum, mean, median and maximum. The cross-tabulation of the categorical covariates is unaffected. Useful when the full table is too wide to read comfortably in the console.
statistic	A character vector specifying the type of statistics used to summarize the quality metrics. Since quality metrics are calculated for all pairwise comparisons between treatment levels, they need to be aggregated for the entire dataset. max: Returns the maximum values of the statistics defined in the type argument (as suggested by Lopez and Gutman, 2017). mean: Returns the corresponding averages. To compute both, provide both names using the c() function. This argument is ignored by the desc_full and desc_reduced metrics, which are not based on pairwise comparisons and are therefore never aggregated across them.
cutoffs	A numeric vector with the same length as the number of balance metrics specified in the type argument. Defines the cutoffs for each corresponding metric, below which the dataset is considered balanced. If NULL, the default cutoffs are used: 0.1 for smd and r, and 2 for var_ratio. The descriptive metrics have no cutoff and are not counted here, so type = c("smd", "desc_full") still requires a single cutoff value.
round	A single non-negative integer specifying the number of decimal places to round the output to.

Value

If assigned to a name, returns a list of summary statistics of class quality containing:

• quality_mean - A data frame with the mean values of the statistics specified in the type argument for all balancing variables used in formula.

• quality_max - A data frame with the maximal values of the statistics specified in the type argument for all balancing variables used in formula.

• quality_desc - A data frame with the descriptive statistics of every balancing variable, laid out like the balance tables above: the statistics are the rows and the two matching stages are the Before and After columns. It holds the numeric and the categorical covariates in a single table, with the columns Variable, Group, Type, Statistic, Before, After, Percent_Before and Percent_After. Type is either "continuous" or "categorical". For a continuous covariate, Statistic names the reported statistic - N, Mean, SD, Min, Q1, Median, Q3, Max, Skewness and Kurtosis for desc_full, or N, Min, Mean, Median and Max for desc_reduced - and the two Percent columns are NA. For a categorical covariate, Statistic names a level of that covariate, Before and After hold its counts, and the two Percent columns hold its share within the treatment level, computed separately for each matching stage. NULL unless one of the two descriptive metrics is included in the type argument. When printed, the counts and percentages of a categorical covariate are compressed into a single ⁠N (%)⁠ cell, with the percentage always shown to one decimal place.

• perc_matched - A single numeric value indicating the percentage of observations in the original dataset that were matched.

• statistic - A single string defining which statistic will be displayed in the console.

• summary_head - A summary of the matching process. If max is included in the statistic, it contains the maximal observed values for each variable; otherwise, it includes the mean values.

• n_before - The number of observations in the dataset before matching.

• n_after - The number of observations in the dataset after matching.

• count_table - A contingency table showing the distribution of the treatment variable before and after matching.

The balqual() function also prints a well-formatted table with the defined summary statistics for each variable in the formula to the console.

References

Rubin, D.B. Using Propensity Scores to Help Design Observational Studies: Application to the Tobacco Litigation. Health Services & Outcomes Research Methodology 2, 169–188 (2001). https://doi.org/10.1023/A:1020363010465

Michael J. Lopez, Roee Gutman "Estimation of Causal Effects with Multiple Treatments: A Review and New Ideas," Statistical Science, Statist. Sci. 32(3), 432-454, (August 2017)

See Also

match_gps() for matching the generalized propensity scores; estimate_gps() for the documentation of the formula argument.

Examples

# We try to balance the treatment variable in the cancer dataset based on age
# and sex covariates
data(cancer)

# Then we can estimate the generalized propensity scores
gps_cancer <- estimate_gps(formula(status ~ age * sex),
  cancer,
  method = "multinom",
  reference = "control",
  verbose_output = TRUE
)

# ... and drop observations based on the common support region...
csr_cancer <- csregion(gps_cancer)

# ... to match the samples using `match_gps()`
matched_cancer <- match_gps(csr_cancer,
  reference = "control",
  caliper = 1,
  kmeans_cluster = 5,
  kmeans_args = list(n.iter = 100),
  verbose_output = TRUE
)

# At the end we can assess the quality of matching using `balqual()`
balqual(
  matched_data = matched_cancer,
  formula = formula(status ~ age * sex),
  type = "smd",
  statistic = "max",
  round = 3,
  cutoffs = 0.2
)

# Adding `desc_full` to `type` additionally reports the descriptive
# statistics of every covariate per treatment level, before and after
# matching, which allows a direct comparison of the covariate distributions
balqual(
  matched_data = matched_cancer,
  formula = formula(status ~ age * sex),
  type = c("smd", "desc_full"),
  statistic = "max",
  round = 3,
  cutoffs = 0.2
)

# `desc_reduced` gives the same table restricted to the minimum, mean,
# median and maximum
balqual(
  matched_data = matched_cancer,
  formula = formula(status ~ age * sex),
  type = c("smd", "desc_reduced"),
  statistic = "max",
  round = 3,
  cutoffs = 0.2
)

vecmatch documentation built on Sept. 9, 2026, 1:06 a.m.