-------------------------------------------------------------------------------
help for stackids
-------------------------------------------------------------------------------

Stack the id variables produced by mahapick

        stackids varlist , idvar(id_varname) idprimevar(prime_id_varname)
                 matchnumvar(matchnum_varname) clear [keepwideids]

Description

    stackids takes the (possibly multiple) matched id variables as produced
    by mahapick using the pickids() option, along with the id of the treated
    cases, and stacks them into a long-shaped dataset.  (See reshape for a
    discussion of wide- versus long-shaped data.)

    varlist contains two parts: The first variable holds the id of the
    treated cases - the "prime id".  The remaining variables constitute the
    id's of the matched control cases; they should be the same as those
    specified in the pickids() option of mahapick (or a subset thereof).
    Note that all of the variables in varlist get stacked into one variable:
    id_varname.  That is, the treated and control cases get stacked together.
    So even if there is only one variable for control case id's, there will
    be some stacking of variables.

    The resulting dataset will have...

        a variable holding all the stacked id's;

        a variable holding the id's of the corresponding treated cases;

        a "matchnum" variable (as will be explained below).


Required Options

    idvar(id_varname) specifies the name for the (new) variable into which
    varlist is to be stacked.

    idprimevar(prime_id_varname) specifies the name of the (new) "prime id"
    variable.  This will hold the id of the treated cases.  Values will be
    repeated for all the control cases matched to a given treated case.

    Note that id_varname == prime_id_varname for treated cases, and they are
    unequal otherwise.

    matchnumvar(matchnum_varname) specifies the name of a (new) variable that
    serves as a counter.  It will contain 0 for the treated cases, and 1, 2,
    etc. for control cases - those corresponding to the latter variables in
    varlist.

    In stating that these variables are new, what is really meant is that
    they are for newly-created variables; but the whole dataset is new, so
    there is nothing restricting you from reusing an existing variable name.

    clear indicates your understanding that the data in memory will be
    replaced.


Optional Options

    keepwideids retains the original varlist of id's in wide form.  They will
    be present only on the treated cases; they will be missing for all
    others.  This is provided in case you want to see the matched control
    cases explicitly connected to the treated cases (in the same cases).  Be
    aware, however, that you get a dataset that is both wide and long
    simultaneously, and it can be fairly wasteful of space.


Remarks

    After obtaining matches using mahapick with the pickids() option, it may
    be more useful, for analysis purposes, to have the data reshaped (or
    stacked) so that all the id values, both treated and control, appear in
    the same variable.  This program does that for you.  (While this can be
    achieved by reshape or stack, some extra steps are required to create a
    structure that contains the connection between the treated cases and
    their matched control cases (which may or may not be important to you).
    stackids takes care of those extra steps for you.)

    stackids program was created to fill a need which was obviated by the
    advent of the genfile() option in mahapick; if you used the genfile()
    option, then you would not need stackids.  Putting aside some possible
    variations resulting from choices of options, the dataset resulting from
    stackids should be the same as that of using the genfile() option in
    mahapick.

    Since it is advisable to use the genfile() option, rather than the
    pickids() option in mahapick, stackids may be needed rarely if ever.  It
    is included for completeness.  stackids may be useful, however, if you
    have used pickids() and later find you would have preferred to use the
    genfile() option, but you don't want to rerun the matching process (which
    can be time-consuming).

    Before running any analyses, you will want to merge some "content" data
    onto the resulting set, as the resulting set bears only identification
    information.  See mahapick for more discussion of this.  Also note that
    there is no explicit variable provided indicating the treated cases.  You
    may recover this information either from the merge to the content data,
    or by identifying the cases with matchnum_varname==0.  (These will also
    be the ones with id_varname == prime_id_varname.)


Example

    . stackids id match1 match2 match3, idvar(id) idprimevar(prime_id)
        matchnumvar(matchnum) clear


Author

    David Kantor; initial development was done at The Institute for Policy
    Studies, Johns Hopkins University.  Email kantor.d@att.net if you observe
    any problems.


Also See
    mahapick, mahascore, mahascores, mahascore2, screenmatches,