Clusterium is a Bayesian nonparametric toolkit for text clustering, analysis, and benchmarking that leverages state-of-the-art embedding models and statistical validation techniques.
Features
Dirichlet Process Clustering: Implements the Dirichlet Process for text clustering
Pitman-Yor Process Clustering: Implements the Pitman-Yor Process for text clustering with improved performance
Evaluation: Evaluates clustering results using a variety of metrics, including Silhouette Score, Davies-Bouldin Index, and Power-law Analysis
Visualization: Generates plots of cluster size distributions
Quick Start
# Install the package
pip install clusx
# Basic clustering with default parameters
clusx cluster --input your_data.txt
# Evaluate clustering results
clusx evaluate \
--input your_data.txt \
--dp-clusters output/clusters_output_dp.csv \
--pyp-clusters output/clusters_output_pyp.csvThat’s it! The tool uses optimized default parameters and saves all outputs to the output directory.
For interactive visualization during evaluation, add the --show-plot option:
clusx evaluate \
--input your_data.txt \
--dp-clusters output/clusters_output_dp.csv \
--pyp-clusters output/clusters_output_pyp.csv \
--show-plotPython API Example
from clusx.clustering import DirichletProcess, PitmanYorProcess
from clusx.clustering.utils import load_data
# Load data
texts = load_data("your_data.txt")
# Perform clustering with default parameters
dp = DirichletProcess(alpha=0.5, kappa=0.3) # Default parameters
clusters_dp = dp.fit_predict(texts)
pyp = PitmanYorProcess(alpha=0.3, kappa=0.3, sigma=0.3) # Default parameters
clusters_pyp = pyp.fit_predict(texts)
# Print number of clusters found
print(f"DP found {len(set(clusters_dp))} clusters")
print(f"PYP found {len(set(clusters_pyp))} clusters")For more advanced usage, including saving results and evaluation, see the Usage Guide.
Project Information
Clusterium is released under the MIT License, its documentation lives at Read the Docs, the code on GitHub, and the latest release on PyPI. It’s rigorously tested on Python 3.11+.
If you’d like to contribute to Clusterium you’re most welcome!
Support
Should you have any question, any remark, or if you find a bug, or if there is something you can’t do with the Clusterium, please open an issue.
1 maintainer
Metadata
1 maintainer
Release files for clusx 0.6.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| clusx-0.6.0.tar.gz | 52.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| clusx-0.6.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 91.5 kB
Release files / clusx-0.6.0.tar.gz
| Download URL | clusx-0.6.0.tar.gz |
|---|---|
| Size | 52.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cd9e54ede30485a2242a96c8161936f4bba9c83b60c1fcb8dee95b790c0e368d
|
|
BLAKE2b-256 checksum How to use checksums |
f2f0b488c68ceb9f4fdab3803220b72884f0259217c5540c9e23b683adb7292d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 16, 2025.
Transparency logRelease files / clusx-0.6.0-py3-none-any.whl
| Download URL | clusx-0.6.0-py3-none-any.whl |
|---|---|
| Size | 38.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e148735c537c3f0852194038889e875170eb6c9998aa009e876af96d4da93d0e
|
|
BLAKE2b-256 checksum How to use checksums |
e40377b238352dd984ec58261c99a426a38a5f441fe21a47d1d8114ce1d1f56c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 16, 2025.
Transparency log
