The R Project SVN – R – Diff – /trunk/src/library/base/man/array2DF.Rd



  analysis or plotting functions.
}
\usage{
array2DF(x, responseName = "Value",
         sep = "", base = list(LETTERS),
         simplify = TRUE, allowLong = TRUE)
}
\arguments{
  \item{x}{an array object.}
  \item{responseName}{character string, used for creating column name(s)
    in the result, if required. }

    should be returned if \code{x} is a list array and all elements of
    \code{x} are unnamed atomic vectors. Ignored unless \code{simplify =
    TRUE}. }
}
\details{
 
  The main use of \code{array2DF} is to convert an array, as typically
  returned by \code{\link{tapply}}, into a data frame.
 
  When \code{simplify = FALSE}, this is similar to
  \code{\link{as.data.frame.table}}, except that it works for list
  arrays as well as atomic arrays. Specifically, the resulting data
  frame has one row for each element of the array, with one column for
  each dimension of the array giving the corresponding
  \code{\link{dimnames}}. The contents of the array are placed in a

  vector or a list.
 
  If \code{x} does not have \code{\link{dimnames}}, they are
  automatically created using \code{base} and \code{sep}.
  
  In the default case, when \code{simplify = TRUE}, some common cases
  are handled specially.
 
  If all components of \code{x} are data frames with identical column
  names (with possibly different numbers of rows), they are
  \code{\link{rbind}}-ed to form the response. The additional columns
  giving \code{dimnames} are repeated according to the number of

  columns, names are constructed using \code{responseName} and
  \code{sep}.
 
}
\value{
 
  A data frame with at least \code{length(dim(x)) + 1} columns. The
  first \code{length(dim(x))} columns each represent one dimension of
  \code{x} and gives the corresponding values of \code{dimnames}, which
  are implicitly created if necessary. The remaining columns contain the
  contents of \code{x}, after attempted simplification if requested.
 
}
\seealso{
  \code{\link{tapply}}, \code{\link{as.data.frame.table}},
  \code{\link{split}}, \code{\link{aggregate}}.
}

           tapply(len, list(dose, supp), mean, simplify = FALSE))
 
str(s1) # atomic array
str(s2) # list array
 
str(array2DF(s1, simplify = FALSE)) # Value column is vector
str(array2DF(s2, simplify = FALSE)) # Value column is list
str(array2DF(s2, simplify = TRUE))  # simplified to vector
 
### The remaining examples use the default 'simplify = TRUE' 
 
## List array with list components: columns are lists (no simplification)
 
with(ToothGrowth,
     tapply(len, list(dose, supp),
     function(x) t.test(x)[c("p.value", "alternative")])) |>
  array2DF() |> str()
 
## List array with data frame components: columns are atomic (simplified)
 
with(ToothGrowth,
     tapply(len, list(dose, supp),
     function(x) with(t.test(x), data.frame(p.value, alternative)))) |>
  array2DF() |> str()
 
## named vectors
 
with(ToothGrowth,
     tapply(len, list(dose, supp),
            quantile)) |> array2DF()
 
## unnamed vectors: long format
 
with(ToothGrowth,
     tapply(len, list(dose, supp),
            sample, size = 5)) |> array2DF()
 
## unnamed vectors: wide format
 
with(ToothGrowth,
     tapply(len, list(dose, supp),
            sample, size = 5)) |> array2DF(allowLong = FALSE)
 
## unnamed vectors of unequal length
 
with(ToothGrowth[-1, ],
     tapply(len, list(dose, supp),
            sample, replace = TRUE)) |>
  array2DF(allowLong = FALSE)
 
## unnamed vectors of unequal length with allowLong = TRUE
## (within-group bootstrap)
 
with(ToothGrowth[-1, ],
     tapply(len, list(dose, supp), sample, replace = TRUE)) |>
  array2DF() |> str()
 
## data frame input
 
tapply(ToothGrowth, ~ dose + supp, FUN = with,
       data.frame(n = length(len), mean = mean(len), sd = sd(len))) |>
  array2DF()
 
}
\keyword{array}

Rev 84178	Rev 84254
Line 13...	Line 13...
13	`analysis or plotting functions.`	13	`analysis or plotting functions.`
14	`}`	14	`}`
15	`\usage{`	15	`\usage{`
16	`array2DF(x, responseName = "Value",`	16	`array2DF(x, responseName = "Value",`
17	`sep = "", base = list(LETTERS),`	17	`sep = "", base = list(LETTERS),`
18	`simplify = FALSE, allowLong = TRUE)`	18	`simplify = TRUE, allowLong = TRUE)`
19	`}`	19	`}`
20	`\arguments{`	20	`\arguments{`
21	`\item{x}{an array object.}`	21	`\item{x}{an array object.}`
22	`\item{responseName}{character string, used for creating column name(s)`	22	`\item{responseName}{character string, used for creating column name(s)`
23	`in the result, if required. }`	23	`in the result, if required. }`
Line 31...	Line 31...
31	`should be returned if \code{x} is a list array and all elements of`	31	`should be returned if \code{x} is a list array and all elements of`
32	`\code{x} are unnamed atomic vectors. Ignored unless \code{simplify =`	32	`\code{x} are unnamed atomic vectors. Ignored unless \code{simplify =`
33	`TRUE}. }`	33	`TRUE}. }`
34	`}`	34	`}`
35	`\details{`	35	`\details{`
36		-
37	`The main use of \code{array2DF} is to convert an array, as typically`	36	`The main use of \code{array2DF} is to convert an array, as typically`
38	`returned by \code{\link{tapply}}, into a data frame.`	37	`returned by \code{\link{tapply}}, into a data frame.`
39		38
40	`In the default case, when \code{simplify = FALSE}, this is similar to`	39	`When \code{simplify = FALSE}, this is similar to`
41	`\code{\link{as.data.frame.table}}, except that it works for list`	40	`\code{\link{as.data.frame.table}}, except that it works for list`
42	`arrays as well as atomic arrays. Specifically, the resulting data`	41	`arrays as well as atomic arrays. Specifically, the resulting data`
43	`frame has one row for each element of the array, with one column for`	42	`frame has one row for each element of the array, with one column for`
44	`each dimension of the array giving the corresponding`	43	`each dimension of the array giving the corresponding`
45	`\code{\link{dimnames}}. The contents of the array are placed in a`	44	`\code{\link{dimnames}}. The contents of the array are placed in a`
Line 48...	Line 47...
48	`vector or a list.`	47	`vector or a list.`
49		48
50	`If \code{x} does not have \code{\link{dimnames}}, they are`	49	`If \code{x} does not have \code{\link{dimnames}}, they are`
51	`automatically created using \code{base} and \code{sep}.`	50	`automatically created using \code{base} and \code{sep}.`
52		51
53	`When \code{simplify = TRUE}, some common cases are handled specially.`	52	`In the default case, when \code{simplify = TRUE}, some common cases`
-		53	`are handled specially.`
54		54
55	`If all components of \code{x} are data frames with identical column`	55	`If all components of \code{x} are data frames with identical column`
56	`names (with possibly different numbers of rows), they are`	56	`names (with possibly different numbers of rows), they are`
57	`\code{\link{rbind}}-ed to form the response. The additional columns`	57	`\code{\link{rbind}}-ed to form the response. The additional columns`
58	`giving \code{dimnames} are repeated according to the number of`	58	`giving \code{dimnames} are repeated according to the number of`
Line 68...	Line 68...
68	`columns, names are constructed using \code{responseName} and`	68	`columns, names are constructed using \code{responseName} and`
69	`\code{sep}.`	69	`\code{sep}.`
70		70
71	`}`	71	`}`
72	`\value{`	72	`\value{`
73		-
74	`A data frame with at least \code{length(dim(x)) + 1} columns. The`	73	`A data frame with at least \code{length(dim(x)) + 1} columns. The`
75	`first \code{length(dim(x))} columns each represent one dimension of`	74	`first \code{length(dim(x))} columns each represent one dimension of`
76	`\code{x} and gives the corresponding values of \code{dimnames}, which`	75	`\code{x} and gives the corresponding values of \code{dimnames}, which`
77	`are implicitly created if necessary. The remaining columns contain the`	76	`are implicitly created if necessary. The remaining columns contain the`
78	`contents of \code{x}, after attempted simplification if requested.`	77	`contents of \code{x}, after attempted simplification if requested.`
79		-
80	`}`	78	`}`
81	`\seealso{`	79	`\seealso{`
82	`\code{\link{tapply}}, \code{\link{as.data.frame.table}},`	80	`\code{\link{tapply}}, \code{\link{as.data.frame.table}},`
83	`\code{\link{split}}, \code{\link{aggregate}}.`	81	`\code{\link{split}}, \code{\link{aggregate}}.`
84	`}`	82	`}`
Line 90...	Line 88...
90	`tapply(len, list(dose, supp), mean, simplify = FALSE))`	88	`tapply(len, list(dose, supp), mean, simplify = FALSE))`
91		89
92	`str(s1) # atomic array`	90	`str(s1) # atomic array`
93	`str(s2) # list array`	91	`str(s2) # list array`
94		92
95	`str(array2DF(s1)) # Value column is vector`	93	`str(array2DF(s1, simplify = FALSE)) # Value column is vector`
96	`str(array2DF(s2)) # Value column is list`	94	`str(array2DF(s2, simplify = FALSE)) # Value column is list`
97	`str(array2DF(s2, simplify = TRUE)) # simplified to vector`	95	`str(array2DF(s2, simplify = TRUE)) # simplified to vector`
-		96
-		97	`### The remaining examples use the default 'simplify = TRUE'`
98		98
99	`## List array with list components: columns are lists`	99	`## List array with list components: columns are lists (no simplification)`
100		100
101	`with(ToothGrowth,`	101	`with(ToothGrowth,`
102	`tapply(len, list(dose, supp),`	102	`tapply(len, list(dose, supp),`
103	`function(x) t.test(x)[c("p.value", "alternative")])) \|>`	103	`function(x) t.test(x)[c("p.value", "alternative")])) \|>`
104	`array2DF(simplify = TRUE) \|> str()`	104	`array2DF() \|> str()`
105		105
106	`## List array with data frame components: columns are atomic`	106	`## List array with data frame components: columns are atomic (simplified)`
107		107
108	`with(ToothGrowth,`	108	`with(ToothGrowth,`
109	`tapply(len, list(dose, supp),`	109	`tapply(len, list(dose, supp),`
110	`function(x) with(t.test(x), data.frame(p.value, alternative)))) \|>`	110	`function(x) with(t.test(x), data.frame(p.value, alternative)))) \|>`
111	`array2DF(simplify = TRUE) \|> str()`	111	`array2DF() \|> str()`
112		112
113	`## named vectors`	113	`## named vectors`
114		114
115	`with(ToothGrowth,`	115	`with(ToothGrowth,`
116	`tapply(len, list(dose, supp),`	116	`tapply(len, list(dose, supp),`
117	`quantile)) \|> array2DF(simplify = TRUE)`	117	`quantile)) \|> array2DF()`
118		118
119	`## unnamed vectors: long format`	119	`## unnamed vectors: long format`
120		120
121	`with(ToothGrowth,`	121	`with(ToothGrowth,`
122	`tapply(len, list(dose, supp),`	122	`tapply(len, list(dose, supp),`
123	`sample, size = 5)) \|> array2DF(simplify = TRUE)`	123	`sample, size = 5)) \|> array2DF()`
124		124
125	`## unnamed vectors: wide format`	125	`## unnamed vectors: wide format`
126		126
127	`with(ToothGrowth,`	127	`with(ToothGrowth,`
128	`tapply(len, list(dose, supp),`	128	`tapply(len, list(dose, supp),`
129	`sample, size = 5)) \|> array2DF(simplify = TRUE, allowLong = FALSE)`	129	`sample, size = 5)) \|> array2DF(allowLong = FALSE)`
130		130
131	`## unnamed vectors of unequal length`	131	`## unnamed vectors of unequal length`
132		132
133	`with(ToothGrowth[-1, ],`	133	`with(ToothGrowth[-1, ],`
134	`tapply(len, list(dose, supp),`	134	`tapply(len, list(dose, supp),`
135	`sample, replace = TRUE)) \|>`	135	`sample, replace = TRUE)) \|>`
136	`array2DF(simplify = TRUE, allowLong = FALSE)`	136	`array2DF(allowLong = FALSE)`
137		137
138	`## unnamed vectors of unequal length with allowLong = TRUE`	138	`## unnamed vectors of unequal length with allowLong = TRUE`
139	`## (within-group bootstrap)`	139	`## (within-group bootstrap)`
140		140
141	`with(ToothGrowth[-1, ],`	141	`with(ToothGrowth[-1, ],`
142	`tapply(len, list(dose, supp), sample, replace = TRUE)) \|>`	142	`tapply(len, list(dose, supp), sample, replace = TRUE)) \|>`
143	`array2DF(simplify = TRUE) \|> str()`	143	`array2DF() \|> str()`
144		144
145	`## data frame input`	145	`## data frame input`
146		146
147	`tapply(ToothGrowth, ~ dose + supp, FUN = with,`	147	`tapply(ToothGrowth, ~ dose + supp, FUN = with,`
148	`data.frame(n = length(len), mean = mean(len), sd = sd(len))) \|>`	148	`data.frame(n = length(len), mean = mean(len), sd = sd(len))) \|>`
149	`array2DF(simplify = TRUE)`	149	`array2DF()`
150		150
151	`}`	151	`}`
152	`\keyword{array}`	152	`\keyword{array}`

The R Project SVN R

(root)/trunk/src/library/base/man/array2DF.Rd – Rev 84178 → 84254