Matching variables between subjects -----------------------------------
^vmatch^ casevar [^if^ exp] , ^g^enerate(newvar) ^show^(idvar) ^save^(filename) ^f^irst ^fuzz^(real 1e-6) [^r^]^d^evia(varlist1 dLo1[/dHi1] [varlist2 dLo2[/dHi2]] ...) [^r^]^e^ucli(varlist1 dist1 [varlist2 dist2] ...) ^o^utof(varlist1 #1 [varlist2 #2]...) ^s^trng(varlist) ^p^ower(#)
Description -----------
^vmatch^ attempts to find records that "match" a given "case" in the sense that they are similar (see rules) with respect to the variables declared in the options. Variable ^casevar^ is assumed to contain a 1 for cases (to be matched) and any other value for non-cases. The new variable ^newvar^ will be created to receive the number of matches for a case and, for non-cases, either the number of times it was called a match or the identification number of the case for which it was first called (see option ^first^). String variables are allowed in the matching process (see option ^strng^)
Cases (casevar==1) are not considered acceptable matches and the optional ^if^ condition only applies to eligible records. To be eligible as match, non-cases must have no missing values on any of the numeric variables declared in the matching options. Stata's -markout- is used for this and therefore string variables are not considered. The pool of eligible records is used when summary statsitics are required to apply matching rules.
There are 4 rules for matching which can be accessed through options. In the description below it is assumed that the values of a given case are denoted X0 or X0_i for vars X or X_i (resp), and d, d1 and d2 represent tolerated values for "distances". Some of the rules may be applied with either absolute or "relative" distances (option prefixed with ^r^). The rules are:
- Deviation ---------> accept as match if -d1 <= devia <= +d2 absolute devia= X-X0 relative devia= 100*( X-X0 ) / X0 %
- Euclidean ---------> accept as match if eucli <= d absolute eucli= p-root( sum{ p-power (X_i-X0_i) over i=1,2,...} ) relative eucli= p-root( sum{ p-power((X_i-X0_i)/s_i) }), where s_i is SD(X_i) The default value of p is 2 and may be optionally modified.
- Out of ---------> accept as match if at least a specified number of exact matches are found among the variables in the specified list.
- String ---------> accept exact matches only (i.e. x==x0)
Options ------- ^generate^ is not an option, the variable newvar must not exist.
^show^ asks that records be identified by the (existing) variable idvar.
^save^ asks that all variables declared in the matching options as well as the idvar and a new var (called Mfor, meaning "match for") be saved in the specified file. If the file already exists it is replaced (no warning). If no idvar is given (i.e. ^show^ option omitted) the sequential number in the present ordering (on entry) is used instead. The variable Mfor is not added to the current data, only saved in the new data file. It identifies (using idvar or seq.num.) the case for which the current record is a match. Cases have Mfor set to missing. Non-cases may appear several times as match(!)
^First^ asks that the generated newvar contain the identification (idvar or seq.num.) of the case for which the present match was first called.
^fuzz^ declares the precision in a numeric comparison: two numbers are considered equal when they differ by less than the specified value; the default is 1e-6. Useful to avoid wrong decisions (exclusions) due to roundoff. It may however cause too many inclusions.
^devia^ or ^rdevia^ request that any record whose deviation from the case (separately on each variable in each successive varlist) does not exceed the specified dLo on the low side nor dHi on the high side be accepted as match. When /dHi is omitted dHi is taken to be the same as dLo; when both are given there must not be blanks within the statement ^dLo/dHi^. When ^rdevia^ is asked, the deviations are taken as percentage deviation from the case (on a scale from 0 to 100, not 0 to 1, see rules above).
^eucli^ or ^reucli^ request that any record which, in the space defined by each varlist successively, lies within the specified distance from the considered case be accepted as match. The distance is computed according to the minkovski formula as the p-th root of the sum of the p-th power of the absolute value of deviations. The value of p is specified via the ^power^ option and defaults to 2 (yielding the euclidean distance). When ^reucli^ is asked the deviations are standardized (X-Xbar)/sdX, so that the difference between a case and a non-case becomes (X-X0)/sdX. The mean Xbar and standard deviation sdX are computed using eligible non-cases only.
^power^ declares the value of the power transformation used in computing distances and only has an effect when the ^[r]eucli^ option is used. A power of 2 produces euclidean distances and a power of 1 the so-called manhattan distance (sum of absolute deviations). When the power is 0 the distance is computed as the antilog of the sum of the log of deviations. Fractional as well as negative values of the power are allowed. Warning: when logs or reciprocals are taken a deviation of zero is replaced by the ^fuzz^ value which may become decisive in declaring matches. Indeed, in the case of logs the distance corresponds to the product of the deviations (i.e. the volume of a box) where some components are zero (or fuzz), thus yielding "small" products and good matching. In the case of negative powers the reciprocals of the fuzz values will become "large", and the sum will result in rather poor matching.
^outof^ : a match is any record for which at least ^#k^ variables within the given varlist^k^ match the considered case's values exactly.
^strng^ : a match is any record for which all string variables in a specified varlist are lexicographically identical to those of the considered case. (note: the option truly is strng without i: at first I was afraid to mix up things, later, well I was afraid to mess them up, or too lazy.)
Examples -------- Here is a do-file using the automobile data, (with an additional string-var color to check ^strng^ option) * cap prog drop aumatch prog def aumatch use auto, clear tempvar u g `u'=1+int(4*uniform()) g str5 color="white" if `u'==1 replace color="blue" if `u'==2 replace color="red" if `u'==3 replace color="green" if `u'==4 sort mak g tbM=mod(_n,15)==11 vmatch tbM, g(nbM1) d(w 200) re(p 1) s(col) show(mak) f vmatch tbM, g(nbM2) e(tru tur mpg 5) p(1) show(mak) save(auto2) end *
- g tbM=mod(_n,15)==11 after sort mak selects seq.num 11,26,41,56,71 (in the alfabetical order of makes) to be matched
- vmatch tbM, g(nbM1) d(w 200) re(p 1) s(col) show(mak) f asks: find matches for cases with tbM==1, store result in new var nbM1 match as follows: ^d^(w 200): weight does not deviate by more than 200 pounds ^re^(p 1) : provided the price is no more than 1 SD away ^s^(col) : make sure they are the same color as the case ^show^(mak) : display casewise (identified by make) list of matches ^f^ : replace nbM1 by first id.num for which non-case was match
- vmatch tbM, g(nbM2) e(tru tur mpg 5) p(1) show(mak) save(auto2) the sum of absolute values of differences (manhattan distance) between a case and its matches on the variables trunk, turn and mpg should not exceed 5; also, casewise display by make and save in file auto2.
Author ------ Guy D. van Melle, university of Lausanne, Switzerland email: guy.van-melle@@inst.hospvd.ch