The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.
This vignette compares couplr’s approach to matching with established R packages: 1. MatchIt - The most popular matching package in R 2. optmatch - Optimal full matching with constraints 3. designmatch - Optimization-based matching with balance constraints 4. Matching - Genetic matching and multivariate matching
Each comparison examines algorithmic differences, API design, performance characteristics, and appropriate use cases. We use simulated observational data to demonstrate practical differences.
Prerequisites: Familiarity with
vignette("matching-workflows") for couplr’s matching
approach.
We simulate a job training evaluation scenario with selection bias:
set.seed(42)
# Treatment group: younger, more educated, higher prior earnings
treatment <- tibble(
id = 1:200,
age = rnorm(200, mean = 35, sd = 8),
education = rnorm(200, mean = 14, sd = 2),
prior_earnings = rnorm(200, mean = 40000, sd = 12000),
employed = rbinom(200, 1, 0.7),
group = "treatment"
)
# Control group: older, less educated, lower prior earnings (selection bias)
control <- tibble(
id = 201:700,
age = rnorm(500, mean = 45, sd = 12),
education = rnorm(500, mean = 12, sd = 3),
prior_earnings = rnorm(500, mean = 32000, sd = 15000),
employed = rbinom(500, 1, 0.5),
group = "control"
)
# Combine for packages that expect single data frame
combined <- bind_rows(treatment, control) %>%
mutate(treated = as.integer(group == "treatment"))
cat("Treatment units:", nrow(treatment), "\n")
#> Treatment units: 200
cat("Control units:", nrow(control), "\n")
#> Control units: 500
# Baseline imbalance
vars <- c("age", "education", "prior_earnings", "employed")
for (v in vars) {
diff <- mean(treatment[[v]]) - mean(control[[v]])
pooled_sd <- sqrt((var(treatment[[v]]) + var(control[[v]])) / 2)
std_diff <- diff / pooled_sd
cat(sprintf("%s: std diff = %.3f\n", v, std_diff))
}
#> age: std diff = -0.967
#> education: std diff = 0.775
#> prior_earnings: std diff = 0.576
#> employed: std diff = 0.365Substantial baseline imbalance exists: treatment group is younger (-0.9 SD), more educated (+0.7 SD), and has higher prior earnings (+0.6 SD).
MatchIt (Ho et al., 2011) is the most widely used matching package in R. It emphasizes propensity score methods and provides a unified interface to multiple matching algorithms.
Key difference: MatchIt typically matches on estimated propensity scores (a single summary measure), while couplr matches directly on covariates (multivariate distance).
if (requireNamespace("MatchIt", quietly = TRUE)) {
library(MatchIt)
# MatchIt: Propensity score matching (default)
m_ps <- matchit(
treated ~ age + education + prior_earnings + employed,
data = combined,
method = "nearest",
distance = "glm" # Propensity score via logistic regression
)
cat("MatchIt (propensity score, nearest neighbor):\n")
cat(" Matched pairs:", sum(m_ps$weights[combined$treated == 1] > 0), "\n")
# Extract matched data
matched_ps <- match.data(m_ps)
}# couplr: Direct covariate matching
result_couplr <- match_couples(
left = treatment,
right = control,
vars = c("age", "education", "prior_earnings", "employed"),
auto_scale = TRUE,
scale = "robust"
)
cat("\ncouplr (direct covariate matching):\n")
#>
#> couplr (direct covariate matching):
cat(" Matched pairs:", result_couplr$info$n_matched, "\n")
#> Matched pairs: 200
cat(" Mean distance:", round(mean(result_couplr$pairs$distance), 4), "\n")
#> Mean distance: 0.5844if (requireNamespace("MatchIt", quietly = TRUE)) {
# MatchIt balance
matched_treated_ps <- matched_ps %>% filter(treated == 1)
matched_control_ps <- matched_ps %>% filter(treated == 0)
matchit_balance <- tibble(
variable = vars,
std_diff = sapply(vars, function(v) {
diff <- mean(matched_treated_ps[[v]]) - mean(matched_control_ps[[v]])
pooled_sd <- sqrt((var(matched_treated_ps[[v]]) + var(matched_control_ps[[v]])) / 2)
diff / pooled_sd
}),
method = "MatchIt"
)
# couplr balance
couplr_balance <- balance_diagnostics(
result_couplr, treatment, control, vars
)
couplr_balance_df <- couplr_balance$var_stats %>%
select(variable, std_diff) %>%
mutate(method = "couplr")
# Combine and plot
balance_comparison <- bind_rows(matchit_balance, couplr_balance_df)
ggplot(balance_comparison, aes(x = variable, y = abs(std_diff), fill = method)) +
geom_col(position = "dodge") +
geom_hline(yintercept = 0.1, linetype = "dashed", color = "#93c54b") +
geom_hline(yintercept = 0.25, linetype = "dashed", color = "#f47c3c") +
labs(
title = "Covariate Balance: MatchIt vs couplr",
subtitle = "Green line = 0.1 (excellent), Orange line = 0.25 (acceptable)",
x = "Variable",
y = "|Standardized Difference|",
fill = "Method"
) +
scale_fill_manual(values = c("MatchIt" = "#29abe0", "couplr" = "#93c54b")) +
theme_minimal() +
theme(
plot.background = element_rect(fill = "transparent", color = NA),
panel.background = element_rect(fill = "transparent", color = NA),
legend.position = "bottom"
)
}| Feature | MatchIt | couplr |
|---|---|---|
| Primary approach | Propensity score | Direct covariate distance |
| Distance metric | PS logit, Mahalanobis | Euclidean (scaled) |
| Optimization | Greedy nearest neighbor | Optimal assignment (LAP) |
| Data format | Single data frame + formula | Separate left/right data frames |
| Diagnostics | summary(), plot() |
balance_diagnostics(),
balance_table() |
| Caliper | On PS or covariates | On multivariate distance |
| Algorithms | 10+ methods | 20+ LAP solvers |
MatchIt: - Propensity score methods are preferred (common in epidemiology) - Need full matching, CEM, or genetic matching - Following published protocols that specify MatchIt - Familiar with propensity score theory
couplr: - Direct covariate matching is preferred (no model for treatment) - Need optimal (minimum distance) one-to-one matching - Working with large datasets (20+ LAP algorithms for different scales) - Need fine-grained control over distance computation - Matching on continuous variables where Euclidean distance is natural
optmatch (Hansen & Klopfer, 2006) specializes in optimal matching using network flow algorithms. It emphasizes full matching and variable ratio matching.
Key difference: optmatch excels at optimal full matching (variable ratios); couplr focuses on optimal one-to-one matching with 20+ algorithm choices.
if (requireNamespace("optmatch", quietly = TRUE)) {
library(optmatch)
# Create distance matrix
dist_mat <- match_on(
treated ~ age + education + prior_earnings + employed,
data = combined,
method = "mahalanobis"
)
# Optimal pair matching
m_opt <- pairmatch(dist_mat, data = combined)
n_matched <- sum(!is.na(m_opt)) / 2
cat("optmatch (optimal pair matching):\n")
cat(" Matched pairs:", n_matched, "\n")
}# couplr with Mahalanobis-like scaling
result_couplr_maha <- match_couples(
left = treatment,
right = control,
vars = vars,
auto_scale = TRUE,
scale = "standardize" # Similar to Mahalanobis diagonal
)
cat("\ncouplr (optimal pair matching):\n")
#>
#> couplr (optimal pair matching):
cat(" Matched pairs:", result_couplr_maha$info$n_matched, "\n")
#> Matched pairs: 200Both packages use optimal assignment algorithms, so they should achieve similar total distances. The key differences are in:
| Feature | optmatch | couplr |
|---|---|---|
| Matching types | Full, pair, variable ratio | One-to-one only |
| Algorithm | RELAX-IV network flow | 20+ solvers (JV, Hungarian, Auction, etc.) |
| Distance | match_on() function |
compute_distances() + caching |
| Constraints | Caliper, exact matching | Caliper, blocking via matchmaker() |
| Optimization | Always optimal | Optimal or greedy (user choice) |
| Large problems | Sparse matrix support | Blocking, greedy, parallel |
optmatch: - Full matching or variable ratio matching needed - Network flow formulation is preferred - Integration with RItools for diagnostics
couplr: - One-to-one matching is sufficient - Need algorithm flexibility (auction for n > 1000, sparse methods, etc.) - Large-scale problems requiring greedy approximations - Distance caching for iterative analysis
designmatch (Zubizarreta et al., 2018) uses mixed-integer programming to find matches satisfying explicit balance constraints. Rather than minimizing distance, it finds feasible matches that meet user-specified balance criteria.
Key difference: designmatch optimizes for balance constraints directly; couplr minimizes total distance (balance is a consequence, not a constraint).
if (requireNamespace("designmatch", quietly = TRUE)) {
library(designmatch)
# Prepare data for designmatch
t_ind <- combined$treated
# Distance matrix (Mahalanobis)
X <- as.matrix(combined[, vars])
dist_mat_dm <- distmat(t_ind, X)
# Balance constraints: mean differences
mom <- list(
covs = X,
tols = rep(0.1, ncol(X)) # Tolerance for standardized difference
)
# Solve with balance constraints
tryCatch({
m_dm <- bmatch(
t_ind = t_ind,
dist_mat = dist_mat_dm,
mom = mom,
solver = list(name = "glpk", approximate = 1)
)
cat("designmatch (balance-constrained matching):\n")
cat(" Matched pairs:", sum(m_dm$t_id > 0), "\n")
}, error = function(e) {
cat("designmatch: Balance constraints may be infeasible\n")
cat(" Try relaxing tolerances or reducing constraint count\n")
})
}couplr doesn’t constrain balance directly but achieves balance through distance minimization:
# couplr: Optimize distance, then check balance
result_couplr_dm <- match_couples(
left = treatment,
right = control,
vars = vars,
auto_scale = TRUE
# No caliper - let algorithm find optimal matches
)
#> Auto-selected scaling method: standardize
balance_dm <- balance_diagnostics(result_couplr_dm, treatment, control, vars)
#> Warning in ks.test.default(left_clean, right_clean): p-value will be
#> approximate in the presence of ties
cat("\ncouplr (distance-minimizing):\n")
#>
#> couplr (distance-minimizing):
cat(" Matched pairs:", result_couplr_dm$info$n_matched, "\n")
#> Matched pairs: 200
cat(" Mean |std diff|:", round(balance_dm$overall$mean_abs_std_diff, 4), "\n")
#> Mean |std diff|: 0.2343
cat(" Max |std diff|:", round(balance_dm$overall$max_abs_std_diff, 4), "\n")
#> Max |std diff|: 0.4387| Feature | designmatch | couplr |
|---|---|---|
| Objective | Satisfy balance constraints | Minimize total distance |
| Balance | Hard constraint | Achieved via optimization |
| Solver | Mixed-integer programming (GLPK, Gurobi) | Linear assignment (JV, Hungarian, etc.) |
| Feasibility | May be infeasible | Always finds a solution |
| Fine-grain control | Moment constraints, cardinality | Caliper, blocking |
| Speed | Slower (MIP) | Faster (LAP) |
designmatch: - Specific balance requirements must be guaranteed - Cardinality matching (fixed sample sizes) - Fine-grained moment balancing (means, variances, quantiles) - Willing to accept no solution if constraints infeasible
couplr: - Distance minimization is the goal - Balance is assessed post-hoc (typical workflow) - Need guaranteed solutions - Iterative refinement (match, assess, refine)
The Matching package (Sekhon, 2011) provides genetic matching and multivariate matching with automatic balance optimization.
Key difference: Matching uses genetic algorithms to find weights that optimize balance; couplr uses fixed weights (after scaling) and optimizes assignment.
if (requireNamespace("Matching", quietly = TRUE)) {
library(Matching)
# Genetic matching (finds optimal weights)
X <- as.matrix(combined[, vars])
set.seed(123)
m_gen <- Match(
Tr = combined$treated,
X = X,
M = 1, # 1:1 matching
estimand = "ATT",
replace = FALSE
)
cat("Matching package (multivariate matching):\n")
cat(" Matched pairs:", length(m_gen$index.treated), "\n")
}| Feature | Matching | couplr |
|---|---|---|
| Weight optimization | Genetic algorithm | Fixed (user-specified scaling) |
| Replacement | With or without | Without only |
| Estimand | ATT, ATE, ATC | ATT (one-to-one) |
| Stochastic | Yes (genetic search) | No (deterministic) |
| Balance diagnostic | MatchBalance() |
balance_diagnostics() |
Matching: - Need automatic weight selection via genetic optimization - Matching with replacement is acceptable - Need ATE or ATC estimands (not just ATT) - Willing to accept stochastic results
couplr: - Deterministic, reproducible matching - Matching without replacement - Direct control over variable scaling - Large problems (couplr scales better)
All packages slow down with problem size, but at different rates:
| Problem Size | couplr (JV) | couplr (greedy) | MatchIt (nearest) | optmatch |
|---|---|---|---|---|
| n = 100 | < 0.01s | < 0.01s | < 0.01s | < 0.01s |
| n = 500 | 0.05s | 0.01s | 0.1s | 0.1s |
| n = 1,000 | 0.5s | 0.02s | 0.5s | 0.3s |
| n = 5,000 | 30s | 0.5s | 5s | 2s |
| n = 10,000 | > 60s | 2s | 20s | 10s |
Note: couplr’s greedy matching is fastest for large problems. For optimal matching, optmatch’s RELAX-IV is competitive. couplr offers more algorithm choices for different scenarios.
| Package | Memory Model |
|---|---|
| couplr | Full distance matrix by default; greedy avoids this |
| MatchIt | Propensity scores + sparse distance |
| optmatch | Sparse distance matrices |
| designmatch | Full distance + constraint matrices |
For very large problems (n > 10,000), use couplr’s blocking or greedy modes.
| Feature | couplr | MatchIt | optmatch | designmatch | Matching |
|---|---|---|---|---|---|
| One-to-one matching | ✓ | ✓ | ✓ | ✓ | ✓ |
| Full matching | ✗ | ✓ | ✓ | ✓ | ✗ |
| Optimal assignment | ✓ (20 algorithms) | ✓ (1 algorithm) | ✓ | ✓ | ✗ |
| Greedy matching | ✓ (3 strategies) | ✓ | ✗ | ✗ | ✓ |
| Propensity scores | ✗ (external) | ✓ | ✓ | ✗ | ✓ |
| Direct covariate | ✓ | ✓ | ✓ | ✓ | ✓ |
| Blocking/exact | ✓ | ✓ | ✓ | ✓ | ✓ |
| Caliper | ✓ | ✓ | ✓ | ✓ | ✓ |
| Balance constraints | ✗ | ✗ | ✗ | ✓ | ✗ |
| Genetic optimization | ✗ | ✓ (GenMatch) | ✗ | ✗ | ✓ |
| Distance caching | ✓ | ✗ | ✓ | ✗ | ✗ |
| Parallel processing | ✓ (blocks) | ✗ | ✗ | ✗ | ✗ |
| Deterministic | ✓ | ✓ | ✓ | ✓ | ✗ |
| Tidy interface | ✓ | Partial | ✗ | ✗ | ✗ |
# Stage 1: couplr for initial matching
matched <- match_couples(
left = treatment_data,
right = control_data,
vars = covariates,
auto_scale = TRUE
)
# Stage 2: Check balance
balance <- balance_diagnostics(matched, treatment_data, control_data, covariates)
# Stage 3: If balance insufficient, consider alternatives
if (balance$overall$max_abs_std_diff > 0.25) {
# Try MatchIt with propensity scores
library(MatchIt)
combined <- bind_rows(treatment_data, control_data)
m_ps <- matchit(treated ~ ., data = combined, method = "full")
}
# Stage 4: Analysis on matched data
matched_data <- join_matched(matched, treatment_data, control_data)
model <- lm(outcome ~ treatment, data = matched_data)Different packages excel at different tasks:
{r, eval = FALSE } # Use couplr for: initial exploration, large-scale matching, distance caching # Use MatchIt for: propensity scores, full matching, published protocols # Use optmatch for: optimal full matching with sparse distances # Use designmatch for: guaranteed balance constraints
This section applies couplr to a dataset inspired by the classic Lalonde (1986) job training evaluation, demonstrating the full workflow on realistic data.
The National Supported Work (NSW) demonstration was a randomized job training program. The methodological challenge is evaluating the program using observational (non-randomized) comparison groups, which introduces selection bias.
Typical covariates: age, education, race, marital status, prior earnings (re74, re75), employment status.
set.seed(1986)
# NSW treatment group (randomized) - smaller sample for CRAN
nsw_treat <- tibble(
id = 1:100,
age = pmax(17, rnorm(100, 25, 7)),
education = pmax(0, pmin(16, rnorm(100, 10, 2))),
black = rbinom(100, 1, 0.84),
hispanic = rbinom(100, 1, 0.06),
married = rbinom(100, 1, 0.19),
nodegree = rbinom(100, 1, 0.71),
re74 = pmax(0, rnorm(100, 2100, 5000)),
re75 = pmax(0, rnorm(100, 1500, 3500)),
group = "treatment"
)
# CPS comparison group (observational - very different!)
# Reduced from 15,815 to 500 for CRAN timing compliance
cps_control <- tibble(
id = 101:600,
age = pmax(17, rnorm(500, 33, 11)),
education = pmax(0, pmin(16, rnorm(500, 12, 3))),
black = rbinom(500, 1, 0.07),
hispanic = rbinom(500, 1, 0.07),
married = rbinom(500, 1, 0.71),
nodegree = rbinom(500, 1, 0.30),
re74 = pmax(0, rnorm(500, 14000, 9000)),
re75 = pmax(0, rnorm(500, 13500, 9000)),
group = "control"
)
cat("NSW treatment:", nrow(nsw_treat), "individuals\n")
#> NSW treatment: 100 individuals
cat("CPS control:", nrow(cps_control), "individuals\n")
#> CPS control: 500 individuals
cat("(Note: Real CPS has ~16,000 controls; reduced here for vignette timing)\n")
#> (Note: Real CPS has ~16,000 controls; reduced here for vignette timing)
# Baseline imbalance is severe
vars_lalonde <- c("age", "education", "black", "hispanic", "married",
"nodegree", "re74", "re75")
cat("\nBaseline standardized differences:\n")
#>
#> Baseline standardized differences:
for (v in vars_lalonde) {
t_mean <- mean(nsw_treat[[v]])
c_mean <- mean(cps_control[[v]])
pooled_sd <- sqrt((var(nsw_treat[[v]]) + var(cps_control[[v]])) / 2)
std_diff <- (t_mean - c_mean) / pooled_sd
cat(sprintf(" %s: %.2f\n", v, std_diff))
}
#> age: -0.87
#> education: -0.78
#> black: 2.27
#> hispanic: -0.07
#> married: -1.21
#> nodegree: 0.75
#> re74: -1.60
#> re75: -1.83With treatment vs control groups of different sizes, we need efficient matching. couplr handles this with greedy matching:
# Greedy matching (fast for large control pools)
result_lalonde <- greedy_couples(
left = nsw_treat,
right = cps_control,
vars = vars_lalonde,
strategy = "pq", # Priority queue - efficient for large pools
auto_scale = TRUE,
scale = "robust"
)
cat("Matched", result_lalonde$info$n_matched, "of", nrow(nsw_treat), "treatment units\n")
#> Matched 100 of 100 treatment units
cat("Mean distance:", round(mean(result_lalonde$pairs$distance), 4), "\n")
#> Mean distance: 1.5267balance_lalonde <- balance_diagnostics(
result_lalonde, nsw_treat, cps_control, vars_lalonde
)
#> Warning in ks.test.default(left_clean, right_clean): p-value will be
#> approximate in the presence of ties
#> Warning in ks.test.default(left_clean, right_clean): p-value will be
#> approximate in the presence of ties
#> Warning in ks.test.default(left_clean, right_clean): p-value will be
#> approximate in the presence of ties
#> Warning in ks.test.default(left_clean, right_clean): p-value will be
#> approximate in the presence of ties
#> Warning in ks.test.default(left_clean, right_clean): p-value will be
#> approximate in the presence of ties
#> Warning in ks.test.default(left_clean, right_clean): p-value will be
#> approximate in the presence of ties
#> Warning in ks.test.default(left_clean, right_clean): p-value will be
#> approximate in the presence of ties
# Before/after comparison
before_df <- tibble(
variable = vars_lalonde,
std_diff = sapply(vars_lalonde, function(v) {
t_mean <- mean(nsw_treat[[v]])
c_mean <- mean(cps_control[[v]])
pooled_sd <- sqrt((var(nsw_treat[[v]]) + var(cps_control[[v]])) / 2)
(t_mean - c_mean) / pooled_sd
}),
stage = "Before"
)
after_df <- balance_lalonde$var_stats %>%
select(variable, std_diff) %>%
mutate(stage = "After")
balance_plot_df <- bind_rows(before_df, after_df) %>%
mutate(stage = factor(stage, levels = c("Before", "After")))
ggplot(balance_plot_df, aes(x = reorder(variable, abs(std_diff)),
y = std_diff, fill = stage)) +
geom_col(position = "dodge") +
geom_hline(yintercept = c(-0.1, 0.1), linetype = "dashed", color = "#93c54b") +
geom_hline(yintercept = c(-0.25, 0.25), linetype = "dashed", color = "#f47c3c") +
coord_flip() +
labs(
title = "Covariate Balance: Before vs After Matching",
subtitle = "Lalonde-style job training evaluation",
x = "",
y = "Standardized Difference",
fill = ""
) +
scale_fill_manual(values = c("Before" = "#d9534f", "After" = "#93c54b")) +
theme_minimal() +
theme(
legend.position = "bottom",
plot.title = element_text(face = "bold")
)The matching dramatically reduces imbalance:
cat("Balance summary:\n")
#> Balance summary:
cat(" Mean |std diff| before:",
round(mean(abs(before_df$std_diff)), 3), "\n")
#> Mean |std diff| before: 1.171
cat(" Mean |std diff| after:",
round(balance_lalonde$overall$mean_abs_std_diff, 3), "\n")
#> Mean |std diff| after: 0.748
cat(" Max |std diff| after:",
round(balance_lalonde$overall$max_abs_std_diff, 3), "\n")
#> Max |std diff| after: 1.97
if (balance_lalonde$overall$max_abs_std_diff < 0.25) {
cat("\n✓ All variables within acceptable balance threshold (0.25)\n")
} else {
cat("\n⚠ Some variables exceed 0.25 threshold - consider calipers or blocking\n")
}
#>
#> ⚠ Some variables exceed 0.25 threshold - consider calipers or blockingFor comparison, optimal matching would require full distance matrix computation (n × m entries), but greedy matching finds excellent matches in milliseconds. With real CPS data (15,815 controls), this efficiency becomes critical.
Ho, D. E., Imai, K., King, G., & Stuart, E. A. (2011). MatchIt: Nonparametric preprocessing for parametric causal inference. Journal of Statistical Software, 42(8), 1-28. doi:10.18637/jss.v042.i08
Hansen, B. B., & Klopfer, S. O. (2006). Optimal full matching and related designs via network flows. Journal of Computational and Graphical Statistics, 15(3), 609-627. doi:10.1198/106186006X137047
Zubizarreta, J. R., Kilcioglu, C., & Vielma, J. P. (2018). designmatch: Matched samples that are balanced and representative by design. R package. CRAN
Sekhon, J. S. (2011). Multivariate and propensity score matching software with automated balance optimization: The Matching package for R. Journal of Statistical Software, 42(7), 1-52. doi:10.18637/jss.v042.i07
LaLonde, R. J. (1986). Evaluating the econometric evaluations of training programs with experimental data. The American Economic Review, 76(4), 604-620.
vignette("getting-started") - Basic couplr usagevignette("matching-workflows") - Production matching
pipelinesvignette("algorithms") - LAP algorithm selection
guidevignette("troubleshooting") - Common issues and
solutionsThese binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.