Troubleshooting

When should I use Core-SG instead of HDBSCAN?

Use Core-SG when you need repeated k analysis on the same dataset or want to inspect MST and hierarchy artifacts. Use plain HDBSCAN when you only need one clustering run and a simpler API is more important than reuse.

When should I use CoreSGClusterer?

Use CoreSGClusterer for ordinary workflows. It provides the scikit-learn-style fit(...) and fit_predict(...) interface and manages the lower-level reusable Core-SG object internally.

What is k_max?

k_max is the largest neighborhood value used to build reusable support. It must be large enough for the largest later extraction.

What is k?

k is the current extraction value. It must satisfy 2 <= k <= k_max.

Does CoreSGClusterer.fit(…) rebuild the graph every time?

No. The first fit(...) call creates core_sg_ and builds the reusable support graph for k_max. Later fit(...) calls reuse core_sg_ and only extract the hierarchy for the requested k. The decision is based on whether core_sg_ exists, not on whether k == k_max.

How do I rebuild with another dataset or another k_max?

Create a new CoreSGClusterer instance. A dedicated reset/refit lifecycle may be added in the future.

Why does labels_ change after extracting a different k?

labels_ always reflects the most recent extracted hierarchy. Save a copy if you need to keep labels for multiple k values.

What is the difference between labels_ and labels_k_max_?

labels_k_max_ is saved from the fit-time reference value. labels_ is the current extraction output.

What is core_sg_?

core_sg_ is the fitted internal reusable Core-SG object owned by CoreSGClusterer. Most users do not need to call it directly.

Why do my results differ from HDBSCAN?

Core-SG reconstructs hierarchy outputs from its reusable support graph and adapter boundary. Differences can also come from HDBSCAN version, tree selection parameters, metric choices, and optional noise reassignment.

Why is Score-SG disconnected for my data?

Score-SG builds an approximate sparse support graph. Some data and parameter settings may not produce a connected graph. In that case, MST extraction is not possible and Core-SG raises a clear error.

What artifacts are available after fit?

After CoreSGClusterer.fit(...), the estimator exposes labels_, probabilities_, cluster_persistence_, condensed_tree_, single_linkage_tree_, minimum_spanning_tree_, k_, k_max_, and core_sg_.

What artifacts are available after hierarchy extraction?

After fit(X, k=...), use labels_, probabilities_, cluster_persistence_, condensed_tree_, single_linkage_tree_, and minimum_spanning_tree_.

How should I interpret minimum_spanning_tree_?

It is the HDBSCAN-style MST wrapper for the current extracted k. Advanced users can access clusterer.core_sg_ when they need lower-level MST arrays or DataFrames.

Why is performance different from the benchmark?

Performance depends on data geometry, sample size, metric, Cython extension availability, HDBSCAN version, PyNNDescent settings, and whether you measure a single run or a repeated multi-k workflow.

Why does PyNNDescent have warm-up behavior?

PyNNDescent may pay setup and compilation-like costs on early runs. Prefer repeated measurements when benchmarking Score-SG or approximate neighbor workflows.

What does it mean that Core-SG uses HDBSCAN internals?

Core-SG uses private HDBSCAN functions to produce familiar hierarchy outputs. Those calls are isolated in core_sg/hdbscan_adapter.py.

Why did I see _tree_to_labels() got an unexpected keyword argument?

Problem:

TypeError: _tree_to_labels() got an unexpected keyword argument 'cluster_selection_persistence'

This happens when the installed HDBSCAN version exposes a private _tree_to_labels(...) function whose signature does not accept a parameter Core-SG knows about. Core-SG filters forwarded keyword arguments at the hdbscan_adapter boundary according to the installed signature.

Upgrade Core-SG to a version that includes adapter-side filtering. If developing locally, rerun:

pytest tests/unit/test_hdbscan_adapter.py