Solve a Sequence of Matchings over One Design Parameter

Solves the matching once for each value of one argument and returns what happened at each: how many units were matched, at what total distance, how balanced the matched sample is, and the certificate saying the matching is optimal for that value. The points are solved as one sequence rather than one at a time, each starting from the matching the previous value found.

Usage

match_path(
  left,
  right,
  vars,
  left_id = NULL,
  right_id = NULL,
  vary = "max_distance",
  values,
  distance = "euclidean",
  weights = NULL,
  scale = FALSE,
  auto_scale = FALSE,
  calipers = NULL,
  sigma = NULL,
  certify = TRUE,
  keep_per_row = .implicit_defaults()$keep_per_row,
  width = .implicit_defaults()$width,
  tol = .implicit_defaults()$tol,
  max_rounds = .implicit_defaults()$max_rounds
)

# S3 method for class 'couplr_path'
print(x, ...)

# S3 method for class 'couplr_path'
summary(object, ...)

# S3 method for class 'couplr_path'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  what = c("path", "balance"),
  ...
)

# S3 method for class 'couplr_path'
plot(x, threshold = 0.1, ...)

Arguments

left, right: Data frames to match. Both are required.
vars: Character vector of matching variables, present in both.
left_id, right_id: Name of the column holding the unit identifier, or NULL (default) to use a column called id, then meaningful row names, then synthesized ids with a warning. See match_couples().
vary: The argument to sweep. "max_distance" sweeps the distance cut.
values: The values to sweep it through, ascending.
distance: Distance metric, as in match_couples().
weights, scale, auto_scale, sigma: Distance construction, as in match_couples().
calipers: Per-variable calipers held fixed across the path, as in match_couples(). Balance is read on the caller's own variables rather than on the coordinates the solver worked in, so a scaled or weighted distance does not change the scale the balance is reported on. It is the same reading balance_diagnostics() gives for a single matching, taken at every point of the sweep.
certify: Whether each point carries a checked certificate. TRUE by default: the certificate is what says a point's matching is the optimal one for its value, which is the claim a path is read for.
keep_per_row, width, tol, max_rounds: The edge-generation loop's search knobs, shared with memory_mode = "implicit". Each point converges on any of them. width is the columns the seed gives a row, and 0, the default, sizes it from the number of columns; $search$seed_width reports what the path used.
x, object: A couplr_path from match_path().
...: Ignored.
row.names, optional: Ignored.
what: For as.data.frame(): "path" (one row per point) or "balance" (one row per point and variable).
threshold: For plot(): reference line for the largest absolute standardized difference (default 0.1).

Value

An object of class couplr_path: $path, one row per point, $balance, one row per point per variable, and the match vector, certificate, round record and Hall witness for each of them.

Details

values must ascend. Each point is solved from the point before it, which works because a wider value only ever adds pairs to choose from; a descending sweep takes pairs away from a matching already using them, and is refused rather than reordered.

Examples

set.seed(1)
left <- data.frame(id = 1:20, x = rnorm(20), y = rnorm(20))
right <- data.frame(id = 1:60, x = rnorm(60), y = rnorm(60))
path <- match_path(left, right, vars = c("x", "y"),
                   vary = "max_distance", values = c(0.5, 1, 2, Inf))
as.data.frame(path)
summary(path)