1% File src/library/utils/man/stack.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2017 R Core Team
4% Distributed under GPL 2 or later
5
6\name{stack}
7\alias{stack}
8\alias{stack.default}
9\alias{stack.data.frame}
10\alias{unstack}
11\alias{unstack.default}
12\alias{unstack.data.frame}
13\title{Stack or Unstack Vectors from a Data Frame or List}
14\description{
15  Stacking vectors concatenates multiple vectors into a single vector
16  along with a factor indicating where each observation originated.
17  Unstacking reverses this operation.
18}
19\usage{
20stack(x, \dots)
21\method{stack}{default}(x, drop=FALSE, \dots)
22\method{stack}{data.frame}(x, select, drop=FALSE, \dots)
23
24unstack(x, \dots)
25\method{unstack}{default}(x, form, \dots)
26\method{unstack}{data.frame}(x, form, \dots)
27}
28\arguments{
29  \item{x}{a list or data frame to be stacked or unstacked.}
30  \item{select}{an expression, indicating which variable(s) to select from a
31    data frame.}
32  \item{form}{a two-sided formula whose left side evaluates to the
33    vector to be unstacked and whose right side evaluates to the
34    indicator of the groups to create.  Defaults to \code{\link{formula}(x)}
35    in the data frame method for \code{unstack}.}
36  \item{drop}{Whether to drop the unused levels from the \dQuote{ind}
37    column of the return value.
38  }
39  \item{\dots}{further arguments passed to or from other methods.}
40}
41\details{
42  The \code{stack} function is used to transform data available as
43  separate columns in a data frame or list into a single column that can
44  be used in an analysis of variance model or other linear model.  The
45  \code{unstack} function reverses this operation.
46
47  Note that \code{stack} applies to \emph{vectors} (as determined by
48  \code{\link{is.vector}}): non-vector columns (e.g., factors) will be
49  ignored with a warning.  Where vectors of different types are selected
50  they are concatenated by \code{\link{unlist}} whose help page explains
51  how the type of the result is chosen.
52
53  These functions are generic: the supplied methods handle data frames
54  and objects coercible to lists by \code{\link{as.list}}.
55}
56
57\value{
58  \code{unstack} produces a list of columns according to the formula
59  \code{form}.  If all the columns have the same length, the resulting
60  list is coerced to a data frame.
61
62  \code{stack} produces a data frame with two columns:
63  \item{values}{the result of concatenating the selected vectors in
64    \code{x}.}
65  \item{ind}{a factor indicating from which vector in \code{x} the
66    observation originated.}
67}
68\author{Douglas Bates}
69\seealso{
70  \code{\link{lm}}, \code{\link{reshape}}
71}
72\examples{
73require(stats)
74formula(PlantGrowth)         # check the default formula
75pg <- unstack(PlantGrowth)   # unstack according to this formula
76pg
77stack(pg)                    # now put it back together
78stack(pg, select = -ctrl)    # omitting one vector
79}
80\keyword{manip}
81