clustpy 0.0.1

Clustering in python

---

The package provides a simple way to cluster data in Python. For this purpose it provides a variety of algorithms from different domains. Additionally, ClustPy includes methods that are often needed for research purposes, such as plots, clustering metrics or evaluation methods. Further, it integrates various frequently used datasets (e.g. from the UCI repository) through largely automated loading options.

The focus of the ClustPy package is not on efficiency (here we recommend e.g. pyclustering), but on the possibility to try out a wide range of modern scientific methods. In particular, this should also make lesser-known methods accessible in a simple and convenient way.

Since it largely follows the implementation conventions of sklearn clustering, it can be combined with many other packages (see below).

Installation

For Users

Stable Version

Stay tuned for the 'pip' release

Development Version

The current development version can be installed directly from git by executing:

sudo pip3 install git+https://github.com/collinleiber/ClustPy.git

Alternatively, clone the repository, go to the directory and execute:

sudo python setup.py install

If you have no sudo rights you can use:

python setup.py install --prefix ~/.local

For Developers

Clone the repository, go to the directory and do the following.

Install package locally and compile C files:

python setup.py install --prefix ~/.local

Copy compiled C files to correct file location:

python setup.py build_ext --inplace

Remove clustpy via pip to avoid ambiguities during development, e.g., when changing files in the code:

pip3 uninstall clustpy

Components

Algorithms

• Partition-based clustering
  • DipExt + DipInit
  • Dip-Means
  • Dip'n'sub
  • GapStatistic
  • G-Means
  • LDA-K-Means
  • PG-Means
  • Projected Dip-Means
  • SkinnyDip + UniDip & TailoredDip
  • SubKmeans
  • X-Means
• Density-based clustering
  • Multi Density DBSCAN
• Hierarchical clustering
  • Diana
• Alternative clustering / Non-redundant clustering
  • AutoNR
  • NR-Kmeans
• Deep clustering
  • Autoencoder
    • Flexible Autoencoder
    • Neighbor Encoder
    • Stacked Autoencoder
    • Variational Autoencoder
  • DCN
  • DEC
  • DipDECK
  • DipEncoder
  • ENRC
  • IDEC
  • VaDE

Other implementations

• Metrics
  • Confusion Matrix
  • Pair Counting Scores (f1, rand, jaccard, recall, precision)
  • Unsupervised Clustering Accuracy
  • Variation of information
  • Scores for multiple labelings (see alternative clustering algorithms)
    • Multiple Labelings Confusion Matrix
    • Multiple Labelings Pair Counting Scores
• Utils
  • Automatic evaluation methods
  • Hartigans Dip-test
  • Various plots
• Datasets
  • Synthetic dataset creator for subspace and alternative clustering
  • Various real-world datasets (e.g. Iris, Wine, Mice protein, Optdigits, MNIST, ...)

Compatible packages

We stick as close as possible to the implementation details of sklean clustering. Therefore, our methods are compatible with many other packages. Examples are:

• sklearn clustering
  • K-Means
  • Affinity propagation
  • Mean-shift
  • Spectral clustering
  • Ward hierarchical clustering
  • Agglomerative clustering
  • DBSCAN
  • OPTICS
  • Gaussian mixtures
  • BIRCH
• kmodes
  • k-modes
  • k-prototypes
• HDBSCAN
  • HDBSCAN
• scikit-learn-extra
  • k-medoids
  • Density-Based common-nearest-neighbors clustering
• Density Peak Clustering
  • DPC

Coding Examples

1)

In this first example, the subspace algorithm SubKmeans is run on a synthetic subspace dataset. Afterwards, the clustering accuracy is calculated to evaluate the result.

from clustpy.partition import SubKmeans
from clustpy.data import create_subspace_data
from clustpy.metrics import unsupervised_clustering_accuracy as acc

data, labels = create_subspace_data(1000, n_clusters=4, subspace_features=[2,5])
sk = SubKmeans(4)
sk.fit(data)
acc_res = acc(labels, sk.labels_)
print("Clustering accuracy:", acc_res)

2)

The second example covers the topic of non-redundant/alternative clustering. Here, the NrKmeans algorithm is run on the CMUfaces dataset. Beware that NrKmeans as a non-redundant clustering algorithm returns multiple labelings. Therefore, we calculate the confusion matrix by comparing each combination of labels using the normalized mutual information (nmi). The confusion matrix will be printed and finally the best matching nmi will be stated for each set of labels.

from clustpy.alternative import NrKmeans
from clustpy.data import load_cmu_faces
from clustpy.metrics import MultipleLabelingsConfusionMatrix
from sklearn.metrics import normalized_mutual_info_score as nmi
import numpy as np

data, labels = load_cmu_faces()
nk = NrKmeans([20, 4, 4, 2])
nk.fit(data)
mlcm = MultipleLabelingsConfusionMatrix(labels, nk.labels_, nmi)
mlcm.rearrange()
print(mlcm.confusion_matrix)
print(np.max(mlcm.confusion_matrix, axis=1))

3)

One mentionable feature of the ClustPy package is the ability to run various modern deep clustering algorithms out of the box. For example, the following code runs the DEC algorithm on the Optdigits dataset. To evaluate the result, we compute the adjusted RAND index (ari).

from clustpy.deep import DEC
from clustpy.data import load_optdigits
from sklearn.metrics import adjusted_rand_score as ari

data, labels = load_optdigits()
dec = DEC(10)
dec.fit(data)
my_ari = ari(labels, dec.labels_)
print(my_ari)

4)

In this more complex example, we use ClustPy's evaluation functions, which automatically run the specified algorithms multiple times on previously defined datasets. All results of the given metrics are stored in a Pandas dataframe.

from clustpy.utils import EvaluationDataset, EvaluationAlgorithm, EvaluationMetric, evaluate_multiple_datasets
from clustpy.partition import ProjectedDipMeans, SubKmeans
from sklearn.metrics import normalized_mutual_info_score as nmi, silhouette_score
from sklearn.cluster import KMeans, DBSCAN
from clustpy.data import load_breast_cancer, load_iris, load_wine
from clustpy.metrics import unsupervised_clustering_accuracy as acc
from sklearn.decomposition import PCA
import numpy as np

def reduce_dimensionality(X, dims):
    pca = PCA(dims)
    X_new = pca.fit_transform(X)
    return X_new

def znorm(X):
    return (X - np.mean(X)) / np.std(X)

def minmax(X):
    return (X - np.min(X)) / (np.max(X) - np.min(X))

datasets = [
    EvaluationDataset("Breast_pca_znorm", data=load_breast_cancer, preprocess_methods=[reduce_dimensionality, znorm],
                      preprocess_params=[{"dims": 0.9}, {}], ignore_algorithms=["pdipmeans"]),
    EvaluationDataset("Iris_pca", data=load_iris, preprocess_methods=reduce_dimensionality,
                      preprocess_params={"dims": 0.9}),
    EvaluationDataset("Wine", data=load_wine),
    EvaluationDataset("Wine_znorm", data=load_wine, preprocess_methods=znorm)]

algorithms = [
    EvaluationAlgorithm("SubKmeans", SubKmeans, {"n_clusters": None}),
    EvaluationAlgorithm("pdipmeans", ProjectedDipMeans, {}),  # Determines n_clusters automatically
    EvaluationAlgorithm("dbscan", DBSCAN, {"eps": 0.01, "min_samples": 5}, preprocess_methods=minmax,
                        deterministic=True),
    EvaluationAlgorithm("kmeans", KMeans, {"n_clusters": None}),
    EvaluationAlgorithm("kmeans_minmax", KMeans, {"n_clusters": None}, preprocess_methods=minmax)]

metrics = [EvaluationMetric("NMI", nmi), EvaluationMetric("ACC", acc),
           EvaluationMetric("Silhouette", silhouette_score, use_gt=False)]

df = evaluate_multiple_datasets(datasets, algorithms, metrics, n_repetitions=5,
                                aggregation_functions=[np.mean, np.std, np.max, np.min],
                                add_runtime=True, add_n_clusters=True, save_path=None,
                                save_intermediate_results=False)
print(df)