cluster_layers

PLSCAN.cluster_layers(max_peaks=None, min_size=None, max_size=None, height=0.0, threshold=0.0, **kwargs)

Return cluster labels and probabilities at each persistence peak.

The persistence trace (persistence_trace_) may have multiple local maxima, each corresponding to a stable minimum cluster size at which a distinct set of leaf-clusters is well-separated. This method detects those peaks via scipy.signal.find_peaks() and returns cluster segmentations for each one, ordered from lowest to highest minimum cluster size.

Parameters:

  • max_peaks (int | None, default: None) – Maximum number of peaks to return. If None, all detected peaks are returned. When specified, only the max_peaks peaks with the highest persistence are kept. Applied after all other filters.

  • min_size (float | None, default: None) – Discard peaks whose minimum cluster size is below this value.

  • max_size (float | None, default: None) – Discard peaks whose minimum cluster size is above this value.

  • height (float, default: 0.0) – Minimum persistence height a peak must exceed to be included, default 0.0. Equivalent to the height parameter of scipy.signal.find_peaks().

  • threshold (float, default: 0.0) – Minimum required persistence drop on at least one side of the peak, default 0.0. Equivalent to the threshold parameter of scipy.signal.find_peaks().

  • **kwargs – Additional keyword arguments forwarded directly to scipy.signal.find_peaks(). Note that the persistence signal is sampled at irregularly spaced minimum cluster size values, so sample-distance parameters (e.g. distance) do not correspond to a uniform spacing.

Return type:

list[tuple[single, Labelling]]

Returns:

list of (min_cluster_size, labels, probabilities) – One entry per detected peak. Each entry is a 3-tuple of:

  • min_cluster_size — the numpy.float32 minimum cluster size at the peak.

  • labels — int64 array of shape (n_samples,) giving the cluster label for each point (-1 for noise).

  • probabilities — float32 array of shape (n_samples,) with cluster membership probabilities.

Returns an empty list when no peaks are found.