..-
help for ^stack^         (Statalist distribution 19 sep 1997; manual:  ^[R] stack^)
..-

Stack data
- ----------

    ^stack^ varlist [^if^ exp] [^in^ range]^,^ { ^i^nto^(^newvars^)^ | ^g^roup^(^#^)^ }
					 [ ^clear^ ^wi^de ]


Description
- -----------

^stack^ stacks variables in varlist vertically.  Consider

	. ^stack a b c d e f, into(g h)^

This would create a new dataset containing

        g      h           ^_stack^
        ---------------------------
        a      b             1            (_N observations)
        c      d             2            (_N observations)
        e      f             3            (_N observations)

The resulting dataset would have 3*_N observations.  The first _N observations
would have all the data from variables a and b, the second _N observation all
the data from c and d, and the third _N observations all the data from e and
f.

^stack^ also creates a new variable, ^_stack^, identifying the groups.

As another example, 

	. ^stack a b c d e f, into(g h i)^

would create a new dataset containing

        g      h      i    ^_stack^
        ---------------------------
        a      b      c      1            (_N observations)
        d      e      f      2            (_N observations)

The number of variables specified by ^into()^ determine the number of groups
formed.  ^into()^ may be specified with variable ranges, such as 

	. ^stack a b c d e f, into(v1-v3)^

as, of course, may the varlist 

	. ^stack a-f, into(v1-v3)^

The new variables formed may have the existing variables' names;

	. ^stack a b c d e f, into(a b)^
and
	. ^stack a b c d e f, into(a b c)^

make perfect sense.

When you want the new variables to have the same names as the variables in the
first group, rather than specifying ^into()^, you may specify ^group()^.
Equivalent to the above are

	. ^stack a b c d e f, group(2)^
and
	. ^stack a b c d e f, group(3)^

For instance, the latter command creates 

        a      b           ^_stack^
        ---------------------------
        a      b             1            (_N observations)
        c      d             2            (_N observations)
        e      f             3            (_N observations)


Options
- -------

^into(^newvars^)^ and ^group(^#^)^ are alternatives and you must specify one or the
    other, but not both.

^into(^newvars^)^ specifies the the names of the new variables to be created.
    The implied number of groups is then v/n, where v is the number of 
    varlist variables and n the number of ^into()^ variables.  For instance,

	. ^stack a b c d e f, into(v1 v2 v3)^

    implies two groups:  (a b c) and (d e f).  

^group(^#^)^ specifies the number of groups and specifies that the new variables
    are to be named according to the first # variables in varlist.  For
    instance,

	. ^stack a b c d e f, group(2)^

    specifies that there are two groups and the new variables are to be called
    a, b, and c.

^clear^ indicates your understanding that the data in memory will be lost; if
    not specified, you will be asked to confirm your intentions.

^wide^ includes any of the original variables in varlist that are not specified
    in newvars in the resulting dataset.


Examples
- --------

See ^[R] stack^.  Here, we will give one mechanical example.

 . ^list^
              a        b        c        d  
   1.         1        2        3        4  
   2.         5        6        7        8  

 . ^stack a b  c d, into(e f) clear^

 . ^list^
              e        f    _stack  
   1.         1        2         1  
   2.         5        6         1  
   3.         3        4         2  
   4.         7        8         2  

That is, the new variable ^e^ is formed by stacking ^a^ and ^c^, while the new
variable ^f^ is formed by stacking ^b^ and ^d^.  ^_stack^ is automatically created
and set equal to 1 for the first (^a^,^b^) group and 2 for the second (^c^,^d^) 
group.  


Also see
- --------

 Manual:  ^[R] stack^
On-line:  help for @reshape@, @xpose@