.. _library_kmeans_clusterer:

``kmeans_clusterer``
====================

k-Means clusterer. It uses Lloyd's algorithm with deterministic
initialization. Supports continuous attributes only.

The library implements the ``clusterer_protocol`` defined in the
``clustering_protocols`` library. It provides predicates for learning a
clusterer from a dataset, assigning new instances to clusters, and
exporting the learned clusterer as a list of predicate clauses or to a
file.

Datasets are represented as objects implementing the
``clustering_dataset_protocol`` protocol from the
``clustering_protocols`` library.

API documentation
-----------------

Open the
`../../apis/library_index.html#kmeans_clusterer <../../apis/library_index.html#kmeans_clusterer>`__
link in a web browser.

Loading
-------

To load this library, load the ``loader.lgt`` file:

::

   | ?- logtalk_load(kmeans_clusterer(loader)).

Testing
-------

To test this library predicates, load the ``tester.lgt`` file:

::

   | ?- logtalk_load(kmeans_clusterer(tester)).

To run the performance benchmark suite, load the
``tester_performance.lgt`` file:

::

   | ?- logtalk_load(kmeans_clusterer(tester_performance)).

Features
--------

- **Continuous Datasets**: Accepts datasets containing only continuous
  attributes.
- **Deterministic Initialization**: Supports ``first_k`` and
  deterministic ``spread`` initialization that repeatedly chooses the
  farthest example from the centroids selected so far.
- **Optional Feature Scaling**: Continuous attributes can be
  standardized using z-score scaling.
- **Rich Training Diagnostics**: Learned clusterers report training
  example count, convergence status, iteration count, and final centroid
  shift.
- **Portable Export**: Learned clusterers can be exported as clauses or
  files and reused later.
- **Stable Empty-Cluster Handling**: Empty clusters keep their previous
  centroids instead of failing.

Options
-------

The following options can be passed to the ``learn/3`` predicate:

- ``k(K)``: Number of clusters to learn. Default is ``2``.
- ``maximum_iterations(Iterations)``: Maximum number of Lloyd
  iterations. Default is ``100``.
- ``tolerance(Tolerance)``: Maximum centroid shift threshold for
  convergence. Default is ``1.0e-6``.
- ``initialization(Initialization)``: Centroid initialization strategy.
  Options: ``spread`` (default) or ``first_k``.
- ``feature_scaling(FeatureScaling)``: Whether to standardize continuous
  attributes before clustering. Options: ``on`` (default) or ``off``.

Diagnostics
-----------

The ``diagnostics/2`` predicate returns a list containing:

- ``model(kmeans_clusterer)``
- ``centroid_count(Count)``
- ``training_example_count(Count)``
- ``convergence(Reason)``
- ``iterations(Count)``
- ``final_shift(Shift)``
- ``options(Options)``

Clusterer representation
------------------------

The learned clusterer is represented as a compound term with the functor
chosen by the user when exporting the clusterer and arity 4. For
example:

::

   kmeans_clusterer(Encoders, Centroids, Options, Diagnostics)

Where:

- ``Encoders``: List of continuous attribute encoders storing attribute
  name, mean, and scale.
- ``Centroids``: List of centroid vectors in cluster-id order.
- ``Options``: Effective training options used to learn the clusterer.
- ``Diagnostics``: Training diagnostics metadata returned by the
  ``diagnostics/2`` predicate.

References
----------

1. MacQueen (1967) - "Some Methods for Classification and Analysis of
   Multivariate Observations". Proceedings of the Fifth Berkeley
   Symposium on Mathematical Statistics and Probability.
2. Lloyd (1982) - "Least Squares Quantization in PCM". IEEE Transactions
   on Information Theory, 28(2), 129-137.
