SCPP: Soft Clustering Python Package - Documentation

SCPP collects 42 soft clustering algorithms behind one estimator protocol, spanning fuzzy, possibilistic, evidential, probabilistic, graph, document, ensemble and deep methods, together with a benchmarking suite for comparing them on equal terms.

This package is designed to support research and applied workflows involving clustering under uncertainty, overlapping memberships, and soft assignments.

Highlights

• One protocol, 42 algorithms — Every estimator exposes memberships_, labels_, centers_ and n_clusters after fit, regardless of whether the method consumes a feature matrix, a graph, raw documents, or an ensemble of partitions.

• Checked, not asserted — A conformance suite fits all 42 estimators on every commit and verifies the contract: membership shape, the partition constraint where the formulation imposes one, out-of-sample behaviour, sklearn.clone round-tripping, and reproducibility under a fixed random_state.

• Benchmarking included — Runtime, memory, scalability and clustering quality, over 20 datasets and 12 validity metrics — shipped inside the package.

• Light by default — A base install requires only numpy, scipy, scikit-learn and typeguard — enough to fit 38 of the 42 estimators. PyTorch and pandas live behind extras you opt into.

• Typed — Ships py.typed; hints are checked at runtime by typeguard and visible to your type checker.

Installation

The package can be installed from PyPI:

pip install soft-clustering

Optional extras, separated by what they are needed for:

Extra	Install	Needed for
(base)	pip install soft-clustering	Fitting any of the 38 non-deep estimators
deep	pip install "soft-clustering[deep]"	CDCGS, DMoN, NOCD, RDFKC
bench	pip install "soft-clustering[bench]"	Running soft_clustering.benchmarking
baselines	pip install "soft-clustering[baselines]"	Agreement checks against third-party implementations
docs	pip install "soft-clustering[docs]"	Building the documentation
dev	pip install -e ".[dev,deep]"	Developing and testing

Requires Python 3.10 or newer.

Quick Start

Basic usage with the package API:

import numpy as np
from soft_clustering import FCM

rng = np.random.default_rng(0)
X = np.vstack([rng.normal([0, 0], 0.4, (100, 2)),
               rng.normal([4, 4], 0.4, (100, 2))])

model = FCM(n_clusters=2, random_state=0).fit(X)

model.memberships_    # (200, 2) degrees of membership, rows sum to 1
model.labels_         # (200,)   arg-max hard assignment
model.centers_        # (2, 2)   cluster prototypes
model.n_clusters      # 2        the partition actually produced

Every estimator follows the same shape, so swapping the method is a one-word change:

from soft_clustering import ECM, GK, PCM, RoughKMeans

for cls in (GK, PCM, ECM, RoughKMeans):
    model = cls(n_clusters=2).fit(X)
    print(f"{cls.__name__:20s} {model.memberships_.shape}")

Algorithm Catalogue

Grouped by what the algorithm consumes. ⚡ marks estimators requiring the deep extra.

Feature matrix — 26 estimators

Estimator	Full Name	Description
FCM	Fuzzy C-Means	The canonical membership-based method
PCM	Possibilistic C-Means	Typicalities; rows need not sum to 1
PFCM	Possibilistic Fuzzy C-Means	Combines memberships and typicalities
GK	Gustafson–Kessel	Adaptive per-cluster covariance
ECM	Evidential C-Means	Belief masses over sets of clusters
KFCM	Kernelized Fuzzy C-Means	Kernel-space distances
SKFCM	Spatially-Constrained Kernelized FCM	Adds an image neighbourhood term
KFCCL	Kernel-based Fuzzy Competitive Learning	Competitive-learning update
CAFCM	Collaborative Annealing FCM	Deterministic annealing
CAFHFCM	Centroid Auto-Fused Hierarchical FCM	Fuses centroids hierarchically
ENTROPYFCM	Entropy c-Means	Entropy regularisation in place of the fuzzifier
AFCM	AFCM with full graph embedding	Graph-regularised memberships
AFCMSimple	AFCM without graph embedding	The unregularised variant
AFCMAdaptive	Adaptive FCM for image segmentation	Operates on a single image
FCC	Fuzzy Color Clustering	Fuzzy colour spheres in CIELAB space
RPFKM	Robust Projected Fuzzy K-Means	Joint dimensionality reduction for noisy, high-dimensional data
SFCMEP	Semi-supervised Fuzzy Clustering with Membership Prior	Consumes a partially labelled target vector
FeMIFuzzy	Federated Multiple Imputation Fuzzy Clustering	Consumes per-client matrices
RoughKMeans	Rough K-Means	Lower and upper approximations
SCM	Subtractive Clustering Method	Determines the cluster count itself
SoftDBSCANGM	Soft DBSCAN with Gaussian mixtures	Density-based, discovers k
SoftKSC	Soft Kernel Spectral Clustering	Semi-supervised; two non-parallel hyperplanes
GMM	Gaussian Mixture (EM)	Responsibilities as memberships
BGMM	Beta-Gaussian Mixture Model	Two aligned views
MBMM	Multivariate Beta Mixture Model	For data on the unit interval
RDFKC ⚡	Robust Deep Fuzzy K-Means	Image tensors

Graphs and networks — 6 estimators

Estimator	Full Name	Description
BIGCLAM	Cluster Affiliation Model for Big Networks	Overlapping communities at scale
BayesianNMF	Bayesian NMF for overlapping communities	Automatic relevance determination
MMSB ⚡	Mixed Membership Stochastic Blockmodel	Generative blockmodel
NOCD ⚡	Neural Overlapping Community Detection	GNN + Bernoulli–Poisson
DMoN ⚡	Deep Modularity Networks	Modularity-optimising pooling
CDCGS ⚡	Community Detection via Gumbel Softmax	Differentiable assignment

Documents and text — 5 estimators

Estimator	Full Name	Description
LDA	Latent Dirichlet Allocation	Topic–word and document–topic factors
PLSI	Probabilistic Latent Semantic Indexing	Likelihood-based topic model
SISC	Similarity-Based Soft Clustering	Discovers the cluster count
KMART	Modified Fuzzy ART for documents	Adaptive resonance
WBSC	Word-Based Soft Clustering	Word-driven soft assignment

Ensembles and consensus — 3 estimators

Estimator	Full Name	Description
SCSPA	Soft CSPA	Similarity-based consensus over soft partitions
SHBGF	Soft HBGF	Bipartite graph consensus over concatenated memberships
SMCLA	Soft MCLA	Groups clusters into meta-clusters

Benchmarking

The benchmarking suite ships inside the package, so it is available straight after installation.

pip install "soft-clustering[bench]"

from soft_clustering import FCM, GK, PCM
from soft_clustering.benchmarking import (
    ClusteringBenchmark,
    ClusteringQualityBenchmark,
    RuntimeBenchmark,
    get_dataset,
)

X, y = get_dataset("iris")

results = ClusteringBenchmark(
    models=[
        FCM(n_clusters=3, random_state=0),
        GK(n_clusters=3, random_state=0),
        PCM(n_clusters=3, random_state=0),
    ],
    benchmarks=[RuntimeBenchmark(n_repeats=3), ClusteringQualityBenchmark()],
).run(X, y)

Included backends:

• ⏱️ RuntimeBenchmark — Fit and predict time, with repeats and standard deviation

• 💾 MemoryBenchmark — Resident set size sampled during the fit

• 📈 ScalabilityBenchmark — Runtime and memory as the sample count grows

• 🎯 ClusteringQualityBenchmark — Silhouette, Calinski–Harabasz, Davies–Bouldin; ARI and NMI when labels are given; partition coefficient and entropy

Also included: 20 datasets (bundled, synthetic and OpenML) and 12 validity metrics.

See Benchmarking for the full reference.

Testing

The project includes a comprehensive test suite in the tests/ directory, covering all implemented algorithms.

To run the tests:

pip install -e ".[dev,deep]"
pytest

See tests/HOW_TO_RUN.txt for more details.

Development

git clone https://github.com/soft-clustering/soft-clustering.git
cd soft-clustering
pip install -e ".[dev,deep]"

pytest                                                    # tests
pytest --cov=soft_clustering --cov-report=term-missing    # with coverage
ruff check soft_clustering tests example tools            # lint
black --check soft_clustering tests example tools         # formatting
sphinx-build -b html -W docs/source docs/_build/html      # docs, warnings are errors

See CONTRIBUTING.md for the estimator protocol and what adding an algorithm involves.

Citation

This package accompanies a paper submitted to the JMLR MLOSS track.

• Paper: arXiv:2607.19620

@misc{rezaee2026scppunifiedpythonlibrary,
   title={SCPP: A Unified Python Library for Soft Clustering},
   author={Kiyan Rezaee and Morteza Ziabakhsh and Artin Bahrampour and
           Seyed Mohammad Ghoreishi and Asal Khaje and Ali Sajedifar and
           Manny Chalak and Ava Zerafatangiz and Sadegh Eskandari},
   year={2026},
   eprint={2607.19620},
   archivePrefix={arXiv},
   primaryClass={cs.LG},
   url={https://arxiv.org/abs/2607.19620},
}

Contributing

Contributions, bug reports and algorithm proposals are all welcome.

• Contributing guidelines

• Code of conduct

• Security policy — please report vulnerabilities privately

• Open an issue

License

Distributed under the terms of the MIT license.

API Reference

• SCPP: Soft Clustering Python Package - Documentation
  • Highlights
  • Installation
  • Quick Start
  • Algorithm Catalogue
  • Benchmarking
  • Testing
  • Development
  • Citation
  • Contributing
  • License
  • API Reference
• Benchmarking
  • Quick start
  • BenchmarkAdapter
  • Benchmark backends
  • Datasets
  • Metrics
• Algorithms
  • AFCM (Full Graph Embedding) Documentation
  • AFCM (Without Graph Embedding) Documentation
  • AFCMAdaptive (Adaptive Fuzzy C-Means for Image Segmentation) Documentation
  • BGMM (Beta-Gaussian Mixture Model) Documentation
  • BIGCLAM (Cluster Affiliation Model for Big Networks) Documentation
  • Bayesian NMF for Overlapping Community Detection
  • CAFCM (Collaborative Annealing FCM) Documentation
  • CAF-HFCM (Centroid Auto-Fused Hierarchical FCM) Documentation
  • CDCGS (Community Detection Clustering via Gumbel Softmax) Documentation
  • DMoN (Deep Modularity Networks) Documentation
  • ECM (Evidential C-Means) Documentation
  • EVCLUS (Evidential Clustering of Proximity Data)
  • FCC (Fuzzy Color Clustering) Documentation
  • Fuzzy C-Means (FCM)
  • FeMIFuzzy (Federated Multiple Imputation Fuzzy Clustering) Documentation
  • GathGeva (Gath–Geva / Fuzzy Maximum-Likelihood Estimation)
  • Gustafson–Kessel (GK)
  • Gaussian Mixture Models (GMM)
  • Kernel-based Fuzzy Competitive Learning (K-FCCL)
  • Kernelized Fuzzy C-Means (KFCM)
  • A Modified Fuzzy ART for Soft Document Clustering (KMART)
  • Latent Dirichlet Allocation (LDA)
  • MBMM (Multivariate Beta Mixture Model) Documentation
  • MMSB (Mixed Membership Stochastic Blockmodel) Documentation
  • Neural Overlapping Community Detection (NOCD)
  • Possibilistic C-Means (PCM)
  • Possibilistic Fuzzy C-Means (PFCM)
  • Probabilistic Latent Semantic Indexing (PLSI)
  • Robust deep fuzzy 𝐾-means clustering for image data (RD-FKC)
  • Rough K-Means (RoughKMeans)
  • RPFKM Algorithm Documentation
  • Subtractive Clustering Method (SCM)
  • SCSPA Algorithm Documentation
  • SFCMEP (Semi-supervised Fuzzy Clustering with Membership Prior)
  • SHBGF Algorithm Documentation
  • Similarity-Based Soft Clustering (SISC)
  • SKFCM (Spatially-Constrained Kernelized Fuzzy C-Means) Documentation
  • SMCLA Algorithm Documentation
  • Soft DBSCAN-GM Documentation
  • SoftKSC (Soft Kernel Spectral Clustering) Documentation
  • Word-Based Soft Clustering (WBSC)
  • EntropyFCM (Entropy c-Means) Documentation