optmatch (version 0.7-5)

caliper: Prepare matching distances suitable for matching within calipers

Description

Encodes calipers, or maximum allowable distances within which to match, calling mdist() on the supplied arguments to calculate the distance on which the caliper is based. (One then applies pairmatch() or fullmatch() to the value of caliper, or to the sum of it and another distance, to match within calipers.)

Usage

caliper(width, ..., exclude = c(), penalty = Inf)

Arguments

width

The width of the caliper: how wide of a margin to allow in matches.

...

Arguments are passed to mdist(), which forms the basic distance matrix. The caliper is then fit to this matrix. See mdist for more information.

exclude

A character vector of observations (corresponding to rownames) to exclude from the caliper.

penalty

Attach a penalty (to be mulitplied to the distance value) for pairs outside of the caliper. The default of Inf prevents matches between such pairs; finite values of penalty permit such matches but discourage them.

Value

• Object of class optmatch.dlist, which is suitable to be given as distance argument to fullmatch or pairmatch. For more information, see pscore.dist

Details

width provides the size of the caliper, the allowable distance for matching. The unit of width will depend on the additional arguments, used to create a basic distance matrix using mdist. There must be at least one such argument, mdist's x. For a formula x argument, width will be in units of the selected covariate(s), specifically squared Mahalanobis distances on those covariates; see Details of mdist. For instance, with a formula with a single, non-categorical covariate on its right hand side, caliper widths are expressed in terms of the variance of that covariate. For a GLM x argument, width is interpreted in pooled standard deviations of the linear propensity score. (If the propensity was fit using glm or similar, this is the linear predictor from that fit, not the fitted conditional probability.) If you pass a matching distance as an additional argument -- that is, a matrix or an object that was produced by mdist -- width is interpreted in the units of that matching distance.

References

P.~R. Rosenbaum and D.~B. Rubin (1985), Constructing a control group using multivariate matched sampling methods that incorporate the propensity score, The American Statistician, 39 33--38.

See Also

mdist, fullmatch, pairmatch

Examples

data(nuclearplants)

### Caliper  of .2 pooled SDs in the propensity score
ppty <- glm(pr~.-(pr+cost), family=binomial(), data=nuclearplants)
(pptycaliper <- caliper(ppty, width = .2))

identical(pptycaliper,  # If not writing 'width=',
caliper(.2,ppty))        # give your width first.

### Caliper on a pre-formed distance
ppty.dist <- mdist(ppty) 
identical(caliper(ppty.dist, width = .2), pptycaliper)

### caliper of 1.5 on the _squared_ Mahalanobis distance
caliper(width = 1.5, pr ~ t1 + t2,
  data = subset(nuclearplants, subset=(pt==1)))             

### caliper of 1.5 on the Mahalanobis distance
caliper(width = 1.5^2, pr ~ t1 + t2,
  data = subset(nuclearplants, subset=(pt==1)))             


### caliper of .6 on date, in its original units (here, years):
caliper(width=.6^2, pr ~ date, inverse.cov=diag(1),
  data = subset(nuclearplants, subset=(pt==1)))

### caliper of .6 on date, in pooled sd's of date:
caliper(width=.6^2, pr ~ date, 
  data = subset(nuclearplants, subset=(pt==1)))


### Mahalanobis distance matching with a caliper
### of 1 pooled SD in the propensity score:
( mhd.pptyc <- caliper(ppty, width = 1) +
  mdist(pr ~ t1 + t2, data = nuclearplants) )
pairmatch(mhd.pptyc)

### Excluding observations from caliper requirements:
caliper(width = 3, pr ~ t1 + t2, data = nuclearplants, exclude = c("A", "f"))