# [Rd] Statistical mode

Arni Magnusson arnima at hafro.is
Thu May 26 22:26:26 CEST 2011

One descriptive statistic that is conspicuously missing from core R is the
statistical mode - the most frequent value in a discrete distribution.

I would like to propose adding the attached 'statmode' (or a similar
function) to the 'stats' package.

Currently, it can be quite cumbersome to calculate the mode of a
distribution in R, both for experts and beginners. The lack of a function
to do this is felt, both when teaching introductory R courses, and when
using sapply() or the like.

Looking forward to your feedback,

Arni
-------------- next part --------------
statmode <- function(x, all=FALSE, ...)
{
if(is.list(x))
{
output <- sapply(x, statmode, all=all, ...)
}
else
{
freq <- table(x, ...)
if(all)
output <- names(freq)[freq==max(freq)]
else
output <- names(freq)[which.max(freq)]
## Coerce to original data type, using any() to handle mts, xtabs, etc.
if(any(class(x) %in% c("integer","numeric","ts","complex","matrix","table")))
output <- as(output, storage.mode(x))
}
return(output)
}
-------------- next part --------------
\name{statmode}
\alias{statmode}
\title{Statistical Mode}
\description{
Compute the statistical mode, the most frequent value in a discrete
distribution.
}
\usage{
statmode(x, all = FALSE, \dots)
}
\arguments{
\item{x}{an \R object, usually vector, matrix, or data frame.}
\item{all}{whether all statistical modes should be returned.}
\item{\dots}{further arguments passed to the \code{\link{table}}
function.}
}
\details{The default is to return only the first statistical mode.}
\value{
The most frequent value in \code{x}, possibly a vector or list,
depending on the class of \code{x} and whether \code{all=TRUE}.
}
\seealso{

\code{\link{density}} can be used to compute the statistical mode of a
continuous distribution.
}
\examples{
## Different location statistics
fw <- faithful$waiting hist(fw) barplot(table(fw)) mean(fw) median(fw) statmode(fw) plot(density(fw)) with(density(fw), x[which.max(y)]) ## Different classes statmode(chickwts$feed)  # factor
statmode(volcano)        # matrix
statmode(discoveries)    # ts
statmode(mtcars)         # data frame

## Multiple modes
table(mtcars$carb) statmode(mtcars$carb)
statmode(mtcars\$carb, TRUE)
statmode(mtcars, TRUE)
}
\keyword{univar}