% File src/library/base/man/apply.Rd
% Part of the R package, https://www.R-project.org
% Copyright (C) 1995-2015 R Core Team
% Distributed under GPL 2 or later

\name{apply}
\alias{apply}
\title{Apply Functions Over Array Margins}
\description{
  Returns a vector or array or list of values obtained by applying a
  function to margins of an array or matrix.
}
\usage{
apply(X, MARGIN, FUN, \dots)
}
\arguments{
  \item{X}{an array, including a matrix.}
  \item{MARGIN}{a vector giving the subscripts which the function will
    be applied over.  E.g., for a matrix \code{1} indicates rows,
    \code{2} indicates columns, \code{c(1, 2)} indicates rows and
    columns. Where \code{X} has named dimnames, it can be a character
    vector selecting dimension names.}
  \item{FUN}{the function to be applied: see \sQuote{Details}.
    In the case of functions like \code{+}, \code{\%*\%}, etc., the
    function name must be backquoted or quoted.}
  \item{\dots}{optional arguments to \code{FUN}.}
}
\details{
  If \code{X} is not an array but an object of a class with a non-null
  \code{\link{dim}} value (such as a data frame), \code{apply} attempts
  to coerce it to an array via \code{as.matrix} if it is two-dimensional
  (e.g., a data frame) or via \code{as.array}.

  \code{FUN} is found by a call to \code{\link{match.fun}} and typically
  is either a function or a symbol (e.g., a backquoted name) or a
  character string specifying a function to be searched for from the
  environment of the call to \code{apply}.

  Arguments in \code{\dots} cannot have the same name as any of the
  other arguments, and care may be needed to avoid partial matching to
  \code{MARGIN} or \code{FUN}.  In general-purpose code it is good
  practice to name the first three arguments if \code{\dots} is passed
  through: this both avoids partial matching to \code{MARGIN}
  or \code{FUN} and ensures that a sensible error message is given if
  arguments named \code{X}, \code{MARGIN} or \code{FUN} are passed
  through \code{\dots}.
}
\value{
  If each call to \code{FUN} returns a vector of length \code{n}, then
  \code{apply} returns an array of dimension \code{c(n, dim(X)[MARGIN])}
  if \code{n > 1}.  If \code{n} equals \code{1}, \code{apply} returns a
  vector if \code{MARGIN} has length 1 and an array of dimension
  \code{dim(X)[MARGIN]} otherwise.
  If \code{n} is \code{0}, the result has length 0 but not necessarily
  the \sQuote{correct} dimension.

  If the calls to \code{FUN} return vectors of different lengths,
  \code{apply} returns a list of length \code{prod(dim(X)[MARGIN])} with
  \code{dim} set to \code{MARGIN} if this has length greater than one.

  In all cases the result is coerced by \code{\link{as.vector}} to one
  of the basic vector types before the dimensions are set, so that (for
  example) factor results will be coerced to a character array.
}
\references{
  Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
  \emph{The New S Language}.
  Wadsworth & Brooks/Cole.
}
\seealso{
  \code{\link{lapply}} and there, \code{\link{simplify2array}};
  \code{\link{tapply}}, and convenience functions
  \code{\link{sweep}} and \code{\link{aggregate}}.
}
\examples{
## Compute row and column sums for a matrix:
x <- cbind(x1 = 3, x2 = c(4:1, 2:5))
dimnames(x)[[1]] <- letters[1:8]
apply(x, 2, mean, trim = .2)
col.sums <- apply(x, 2, sum)
row.sums <- apply(x, 1, sum)
rbind(cbind(x, Rtot = row.sums), Ctot = c(col.sums, sum(col.sums)))

stopifnot( apply(x, 2, is.vector))

## Sort the columns of a matrix
apply(x, 2, sort)

## keeping named dimnames
names(dimnames(x)) <- c("row", "col")
x3 <- array(x, dim = c(dim(x),3),
	    dimnames = c(dimnames(x), list(C = paste0("cop.",1:3))))
identical(x,  apply( x,  2,  identity))
identical(x3, apply(x3, 2:3, identity))
\dontshow{
xN <- x; dimnames(xN) <- list(row=NULL, col=NULL)
x2 <- x; names(dimnames(x2)) <- NULL
fXY <- function(u) c(X=u[1], Y=u[2])
ax1 <- apply(x, 1, fXY)
ax2 <- apply(x2,1, fXY)
stopifnot(identical(dimnames(ax1), list(col=c("X.x1", "Y.x2"), row=letters[1:8])),
          identical(dimnames(ax2), unname(dimnames(ax1))),
          identical( x, apply( x, 2, identity)),
          identical(xN, apply(xN, 2, identity)),
	  identical(dimnames(x),
		    dimnames(apply(x, 2, format))),
          identical(x3, apply(x3, 2:3, identity)),
	  identical(dimnames(apply(x3, 2:1, identity)),
		    dimnames(x3)[3:1]))
rm(xN, x2, fXY, ax1, ax2)
}
##- function with extra args:
cave <- function(x, c1, c2) c(mean(x[c1]), mean(x[c2]))
apply(x, 1, cave,  c1 = "x1", c2 = c("x1","x2"))

ma <- matrix(c(1:4, 1, 6:8), nrow = 2)
ma
apply(ma, 1, table)  #--> a list of length 2
apply(ma, 1, stats::quantile) # 5 x n matrix with rownames

stopifnot(dim(ma) == dim(apply(ma, 1:2, sum)))

## Example with different lengths for each call
z <- array(1:24, dim = 2:4)
zseq <- apply(z, 1:2, function(x) seq_len(max(x)))
zseq         ## a 2 x 3 matrix
typeof(zseq) ## list
dim(zseq) ## 2 3
zseq[1,]
apply(z, 3, function(x) seq_len(max(x)))
# a list without a dim attribute
}
\keyword{iteration}
\keyword{array}