cmp::cluster::GeometricCluster Class Reference

Implements a standard k-means clustering algorithm. More...

#include <cluster.h>

Public Member Functions
	GeometricCluster ()=default
bool	fit (const Eigen::Ref< const Eigen::MatrixXd > &points, size_t nClusters, std::default_random_engine &rng, size_t max_iter=1000)
	Fits the K-means clustering model on the given dataset.
const size_t &	operator[] (size_t i) const
	Accesses the cluster label of the i-th point.
Eigen::VectorXd	centroid (size_t i) const
	Returns the centroid of the i-th cluster.
size_t	nClusters () const
	Returns the number of clusters.
size_t	nPoints () const
	Returns the number of data points.
size_t	dim () const
	Returns the dimension of the data.
const Eigen::VectorXs &	getLabels () const
	Returns the cluster assignments vector.

Private Attributes
Eigen::VectorXs	labels_
	Cluster label assigned to each data point.
Eigen::MatrixXd	centroids_
	Centroid coordinates for each cluster.
size_t	nClusters_
	Number of clusters.
size_t	nPoints_
	Number of data points.
size_t	dim_
	Dimensionality of data features.

Detailed Description

Implements a standard k-means clustering algorithm.

Mathematical Formulation K-means partitions \(N\) observations \(\{\mathbf{x}_1, \dots, \mathbf{x}_N\}\) where \(\mathbf{x}_j \in \mathbb{R}^d\) into \(K\) clusters \(\mathbf{S} = \{S_1, \dots, S_K\}\) to minimize the within-cluster sum of squares (WCSS):

\[ \arg\min_{\mathbf{S}} \sum_{i=1}^K \sum_{\mathbf{x} \in S_i} \|\mathbf{x} - \boldsymbol{\mu}_i\|_2^2 \]

where \(\boldsymbol{\mu}_i\) is the centroid of the points in \(S_i\).

Implementation Algorithm

1. Initialize centroids \(\boldsymbol{\mu}_i\) by randomly selecting \(K\) distinct data points.
2. Assign each point \(\mathbf{x}_j\) to the cluster with the nearest centroid:

   \[ S_i^{(t)} = \left\{ \mathbf{x}_j : \|\mathbf{x}_j - \boldsymbol{\mu}_i^{(t)}\|_2 \le \|\mathbf{x}_j - \boldsymbol{\mu}_m^{(t)}\|_2 \ \forall m=1,\dots,K \right\} \]

3. Update the centroids to be the arithmetic mean of all points in that cluster:

   \[ \boldsymbol{\mu}_i^{(t+1)} = \frac{1}{|S_i^{(t)}|} \sum_{\mathbf{x}_j \in S_i^{(t)}} \mathbf{x}_j \]

4. Iterate steps 2-3 until convergence (centroids no longer change or max_iter is reached).

Constructor & Destructor Documentation

GeometricCluster()

cmp::cluster::GeometricCluster::GeometricCluster ( )

default

Member Function Documentation

centroid()

Eigen::VectorXd cmp::cluster::GeometricCluster::centroid

(

size_t

i

)

const

Returns the centroid of the i-th cluster.

Parameters

i	Cluster index.

Returns

Vector representation of the cluster centroid.

dim()

size_t cmp::cluster::GeometricCluster::dim

(

)

const

Returns the dimension of the data.

fit()

bool cmp::cluster::GeometricCluster::fit	(	const Eigen::Ref< const Eigen::MatrixXd > &	points,
		size_t	nClusters,
		std::default_random_engine &	rng,
		size_t	max_iter = 1000
	)

Fits the K-means clustering model on the given dataset.

Parameters

points	N x d matrix of points to cluster.
nClusters	The number of clusters K.
rng	Random number generator used to initialize centroids.
max_iter	Maximum number of K-means iterations.

Returns

true if convergence was reached, false if maximum iterations was exceeded.

getLabels()

const Eigen::VectorXs & cmp::cluster::GeometricCluster::getLabels ( ) const

inline

Returns the cluster assignments vector.

Returns

Reference to the vector of cluster labels.

nClusters()

size_t cmp::cluster::GeometricCluster::nClusters

(

)

const

Returns the number of clusters.

nPoints()

size_t cmp::cluster::GeometricCluster::nPoints

(

)

const

Returns the number of data points.

operator[]()

const size_t & cmp::cluster::GeometricCluster::operator[]

(

size_t

i

)

const

Accesses the cluster label of the i-th point.

Parameters

i	Index of the point.

Returns

Cluster label index.

Member Data Documentation

centroids_

Eigen::MatrixXd cmp::cluster::GeometricCluster::centroids_

private

Centroid coordinates for each cluster.

dim_

size_t cmp::cluster::GeometricCluster::dim_

private

Dimensionality of data features.

labels_

Eigen::VectorXs cmp::cluster::GeometricCluster::labels_

private

Cluster label assigned to each data point.

nClusters_

size_t cmp::cluster::GeometricCluster::nClusters_

private

Number of clusters.

nPoints_

size_t cmp::cluster::GeometricCluster::nPoints_

private

Number of data points.

---

The documentation for this class was generated from the following files:

• include/cluster.h
• src/cluster.cpp