apply                  package:base                  R Documentation

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.

Usage:

     apply(X, MARGIN, FUN, ...)

Arguments:

       X: the array to be used.

  MARGIN: a vector giving the subscripts which the function will be
          applied over. `1' indicates rows, `2' indicates columns,
          `c(1,2)' indicates rows and columns.

     FUN: the function to be applied. In the case of functions like
          `+', `%*%', etc., the function name must be quoted.

     ...: optional arguments to `FUN'.

Value:

     If each call to `FUN' returns a vector of length `n', then `apply'
     returns an array of dimension `c(n, dim(X)[MARGIN])' if `n > 1'. 
     If `n' equals `1', `apply' returns a vector if `MARGIN' has length
     1 and an array of dimension `dim(X)[MARGIN]' otherwise.

     If the calls to `FUN' return vectors of different lengths, `apply'
     returns a list of length `dim(X)[MARGIN]'.

See Also:

     `lapply', `tapply', and convenience functions `sweep' and
     `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)) # not ok in R <= 0.63.2

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

     ##- 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), nr = 2)
     ma
     apply(ma, 1, table)  #--> a list of length 2
     apply(ma, 1, quantile)# 5 x n matrix with rownames

     stopifnot(dim(ma) == dim(apply(ma, 1:2, sum)))## wasn't ok before R 0.63.1

