________________________________________________________________________

This file is part of Logtalk <https://logtalk.org/>
SPDX-FileCopyrightText: 1998-2026 Paulo Moura <pmoura@logtalk.org>
SPDX-License-Identifier: Apache-2.0

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
________________________________________________________________________


`kmedoids_clusterer`
==========

k-Medoids clusterer. It uses an iterative medoid-update algorithm with
deterministic initialization and deterministic cluster assignments.
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#kmedoids_clusterer](../../apis/library_index.html#kmedoids_clusterer)
link in a web browser.


Loading
-------

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

	| ?- logtalk_load(kmedoids_clusterer(loader)).


Testing
-------

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

	| ?- logtalk_load(kmedoids_clusterer(tester)).

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

	| ?- logtalk_load(kmedoids_clusterer(tester_performance)).


Features
--------

- **Continuous Datasets**: Accepts datasets containing only continuous attributes.
- **Distance Metrics**: Supports Euclidean and Manhattan distances.
- **Deterministic Initialization**: Supports `first_k` and deterministic `spread` initialization that repeatedly chooses the farthest example from the medoids 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 medoid shift.
- **Portable Export**: Learned clusterers can be exported as clauses or files and reused later.
- **Stable Empty-Cluster Handling**: Empty clusters keep their previous medoids 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 medoid-update iterations. Default is `100`.
- `tolerance(Tolerance)`: Maximum medoid shift threshold for convergence. Default is `1.0e-6`.
- `initialization(Initialization)`: Medoid initialization strategy. Options: `spread` (default) or `first_k`.
- `distance_metric(Metric)`: Distance metric to use. Options: `euclidean` (default) or `manhattan`.
- `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(kmedoids_clusterer)`
- `medoid_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:

	kmedoids_clusterer(Encoders, Medoids, Options, Diagnostics)

Where:

- `Encoders`: List of continuous attribute encoders storing attribute name, mean, and scale.
- `Medoids`: List of medoid 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. Kaufman & Rousseeuw (1987) - "Clustering by Means of Medoids". In Statistical Data Analysis Based on the L1-Norm and Related Methods.
2. Kaufman & Rousseeuw (1990) - "Finding Groups in Data: An Introduction to Cluster Analysis". Wiley.
