XMeans<T>

Models & Types · AiDotNet.Clustering.AutoK

X-Means clustering with automatic K determination using BIC.

Inheritance: ClusteringBase<T> → XMeans<T>

For Beginners

X-Means is K-Means that chooses K for you.

Instead of guessing the right number of clusters:

  • Start small (e.g., K=2)
  • Try splitting each cluster
  • Keep splits that make statistical sense
  • Stop when splitting doesn’t help

BIC tells us when a split is worthwhile:

  • Lower BIC = better model
  • Splitting adds complexity (penalized)
  • Only split if the fit improvement outweighs the penalty

How It Works

X-Means iteratively applies K-Means and decides whether to split clusters based on the Bayesian Information Criterion (BIC). It automatically determines the optimal number of clusters.

Algorithm:

  1. Run K-Means with initial K
  2. For each cluster, try splitting into two
  3. Compare BIC of parent vs children
  4. Accept split if BIC improves
  5. Repeat until no splits improve or max K reached

Example

using AiDotNet;
using AiDotNet.Data.Loaders;
using AiDotNet.Clustering.AutoK;
using AiDotNet.Tensors.LinearAlgebra;

var data = new Matrix<double>(6, 2);
double[][] rows = { new[] { 1.0, 1.0 }, new[] { 1.2, 0.9 }, new[] { 1.1, 1.1 },
                    new[] { 8.0, 8.0 }, new[] { 8.2, 7.9 }, new[] { 7.9, 8.1 } };
for (int i = 0; i < 6; i++) { data[i, 0] = rows[i][0]; data[i, 1] = rows[i][1]; }

var result = await new AiModelBuilder<double, Matrix<double>, Vector<double>>()
    .ConfigureModel(new XMeans<double>())
    .ConfigureDataLoader(DataLoaders.FromMatrix(data))
    .BuildAsync();

var labels = result.Predict(data);
Console.WriteLine($"XMeans: clustered {labels.Length} points.");

Constructors

Constructor Summary
XMeans(XMeansOptions<T> options) Initializes a new XMeans instance.

Properties

Property Summary
T BIC { get; } Gets the final BIC value.

Methods

Method Summary
IFullModel<T, Matrix<T>, Vector<T>> WithParameters(Vector<T> parameters)
ModelOptions GetOptions()
Vector<T> FitPredict(Matrix<T> x)
Vector<T> Predict(Matrix<T> x)
void Train(Matrix<T> x, Vector<T> y)