[Rd] Statistical mode

[Arni Magnusson]

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{mean}}, \code{\link{median}}, \code{\link{table}}.

  \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}