% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gmeans.R
\name{gmeans}
\alias{gmeans}
\title{G-means Clustering}
\usage{
gmeans(x, k_init = 2L, k_max = 10L, level = 0.05, ...)
}
\arguments{
\item{x}{(\code{matrix()})\cr
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{k_init}{(\code{integer(1)})\cr
Initial amount of centers. Default is \code{2L}.}

\item{k_max}{(\code{integer(1)})\cr
Maximum amount of centers. Default is \code{10L}.}

\item{level}{(\code{numeric(1)})\cr
Significance level for the Anderson-Darling test.
Default is \code{0.05}. See \code{\link[=ad.test]{ad.test()}} for more information.}

\item{...}{(\code{any})\cr
Additional arguments passed to \code{\link[stats:kmeans]{stats::kmeans()}}.}
}
\value{
An object of class \code{c("gmeans", "kmeans")}. See \code{\link[stats:kmeans]{stats::kmeans()}} for details.
}
\description{
Perform G-means clustering on a data matrix.
}
\details{
The G-means clustering algorithm is an extension of the traditional k-means
algorithm that automatically determines the number of clusters by iteratively
testing the Gaussianity of data within clusters. The process begins with a specified
initial number of clusters (\code{k_init}) and iteratively increases the number of
clusters until it reaches the specified maximum (\code{k_max}) or the data within
clusters is determined to be Gaussian at the specified significance level (\code{level}).

The algorithm is outlined as follows:
\enumerate{
\item Let \eqn{C} be the initial set of centers (usually
\eqn{C \leftarrow \{\bar{x}\}}).
\item Perform k-means clustering on the dataset \eqn{X} using the current set of
centers \eqn{C}, i.e., \eqn{C \leftarrow \text{kmeans}(C, X)}.
\item For each center \eqn{c_j}, identify the set of data points
\eqn{\{x_i \mid \text{class}(x_i) = j\}} that are assigned to \eqn{c_j}.
\item Use the Anderson-Darling test to check if the set of data points
\eqn{\{x_i \mid \text{class}(x_i) = j\}} follows a Gaussian distribution
at the confidence level \eqn{\alpha}.
\item If the data points appear Gaussian, keep \eqn{c_j}.
Otherwise, replace \eqn{c_j} with two new centers.
\item Repeat from step 2 until no more centers are added.
}
}
\examples{
set.seed(123)
x <- rbind(
  matrix(rnorm(100, sd = 0.3), ncol = 2),
  matrix(rnorm(100, mean = 1, sd = 0.3), ncol = 2)
)
colnames(x) <- c("x", "y")
cl <- gmeans(x)
}
\references{
Hamerly, Greg, Elkan, Charles (2003).
\dQuote{Learning the k in k-means.}
In Thrun S, Saul L, Schölkopf B (eds.), \emph{Advances in Neural Information Processing Systems}, volume 16.
\url{https://proceedings.neurips.cc/paper_files/paper/2003/file/234833147b97bb6aed53a8f4f1c7a7d8-Paper.pdf}.
}
