opt_nearfar {nearfar}

Finds optimal near-far match

Description

Discovers optimal near-far matches using the partial F statistic (for continuous treatments) or partial deviance (for binary and treatments)

Usage

opt_nearfar(dta, trt, covs, iv, trt.type = "cont", imp.var = NA,
tol.var = NA, adjust.IV = TRUE, sink.range = c(0, 0.5), cutp.range = NA,
max.time.seconds = 300)

Arguments

dta

The name of the data frame on which matching was performed

trt

The name of the treatment variable, e.g., “educ”

iv

The name of the instrumental variable, e.g., iv="QOB"

covs

A vector of the names of the covariates to make “near”, e.g., covs=c("age", "sex", "race")

trt.type

Treatment variable type: “cont” for continuous, or “bin” for binary

imp.var

A list of (up to 5) named variables to prioritize in the “near” matching

tol.var

A list of (up to 5) tolerances attached to the prioritized variables where 0 is highest penalty for mismatch

adjust.IV

if TRUE, include measured confounders in treatment~IV model that is optimized; if FALSE, exclude

sink.range

A two element vector of (min, max) for range of sinks over which to optimize in the near-far match; default (0, 0.5) such that maximally 50% of observations can be removed

cutp.range

a two element vector of (min, max) for range of cutpoints (how far apart the IV will become) over which to optimize in the near-far match; default is (one SD of IV, range of IV)

max.time.seconds

How long to let the optimization algorithm run; default is 300 seconds = 5 minutes

Value

n.calls

Number of calls made to the objective function

sink.range

A two element vector of (min, max) for range of sinks over which to optimize in the near-far match; default (0, 0.5) such that maximally 50% of observations can be removed

cutp.range

a two element vector of (min, max) for range of cutpoints (how far apart the IV will become) over which to optimize in the near-far match; default is (one SD of IV, range of IV)

pct.sink

Optimal percent sinks

cutp

Optimal cutpoint

maxF

Highest value of partial F-statistic (continuous treatment) or residual deviance (binary treatment) found by simulated annealing optimizer

match

A two column matrix where the first column is the index of an “encouraged” individual and the second column is the index of the corresponding “discouraged” individual from the pair matching

summ

A table of mean variable values for both the “encouraged” and “discouraged” groups across all variables plus absolute standardized differences for each variable

Author(s)

Joseph Rigdon [e-mail]

References

Lu B, Greevy R, Xu X, Beck C (2011). Optimal nonbipartite matching and its statistical applications. The American Statistician, 65(1), 21-30.

Xiang Y, Gubian S, Suomela B, Hoeng J (2013). Generalized Simulated Annealing for Efficient Global Optimization: the GenSA Package for R. The R Journal, 5(1). URL http://journal.r-project.org/.

Examples

k = opt_nearfar(dta=mtcars, trt="drat", covs=c("cyl", "disp"),
    trt.type="cont", iv="carb", imp.var=NA, tol.var=NA, adjust.IV=TRUE,
    max.time.seconds=2)
summary(k)