\Header{kmeans}{K-Means Clustering}
\keyword{multivariate}{kmeans}
\keyword{cluster}{kmeans}
\begin{Description}\relax
Perform k-means clustering on a data matrix.
\end{Description}
\begin{Usage}
\begin{verbatim}
kmeans(x, centers, iter.max = 10)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] A numeric matrix of data, or an object that can be coerced to such a
matrix (such as a numeric vector or a data frame with all numeric columns).

\item[\code{centers}] Either the number of clusters or a set of initial cluster centers.
If the first, a random set of rows in \code{x} are chosen as the initial
centers.

\item[\code{iter.max}] The maximum number of iterations allowed.

\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The data given by \code{x} is clustered by the k-means algorithm.
When this terminates, all cluster centres are at the mean of
their Voronoi sets (the set of data points which are nearest to
the cluster centre).

The algorithm of Hartigan and Wong (1979) is used.
\end{Details}
\begin{Value}
A list with components:

\begin{ldescription}
\item[\code{cluster}] A vector of integers indicating the cluster to which each point is
allocated.

\item[\code{centers}] A matrix of cluster centres.
\item[\code{withinss}] The within-cluster sum of squares for each cluster.
\item[\code{size}] The number of points in each cluster.
\end{ldescription}
\end{Value}
\begin{References}\relax
Hartigan, J.A. and Wong, M.A. (1979).
A K-means clustering algorithm.
\emph{Applied Statistics} \bold{28}, 100--108.
\end{References}
\begin{Examples}
\begin{ExampleCode}
# a 2-dimensional example
x <- rbind(matrix(rnorm(100, sd = 0.3), ncol = 2),
           matrix(rnorm(100, mean = 1, sd = 0.3), ncol = 2))
cl <- kmeans(x, 2, 20)
plot(x, col = cl$cluster)
points(cl$centers, col = 1:2, pch = 8)
\end{ExampleCode}
\end{Examples}

