Welcome to PyCVI’s documentation!

PyCVI is a Python package specialized in internal Clustering Validity Indices (CVI). Internal CVIs are used to select the best clustering among a set of pre-computed clusterings when no external information is available such as the labels of the datapoints.

Although being fundamental to clustering tasks and being an active research topic, very few internal CVIs are implemented in standard python libraries (only 3 in scikit-learn, more were available in R but few were maintained and kept in CRAN). This is despite the well-known limitations of all existing CVIs and the need to use the right one(s) according to the specific dataset at hand.

In addition, all CVIs rely on the definition of a distance between datapoints and most of them on the notion of cluster center.

For non-time-series data, the distance used is usually the euclidean distance and the cluster center is defined as the usual average. Libraries such as scipy, numpy, scikit-learn, etc. offer a large selection of distance measures that are compatible with all their functions.

For time-series data however, the common distance used is Dynamic Time Warping (DTW) and the barycenter of a group of time series is then not defined as the usual mean, but as the DTW Barycentric Average (DBA). Unfortunately, DTW and DBA are not compatible with the libraries mentioned above, which among other reasons, made additional machine learning libraries specialized in time series data such as aeon, sktime and tslearn necessary.

PyCVI then tries to fill that gap by implementing 12 state-of-the-art internal CVIs and by making them compatible with DTW and DBA (and obviously non time-series data). PyCVI is entirely compatible with scikit-learn, scikit-learn extra, aeon and sktime, in order to be easily integrated into any clustering pipeline in python.

To compute DTW and DBA, PyCVI relies on the aeon library.

Main features

12 internal CVIs implemented: Hartigan, Calinski-Harabasz, GapStatistic, Silhouette, ScoreFunction, Maulik-Bandyopadhyay, SD, SDbw, Dunn, Xie-Beni, XB* and Davies-Bouldin.
Compute CVI values and select the best clustering based on the results.
Compatible with time-series, Dynamic Time Warping (DTW) and Dynamic time warping Barycentric Average (DBA).
Compatible with scikit-learn, scikit-learn extra, aeon and sktime, for an easy integration into any clustering pipeline in python.
Can compute the clusterings beforehand if provided with a sklearn-like clustering class.
Enable users to define custom CVIs.
Multiple CVIs can easily be combined to select the best clustering based on a majority vote.
Variation of Information implemented (distances between clustering).

Install

With uv:

# From PyPI
uv add pycvi-lib
# Alternatively, from github directly
uv add "pycvi-lib @ git+https://github.com/nglm/pycvi.git"

With poetry

# From PyPI
poetry add pycvi-lib
# Alternatively, from github directly
poetry add git+https://github.com/nglm/pycvi.git

With pip

# From PyPI
pip install pycvi-lib
# Alternatively, from github directly
pip install git+https://github.com/nglm/pycvi.git

With anaconda

# activate your environment (replace myEnv with your environment name)
conda activate myEnv
# install pip first in your environment
conda install pip
# install pycvi on your anaconda environment with pip
pip install pycvi-lib

Extra dependencies

In order to run the example scripts, extra dependencies are necessary. The install command is then:

# For uv
uv add pycvi-lib[examples]
# For poetry
poetry add pycvi-lib[examples]
# For pip and anaconda
pip install pycvi-lib[examples]

Alternatively, you can manually install in your environment the packages that are necessary to run the example scripts (matplotlib and/or scikit-learn-extra depending on the example).

Important note: As of now (June 2026), the latest version of scikit-learn-extra (0.3.0) is not compatible with numpy>= 2.0.0. To avoid adding restrictions on the version of numpy for users who do not want to run the example scripts that require scikit-learn-extra, no explicit version of numpy is specified in the pyproject.toml file.

This means that if you want to run example scripts, you’ll have to make sure that you are using a version of numpy that is strictly below 2.0.0 in your environment.

If you wish to run the example scripts on your own computer, please follow the instructions detailed in the documentation first: Running example scripts on your computer.

Examples:

If you wish to run the example scripts on your own computer, please first follow the instructions detailed in Running example scripts on your computer.

Main Modules

All implemented CVIs are available here:

pycvi.cvi

Python implementation of state-of-the-art internal CVIs.

High level functions are defined to compute clusterings, compare clusterings and evaluate clusterings:

`pycvi.cluster.generate_all_clusterings`	Generate all clusterings for the given data and clustering model.
`pycvi.vi.variation_information`	Variation of information between two clusterings.
`pycvi.compute_scores.compute_all_scores`	Computes all CVI values for the given clusterings.

More low-level functions are defined to perform common operations but that can handle the case of DTW and DBA if working on time-series data:

`pycvi.dist.f_pdist`	Pairwise distances within a group of elements.
`pycvi.dist.f_cdist`	Distances between two (groups of) elements.
`pycvi.compute_scores.f_inertia`	Inertia of a group of elements.
`pycvi.cluster.compute_center`	Compute the center of a cluster.
`pycvi.cluster.compute_centers`	Compute the centers of all clusters.

Full API

pycvi

Internal Cluster Validity Indices (CVIs), compatible with DTW and DBA.

Contribute

Issue Tracker: github.com/nglm/pycvi/issues.
Source Code: github.com/nglm/pycvi.

Support

If you are having issues, please let me know or create an issue.

How to cite PyCVI

If you are using PyCVI in your work, please cite us by using one of the following entries referring to the JOSS paper “PyCVI: A Python package for internal Cluster Validity Indices, compatible with time-series data” by N. Galmiche:

BibTeX

@article{Galmiche2024,
    author = {Natacha Galmiche},
    title = {PyCVI: A Python package for internal Cluster Validity Indices, compatible with time-series data},
    doi = {10.21105/joss.06841},
    url = {https://doi.org/10.21105/joss.06841},
    year = {2024},
    publisher = {The Open Journal},
    volume = {9},
    number = {102},
    pages = {6841},
    journal = {Journal of Open Source Software}
}

Plain text

Galmiche, N., (2024). PyCVI: A Python package for internal Cluster Validity Indices, compatible with time-series data. Journal of Open Source Software, 9(102), 6841, https://doi.org/10.21105/joss.06841

Index

Index