DS2L-SOM

DS2L-SOM is a topological, density-based clustering algorithm. It combines a Self-Organizing Map (SOM) for prototype learning with Gaussian KDE density estimation and gradient ascent to detect clusters — without requiring the number of clusters to be specified in advance.

Based on the papers by Cabanes, Bennani and Fresneau (2008, 2012).

Usage

from ds2l_som.ds2lsom import DS2LSOM

model = DS2LSOM(n_prototypes=100, threshold=10)
model.fit(X)
labels = model.predict(X)   # sequential integers; -1 = unassigned

# or short:
labels = model.fit_predict(X)

DS2LSOM implements the scikit-learn API (ClusterMixin, BaseEstimator) and is compatible with sklearn pipelines and GridSearchCV.

Parameters

Example with custom SOM parameters:

model = DS2LSOM(
    n_prototypes=100,
    threshold=10,
    model_args={"init": {"sigma_end": 1.0, "random_state": 42}},
)

Performance

Evaluated on load_digits (1797 samples, 64 features, 10 classes) using pairwise Rand and Jaccard index (as defined in the papers). DS2LSOM does not receive the true number of clusters.

HDBSCAN metrics are excluded: 69% noise points make the scores not comparable.

Scalability

Time and memory complexity: O(n · k) where k ≈ 10·√n (default heuristic), giving O(n^1.5) overall. The distance matrix (shape k × n) is the main memory bottleneck — practical limit is around 50 000–100 000 samples.

Installing

# Development
git clone https://github.com/SandroMartens/ds2l-som.git
cd ds2l-som
uv sync

# As a dependency in another project
uv add ds2l-som

References

• A Local Density-based Simultaneous Two-level Algorithm for Topographic Clustering, Guénaël Cabanes and Younès Bennani, 2008
• Enriched topological learning for cluster detection and visualization, Guénaël Cabanes, Younès Bennani and Dominique Fresneau, 2012