blob: 2185ba3a69b9a2d642a473d8019059747e144134 [file] [log] [blame]
% File src/library/base/man/grouping.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2016 R Core Team
% Distributed under GPL 2 or later
\name{grouping}
\title{Grouping Permutation}
\alias{grouping}
\concept{aggregation}
\description{
\code{grouping} returns a permutation which rearranges its first
argument such that identical values are adjacent to each other. Also
returned as attributes are the group-wise partitioning and the maximum
group size.
}
\usage{
grouping(\dots)
}
\arguments{
\item{\dots}{a sequence of numeric, character or logical
vectors, all of the same length, or a classed \R object.}
}
\details{
The function partially sorts the elements so that identical values are
adjacent. \code{NA} values come last. This is guaranteed to be
stable, so ties are preserved, and if the data are already
grouped/sorted, the grouping is unchanged. This is useful for
aggregation and is particularly fast for character vectors.
Under the covers, the \code{"radix"} method of \code{\link{order}} is
used, and the same caveats apply, including restrictions on character
encodings and lack of support for long vectors (those with
\eqn{2^{31}}{2^31} or more elements). Real-valued numbers are slightly
rounded to account for numerical imprecision.
Like \code{order}, for a classed \R object the grouping is based on
the result of \code{\link{xtfrm}}.
}
\value{
An object of class \code{"grouping"}, the representation of which
should be considered experimental and subject to change. It is an
integer vector with two attributes:
\item{ends}{subscripts in the result corresponding to the last
member of each group}
\item{maxgrpn}{the maximum group size}
}
\seealso{
\code{\link{order}}, \code{\link{xtfrm}}.
}
\examples{
(ii <- grouping(x <- c(1, 1, 3:1, 1:4, 3), y <- c(9, 9:1), z <- c(2, 1:9)))
## 6 5 2 1 7 4 10 8 3 9
rbind(x, y, z)[, ii]
}
\keyword{manip}