optmatch (version 0.8-0)

fullmatch: Optimal full matching

Description

Given two groups, such as a treatment and a control group, and a treatment-by-control discrepancy matrix indicating desirability and permissibility of potential matches, create optimal full matches of members of the groups. Optionally, incorporate restrictions on matched sets' ratios of treatment to control units.

Usage

fullmatch(distance, min.controls = 0, max.controls = Inf,
    omit.fraction = NULL, tol = 0.001, data = NULL)

Arguments

distance

A matrix of non-negative discrepancies, each indicating the permissibility and desirability of matching the unit corresponding to its row (a 'treatment') to the unit corresponding to its column (a 'control'); or, better, a distance specification a

min.controls

The minimum ratio of controls to treatments that is to be permitted within a matched set: should be non-negative and finite. If min.controls is not a whole number, the reciprocal of a whole number, or zero, then it is rounded d

max.controls

The maximum ratio of controls to treatments that is to be permitted within a matched set: should be positive and numeric. If max.controls is not a whole number, the reciprocal of a whole number, or Inf, then it is rounded

omit.fraction

Optionally, specify what fraction of controls or treated subjects are to be rejected. If omit.fraction is a positive fraction less than one, then fullmatch leaves up to that fraction of the control reservoir unmatched.

tol

Because of internal rounding, fullmatch may solve a slightly different matching problem than the one specified, in which the match generated by fullmatch may not coincide with an optimal solution of the specified problem.

data

Optional data.frame or vector to use to get order of the final matching factor. If a data.frame, the rownames are used. If a vector, the names are first tried, otherwise the contents

Value

• A optmatch object (factor) indicating matched groups.

Details

Finite entries in matrix slots of distance indicate permissible matches, with smaller discrepancies indicating more desirable matches. Matrix distance must have row and column names.

Consider using match_on to generate the distances. This generic function as several useful methods for handling propensity score models, computing Mahalanobis distances (and other arbitrary distances), and using user supplied functions. These distances can also be combined with those generated by exactMatch and caliper to create very nuanced matching specifications.

The value of tol can have a substantial effect on computation time; with smaller values, computation takes longer. Not every tolerance can be met, and how small a tolerance is too small varies with the machine and with the details of the problem. If fullmatch can't guarantee that the tolerance is as small as the given value of argument tol, then matching proceeds but a warning is issued.

References

Hansen, B.B. and Klopfer, S.O. (2006), Optimal full matching and related designs via network flows, Journal of Computational and Graphical Statistics, 15, 609--627.

Hansen, B.B. (2004), Full Matching in an Observational Study of Coaching for the SAT, Journal of the American Statistical Association, 99, 609--618.

Rosenbaum, P. (1991), A Characterization of Optimal Designs for Observational Studies, Journal of the Royal Statistical Society, Series B, 53, 597--610.

Examples

data(nuclearplants)
### Full matching on a Mahalanobis distance
mhd  <- match_on(pr ~ t1 + t2, data = nuclearplants)
( fm1 <- fullmatch(mhd, data = nuclearplants) )
summary(fm1)
### Full matching with restrictions
( fm2 <- fullmatch(mhd, min=.5, max=4, data = nuclearplants) )
summary(fm2)
### Full matching to half of available controls
( fm3 <- fullmatch(mhd, omit.fraction=.5, data = nuclearplants) )
summary(fm3)
### Full matching within a propensity score caliper.
ppty <- glm(pr~.-(pr+cost), family=binomial(), data = nuclearplants)
### Note that units without counterparts within the
### caliper are automatically dropped.
( fm4 <- fullmatch(mhd + caliper(match_on(ppty), 1), data = nuclearplants) )
summary(fm4)

### Propensity balance assessment. Requires RItools package.
if (require(RItools)) summary(fm4,ppty) 

### The order of the names in the match factor is the same
### as the nuclearplants data.frame since we used the data argument
### when calling fullmatch. The order would be unspecified otherwise.
cbind(nuclearplants, matches = fm4)