Skip to main content

KMeans

Namespace: MATHLIB  ·  Library: Math Library

#include <math/kmeans.h>

class UTILSLIB::KMeans

Lloyd-style K-means partitional clustering with configurable distance metric, seeding strategy, replicate count, empty-cluster policy and optional online refinement phase.

Lloyd-style K-means clustering with configurable metric, seeding and replicates.

src/examples/ex_math/main.cpp
MatrixXd X(6, 2); // two well separated groups of three points
X << 0.0, 0.0, 0.1, 0.0, 0.0, 0.1, 5.0, 5.0, 5.1, 5.0, 5.0, 5.1;
KMeans kmeans(KMeansDistance::SquaredEuclidean, KMeansStart::Sample, 5); // best of 5 replicates
VectorXi idx;
MatrixXd centroids, distances;
VectorXd sumD;
kmeans.calculate(X, 2, idx, centroids, sumD, distances);

Public Methods​

KMeans(distance, start, replicates, emptyact, online, maxit)​

Constructs a KMeans algorithm object.

Parameters:

  • distance : QString (optional) K-Means distance measure: "sqeuclidean" (default), "cityblock" , "cosine", "correlation", "hamming".

  • start : QString (optional) Cluster initialization: "sample" (default), "uniform", "cluster".

  • replicates : qint32 (optional) Number of K-Means replicates, which are generated. Best is returned.

  • emptyact : QString (optional) What happens if a cluster goes empty: "error", "drop", "singleton" (default).

  • online : bool (optional) If centroids should be updated during iterations: true (default), false.

  • maxit : qint32 (optional) Maximal number of iterations per replicate; 100 by default.

KMeans(distance, start, replicates, emptyact, online, maxit)​

Constructs a KMeans algorithm object using enum parameters (preferred for performance).

Parameters:

  • distance : KMeansDistance Distance metric.

  • start : KMeansStart Cluster initialization strategy.

  • replicates : qint32 Number of K-Means replicates. Best is returned.

  • emptyact : KMeansEmptyAction What happens if a cluster goes empty.

  • online : bool If centroids should be updated during iterations.

  • maxit : qint32 Maximal number of iterations per replicate.

calculate(X, kClusters, idx, C, sumD, D)​

Clusters input data X.

Parameters:

  • X : const Eigen::MatrixXd & Input data (rows = points; cols = p dimensional space).

  • kClusters : qint32 Number of k clusters.

  • idx : Eigen::VectorXi & The cluster indices to which cluster the input points belong to.

  • C : Eigen::MatrixXd & Cluster centroids k x p.

  • sumD : Eigen::VectorXd & Summation of the distances to the centroid within one cluster.

  • D : Eigen::MatrixXd & Cluster distances to the centroid.

Returns:

  • bool — true if clustering succeeded, false otherwise.

calculate(X, start, idx, C, sumD, D)​

Clusters input data X from given initial centroids (MATLAB's numeric Start), running one replicate.

Parameters:

  • X : const Eigen::MatrixXd & Input data (rows = points; cols = p dimensional space).

  • start : const Eigen::MatrixXd & Initial centroids k x p; k is the number of clusters.

  • idx : Eigen::VectorXi & The cluster indices to which cluster the input points belong to.

  • C : Eigen::MatrixXd & Cluster centroids k x p.

  • sumD : Eigen::VectorXd & Summation of the distances to the centroid within one cluster.

  • D : Eigen::MatrixXd & Cluster distances to the centroid.

Returns:

  • bool — true if clustering succeeded, false otherwise.

Example​

Used in examples​

ex_math​

Math library on inputs with known answers.

src/examples/ex_math/main.cpp, line 163
MatrixXd X(6, 2); // two well separated groups of three points
X << 0.0, 0.0, 0.1, 0.0, 0.0, 0.1, 5.0, 5.0, 5.1, 5.0, 5.0, 5.1;
KMeans kmeans(KMeansDistance::SquaredEuclidean, KMeansStart::Sample, 5); // best of 5 replicates
VectorXi idx;
MatrixXd centroids, distances;
VectorXd sumD;
kmeans.calculate(X, 2, idx, centroids, sumD, distances);
const bool grouped = idx(0) == idx(1) && idx(1) == idx(2) && idx(3) == idx(4) && idx(4) == idx(5) && idx(0) != idx(3);
const double lowCentroid = std::min(centroids(0, 0), centroids(1, 0));
ok &= expect(grouped && std::fabs(lowCentroid - 0.1 / 3.0) < 1e-12, "KMeans finds both groups and their means");

Authors of this file​