The R Project SVN R

% File src/library/base/man/array2DF.Rd

% Part of the R package, https://www.R-project.org

% Copyright 2023 R Core Team

% Distributed under GPL 2 or later

\name{array2DF}

\title{Convert array to data frame}

\alias{array2DF}

\description{

  \code{array2DF} converts an array, including list arrays commonly

  returned by \code{tapply}, into data frames for use in further

  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. }

  \item{sep}{character string, used as separator when creating new

    names, if required. }

  \item{base}{character vector, giving an initial set of names to create

    dimnames of \code{x}, if missing. }

  \item{simplify}{logical, whether to attempt simplification of the

    result. }

  \item{allowLong}{logical, specifying whether a long format data frame

    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

  column whose name is given by the \code{responseName} argument. The

  mode of this column is the same as that of \code{x}, usually an atomic

  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

  rows, and \code{responseName} is ignored in this case.

  If all components of \code{x} are \emph{unnamed} atomic vectors

  \emph{and} \code{allowLong = TRUE}, each component is treated as a

  single-column data frame with column name given by

  \code{responseName}, and processed as above.

  In all other cases, an attempt to simplify is made by

  \code{\link{simplify2array}}. If this results in multiple unnamed

  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}}.

}

\examples{

s1 <- with(ToothGrowth,

           tapply(len, list(dose, supp), mean, simplify = TRUE))

s2 <- with(ToothGrowth,

           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}