apply
Apply a Function to Sections of an Array

### Description

Returns a vector or array by applying a specified function to sections of an array.

### Usage

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

### Arguments

X | an array or a matrix. Other types are converted with as.matrix (if dim(X) has two elements) or as.array (otherwise). Missing values (NAs) are allowed if FUN accepts them.
MARGIN | A vector of integers or character strings over which the function is to be applied. For example, if X is a matrix, then MARGIN=1 indicates rows and MARGIN=2 indicates columns. If MARGIN is a vector of character strings, then those character strings should be a subset of names(dimnames(X)). If MARGIN is a vector of integers, then the integers should a subset of seq_along(dim(X)). Note that MARGIN tells which dimensions of X are retained in the result.
FUN | a function to be applied to the specified array sections, or a character string giving the name of the function. The character form is necessary only for functions with unusual names, such as "%*%".
... | any arguments to FUN. The arguments are passed unchanged to each call of FUN and include their names.

### Details

The arguments to apply have unusual upper-case names, so they do not conflict with names that might be used by FUN.
A subarray is extracted from X for each combination of the levels of the subscripts named in MARGIN. The function FUN is invoked for each of these subarrays, and the results (if any) are concatenated into a new array.
Each section of the input array is passed as the first argument to an invocation of FUN. It is passed without a keyword modifier, so, by attaching keywords in ..., it is possible to make the array section correspond to any argument of FUN. See the examples for an illustration.
In one example below, z is a 4-way array with the dimension vector (2,3,4,5). The expression apply(z, c(1,3), sum) computes the 2 by 4 matrix obtained by summing over the second and fourth extents of z. That is, sum is called 8 times, each time on 15 values.
The sorting examples below show the difference between row and column operations when the result returned by FUN is a vector. The returned value is the first dimension of the result, hence the transpose (via the t or more general aperm function) is necessary with row sorts.
If the results returned by FUN are of different dimensions or lengths, apply returns a list rather than an array, as shown in the last example below.
Value

- If each call to FUN returns a vector of length N, and N>1, apply returns an array of dimension c(N, dim(X)[MARGIN]).
- If N==1 and MARGIN has length > 1, apply returns an array of dimension dim(X)[MARGIN].
- Otherwise, apply returns a vector.

Note

- The functions lapply and sapply apply a function to each element of a list.
- The function tapply applies a function to a ragged array defined by categories.
- The sweep function for arrays is similar to apply.

To perform explicit looping, use for, while, or repeat.
The functions colSums, colMeans, rowSums, and rowMeans provide common operations, for which you do not need apply.
If X is a data frame, then X is coerced to a matrix using as.matrix. This can give surprising results. If there are any factor columns then as.matrix converts all columns to character. For more predictable results, operate on columns with sapply.
See Also
lapply, sapply, tapply, sweep, t, aperm, colSum, colMeans.
Examples

    # 25% trimmed column means. The result is a vector of length ncol(x).
    x <- matrix(round(sin(20:1),2), ncol=5, dimnames=list(Subject=NULL,Quality=paste0("q",1:5)))
    apply(x, 2, mean, trim=.25)
    apply(x, "Quality", mean, trim=.25)
    apply(matrix(1:4,nrow=2),2,function(x,y) x^y, 2)
    apply(matrix(1:4,nrow=2),2,function(x,y) x^y, x=2)
    # Sort the columns of x.
    apply(x, "Quality", sort)
    # Transpose the result of row sort.
    t(apply(x, "Subject", sort))
    # This apply command returns the equivalent of
    # z[,1,,1] + z[,1,,2] + z[,1,,3] + z[,1,,4] + z[,1,,5] +
    # z[,2,,1] + z[,2,,2] + z[,2,,3] + z[,2,,4] + z[,2,,5] +
    # z[,3,,1] + z[,3,,2] + z[,3,,3] + z[,3,,4] + z[,3,,5]
    z <- array(c(1:24, 101:124, 201:224, 301:324, 401:424), dim=c(2,3,4,5))
    apply(z, c(1, 3), sum)
    # This command returns a list, since the lengths of
    # results are not equal.
    apply(matrix(1:12, nrow=4), 2, function(x) which(x <= 6))

Package base version 6.1.5-18
Package Index