EVOLUTION-MANAGER
Edit File: tapply.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Apply a Function Over a Ragged Array</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for tapply {base}"><tr><td>tapply {base}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Apply a Function Over a Ragged Array</h2> <h3>Description</h3> <p>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. </p> <h3>Usage</h3> <pre> tapply(X, INDEX, FUN = NULL, ..., default = NA, simplify = TRUE) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>X</code></td> <td> <p>an <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> object for which a <code><a href="split.html">split</a></code> method exists. Typically vector-like, allowing subsetting with <code><a href="Extract.html">[</a></code>.</p> </td></tr> <tr valign="top"><td><code>INDEX</code></td> <td> <p>a <code><a href="list.html">list</a></code> of one or more <code><a href="factor.html">factor</a></code>s, each of same length as <code>X</code>. The elements are coerced to factors by <code><a href="factor.html">as.factor</a></code>.</p> </td></tr> <tr valign="top"><td><code>FUN</code></td> <td> <p>a function (or name of a function) to be applied, or <code>NULL</code>. In the case of functions like <code>+</code>, <code>%*%</code>, etc., the function name must be backquoted or quoted. If <code>FUN</code> is <code>NULL</code>, tapply returns a vector which can be used to subscript the multi-way array <code>tapply</code> normally produces.</p> </td></tr> <tr valign="top"><td><code>...</code></td> <td> <p>optional arguments to <code>FUN</code>: the Note section.</p> </td></tr> <tr valign="top"><td><code>default</code></td> <td> <p>(only in the case of simplification to an array) the value with which the array is initialized as <code><a href="array.html">array</a>(default, dim = ..)</code>. Before <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> 3.4.0, this was hard coded to <code><a href="array.html">array</a>()</code>'s default <code>NA</code>. If it is <code>NA</code> (the default), the missing value of the answer type, e.g. <code><a href="NA.html">NA_real_</a></code>, is chosen (<code><a href="raw.html">as.raw</a>(0)</code> for <code>"raw"</code>). In a numerical case, it may be set, e.g., to <code>FUN(integer(0))</code>, e.g., in the case of <code>FUN = sum</code> to <code>0</code> or <code>0L</code>.</p> </td></tr> <tr valign="top"><td><code>simplify</code></td> <td> <p>logical; if <code>FALSE</code>, <code>tapply</code> always returns an array of mode <code>"list"</code>; in other words, a <code><a href="list.html">list</a></code> with a <code><a href="dim.html">dim</a></code> attribute. If <code>TRUE</code> (the default), then if <code>FUN</code> always returns a scalar, <code>tapply</code> returns an array with the mode of the scalar.</p> </td></tr> </table> <h3>Details</h3> <p>If <code>FUN</code> is not <code>NULL</code>, it is passed to <code><a href="match.fun.html">match.fun</a></code>, and hence it can be a function or a symbol or character string naming a function. </p> <h3>Value</h3> <p>When <code>FUN</code> is present, <code>tapply</code> calls <code>FUN</code> for each cell that has any data in it. If <code>FUN</code> returns a single atomic value for each such cell (e.g., functions <code>mean</code> or <code>var</code>) and when <code>simplify</code> is <code>TRUE</code>, <code>tapply</code> returns a multi-way <a href="array.html">array</a> containing the values, and <code>NA</code> for the empty cells. The array has the same number of dimensions as <code>INDEX</code> has components; the number of levels in a dimension is the number of levels (<code>nlevels()</code>) in the corresponding component of <code>INDEX</code>. Note that if the return value has a class (e.g., an object of class <code>"<a href="Dates.html">Date</a>"</code>) the class is discarded. </p> <p><code>simplify = TRUE</code> always returns an array, possibly 1-dimensional. </p> <p>If <code>FUN</code> does not return a single atomic value, <code>tapply</code> returns an array of mode <code><a href="list.html">list</a></code> whose components are the values of the individual calls to <code>FUN</code>, i.e., the result is a list with a <code><a href="dim.html">dim</a></code> attribute. </p> <p>When there is an array answer, its <code><a href="dimnames.html">dimnames</a></code> are named by the names of <code>INDEX</code> and are based on the levels of the grouping factors (possibly after coercion). </p> <p>For a list result, the elements corresponding to empty cells are <code>NULL</code>. </p> <h3>Note</h3> <p>Optional arguments to <code>FUN</code> supplied by the <code>...</code> argument are not divided into cells. It is therefore inappropriate for <code>FUN</code> to expect additional arguments with the same length as <code>X</code>. </p> <h3>References</h3> <p>Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) <em>The New S Language</em>. Wadsworth & Brooks/Cole. </p> <h3>See Also</h3> <p>the convenience functions <code><a href="by.html">by</a></code> and <code><a href="../../stats/html/aggregate.html">aggregate</a></code> (using <code>tapply</code>); <code><a href="apply.html">apply</a></code>, <code><a href="lapply.html">lapply</a></code> with its versions <code><a href="lapply.html">sapply</a></code> and <code><a href="mapply.html">mapply</a></code>. </p> <h3>Examples</h3> <pre> require(stats) groups <- as.factor(rbinom(32, n = 5, prob = 0.4)) tapply(groups, groups, length) #- is almost the same as table(groups) ## contingency table from data.frame : array with named dimnames tapply(warpbreaks$breaks, warpbreaks[,-1], sum) tapply(warpbreaks$breaks, warpbreaks[, 3, drop = FALSE], sum) n <- 17; fac <- factor(rep_len(1:3, n), levels = 1:5) table(fac) tapply(1:n, fac, sum) tapply(1:n, fac, sum, default = 0) # maybe more desirable tapply(1:n, fac, sum, simplify = FALSE) tapply(1:n, fac, range) tapply(1:n, fac, quantile) tapply(1:n, fac, length) ## NA's tapply(1:n, fac, length, default = 0) # == table(fac) ## example of ... argument: find quarterly means tapply(presidents, cycle(presidents), mean, na.rm = TRUE) ind <- list(c(1, 2, 2), c("A", "A", "B")) table(ind) tapply(1:3, ind) #-> the split vector tapply(1:3, ind, sum) ## Some assertions (not held by all patch propsals): nq <- names(quantile(1:5)) stopifnot( identical(tapply(1:3, ind), c(1L, 2L, 4L)), identical(tapply(1:3, ind, sum), matrix(c(1L, 2L, NA, 3L), 2, dimnames = list(c("1", "2"), c("A", "B")))), identical(tapply(1:n, fac, quantile)[-1], array(list(`2` = structure(c(2, 5.75, 9.5, 13.25, 17), .Names = nq), `3` = structure(c(3, 6, 9, 12, 15), .Names = nq), `4` = NULL, `5` = NULL), dim=4, dimnames=list(as.character(2:5))))) </pre> <hr /><div style="text-align: center;">[Package <em>base</em> version 3.6.0 <a href="00Index.html">Index</a>]</div> </body></html>