Package: clustpy
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 theUCI 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 ofsklearn clustering,
it can be combined with many other packages (see below).InstallationFor UsersStable VersionStay tuned for the 'pip' releaseDevelopment VersionThe current development version can be installed directly from git by executing:sudo pip3 install git+https://github.com/collinleiber/ClustPy.gitAlternatively, clone the repository, go to the directory and execute:sudo python setup.py installIf you have no sudo rights you can use:python setup.py install --prefix ~/.localFor DevelopersClone the repository, go to the directory and do the following.Install package locally and compile C files:python setup.py install --prefix ~/.localCopy compiled C files to correct file location:python setup.py build_ext --inplaceRemove clustpy via pip to avoid ambiguities during development, e.g., when changing files in the code:pip3 uninstall clustpyComponentsAlgorithmsPartition-based clusteringDipExt + DipInitDip-MeansDip'n'subGapStatisticG-MeansLDA-K-MeansPG-MeansProjected Dip-MeansSkinnyDip + UniDip& TailoredDipSubKmeansX-MeansDensity-based clusteringMulti Density DBSCANHierarchical clusteringDianaAlternative clustering / Non-redundant clusteringAutoNRNR-KmeansDeep clusteringAutoencoderFlexible AutoencoderNeighbor EncoderStacked AutoencoderVariational AutoencoderDCNDECDipDECKDipEncoderENRCIDECVaDEOther implementationsMetricsConfusion MatrixPair Counting Scores (f1, rand, jaccard, recall, precision)Unsupervised Clustering AccuracyVariation of informationScores for multiple labelings (see alternative clustering algorithms)Multiple Labelings Confusion MatrixMultiple Labelings Pair Counting ScoresUtilsAutomatic evaluation methodsHartigans Dip-testVarious plotsDatasetsSynthetic dataset creator for subspace and alternative clusteringVarious real-world datasets (e.g. Iris, Wine, Mice protein, Optdigits, MNIST, ...)Compatible packagesWe stick as close as possible to the implementation details of sklean clustering. Therefore, our methods are compatible with many other packages. Examples are:sklearn clusteringK-MeansAffinity propagationMean-shiftSpectral clusteringWard hierarchical clusteringAgglomerative clusteringDBSCANOPTICSGaussian mixturesBIRCHkmodesk-modesk-prototypesHDBSCANHDBSCANscikit-learn-extrak-medoidsDensity-Based common-nearest-neighbors clusteringDensity Peak ClusteringDPCCoding Examples1)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.fromclustpy.partitionimportSubKmeansfromclustpy.dataimportcreate_subspace_datafromclustpy.metricsimportunsupervised_clustering_accuracyasaccdata,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.fromclustpy.alternativeimportNrKmeansfromclustpy.dataimportload_cmu_facesfromclustpy.metricsimportMultipleLabelingsConfusionMatrixfromsklearn.metricsimportnormalized_mutual_info_scoreasnmiimportnumpyasnpdata,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).fromclustpy.deepimportDECfromclustpy.dataimportload_optdigitsfromsklearn.metricsimportadjusted_rand_scoreasaridata,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.fromclustpy.utilsimportEvaluationDataset,EvaluationAlgorithm,EvaluationMetric,evaluate_multiple_datasetsfromclustpy.partitionimportProjectedDipMeans,SubKmeansfromsklearn.metricsimportnormalized_mutual_info_scoreasnmi,silhouette_scorefromsklearn.clusterimportKMeans,DBSCANfromclustpy.dataimportload_breast_cancer,load_iris,load_winefromclustpy.metricsimportunsupervised_clustering_accuracyasaccfromsklearn.decompositionimportPCAimportnumpyasnpdefreduce_dimensionality(X,dims):pca=PCA(dims)X_new=pca.fit_transform(X)returnX_newdefznorm(X):return(X-np.mean(X))/np.std(X)defminmax(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 automaticallyEvaluationAlgorithm("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)