.-
help for ^stak^                                                (Version 1.2.1)
.-

Simple data stacker
-------------------

    ^stak^ varlist [^if^ exp] [^in^ range]^,^ [ ^i^nto^(^newvar^)^ ^g^id^(^newvar^)^ 
			   ^l^abels ^r^etain { ^w^ide | ^d^ummy } ^clear^ ]


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

^stak^ is a painless program to do simple ^reshape^s or ^stack^s.  It vertically
stacks the variables in varlist into a single new variable and has options for
retaining the varlist and other variables in the data set.  Use ^stack^ if you 
need more than a single stacked variable or ^reshape^ for more complicated
restructuring.

Variables to be stacked must be either all numeric or all string.  Variables 
may be repeated in varlist.

Consider the following data:

            a         b         c 
  1.        1         4         7  
  2.        2         5         8  
  3.        3         6         9  

^stak a b c^ creates a new dataset containing:

        _into      _gid 
  1.        1         a  
  2.        2         a  
  3.        3         a  
  4.        4         b  
  5.        5         b  
  6.        6         b  
  7.        7         c  
  8.        8         c  
  9.        9         c  

The new dataset has 2 variables (^_into^ and ^_gid^) with k*n observations (k is 
the number of variables in varlist and n equals _N from the old dataset).  
The first n observations of ^_into^ are the data from variable a, the second n
observations are the data from variable b, and the third n observations are 
the data from variable c.

Variable ^_gid^ identifies the groups.  ^_gid^ is a labeled numeric variable that
incrementally numbers the groups starting from 1.  The value labels are the 
names of the stacked variables.


Options
-------

^into(^newvar^)^ specifies the name of the stacked variable to be created.  The
default name is ^_into^.  The name cannot be the same as any varname in varlist;
when ^retain^ is specified, it cannot be the same as any varname in the dataset.

^gid(^newvar^)^ specifies the name of the group id variable to be created.  The
default name is ^_gid^.  The name cannot be the same as any varname in varlist; 
when ^retain^ is specified, it cannot be the same as any varname in the dataset.

^labels^ specifies that the variable labels of the varlist variables are to be 
used as value labels of the ^gid()^ variable.  The default is to use the 
variable names of the varlist variables.

^retain^ includes a stacked copy of each variable not specified in varlist.  
A "stacked copy" is k stacked replicates of the original data.  

^wide^ includes a wide copy of each variable in varlist.  A "wide copy" 
replicates the original data of the kth variable in varlist when the ^gid()^ 
variable has value k; the wide copy has missing values otherwize.  ^wide^ and 
^dummy^ are alternatives; you can specify one but not both.

^dummy^ includes a dummy (or indicator) variable for each variable in varlist.  
A "dummy" has value 1 for the kth variable in varlist when the ^gid()^ variable
has value k; it has value 0 otherwize.  Dummies are returned in the original
variable names.  ^dummy^ and ^wide^ are alternatives; you can specify one but not
both.

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


Comments
--------

The new, stacked data file will be unnamed and the changed flag will be set.
The data label will be a modified version of the data label (if any) of the
original data. The modified version has "stak: " added as a prefix.

The treatment of existing value labels, variable labels, and formats depends
on the type of variable:

 ^into()^ variable: none are transferred.
  ^gid()^ variable: none are transferred.
  ^wide^ variables: all are transferred.
^retain^ variables: all are transferred.
 ^dummy^ variables: all are modified... 
           - existing value labels are dropped;
           - the variable label has " dummy" appended; 
           - the format is set to %8.0g.

By default, the name of the value label assigned to the ^gid()^ variable is the
same as the name of the ^gid()^ variable itself.  If that value label name is in
use by another variable (and that variable will be transferred to the new data
file), then ^_gid^ is used instead.  If ^_gid^ is already in use, it will be 
deleted, without notice, and reused for the ^gid()^ variable.

The storage type for the ^into()^ variable is automatically set to that of the
"largest" type among the varlist variables so no precision is lost.

All variables in the new dataset are ^compress^ed.  Although storage types of 
existing variables may change, precision will be maintained.

Characteristics?  The _dta[] chars are retained.  Variable-specific chars are 
retained when the variable is in the new dataset.  ^dummy^ variables inherit 
the characteristics of their "parent" variables.

No attempt is made to determine whether the current ^set memory^ allocation is
large enough to contain the new dataset.  Nonetheless, the data are preserved 
and will be restored if a memory shortage occurs.  The required memory 
allocation will depend on the number of variables to be stacked and whether 
the ^retain^, {^wide^|^dummy^}, and ^labels^ options are specified.  The "worst case"
scenario, for k stacked variables and options ^retain^, ^wide^ and ^label^ specified,
will be a new dataset of size slightly larger than k times the size of the 
original dataset.  


Examples
--------

Given data:

            a         b         c
  1.        1         4         7
  2.        2         5         8
  3.        3         6         9


 ^. stak a b, into(value) gid(group) retain wide clear^

 ^. list^

        value     group         a         b         c
  1.        1         a         1         .         7
  2.        2         a         2         .         8
  3.        3         a         3         .         9
  4.        4         b         .         4         7
  5.        5         b         .         5         8
  6.        6         b         .         6         9

Variable value contains the stacked values of variables a and b.  The varname 
"value" was specified in the ^into()^ option.

Variable group is a labeled numeric variable identifying the stacked groups 
of data. The varname "group" was specified in the ^gid()^ option.

Variables a and b result from the ^wide^ option.  

Variable c results from the ^retain^ option.

Option ^clear^ eliminated a warning that the existing dataset will be cleared.


Alternatively, we could have specified:

 ^. stak a b, i(value) g(group) r dummy labels clear^

 ^. list^

        value     group         a         b         c
  1.        1   'a' var         1         0         7
  2.        2   'a' var         1         0         8
  3.        3   'a' var         1         0         9
  4.        4   'b' var         0         1         7
  5.        5   'b' var         0         1         8
  6.        6   'b' var         0         1         9

There are two differences from the first example.
  
Specifying ^labels^ caused the value labels of group to be the variable labels
of the stacked variables (rather than the variable names).

Specifying ^dummy^ (rather than ^wide^) caused variables a and b to be dummy
(indicator) variables.


Author
------

  Thomas J. Steichen, RJRT, steicht@@rjrt.com


Acknowledgments
---------------

  Nicholas J. Cox made helpful comments (and was the original author  
                  of some code and code ideas that I willfully pilfered).


Also see
--------

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