*! version 1.0.0 9may2017

Title

calipmatch -- General caliper matching, without replacement

Syntax

Create a variable indicating groups of matched cases and controls

calipmatch
[if] [in],
generate(newvar)
casevar(varname)
maxmatches(#)
calipermatch(varlist)
caliperwidth(numlist)
[exactmatch(varlist)]

options

Required
generate(newvar) variable to generate
indicating groups of matched cases and controls

casevar(varname) binary variable with cases=1 and controls=0

maxmatches(#) maximum number of controls to match with each case

calipermatch(varlist) list of numeric variables to match on using
calipers

caliperwidth(numlist) list of caliper widths to use for caliper
matching

Optional
exactmatch(varlist) list of integer variables to match on exactly

Description

calipmatch matches case observations to control observations using "calipers",
generating a new variable with a unique value for each group of matched cases and controls.
It performs 1:1 or 1:m matching without replacement.

Matched observations must have values within +/- the caliper
width for every caliper matching variable. Matched observations must also have identical values
for every exact matching variable, if any exact matching variables are specified.

Controls are randomly matched to cases without replacement. For each case, calipmatch
searches for matching controls until it either finds the pre-specified maximum number of
matches or runs out of controls. The search is performed greedily: it is possible that
some cases end up unmatched because all possible matching controls have already been matched with
another case.

Options

Required

generate(newvar) specifies a new variable to be generated,
indicating groups of matched cases and controls. If M case observations
were successfully matched to control observations, then this new variable
will take values {1, ..., M}. Each of the matched case observations will
be assigned a unique value. Each of the matched control observations
will be assigned the same value as the case it is matched to.

casevar(varname) specifies the binary variable that indicates whether
each observation is a case (=1) or a control (=0). Observations with a
missing value are excluded from matching.

maxmatches(#) sets the maximum number of controls to be matched
with each case. Setting maxmatches(1) performs a 1:1 matching: calipmatch
searches for one matching control observation for each case observation.

By setting maxmatches(#) greater than 1, calipmatch will proceed in
random order through
the cases and search for matching control observations until it either finds the
maximum number of matches or runs out of controls. The search is performed greedily: it
is possible that some cases end up unmatched because all possible matching
controls have already been matched with another case.

calipermatch(varlist) is a list of one or more numeric variables to
use for caliper matching. Matched observations must have values within +/- the caliper
width for every caliper matching variable listed.

caliperwidth(numlist) is a list of positive numbers to use as caliper
widths. The widths are associated with caliper matching variables using the order they are
listed in: the first number will be used as the width for the first caliper
matching variable, etc.

Optional

exactmatch(varlist) is a list of one or more integer-valued variables to use
for exact matching. When specified, matched observations must not only match on the caliper
matching variables, they must also have identical values for every exact matching variable.

Exact matching variables must have a data type of byte,
int or long. This enables speedy exact matching, by ensuring that
all values are stored as precise integers.

Saved results

calipmatch saves the following in r():

Scalars

r(cases_total) number of cases in sample

r(cases_matched) number of matched cases in sample

r(match_rate) fraction of cases matched to controls

Matrices

r(matches) tabulation of number of controls matched to each case

Authors

Michael Stepner

Massachusetts Institute of Technology

stepner@mit.edu

Allan Garland, M.D. M.A.

University of Manitoba Faculty of Medicine

agarland@hsc.mb.ca