dspk.synapse.clustering

Clustering of feature points (n, d) (spike features, PCs, positions): k-means, HDBSCAN and Gaussian mixtures on the runtime’s device; density peaks and KDE valley merging on the host; and the random choice of peaks sorters cluster on. Labels are int64 (-1: noise / outlier).

density_peaks	Density-peaks clustering (Rodriguez & Laio, 2014), on the host.
gmm	A Gaussian mixture on the device, its number of components chosen by BIC.
hdbscan	HDBSCAN clustering on the device, as the hdbscan package (excess of mass).
kde_merge	Over-clusters with k-means, then merges clusters with no density valley between them (host).
kmeans	k-means clustering on the device.
subsample_peaks	Chooses peaks at random, as sorters do before clustering.

Functions

density_peaks

density_peaks(
    points,
    *,
    cutoff_distance: float,
    num_clusters: int,
    max_points: int | None = None,
) -> dict

Density-peaks clustering (Rodriguez & Laio, 2014), on the host.

Parameters

• points : array_like
  Feature points (n, d) (spike features, principal components, positions), converted to float32 on the host; 1-D is (n, 1).
• cutoff_distance : float
  Neighbourhood radius of the density.
• num_clusters : int
  Clusters (the points of highest density times distance).
• max_points : int, default None
  Bounds the O(n²) work with an evenly strided subsample.

Returns

• dict — labels, centers (exemplar indices), densities, deltas.

gmm

gmm(
    points,
    *,
    k_min: int = DEFAULT_GMM_K_MIN,
    k_max: int = DEFAULT_GMM_K_MAX,
    covariance: str = 'full',
    max_iterations: int = DEFAULT_GMM_MAX_ITERATIONS,
    tolerance: float = DEFAULT_GMM_TOLERANCE,
    regularization: float = DEFAULT_GMM_REGULARIZATION,
    outlier_mahalanobis_sq: float | None = None,
    mask=None,
    runtime: str | None = None,
) -> dict

A Gaussian mixture on the device, its number of components chosen by BIC.

Parameters

• points : array_like
  Feature points (n, d) (spike features, principal components, positions), converted to float32 on the host; 1-D is (n, 1).
• k_min : int, default DEFAULT_GMM_K_MIN (1)
  Components tried, k_min to k_max included.
• k_max : int, default DEFAULT_GMM_K_MAX (8)
  Components tried, k_min to k_max included.
• covariance : {"full", "diagonal", "masked"}, default 'full'
  Covariance model; "masked" is KlustaKwik’s masked EM and needs mask.
• max_iterations : int, default DEFAULT_GMM_MAX_ITERATIONS (100)
  EM iterations.
• tolerance : float, default DEFAULT_GMM_TOLERANCE (0.001)
  Convergence tolerance of the log-likelihood.
• regularization : float, default DEFAULT_GMM_REGULARIZATION (0.0001)
  Added to each covariance’s diagonal.
• outlier_mahalanobis_sq : float, default None
  Points beyond this squared Mahalanobis distance get the label -1 (25: beyond 5 sigma).
• mask : array_like, default None
(n, d): a weight for each feature of each point ("masked" only).
• runtime : str, default None
  A runtime from runtime.available; by default the current one.

Returns

• dict — labels, weights, means, covariances, responsibilities, mahalanobis_sq, log_likelihood, bic.

hdbscan

hdbscan(
    points,
    *,
    min_cluster_size: int = DEFAULT_MIN_CLUSTER_SIZE,
    allow_single_cluster: bool = False,
    runtime: str | None = None,
) -> np.ndarray

HDBSCAN clustering on the device, as the hdbscan package (excess of mass).

Parameters

• points : array_like
  Feature points (n, d) (spike features, principal components, positions), converted to float32 on the host; 1-D is (n, 1).
• min_cluster_size : int, default DEFAULT_MIN_CLUSTER_SIZE (5)
  Smallest group of points that counts as a cluster.
• allow_single_cluster : bool, default False
  Allow all points to form one cluster.
• runtime : str, default None
  A runtime from runtime.available; by default the current one.

Returns

• np.ndarray — labels (n,) int64; -1 for noise.

kde_merge

kde_merge(
    points,
    *,
    initial_k: int,
    dip_threshold: float = DEFAULT_DIP_THRESHOLD,
    min_cluster_size: int = DEFAULT_KDE_MIN_CLUSTER_SIZE,
) -> dict

Over-clusters with k-means, then merges clusters with no density valley between them (host).

Parameters

• points : array_like
  Feature points (n, d) (spike features, principal components, positions), converted to float32 on the host; 1-D is (n, 1).
• initial_k : int
  Clusters of the first k-means.
• dip_threshold : float, default DEFAULT_DIP_THRESHOLD (1.5)
  Pairs whose dip score (0 to 3: the depth of the density valley between them) is below this merge.
• min_cluster_size : int, default DEFAULT_KDE_MIN_CLUSTER_SIZE (5)
  Smaller clusters are merged into their nearest.

Returns

• dict — labels, centroids.

kmeans

kmeans(
    points,
    k: int,
    *,
    n_init: int = DEFAULT_N_INIT,
    max_iter: int = DEFAULT_MAX_ITER,
    tol: float = DEFAULT_TOL,
    seed: int = 0,
    runtime: str | None = None,
) -> dict

k-means clustering on the device: k-means++ starts, the best of n_init runs.

Parameters

• points : array_like
  Feature points (n, d) (spike features, principal components, positions), converted to float32 on the host; 1-D is (n, 1).
• k : int
  Clusters.
• n_init : int, default DEFAULT_N_INIT (10)
  Runs from different starts; the one with the lowest inertia is kept.
• max_iter : int, default DEFAULT_MAX_ITER (300)
  Iterations per run.
• tol : float, default DEFAULT_TOL (0.0001)
  Convergence tolerance, relative to the data’s mean per-feature variance (as scikit-learn).
• seed : int, default 0
  Seed of the starts.
• runtime : str, default None
  A runtime from runtime.available; by default the current one.

Returns

• dict — labels (n,) int64, centers (k, d), inertia.

Examples

>>> import numpy as np
>>> import dspk
>>> rng = np.random.default_rng(0)
>>> pts = np.concatenate([rng.normal(0, 1, (100, 2)), rng.normal(8, 1, (100, 2))])
>>> out = dspk.synapse.clustering.kmeans(pts, 2)
>>> len(set(out["labels"][:100])), len(set(out["labels"][100:]))
(1, 1)

subsample_peaks

subsample_peaks(
    samples,
    channels,
    *,
    n_peaks: int,
    per_channel: bool = False,
    seed: int = 0,
) -> np.ndarray

Chooses peaks at random, as sorters do before clustering.

Parameters

• samples : array_like
  Sample of every peak.
• channels : array_like
  Channel of every peak.
• n_peaks : int
  Peaks to choose: in total, or on each channel with per_channel.
• per_channel : bool, default False
  Choose n_peaks on every channel.
• seed : int, default 0
  Seed of the choice.

Returns

• np.ndarray — Indices of the chosen peaks, in sample order.

Constants

Name	Type	Value	Description
DEFAULT_DIP_THRESHOLD	float	1.5
DEFAULT_GMM_K_MAX	int	8
DEFAULT_GMM_K_MIN	int	1
DEFAULT_GMM_MAX_ITERATIONS	int	100
DEFAULT_GMM_REGULARIZATION	float	0.0001
DEFAULT_GMM_TOLERANCE	float	0.001
DEFAULT_KDE_MIN_CLUSTER_SIZE	int	5
DEFAULT_MAX_ITER	int	300
DEFAULT_MIN_CLUSTER_SIZE	int	5
DEFAULT_N_INIT	int	10
DEFAULT_TOL	float	0.0001