Core-SG

Core-SG is a graph-based library for repeated HDBSCAN-style clustering over multiple neighborhood values. The recommended public workflow is core_sg.CoreSGClusterer, a scikit-learn-style estimator that builds a reusable support graph at k_max and extracts hierarchy artifacts for any valid k <= k_max without rebuilding the full structure each time.

The project is aimed at exploratory density-based analysis where comparing several smoothing levels on the same dataset is part of the workflow. A single plain HDBSCAN run may be simpler when only one k value is needed.

For larger datasets, use the algorithm choice deliberately. The exact algorithm="core-sg" path uses dense pairwise distance information and can be limited by n_samples. The approximate algorithm="score-sg" path is the scalable alternative for larger repeated multi-k workloads.

Key Features

use a scikit-learn-style estimator with fit(...) and fit_predict(...);
build once at k_max and extract many smaller k values;
inspect MSTs, condensed trees, single linkage trees, labels, probabilities, and persistence values;
run the classical exact algorithm="core-sg" path or the approximate algorithm="score-sg" path;
keep HDBSCAN-specific internals behind a documented adapter boundary.

Recommended Estimator API

core_sg.CoreSGClusterer is the user-facing API. It provides constructor parameters, fit(...), fit_predict(...), get_params, set_params, and clone compatibility. The lower-level reusable object is created behind the estimator and exposed as core_sg_ for advanced inspection.

Quick Example

from sklearn.datasets import make_blobs
from core_sg import CoreSGClusterer

X, _ = make_blobs(n_samples=1000, centers=5, random_state=42)

clusterer = CoreSGClusterer(k_max=15)
clusterer.fit(X, k=10)

labels = clusterer.labels_

Note

Calling clusterer.fit(X, k=8) later reuses the same internal core_sg_ object and extracts the hierarchy for k=8. The reuse decision is based on whether core_sg_ exists, not on whether k == k_max.

When To Use Core-SG

Core-SG is useful when you need a sklearn-style estimator that can compare many k values on the same data, inspect graph-level artifacts, or reproduce HDBSCAN-style hierarchy outputs from a reusable support graph.

When Not To Use Core-SG

Plain HDBSCAN may be a better first choice when you only need one clustering result, do not need MST or hierarchy inspection, or want the smallest possible API surface.

Documentation Contents

Support And Development