kmedoids

https://python-kmedoids.readthedocs.io/en/latest/
Admin
kmedoids is a fast k-medoids clustering library for Python that implements FasterPAM, FastPAM, and...
Tokens:9,485
Snippets:95
Trust Score:9.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Compile and Install from Source

Source: https://python-kmedoids.readthedocs.io/en/latest

Install the package by compiling the Rust code. Ensure you have Rust and Python 3 installed, and use a virtual environment. This method uses the latest git version.

```bash
pip install maturin
git clone https://github.com/kno10/python-kmedoids.git
cd python-kmedoids
# build and install the package:
maturin develop --release
```

--------------------------------

### Install kmedoids with pip

Source: https://python-kmedoids.readthedocs.io/en/latest/_sources/index.rst.txt

Install the kmedoids package using pip. This is the standard method for most users.

```sh
pip install kmedoids
```

--------------------------------

### DynMSC Algorithm Example

Source: https://python-kmedoids.readthedocs.io/en/latest

Example demonstrating the use of the DynMSC algorithm to find the optimal number of clusters within a specified range.

```APIDOC
## Choosing the optimal number of clusters
This package includes DynMSC, an algorithm that optimizes the Medoid Silhouette, and chooses the “optimal” number of clusters in a range of kmin..kmax. Beware that if you allow a too large kmax, the optimum result will likely have many one-elemental clusters. A too high kmax may mask more desirable results, hence it is recommended that you choose only 2-3 times the number of clusters you expect as maximum.
```python
import kmedoids, numpy
from sklearn.datasets import fetch_openml
from sklearn.metrics.pairwise import euclidean_distances
X, _ = fetch_openml('mnist_784', version=1, return_X_y=True, as_frame=False)
X = X[:10000]
diss = euclidean_distances(X)
kmin = 10
kmax = 20
dm = kmedoids.dynmsc(diss, kmax, kmin)
print("Optimal number of clusters according to the Medoid Silhouette:", dm.bestk)
print("Medoid Silhouette over range of k:", dm.losses)
print("Range of k:", dm.rangek)
```
```

--------------------------------

### Basic kmedoids clustering

Source: https://python-kmedoids.readthedocs.io/en/latest/_sources/index.rst.txt

Perform k-medoids clustering using the fasterpam algorithm. This example assumes a pre-computed distance matrix.

```python
import kmedoids
c = kmedoids.fasterpam(distmatrix, 5)
print("Loss is:", c.loss)
```

--------------------------------

### FasterPAM Algorithm

Source: https://python-kmedoids.readthedocs.io/en/latest

Example of using the FasterPAM algorithm with a distance matrix.

```APIDOC
## FasterPAM Algorithm

### Description
Directly call the `fasterpam` function with a precomputed distance matrix and the desired number of clusters.

### Method
`kmedoids.fasterpam(distmatrix, n_clusters)`

### Parameters
- **distmatrix** (numpy.ndarray or similar) - Required - A square matrix representing the pairwise distances between data points.
- **n_clusters** (int) - Required - The number of clusters to form.

### Response
- **loss** (float) - The clustering loss.

### Request Example
```python
import kmedoids
c = kmedoids.fasterpam(distmatrix, 5)
print("Loss is:", c.loss)
```
```

--------------------------------

### Install kmedoids with conda

Source: https://python-kmedoids.readthedocs.io/en/latest/_sources/index.rst.txt

Install the kmedoids package from the conda-forge channel. This is an alternative installation method.

```sh
conda install -c conda-forge kmedoids
```

--------------------------------

### Compile kmedoids from source

Source: https://python-kmedoids.readthedocs.io/en/latest/_sources/index.rst.txt

Build and install the kmedoids package from source. This requires Rust and Python 3, and uses maturin for compilation.

```sh
# activate your desired virtual environment first
pip install maturin
git clone https://github.com/kno10/python-kmedoids.git
cd python-kmedoids
# build and install the package:
maturin develop --release
```

--------------------------------

### Run integration tests

Source: https://python-kmedoids.readthedocs.io/en/latest/_sources/index.rst.txt

Execute integration tests to validate the kmedoids installation. This command discovers and runs tests within the tests directory.

```sh
python -m unittest discover tests
```

--------------------------------

### sklearn-compatible KMedoids Class

Source: https://python-kmedoids.readthedocs.io/en/latest

Example of using the sklearn-compatible KMedoids class for clustering.

```APIDOC
## sklearn-compatible KMedoids Class

### Description
Instantiate the `KMedoids` class for a scikit-learn compatible API. It defaults to the 'precomputed' metric, expecting a distance matrix. If scikit-learn is installed, you can use `metric='euclidean'` for other distance types.

### Method
`kmedoids.KMedoids(n_clusters, **kwargs)`

### Parameters
- **n_clusters** (int) - Required - The number of clusters to form.
- **method** (str) - Optional - The k-medoids algorithm to use (e.g., 'fasterpam'). Defaults to 'fasterpam'.
- **metric** (str) - Optional - The distance metric to use. Defaults to 'precomputed'.

### Response
- **inertia_** (float) - The inertia (sum of squared distances to the nearest centroid) of the solution.

### Request Example
```python
import kmedoids
km = kmedoids.KMedoids(5, method='fasterpam')
c = km.fit(distmatrix)
print("Loss is:", c.inertia_)
```
```

--------------------------------

### get_params(deep=True)

Source: https://python-kmedoids.readthedocs.io/en/latest

Gets the parameters for this estimator.

```APIDOC
## get_params(deep=True)

### Description
Get parameters for this estimator.

### Parameters

#### `deep` (bool, default=True)
  If True, will return the parameters for this estimator and contained subobjects that are estimators.

```

--------------------------------

### kmedoids.fastmsc

Source: https://python-kmedoids.readthedocs.io/en/latest

FastMSC clustering is an accelerated version of PAMMEDSIL clustering. It performs the same swaps as the original PAMMEDSIL (given the same starting conditions) but finds the best swap O(k^2) times faster.

```APIDOC
## kmedoids.fastmsc

### Description
FastMSC clustering is an accelerated version of PAMMEDSIL clustering. It performs the same swaps as the original PAMMEDSIL (given the same starting conditions) but finds the best swap O(k^2) times faster.

### Parameters
* **diss** (ndarray) – square numpy array of dissimilarities
* **medoids** (int or ndarray) – number of clusters to find or existing medoids
* **max_iter** (int) – maximum number of iterations
* **init** (str, "random", "first" or "build") – initialization method
* **random_state** (int, RandomState instance or None) – random seed if no medoids are given

### Returns
k-medoids clustering result

### Return type
KMedoidsResult
```

--------------------------------

### PAM BUILD Algorithm

Source: https://python-kmedoids.readthedocs.io/en/latest/_sources/index.rst.txt

Implementation of the BUILD step of the PAM algorithm.

```APIDOC
## PAM BUILD

### Description
Implementation of the BUILD step of the PAM algorithm.

### Function Signature
.. autofunction:: pam_build
```

--------------------------------

### PAM Algorithm

Source: https://python-kmedoids.readthedocs.io/en/latest/_sources/index.rst.txt

Implementation of the Partitioning Around Medoids (PAM) algorithm with BUILD and SWAP steps.

```APIDOC
## PAM

### Description
Implementation of the PAM algorithm with BUILD and SWAP.

### Function Signature
.. autofunction:: pam
```

--------------------------------

### MNIST Dataset Clustering Comparison

Source: https://python-kmedoids.readthedocs.io/en/latest

Load the MNIST dataset, compute the Euclidean distance matrix, and compare the performance and loss of FasterPAM and PAM algorithms. Timing is included for performance measurement.

```python
import kmedoids
import numpy
from sklearn.datasets import fetch_openml
from sklearn.metrics.pairwise import euclidean_distances
import time
X, _ = fetch_openml('mnist_784', version=1, return_X_y=True, as_frame=False)
X = X[:10000]
diss = euclidean_distances(X)
start = time.time()
fp = kmedoids.fasterpam(diss, 100)
print("FasterPAM took: %.2f ms" % ((time.time() - start)*1000))
print("Loss with FasterPAM:", fp.loss)
start = time.time()
pam = kmedoids.pam(diss, 100)
print("PAM took: %.2f ms" % ((time.time() - start)*1000))
print("Loss with PAM:", pam.loss)
```

--------------------------------

### FasterPAM and PAM Comparison on MNIST

Source: https://python-kmedoids.readthedocs.io/en/latest

Compares the performance and loss of FasterPAM and PAM algorithms on the MNIST dataset.

```APIDOC
## FasterPAM and PAM Comparison on MNIST

### Description
This example demonstrates how to use both `fasterpam` and `pam` functions on a subset of the MNIST dataset, measuring the time taken and the resulting clustering loss.

### Parameters
- **diss** (numpy.ndarray) - Pairwise distance matrix computed from the MNIST data.
- **n_clusters** (int) - The number of clusters to form (100 in this example).

### Request Example
```python
import kmedoids
import numpy
from sklearn.datasets import fetch_openml
from sklearn.metrics.pairwise import euclidean_distances
import time

X, _ = fetch_openml('mnist_784', version=1, return_X_y=True, as_frame=False)
X = X[:10000]
diss = euclidean_distances(X)

start = time.time()
fp = kmedoids.fasterpam(diss, 100)
print("FasterPAM took: %.2f ms" % ((time.time() - start)*1000))
print("Loss with FasterPAM:", fp.loss)

start = time.time()
pam = kmedoids.pam(diss, 100)
print("PAM took: %.2f ms" % ((time.time() - start)*1000))
print("Loss with PAM:", pam.loss)
```
```

--------------------------------

### Silhouette Algorithm

Source: https://python-kmedoids.readthedocs.io/en/latest/_sources/index.rst.txt

Implementation of the Silhouette algorithm for evaluation.

```APIDOC
## Silhouette

### Description
Implementation of the Silhouette algorithm for evaluation.

### Function Signature
.. autofunction:: silhouette
```

--------------------------------

### kmedoids.pam_build

Source: https://python-kmedoids.readthedocs.io/en/latest

PAM k-medoids clustering – BUILD only. This is an implementation of the original PAM (Partitioning Around Medoids) clustering algorithm.

```APIDOC
## kmedoids.pam_build

### Description
PAM k-medoids clustering – BUILD only
This is an implementation of the original PAM (Partitioning Around Medoids) clustering algorithm. For improved versions, see the fastpam and fasterpam methods.

### Parameters
* **diss** (ndarray) – square numpy array of dissimilarities
* **k** (int) – number of clusters to find

### Returns
k-medoids clustering result

### Return type
KMedoidsResult
```

--------------------------------

### MNIST clustering with FasterPAM and PAM

Source: https://python-kmedoids.readthedocs.io/en/latest/_sources/index.rst.txt

Compares the performance and loss of FasterPAM and PAM algorithms on the MNIST dataset. Requires sklearn for data fetching and distance calculation.

```python
import kmedoids
import numpy
from sklearn.datasets import fetch_openml
from sklearn.metrics.pairwise import euclidean_distances
X, _ = fetch_openml('mnist_784', version=1, return_X_y=True, as_frame=False)
X = X[:10000]
diss = euclidean_distances(X)
start = time.time()
fp = kmedoids.fasterpam(diss, 100)
print("FasterPAM took: %.2f ms" % ((time.time() - start)*1000))
print("Loss with FasterPAM:", fp.loss)
start = time.time()
pam = kmedoids.pam(diss, 100)
print("PAM took: %.2f ms" % ((time.time() - start)*1000))
print("Loss with PAM:", pam.loss)
```

--------------------------------

### Alternating k-medoids (k-means style)

Source: https://python-kmedoids.readthedocs.io/en/latest/_sources/index.rst.txt

Implementation of the k-means style 'alternating' algorithm for k-medoids clustering.

```APIDOC
## Alternating k-medoids (k-means style)

### Description
Implementation of the k-means style alternating algorithm.

### Function Signature
.. autofunction:: alternating
```

--------------------------------

### set_output(*, transform=None)

Source: https://python-kmedoids.readthedocs.io/en/latest

Set output container. This method allows configuration of the output format for transform and fit_transform methods, with options for default, pandas DataFrame, or unchanged configuration.

```APIDOC
## set_output(*, transform=None)

### Description
Set output container.
See sphx_glr_auto_examples_miscellaneous_plot_set_output.py for an example on how to use the API.

### Parameters
#### Path Parameters
- **transform** ({"default", "pandas"}, default=None) – Configure output of transform and fit_transform.
  * "default": Default output format of a transformer
  * "pandas": DataFrame output
  * None: Transform configuration is unchanged

### Returns
self
estimator instance
```

--------------------------------

### PAMSIL Algorithm

Source: https://python-kmedoids.readthedocs.io/en/latest/_sources/index.rst.txt

Implementation of the PAMSIL algorithm for silhouette clustering.

```APIDOC
## PAMSIL

### Description
Implementation of the PAMSIL algorithm.

### Function Signature
.. autofunction:: pamsil
```

--------------------------------

### FasterPAM Function

Source: https://python-kmedoids.readthedocs.io/en/latest

FasterPAM is an accelerated version of PAM clustering that eagerly performs any swap found and includes an O(k) improvement for finding the best swaps faster.

```APIDOC
## FasterPAM

kmedoids.fasterpam(_diss_ , _medoids_ , _max_iter =100_, _init ='random'_, _random_state =None_, _n_cpu =-1_)
    
FasterPAM k-medoids clustering
This is an accelerated version of PAM clustering, that eagerly performs any swap found, and contains the O(k) improvement to find the best swaps faster.
References:
Erich Schubert, Peter J. Rousseeuw
Fast and Eager k-Medoids Clustering:
O(k) Runtime Improvement of the PAM, CLARA, and CLARANS Algorithms
Information Systems (101), 2021, 101804
https://doi.org/10.1016/j.is.2021.101804 (open access)
Erich Schubert, Peter J. Rousseeuw:
Faster k-Medoids Clustering: Improving the PAM, CLARA, and CLARANS Algorithms
In: 12th International Conference on Similarity Search and Applications (SISAP 2019), 171-187.
https://doi.org/10.1007/978-3-030-32047-8_16
Preprint: https://arxiv.org/abs/1810.05691 

Parameters:
    
  * **diss** (_ndarray_) – square numpy array of dissimilarities
  * **medoids** (_int_ _or_ _ndarray_) – number of clusters to find or existing medoids
  * **max_iter** (_int_) – maximum number of iterations
  * **init** (_str_ _,__"random"__,__"first"__or_ _"build"_) – initialization method
  * **random_state** (_int_ _,__RandomState instance_ _or_ _None_) – random seed (also used for shuffling the processing order)
  * **n_cpu** (_int_) – number of threads to use (-1: automatic)


Returns:
    
k-medoids clustering result 

Return type:
    
KMedoidsResult
```

--------------------------------

### KMedoids Class Initialization

Source: https://python-kmedoids.readthedocs.io/en/latest

Initializes the KMedoids clustering model with various parameters to control the clustering process.

```APIDOC
## KMedoids

### Description
K-Medoids Clustering using PAM, FasterPAM, and FasterMSC (sklearn-compatible API).

### Parameters

#### `n_clusters` (int)
  The number of clusters to form (maximum number of clusters if method="dynmsc")

#### `metric` (string, default: 'precomputed')
  It is recommended to use ‘precomputed’, in particular when experimenting with different n_clusters. If you have sklearn installed, you may pass any metric supported by sklearn.metrics.pairwise_distances.

#### `metric_params` (dict, default=None)
  Additional keyword arguments for the metric function.

#### `method` (string, "fasterpam"(default), "fastpam1", "pam", "alternate", "fastermsc", "fastmsc", "pamsil" or "pammedsil")
  Which algorithm to use

#### `init` (string, "random"(default), "first" or "build")
  initialization method

#### `max_iter` (int)
  Specify the maximum number of iterations when fitting

#### `random_state` (int, RandomState instance or None)
  random seed if no medoids are given

### Attributes

#### `cluster_centers`
  None for ‘precomputed’

#### `medoid_indices`
  The indices of the medoid rows in X

#### `labels`
  Labels of each point

#### `inertia`
  Sum of distances of samples to their closest cluster center
```

--------------------------------

### kmedoids.fastpam1

Source: https://python-kmedoids.readthedocs.io/en/latest

FastPAM1 k-medoids clustering. This is an accelerated version of PAM clustering that performs the same swaps as the original PAM but finds the best swap O(k) times faster.

```APIDOC
## kmedoids.fastpam1

### Description
FastPAM1 k-medoids clustering. This is an accelerated version of PAM clustering, that performs the same swaps as the original PAM (given the same starting conditions), but finds the best swap O(k) times faster.

### Parameters
* **diss** (ndarray) – square numpy array of dissimilarities
* **medoids** (int or ndarray) – number of clusters to find or existing medoids
* **max_iter** (int) – maximum number of iterations
* **init** (str, "random", "first" or "build") – initialization method
* **random_state** (int, RandomState instance or None) – random seed if no medoids are given

### Returns
k-medoids clustering result

### Return type
KMedoidsResult
```

--------------------------------

### Medoid Silhouette Evaluation

Source: https://python-kmedoids.readthedocs.io/en/latest/_sources/index.rst.txt

Implementation of the Medoid Silhouette algorithm for evaluation.

```APIDOC
## Medoid Silhouette

### Description
Implementation of the Medoid Silhouette algorithm for evaluation.

### Function Signature
.. autofunction:: medoid_silhouette
```

--------------------------------

### kmedoids.pam

Source: https://python-kmedoids.readthedocs.io/en/latest

PAM k-medoids clustering. This is an implementation of the original PAM (Partitioning Around Medoids) clustering algorithm.

```APIDOC
## kmedoids.pam

### Description
PAM k-medoids clustering. This is an implementation of the original PAM (Partitioning Around Medoids) clustering algorithm. For improved versions, see the fastpam and fasterpam methods.

### Parameters
* **diss** (ndarray) – square numpy array of dissimilarities
* **medoids** (int or ndarray) – number of clusters to find or existing medoids
* **max_iter** (int) – maximum number of iterations
* **init** (str, "random", "first" or "build") – initialization method
* **random_state** (int, RandomState instance or None) – random seed if no medoids are given

### Returns
k-medoids clustering result

### Return type
KMedoidsResult
```

--------------------------------

### FasterMSC Algorithm

Source: https://python-kmedoids.readthedocs.io/en/latest/_sources/index.rst.txt

Implementation of the FasterMSC algorithm for silhouette clustering.

```APIDOC
## FasterMSC

### Description
Implementation of the FasterMSC algorithm.

### Function Signature
.. autofunction:: fastermsc
```

--------------------------------

### FastMSC Algorithm

Source: https://python-kmedoids.readthedocs.io/en/latest/_sources/index.rst.txt

Implementation of the FastMSC algorithm for silhouette clustering.

```APIDOC
## FastMSC

### Description
Implementation of the FastMSC algorithm.

### Function Signature
.. autofunction:: fastmsc
```

--------------------------------

### FasterPAM Algorithm

Source: https://python-kmedoids.readthedocs.io/en/latest/_sources/index.rst.txt

Implementation of the FasterPAM algorithm for k-medoids clustering.

```APIDOC
## FasterPAM

### Description
Implementation of the FasterPAM algorithm.

### Function Signature
.. autofunction:: fasterpam
```

--------------------------------

### PAMMEDSIL Algorithm

Source: https://python-kmedoids.readthedocs.io/en/latest/_sources/index.rst.txt

Implementation of the PAMMEDSIL algorithm for silhouette clustering.

```APIDOC
## PAMMEDSIL

### Description
Implementation of the PAMMEDSIL algorithm.

### Function Signature
.. autofunction:: pammedsil
```

--------------------------------

### FastPAM1 Algorithm

Source: https://python-kmedoids.readthedocs.io/en/latest/_sources/index.rst.txt

Implementation of the FastPAM1 algorithm for k-medoids clustering.

```APIDOC
## FastPAM1

### Description
Implementation of the FastPAM1 algorithm.

### Function Signature
.. autofunction:: fastpam1
```

--------------------------------

### sklearn-compatible API

Source: https://python-kmedoids.readthedocs.io/en/latest/_sources/index.rst.txt

Provides an sklearn-compatible API for K-Medoids clustering.

```APIDOC
## sklearn-compatible API

### Description
Provides an sklearn-compatible API for K-Medoids clustering.

### Class Definition
.. autoclass:: KMedoids
   :members: 
   :inherited-members:
```

--------------------------------

### DynMSC Algorithm

Source: https://python-kmedoids.readthedocs.io/en/latest/_sources/index.rst.txt

Implementation of the DynMSC algorithm for silhouette clustering.

```APIDOC
## DynMSC

### Description
Implementation of the DynMSC algorithm.

### Function Signature
.. autofunction:: dynmsc
```

--------------------------------

### fit(X, y=None)

Source: https://python-kmedoids.readthedocs.io/en/latest

Fits the KMedoids model to the provided data.

```APIDOC
## fit(X, y=None)

### Description
Fit K-Medoids to the provided data.

### Parameters

#### `X` (array-like or sparse matrix, shape = (n_samples, n_samples))
  Dataset to cluster

#### `y` (Ignored)
  Not used, present for API consistency by convention

### Returns

self
```

--------------------------------

### fit_transform(X, y=None, **fit_params)

Source: https://python-kmedoids.readthedocs.io/en/latest

Fits the transformer to the data and returns a transformed version of X.

```APIDOC
## fit_transform(X, y=None, **fit_params)

### Description
Fit to data, then transform it. Fits transformer to X and y with optional parameters fit_params and returns a transformed version of X.

### Parameters

#### `X` (array-like of shape (n_samples, n_features))
  Input samples.

#### `y` (array-like of shape (n_samples,) or (n_samples, n_outputs), default=None)
  Target values (None for unsupervised transformations).

#### `fit_params` (dict)
  Additional fit parameters.

### Returns

`X_new` (ndarray of shape (n_samples, n_features_new))
  Transformed array.
```

--------------------------------

### kmedoids.pamsil

Source: https://python-kmedoids.readthedocs.io/en/latest

Performs k-medoids clustering using the PAMSIL algorithm. It takes a dissimilarity matrix and either the number of clusters or existing medoids as input, along with optional parameters for maximum iterations, initialization method, and random state.

```APIDOC
## kmedoids.pamsil

### Description
PAMSIL k-medoids clustering.
This is an implementation of the original PAMSIL.

### Parameters
* **diss** (ndarray) – square numpy array of dissimilarities
* **medoids** (int or ndarray) – number of clusters to find or existing medoids
* **max_iter** (int) – maximum number of iterations
* **init** (str, "random", "first" or "build") – initialization method
* **random_state** (int, RandomState instance or None) – random seed if no medoids are given

### Returns
k-medoids clustering result

### Return type
KMedoidsResult
```

--------------------------------

### set_params(**params)

Source: https://python-kmedoids.readthedocs.io/en/latest

Set the parameters of this estimator. This method works on simple estimators as well as nested objects, allowing for parameter updates via a dictionary.

```APIDOC
## set_params(**params)

### Description
Set the parameters of this estimator.
The method works on simple estimators as well as on nested objects (such as `Pipeline`). The latter have parameters of the form `<component>__<parameter>` so that it’s possible to update each component of a nested object.

### Parameters
#### Path Parameters
- **params** (dict) – Estimator parameters.

### Returns
self
estimator instance
```

--------------------------------

### transform(_X_)

Source: https://python-kmedoids.readthedocs.io/en/latest

Transforms X to cluster-distance space. This method takes input data and returns it transformed into the new space of distances to cluster centers.

```APIDOC
## transform(_X_)

### Description
Transforms X to cluster-distance space.

### Parameters
#### Path Parameters
- **X** (array-like, shape = (n_query, n_features), or (n_query, n_indexed) if metric == 'precomputed') – Data to transform

### Returns
X transformed in the new space of distances to cluster centers

### Return type
{array-like}, shape=(n_query, n_clusters)
```

--------------------------------

### kmedoids.fastermsc

Source: https://python-kmedoids.readthedocs.io/en/latest

FasterMSC clustering is an accelerated version of PAMMEDSIL clustering, which eagerly performs any swap found and includes an O(k^2) improvement for faster identification of the best swaps.

```APIDOC
## kmedoids.fastermsc

### Description
FasterMSC clustering is an accelerated version of PAMMEDSIL clustering, which eagerly performs any swap found and includes an O(k^2) improvement for faster identification of the best swaps.

### Parameters
* **diss** (ndarray) – square numpy array of dissimilarities
* **medoids** (int or ndarray) – number of clusters to find or existing medoids
* **max_iter** (int) – maximum number of iterations
* **init** (str, "random", "first" or "build") – initialization method
* **random_state** (int, RandomState instance or None) – random seed if no medoids are given

### Returns
k-medoids clustering result

### Return type
KMedoidsResult
```

--------------------------------

### kmedoids.medoid_silhouette

Source: https://python-kmedoids.readthedocs.io/en/latest

Computes the Medoid Silhouette index, an approximation of the Silhouette index that uses distances to cluster medoids. It requires a dissimilarity matrix and the indices of the medoids, with an option to return individual sample values.

```APIDOC
## kmedoids.medoid_silhouette

### Description
Medoid Silhouette index for cluster evaluation.
The Medoid Silhouette is an approximation to the Silhouette index, that uses the distance to the cluster medoids instead of the average distance to the other cluster members. If every point is assigned to the nearest medoid, the Medoid Silhouette of a point reduces to 1-a/b where a is the distance to the nearest, and b the distance to the second nearest medoid. If b is 0, the Medoid Silhouette is 1.
This function assumes you already have a distance matrix. It is not necessary to compute a distance matrix to evaluate the medoid silhouette – only the distances between points and medoids are necessary. If you do not have a distance matrix, simply compute the medoid Silhouette directly, by computing (1) the N x k distance matrix to the medoids, (2) finding the two smallest values for each data point, and (3) computing the average of 1-a/b on these (with 0/0 as 0). This can be implemented in a few lines with numpy easily.

### Parameters
* **diss** (ndarray) – square numpy array of dissimilarities
* **meds** (ndarray of int) – medoid indexes (k distinct values in 0 to n-1)
* **samples** (boolean) – whether to return individual samples or not

### Returns
tuple containing the average Medoid Silhouette and the individual samples

### Return type
(float, ndarray)
```

--------------------------------

### Sklearn-compatible KMedoids API

Source: https://python-kmedoids.readthedocs.io/en/latest/_sources/index.rst.txt

Use the sklearn-compatible KMedoids class for clustering. It defaults to the 'precomputed' metric, expecting a distance matrix.

```python
import kmedoids
km = kmedoids.KMedoids(5, method='fasterpam')
c = km.fit(distmatrix)
print("Loss is:", c.inertia_)
```

--------------------------------

### Optimize number of clusters with DynMSC

Source: https://python-kmedoids.readthedocs.io/en/latest/_sources/index.rst.txt

Utilizes the DynMSC algorithm to find the optimal number of clusters based on the Medoid Silhouette score within a specified range. Requires sklearn for data preparation.

```python
import kmedoids, numpy
from sklearn.datasets import fetch_openml
from sklearn.metrics.pairwise import euclidean_distances
X, _ = fetch_openml('mnist_784', version=1, return_X_y=True, as_frame=False)
X = X[:10000]
diss = euclidean_distances(X)
kmin = 10
kmax = 20
dm = kmedoids.dynmsc(diss, kmax, kmin)
print("Optimal number of clusters according to the Medoid Silhouette:", dm.bestk)
print("Medoid Silhouette over range of k:", dm.losses)
print("Range of k:", dm.rangek)
```

--------------------------------

### get_metadata_routing()

Source: https://python-kmedoids.readthedocs.io/en/latest

Retrieves the metadata routing for the object.

```APIDOC
## get_metadata_routing()

### Description
Get metadata routing of this object. Please check User Guide on how the routing mechanism works.

### Returns

`routingMetadataRequest`
  A `MetadataRequest` encapsulating routing information.
```

--------------------------------

### fit_predict(X, y=None)

Source: https://python-kmedoids.readthedocs.io/en/latest

Fits the KMedoids model to the data and predicts the closest cluster for each sample.

```APIDOC
## fit_predict(X, y=None)

### Description
Predict the closest cluster for each sample in X.

### Parameters

#### `X` (array-like of shape (n_samples, n_features))
  Input data

#### `y` (Ignored)
  Not used, present for API consistency by convention

### Returns

Cluster labels

### Return type

ndarray of shape (n_samples,)
```

--------------------------------

### predict(_X_)

Source: https://python-kmedoids.readthedocs.io/en/latest

Predict the closest cluster for each sample in X. This method takes new data and returns the index of the cluster each sample belongs to.

```APIDOC
## predict(_X_)

### Description
Predict the closest cluster for each sample in X.

### Parameters
#### Path Parameters
- **X** (array-like, sparse matrix, shape = (n_samples, n_samples)) – New data to predict

### Returns
Index of the cluster each sample belongs to

### Return type
array, shape = (n_query,)
```

--------------------------------

### kmedoids.dynmsc

Source: https://python-kmedoids.readthedocs.io/en/latest

DynMSC clustering with automatic cluster number selection. It performs FasterMSC for a minimum k to the number of input medoids and returns the clustering with the highest Average Medoid Silhouette.

```APIDOC
## kmedoids.dynmsc

### Description
DynMSC clustering with automatic cluster number selection. It performs FasterMSC for a minimum k to the number of input medoids and returns the clustering with the highest Average Medoid Silhouette.

### Parameters
* **diss** (ndarray) – square numpy array of dissimilarities
* **medoids** (int or ndarray) – maximum number of clusters to find or existing medoids with length of maximum number of clusters to find
* **minimum_k** (int) – minimum number of clusters to find
* **max_iter** (int) – maximum number of iterations
* **init** (str, "random", "first" or "build") – initialization method
* **random_state** (int, RandomState instance or None) – random seed if no medoids are given

### Returns
k-medoids clustering with automatic number of clusters

### Return type
DynkResult
```

--------------------------------

### kmedoids.pammedsil

Source: https://python-kmedoids.readthedocs.io/en/latest

PAMMEDSIL clustering is an implementation of the original PAMMEDSIL clustering algorithm. For improved versions, consider using fastmsc and fastermsc methods.

```APIDOC
## kmedoids.pammedsil

### Description
PAMMEDSIL clustering is an implementation of the original PAMMEDSIL clustering algorithm. For improved versions, consider using fastmsc and fastermsc methods.

### Parameters
* **diss** (ndarray) – square numpy array of dissimilarities
* **medoids** (int or ndarray) – number of clusters to find or existing medoids
* **max_iter** (int) – maximum number of iterations
* **init** (str, "random", "first" or "build") – initialization method
* **random_state** (int, RandomState instance or None) – random seed if no medoids are given

### Returns
k-medoids clustering result

### Return type
KMedoidsResult
```

--------------------------------

### kmedoids.silhouette

Source: https://python-kmedoids.readthedocs.io/en/latest

Calculates the Silhouette index for cluster evaluation. This index measures how similar an object is to its own cluster compared to other clusters. It accepts a dissimilarity matrix, cluster labels, and optional parameters for returning individual samples and the number of CPUs to use.

```APIDOC
## kmedoids.silhouette

### Description
Silhouette index for cluster evaluation.
The Silhouette, proposed by Peter Rousseeuw in 1987, is a popular internal evaluation measure for clusterings. Although it is defined on arbitary metrics, it is most appropriate for evaluating “spherical” clusters, as it expects objects to be closer to all members of its own cluster than to members of other clusters.

### Parameters
* **diss** (ndarray) – square numpy array of dissimilarities
* **labels** (ndarray of int) – cluster labels (use 0 to k-1, no negative values allowed)
* **samples** (boolean) – whether to return individual samples or not
* **n_cpu** (int) – number of threads to use (-1: automatic)

### Returns
tuple containing the average silhouette and the individual samples

### Return type
(float, ndarray)
```

--------------------------------

### KMedoidsResult Object

Source: https://python-kmedoids.readthedocs.io/en/latest/_sources/index.rst.txt

Represents the result object for k-medoids clustering.

```APIDOC
## k-Medoids result object

### Description
Represents the result object for k-medoids clustering.

### Class Definition
.. autoclass:: KMedoidsResult
```
Tokens:
Raw