[ RDocumentation ](/)

Moon  [ ](https://github.com/datacamp/rdocumentation-2.0) [ Learn R
](https://www.datacamp.com/learn/r)

Search all packages and functions

[ base  (version  3.6.2  ) ](/packages/base/versions/3.6.2)

#  apply: 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, …)

##  Arguments

X

an array, including a matrix.

MARGIN

a vector giving the subscripts which the function will be applied over. E.g.,
for a matrix ` 1 ` indicates rows, ` 2 ` indicates columns, ` c(1, 2) `
indicates rows and columns. Where ` X ` has named dimnames, it can be a
character vector selecting dimension names.

FUN

the function to be applied: see ‘Details’. In the case of functions like ` + `
, ` %*% ` , etc., the function name must be backquoted or 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 ` n ` is ` 0 ` , the
result has length 0 but not necessarily the ‘correct’ dimension.

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

In all cases the result is coerced by ` [ as.vector
](/link/as.vector?package=base&version=3.6.2) ` 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.

##  Details

If ` X ` is not an array but an object of a class with a non-null ` [ dim
](/link/dim?package=base&version=3.6.2) ` value (such as a data frame), `
apply ` attempts to coerce it to an array via ` as.matrix ` if it is two-
dimensional (e.g., a data frame) or via ` as.array ` .

` FUN ` is found by a call to ` [ match.fun
](/link/match.fun?package=base&version=3.6.2) ` 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 `
apply ` .

Arguments in ` … ` cannot have the same name as any of the other arguments,
and care may be needed to avoid partial matching to ` MARGIN ` or ` FUN ` . In
general-purpose code it is good practice to name the first three arguments if
` … ` is passed through: this both avoids partial matching to ` MARGIN ` or `
FUN ` and ensures that a sensible error message is given if arguments named `
X ` , ` MARGIN ` or ` FUN ` are passed through ` … ` .

##  References

Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S Language_ .
Wadsworth & Brooks/Cole.

##  See Also

` [ lapply ](/link/lapply?package=base&version=3.6.2) ` and there, ` [
simplify2array ](/link/simplify2array?package=base&version=3.6.2) ` ; ` [
tapply ](/link/tapply?package=base&version=3.6.2) ` , and convenience
functions ` [ sweep ](/link/sweep?package=base&version=3.6.2) ` and ` [
aggregate ](/link/aggregate?package=base&version=3.6.2) ` .

##  Examples

[ Run this code
](https://app.datacamp.com/workspace/preview?_tag=rdocs&rdocsPath=packages%2Fbase%2Fversions%2F3.6.2%2Ftopics%2Fapply&utm_source=r-docs&utm_medium=docs&utm_term=apply&utm_content=run_example_in_workspace)

    
    
    # NOT RUN {
    ## 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",