[ 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)

#  tapply: Apply a Function Over a Ragged Array

##  Description

Apply a function to each cell of a ragged array, that is to each (non-empty)
group of values given by a unique combination of the levels of certain
factors.

##  Usage

    
    
    tapply(X, INDEX, FUN = NULL, …, default = NA, simplify = TRUE)

##  Arguments

X

an  R  object for which a ` [ split ](/link/split?package=base&version=3.6.2)
` method exists. Typically vector-like, allowing subsetting with ` [ [
](/link/%5B?package=base&version=3.6.2) ` .

INDEX

a ` [ list ](/link/list?package=base&version=3.6.2) ` of one or more ` [
factor ](/link/factor?package=base&version=3.6.2) ` s, each of same length as
` X ` . The elements are coerced to factors by ` [ as.factor
](/link/as.factor?package=base&version=3.6.2) ` .

FUN

a function (or name of a function) to be applied, or ` NULL ` . In the case of
functions like ` + ` , ` %*% ` , etc., the function name must be backquoted or
quoted. If ` FUN ` is ` NULL ` , tapply returns a vector which can be used to
subscript the multi-way array ` tapply ` normally produces.

…

optional arguments to ` FUN ` : the Note section.

default

(only in the case of simplification to an array) the value with which the
array is initialized as ` [ array ](/link/array?package=base&version=3.6.2)
(default, dim = ..) ` . Before  R  3.4.0, this was hard coded to ` [ array
](/link/array?package=base&version=3.6.2) () ` 's default ` NA ` . If it is `
NA ` (the default), the missing value of the answer type, e.g. ` [ NA_real_
](/link/NA_real_?package=base&version=3.6.2) ` , is chosen ( ` [ as.raw
](/link/as.raw?package=base&version=3.6.2) (0) ` for ` "raw" ` ). In a
numerical case, it may be set, e.g., to ` FUN(integer(0)) ` , e.g., in the
case of ` FUN = sum ` to ` 0 ` or ` 0L ` .

simplify

logical; if ` FALSE ` , ` tapply ` always returns an array of mode ` "list" `
; in other words, a ` [ list ](/link/list?package=base&version=3.6.2) ` with a
` [ dim ](/link/dim?package=base&version=3.6.2) ` attribute. If ` TRUE ` (the
default), then if ` FUN ` always returns a scalar, ` tapply ` returns an array
with the mode of the scalar.

##  Value

When ` FUN ` is present, ` tapply ` calls ` FUN ` for each cell that has any
data in it. If ` FUN ` returns a single atomic value for each such cell (e.g.,
functions ` mean ` or ` var ` ) and when ` simplify ` is ` TRUE ` , ` tapply `
returns a multi-way [ array ](/link/array?package=base&version=3.6.2)
containing the values, and ` NA ` for the empty cells. The array has the same
number of dimensions as ` INDEX ` has components; the number of levels in a
dimension is the number of levels ( ` nlevels() ` ) in the corresponding
component of ` INDEX ` . Note that if the return value has a class (e.g., an
object of class ` " [ Date ](/link/Date?package=base&version=3.6.2) " ` ) the
class is discarded.

` simplify = TRUE ` always returns an array, possibly 1-dimensional.

If ` FUN ` does not return a single atomic value, ` tapply ` returns an array
of mode ` [ list ](/link/list?package=base&version=3.6.2) ` whose components
are the values of the individual calls to ` FUN ` , i.e., the result is a list
with a ` [ dim ](/link/dim?package=base&version=3.6.2) ` attribute.

When there is an array answer, its ` [ dimnames
](/link/dimnames?package=base&version=3.6.2) ` are named by the names of `
INDEX ` and are based on the levels of the grouping factors (possibly after
coercion).

For a list result, the elements corresponding to empty cells are ` NULL ` .

##  Details

If ` FUN ` is not ` NULL ` , it is passed to ` [ match.fun
](/link/match.fun?package=base&version=3.6.2) ` , and hence it can be a
function or a symbol or character string naming a function.

##  References

Becker, R. A., Chamb