File: mApply.Rd

package info (click to toggle)
hmisc 4.2-0-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 3,332 kB
  • sloc: asm: 27,116; fortran: 606; ansic: 411; xml: 160; makefile: 2
file content (85 lines) | stat: -rw-r--r-- 2,718 bytes parent folder | download | duplicates (6)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
\name{mApply}
\concept{apply for matrix}
\concept{apply for vector}
\alias{mApply}

\title{Apply a Function to Rows of a Matrix or Vector}

\description{
\code{mApply} is like \code{tapply} except that the first argument can
be a matrix or a vector, and the output is cleaned up if \code{simplify=TRUE}.
It uses code adapted from Tony Plate (\email{tplate@blackmesacapital.com}) to
operate on grouped submatrices.

As \code{mApply} can be much faster than using \code{by}, it is often
worth the trouble of converting a data frame to a numeric matrix for
processing by \code{mApply}.  \code{asNumericMatrix} will do this, and
\code{matrix2dataFrame} will convert a numeric matrix back into a data
frame.
}

\usage{
mApply(X, INDEX, FUN, \dots, simplify=TRUE, keepmatrix=FALSE)
}

\arguments{
\item{X}{
a vector or matrix capable of being operated on by the
function specified as the \code{FUN} argument
}
\item{INDEX}{
list of factors, each of same number of rows as 'X' has.
}
\item{FUN}{
the function to be applied.  In the case of functions like
'+', '%*%', etc., the function name must be quoted.
}
\item{\dots}{
optional arguments to 'FUN'.
}
\item{simplify}{
set to 'FALSE' to suppress simplification of the result in to
an array, matrix, etc.
}
\item{keepmatrix}{set to \code{TRUE} to keep result as a matrix even if
  \code{simplify} is \code{TRUE}, in the case of only one stratum
  }
}
\value{
For \code{mApply}, the returned value is a vector, matrix, or list.
If \code{FUN} returns more than one number, the result is an array if
\code{simplify=TRUE} and is a list otherwise.  If a matrix is returned,
its rows correspond to unique combinations of \code{INDEX}.  If
\code{INDEX} is a list with more than one vector, \code{FUN} returns
more than one number, and \code{simplify=FALSE}, the returned value is a
list that is an array with the first dimension corresponding to the last
vector in \code{INDEX}, the second dimension corresponding to the next
to last vector in \code{INDEX}, etc., and the elements of the list-array
correspond to the values computed by \code{FUN}.  In this situation the
returned value is a regular array if \code{simplify=TRUE}.   The order
of dimensions is as previously but the additional (last) dimension
corresponds to values computed by \code{FUN}.
}

\author{
Frank Harrell
\cr
Department of Biostatistics
\cr
Vanderbilt University
\cr
\email{f.harrell@vanderbilt.edu}
}

\seealso{
\code{\link{asNumericMatrix}}, \code{\link{matrix2dataFrame}}, \code{\link{tapply}},
\code{\link{sapply}}, \code{\link{lapply}}, \code{\link{mapply}}, \code{\link{by}}.
}

\examples{
require(datasets, TRUE)
a <- mApply(iris[,-5], iris$Species, mean)
}

\keyword{iteration}
\keyword{category}