Last updated August 29, 2001

{smcl}
{hline}
help for {hi: psmatch}
{hline}

{title: Perform various types of propensity score matching}

{p 8 25}
{cmdab: psmatch}
{it: treatvar}
{cmd:,} {{cmdab:on(}{it:matchvar1} [{it:matchvar2} [{it:matchvar3}]]{cmd:)}|{cmdab:est:imate}{cmd:(}{it:varlist}{cmd:)}} {p_end}
{p 25 25}   
  [ {cmdab:log:it} 
  {cmdab:ind:ex} 
  {cmdab:cal:iper}{cmd:(}{it:real}{cmd:)}
  {cmdab:out:come}{cmd:(}{it:outcomevar}{cmd:)}
  {cmdab:id}{cmd:(}{it:idvar}{cmd:)}
  {cmdab:ker:nel}{cmd:(}{it:outcomevar}{cmd:)}
  {cmdab:bw:idth}{cmd:(}{it:real}{cmd:)} 
  {cmdab:ep:an}
  {cmdab:tr:icube}{cmd:(}{it:outcomevar}{cmd:)}
  {cmdab:spl:ine}{cmd:(}{it:outcomevar}{cmd:)}
  {cmdab:nk:nots}{cmd:(}{it:integer}{cmd:)}
  {cmdab:me:an}{cmd:(}{it:outcomevar}{cmd:)}
  {cmdab:nei:ghbour}{cmd:(}{it:integer}{cmd:)}
  {cmdab:li:ne}{cmd:(}{it:outcomevar}{cmd:)}
  {cmdab:low:ess}{cmd:(}{it:outcomevar}{cmd:)}
  {cmdab:bo:th}
  {cmdab:nocommon}
  {cmdab:noc:ount}
  {cmdab:qua:lity}{cmd:(}{it:varlist}{cmd:)}
  {cmdab:sa:ving}{cmd:(}{it:filename}{cmd:)}
  {cmdab:boot:strap}
  {cmdab:r:eps(}{it:integer}{cmd:)} {cmdab:d:ots}
  {cmdab:si:ze(}{it:integer}{cmd:)} 
  {cmdab:ev:ery(}{it:integer}{cmd:)} {cmd:replace} 
  {cmdab:doub:le} {cmdab:l:evel(}{it:integer}{cmd:)} ]


{title:Description}

{p}
{it:treatvar} is a 0-1 variable identifying two groups, 1 for the 'treated' and 0 for the 'controls'.   
{cmd: psmatch} pairs to each treated unit one or more 'comparable' (in terms of the {it: matchvars}) non-treated        
units and associates to the outcome of the treated unit,               
the (weighted) outcomes of his 'neighbours' in the comparison group,   
where the weights can optionally depend on their 'distance' to the treated unit under consideration.                


{title:Options}

{p 0 4}
{cmd:on}{cmd:(}{it:matchvar1} [{it:matchvar2} [{it:matchvar3}]]{cmd:)} specifies the  
variable(s) on which to match.
The 'propensity score', the probability of belonging to the treated group given observable 
characteristics, can be used as a summary of these characteristics (Rosenbaum and Rubin, 1983). It can be 
estimated via {help logit} or {help probit} regressions, 
and the predicted probability or the index used as {it: matchvar1}. 
I suggest the use of {com:double} as storage type for {it: matchvar1} in order to decrease the likelihood of 
multiple 'exact' matches for a given treated.
If a second or third {it: matchvar} is specified (e.g. matching on a finer basis, or
on multiple scores estimated from 
a multinomial model such as {help mlogit} or {help nlogit}), {cmd: psmatch} will look for the 
closest match in terms of the Mahalanobis distance constructed from the two or three variables.
This {com: Mahalanobis-metric matching} (formula from Rubin, 1980) is presently only allowed for the one-to-one and kernel-based (gaussian
and epanechnikov) versions. 
Note: 1) Mahalanobis-metric matching may take long to implement.
2) If required, it is the user who has in this case to programme bootstrapping with the appropiate scores estimation procedure.


{p 0 4}
{cmd:estimate}{cmd:(}{it:varlist}{cmd:)} is an alternative to  
{cmd:on}{cmd:(}{it:matchvar1}{cmd:)} and estimates the propensity score 
(i.e. the predicted probability, unless the option {cmd:index} is specified)
using the user-specified {it:varlist} as regressors in a probit model (unless the 
option {cmd:logit} is specified).
{p_end}
{p 4 4}
Either {cmd:on} or {cmd:estimate} must be specified.

{p 0 4}                                                      
{cmd:logit} uses a logit model to {cmd:estimate} the propensity score.

{p 0 4}                                                      
{cmd:index} requires the use of the linear index as the propensity score when {cmd:estimate}d.

{p}
If no smoothing type of matching is specifed via the options {cmd:kernel}, {cmd:spline}, {cmd:mean}, 
{cmd:line}, {cmd:lowess} or {cmd:tricube}, the default is to perform 
{com:one-to-one} (or {com:nearest-neighbour}) {com:matching with replacement}:
{p_end}
{p}
To each treated unit that single control unit with the closest propensity score is matched;
a given control unit can be matched to more than one treated unit. This latter choice is 
necessary for estimation in the multiple-treatment case,
where each sub-group will act both as a treated group and as (several) comparison groups.
Two new variables are created:

{p 4 4}
{com: _times} stores the number of times a unit is used (1 for all matched treated); it is missing
for the unmatched treated and unmatched control units.
In subsequent analyses use {inp: [fw=_times]} or else {inp: expand _times}
{p_end}
{p 4 4}
{com: _matchdif} is defined only for matched treated and stores the absolute distance 
(in terms of the propensity score or the Mahalanobis metric) of that treated unit with its matched control. 
It is useful to assess matching quality and decide on possibly refining or widening the caliper.

{p 0 4}
{cmd:caliper}{cmd:(}{it:real}{cmd:)} calls for {com:one-to-one caliper matching} 
(Cochran and Rubin, 1973) with replacement to be performed: 
Treated units for which no control unit is found within the maximum absolute distance given by the caliper 
are left unmatched. 

{p 0 4}
{cmd:id}{cmd:(}{it:idvar}{cmd:)} specifies the {it:numeric} variable identifying the individual units. 
If specified, the programme will check that the dataset contains only one observation
per individual, as needed by {cmd:psmatch}.{p_end}
{p 4 4}
For one-to-one matching, it will also ensure that the same matched control 
is always used should there be multiple 'exact' matches. Secondly, it will create the variable {com: _matchedid}, 
defined only for matched treated and storing the identifier {it:idvar} of the 
corresponding matched control.

{p 0 4}
{cmd:outcome}{cmd:(}{it:outcomevar}{cmd:)} specifies the numeric outcome variable which the user
intends to evaluate by one-to-one matching. If specified, the means of {it:outcomevar}
for the matched treated and for the matched controls, together with their difference, 
an approximate standard error of the effect and the corresponding t-test statistic 
will be directly displayed after matching is performed. Secondly, a new variable {com:_moutcomevar}
will be created, storing for each matched treated the {it:outcomevar} of his matched control.

{p 0 4}
{cmd:kernel}{cmd:(}{it:outcomevar}{cmd:)} 
asks for {com: kernel-based matching} to be performed (Heckman et al., 1997 and 1998). {it:outcomevar} is the outcome being 
evaluated. All controls are used to construct a weighted matched {it:outcomevar} for a given 
treated unit (within the common support). These values are stored in the new variable, 
{com: _moutcomevar}.

{p 0 4}
{cmd: bwidth}{cmd:(}{it:real}{cmd:)} specifies the bandwidth to be used for {cmd:kernel}. Default is 0.06.
It is also the bandwidth to be used by {cmd:mean}, {cmd:line}, {cmd:lowess} and {cmd:tricube}, this
time however constrained in (0,1] and expressed in terms of the percentage of non-treated units 
to be used in smoothing.
Default is 0.8.

{p 0 4}
{cmd: epan} specifies that the Epanechnikov kernel be used by {cmd:kernel} rather than the 
default Gaussian one.
This means that only those controls falling within a radius of {cmd:bwdith} are used to construct 
{com: _moutcomevar} for a given 
treated unit (within the common support). 

{p 0 4}       
{cmd: tricube}{cmd:(}{it:outcomevar}{cmd:)} performs kernel-based matching using a tricube weight.
Only those controls within a neighbourhood determined by {cmd:bwdith} are used to construct a weighted matched {it:outcomevar} for a given 
treated unit (within the common support). These values are stored in the new variable, 
{com: _moutcomevar}.

{p 0 4}                                   
{cmd:spline}{cmd:(}{it:outcomevar}{cmd:)} performs '{com:spline-smoothing matching}' by first
fitting a natural cubic spline on {it:matchvar1}
(or on the result from {cmd: estimate}) to {it:outcomevar} for the non-treated. The matched values are
stored in the new variable, {com:_moutcomevar}.
It requires the STB spline programme, which can be downloaded by typing: {p_end}
{p 4 4}
{inp:net install snp7_1}.

{p 0 4}       
{cmd: nknots}{cmd:(}{it:integer}{cmd:)} specifies the number of interior knots for spline smoothing. 
Default is the fourth root of the number of non-treated units. 

{p 0 4}       
{cmd: mean}{cmd:(}{it:outcomevar}{cmd:)} performs {com:nearest-neighbours matching} (with equal weights).
The number of non-treated neighbours is governed by either {cmd:bwidth} (default is 0.8) or more directly
by {cmd:neighbour}. The matched values are stored in the new variable, {com:_moutcomevar}.

{p 0 4}       
{cmd: neighbour}{cmd:(}{it:integer}{cmd:)} (or {cmd: neighbor()}) specifies the number of neighbours for nearest-neighbours matching.

{p 0 4}       
{cmd: line}{cmd:(}{it:outcomevar}{cmd:)} performs '{com:least-squares-smoothing matching}', obtained
by locally fitting an (unweighted) line in the neighbourhood determined by {cmd:bwidth}. The matched values are
stored in the new variable, {com:_moutcomevar}.

{p 0 4}       
{cmd: lowess}{cmd:(}{it:outcomevar}{cmd:)} performs a type of {com:local linear matching} (Heckman et al., 1997), smoothing the 
non-treated in a neighbourhood determined by {cmd:bwidth} and weighting their contribution by a tricube weight.
The matched values are stored in the new variable, {com:_moutcomevar}.

{p 0 4}
{cmd: both} asks {cmd:kernel} or {cmd:tricube} or {cmd:spline} or {cmd:mean} or {cmd:line} or {cmd:lowess}
to smooth {it:outcomevar} for the treated as well and to store the smoothed values 
in the new {com:_soutcomevar}.

{p 0 4}
{cmd: nocommon} forces treated individuals outside the common support to be matched too
(for the smoothed matching estimators).

{p 0 4}
{cmd: nocount} suppresses the display of the 'count down' of the treated being matched - which 
is shown by default in the more
time-consuming types of estimators (one-to-one on more than one score; kernel) -, as well
as the display of a summary of instructions (log files should remain unaffected anyway).

{p 0 4}       
{cmd: quality}{cmd:(}{it:varlist}{cmd:)} creates a new dataset (named as specified by the {cmd:saving} option)
containing (one-to-one) matching quality indicator variables for the regressors specified in {it:varlist}.
The variables in the created dataset are: a string variable storing the name of the regressor,
the corresponding means in the treated and control groups (both for the full and for the matched groups),
the standardised percentage bias (a) before and (b) after matching for that regressor 
(the difference of the sample means in the treated and non-treated - (a) full or (b) matched - 
sub-samples as a percentage of the square root of the average of the sample variances in the treated 
and non-treated groups; formulae from Rosenbaum and Rubin, 1985), 
and the percentage bias reduction. 

{p 0 4}{cmd:saving(}{it:filename}{cmd:)} creates a dataset named {it:filename}.dta 
containing either the quality information requested if {cmd:quality} was specified
or the bootstrap distribution for the treatment effect if {cmd:bootstrap} was specified.
Note that for {cmd:quality}, a dataset with the same {it:filename} will {hi:automatically} 
be OVERWRITTEN; for {cmd:bootstrap} it will not, unless the option {cmd:replace} is also specified. 

{p 0 4}       
{cmd: bootstrap} performs bootstrapping of the treatment effect. The option {cmd:estimate} needs to be specified, and for 
one-to-one matching {cmd:outcome} as well. The option {cmd:quality} cannot be requested.
{p_end}
{p 4 4}
ATTENTION: This can be quite time-consuming. Also note that for non-standard estimation of the
score (e.g. in a multiple-treatment framework) and/or non-standard type of outcome (e.g. histories), it is the user
who should post the saved {inp:r(effect)} in a tailor-made programme to be called by STATA's {help bstrap}.
{p_end}
{p 4 4}
If interested in the reproducibility of the results, set the random-number seed by typing
{cmd:set seed} {it:integer} before bootstrapping. (This may not work exactly if there      
are ties in one-to-one matching). {p_end}
{p 4 4}
The following 7 options and {cmd:saving} are those of {help bstrap}; see also the relevant entry in STATA's manual.

{p 0 4}{cmd:reps(}{it:integer}{cmd:)} specifies the number of bootstrap replications
to be performed.  The default is 50.

{p 0 4}{cmd:dots} requests a dot be placed on the screen at the beginning of
each replication.

{p 0 4}{cmd:size(}{it:integer}{cmd:)} specifies the size of the samples to be drawn.
The default is _N, that is the size as the data.

{p 0 4}{cmd:every(}{it:integer}{cmd:)} specifies that the results should be saved
every {it:integer}-th replication.  

{p 0 4}{cmd:replace} indicates that the file specified by {cmd:saving()} may
be overwritten.

{p 0 4}{cmd:double} specifies that the bootstrap results for each replication
are to be stored as double (8-byte reals) rather than as the default
float (4-byte reals).  

{p 0 4}{cmd:level(}{it:integer}{cmd:)} specifies the confidence level, in percent,
for confidence intervals.  The default is 95 or as set by
{cmd:set level}.


{title: Remarks}

{p}
The dataset needs to contain ONLY ONE observation per unit; Stata will check this for you if
the option {cmd:id()} is specified; if not, it is your responsibility!
{p_end}
{p}
If running {cmd: psmatch} more than once on the same dataset, 
it is presumed the user is no longer interested in the _* variables previously 
created; if they are not renamed first, they will be REPLACED by the new ones.


{title: Saved Results}

{p}
For the smoothed types of matching and, if the option {cmd:outcome} is specified for one-to-one matching,
{cmd:psmatch} saves the (possibly smoothed) average outcome for the matched treated in scalar {inp:r(mean1)}, 
for the matched controls in scalar {inp:r(mean0)}; the average treatment effect on the treated 
is stored in scalar {inp:r(effect)}.


{title: Examples}

{inp:. psmatch treated, on(score) caliper(.001) id(serialno) outcome(wage)}

{inp:. psmatch treated, on(score age) quality(age-sex) saving(qual1)}
{inp:. stset days [fw=_times], failure(fail)}
{inp:. sts graph, by(treated)}

{inp:. psmatch group1, on(p1 p2) kernel(logwage) bwidth(0.01) epan nocommon}

{inp:. psmatch treated, est(age-sex) lowess(logwage) bwidth(0.2) both}

{inp:. psmatch reform, est(age-sex) mean(educat) neighb(5) boot reps(100) dots}


{title: Author}

	Barbara Sianesi
	University College London and Institute for Fiscal Studies 
	Email: barbara_s@ifs.org.uk

	
{title: Aknowledgements}

{p}
The core code for one-to-one matching has been made faster by adapting a clever idea by Andrea
Ichino (European University Institute).
{p_end}
{p}
{cmd:spline} uses Peter Sasieni's STB-24 snp7.1 spline programme.
{p_end}
{p}
{cmd:mean}, {cmd:line}, {cmd:lowess} and {cmd:tricube} are based on STATA's
{help ksm} command. See the corresponding entry in the manual for additional information.

	
{title: Bibliography and Sources}

{p 0 2}
Cochran, W. and Rubin, D.B. (1973), "Controlling Bias in Observational Studies", Sankyha, 
35, 417-446.
{p_end}
{p 0 2}
Dehejia, R.H and Wahba, S. (1999), "Causal Effects in Non-Experimental Studies:
Re-Evaluating the Evaluation of Training Programmes", Journal of the American
Statistical Association, 94, 1053-1062.
{p_end}
{p 0 2}
Heckman, J.J., Ichimura, H. and Todd, P.E. (1997), "Matching As An Econometric Evaluation 
Estimator: Evidence from Evaluating a Job Training Programme", Review of Economic Studies, 
64, 605-654.
{p_end}
{p 0 2}
Heckman, J.J., Ichimura, H. and Todd, P.E. (1998), "Matching as an Econometric Evaluation 
Estimator", Review of Economic Studies, 65, 261-294.
{p_end}
{p 0 2}
Heckman, J.J., Ichimura, H., Smith, J.A. and Todd, P. (1998), "Characterising Selection Bias 
Using Experimental Data", Econometrica, 66, 5.{p_end}
{p 0 2}
Heckman, J.J., LaLonde, R.J., Smith, J.A. (1998), "The Economics and Econometrics of Active 
Labour Market Programmes", in Ashenfelter, O. and Card, D. (eds.), The Handbook of Labour 
Economics, Volume III.{p_end}
{p 0 2}
Imbens, G. (2000), "The Role of Propensity Score in Estimating Dose-Response Functions", 
Biometrika, 87, 3, 706-710.
{p_end}
{p 0 2}
Lechner, M. (2001), Identification and Estimation of Causal Effects of Multiple Treatments 
under the Conditional Independence Assumption, in: Lechner, M., Pfeiffer, F. (eds), 
Econometric Evaluation of Labour Market Policies, Heidelberg: Physica/Springer, p. 43-58.
{p_end}
{p 0 2}
Rosenbaum, P.R. and Rubin, D.B. (1983), "The Central Role of the Propensity Score in 
Observational Studies for Causal Effects", Biometrika, 70, 1, 41-55.
{p_end}
{p 0 2}
Rosenbaum, P.R. and Rubin, D.B. (1985), "Constructing a Control Group Using Multivariate
Matched Sampling Methods that Incorporate the Propensity Score", The American Statistician, 
39, 1, 33-38.
{p_end}
{p 0 2}
Rubin, D.B. (1974), "Estimating Causal Effects of Treatments in Randomised and Non-Randomised 
Studies", Journal of Educational Psychology, 66, 688-701.
{p_end}
{p 0 2}
Rubin, D.B. (1980), "Bias Reduction Using Mahalanobis-Metric Matching", Biometrics, 36, 293-298.
{p_end}