\name{clusteration}
\alias{clusteration}
\alias{nclusteration}
\alias{print.clusteration}
\title{ Cluster combinations }
\description{
  Functions to construct all possible groupings or calculate the number of possible groupings.
}
\usage{
clusteration(n = NULL, k = NULL, nmax = NULL, kmax = nmax)
nclusteration(n = NULL, k = NULL, nmax = NULL, kmax = nmax)
\method{print}{clusteration}(x, within = "-", between = "+", \dots)
}
\arguments{
  \item{n}{ number of elements }
  \item{k}{ number of groups (optional) }
  \item{nmax}{ maximal number of elements }
  \item{kmax}{ maximal number of groups }
  \item{x}{ an object of class 'clusteration' }
  \item{within}{ character to seperate elements within the same grouping }
  \item{between}{ charachter to seperate between groupings }
  \item{\dots}{ ignored }
}
\details{
  Can be used to create/calculate all groupings (using \code{nmax}), where the number of groupings can be restricted (\code{kmax}).
  The result is a matrix (n x k) which contains in the \code{\link[base]{lower.tri}} Jens' triangle not unlike Pascal's triangle.
  \cr
  Using \code{n} instead of \code{nmax} will return a vector equaling the last line of the triangle,
  using \code{k} can be used to directly return the groupings/number of groupings for a single fixed number of groups.
  All results are created using the triangle construction method
  just calling \code{nclusteration(n=, k=) makes use of Jensen's formula}
  \deqn{C(n,k)=\frac{1}{k!} \cdot \sum_{c=1}^{k}{\over{k}{c} \cdot k^n }}
  The triangle construction method uses the recursive formula
  \deqn{C(n,k)=C(n-1,k-1) + k \cdot C(n-1,k)}
  where \eqn{C(n,1)=1} and \eqn{C(n,n)=1}.
}
\value{
  Function \code{nclusteration} returns either a matrix[n,k] or a vector[k] or a scalar.
  Function \code{clusteration} returns either a list matrix[[n,k]] or a list vector[[k]] or a single element list vector[[1]] of list of \emph{groupings},
  where \emph{groupings} is a list with as many elements as groups and each group beeing represented by a vector of group member indices. A special print method prints this nicely.
}
\references{ Jensen, R.E. (1969) A dynamic programming algorithm for cluster analysis. \emph{Operations Research}, 17, 1034-57. }
\author{ Jens Oehlschlägel }
\note{ The total number of possible groupings increases worse than exponential }
\seealso{ \code{\link{margination}}, \code{\link{combination}}, \code{\link[base]{choose}} }
\examples{
   clusteration(nmax=5)
   clusteration(n=5)
   clusteration(n=5, k=3)
   nclusteration(nmax=5)
   nclusteration(n=5)
   nclusteration(n=5, k=3)

   n <- 100
   k <- 5
   x <- nclusteration(nmax=n)
   matplot(1:n, cbind((1:n)^(1:n), rowSums(x), k^(1:n), x[,k])
   , log="y", type="l"
   , lty=1:4, xlab="n"
   , ylab = "combinations"
   , main = "number of possible groupings"
   )
   legend(n,1
   , c(expression(n^n), expression(k \%in\% group("{", list(1,2,...,n), "}")), substitute(k^n, list(k=k)), substitute(k==c, list(c=k))
   ), lty=1:4, col=1:4, xjust=1, yjust=0)
}
\keyword{ math }
\keyword{ cluster }
