-------------------------------------------------------------------------------
help for longshape
-------------------------------------------------------------------------------

Reshape to long (limited alternative version)

        longshape varlist [if exp] [in range] , iname(idvar(s)) jname(newvar)
                 [ yname(newvar) yvallab(lblname) replace ]

   
Description 

    longshape is a convenience command automating one kind of simple reshape
    long. Please study the Remarks below carefully to see if it matches your
    needs. Otherwise, it is likely that you really do need reshape.


Remarks 

    Suppose that observations are identified by one or more existing
    variables idvar(s) and that you want to reshape a single bunch of
    variables varlist to long, i.e. to stack varlist into one variable.  Any
    other variables are to be repeated alongside. reshape will do this for
    you, but three details can bite:

        1. reshape requires that the variable names in varlist start with the
        same prefix or stub. Thus if a b c are to be stacked into one
        variable y, they would need to be called ya yb yc. It is easy enough
        to rename these variables before a reshape, but with longshape it is
        only necessary to specify a desired new name through the yname()
        option.

        2. More awkwardly, with a reshape long the variable labels of varlist
        would disappear, so that it would be necessary to save them somewhere
        and put them back, or at worst to retype them. With longshape the
        variable labels, when they exist, become the value labels of a new
        variable.

        3. On occasion, you might want to specify directly that the new
        variable be assigned particular value labels. longshape has an option
        for that.

    One converse to this is that longshape does not support simultaneous
    reshaping of several bunches of variables, so for that you need reshape
    (or stack).


Options 

    iname() specifies the name(s) of the variables that singly or jointly
        specify observations uniquely.  This is a required option.

    jname() specifies a name for a new variable to hold information on
        variables in varlist. Specifically, longshape creates two new
        variables, as follows. Suppose you specify jname(which). Then two new
        variables which and _which will be created. which is a numeric
        variable with value labels, which will be the original variable
        labels if defined and otherwise the original variable names.  _which
        is a string variable with the original variable names. Thus when
        specifying jname(jname) it is necessary that both jname and _jname be
        available as new variable names.  This is a required option.

    yname() specifies a name for the single new variable formed by stacking
        varlist. The name defaults to y, so long as that is a new variable
        name.

    replace forces a replacement of the existing dataset by the new reshaped
        dataset even though that existing dataset has changed since it was
        last saved or has not been saved at all. See save. Although this
        option may be used, it is better strategy to save the dataset first.

    yvallab() specifies that a particular set of value labels be assigned to
        the new variable named in yname(). This is an occasionally used
        option.


Examples 

    . clear
    . set obs 6
    . gen id = _n
    . gen a = ceil(10 * runiform())
    . label var a "the label of a"
    . gen b = ceil(10 * runiform())
    . label var b "the label of b"
    . l
    . save longshapetest, replace
    . longshape a b, i(id) j(which)
    . l

    (ecological data, observations are sites, species abundances to be
        stacked into one variable)
    . longshape achmil-calcus, i(id) j(species) y(abundance)


Author 

    Nicholas J. Cox, Durham University, U.K.
    n.j.cox@durham.ac.uk


Also see 

    Online: help for reshape, stack