dspk.synapse.matching

Templates and matching: lag-maximised cosine similarity of templates, merge suggestions, and matching pursuit of a recording against templates (on the runtime’s device).

Templates are (units, rows, samples); row r of unit u is recording channel channels[u, r] (default: rows are channels 0..rows).

matching_pursuit	Finds spikes by subtracting the best-fitting template, pass after pass, on the device.
suggest_merges	Pairs of units whose templates are alike enough to be one unit.
template_similarity	Cosine similarity of every pair of templates, each at its best lag.

Functions

matching_pursuit

matching_pursuit(
    data,
    templates,
    *,
    min_amplitude_scale: float = DEFAULT_MIN_AMPLITUDE_SCALE,
    max_amplitude_scale: float = DEFAULT_MAX_AMPLITUDE_SCALE,
    min_explained_energy: float = DEFAULT_MIN_EXPLAINED_ENERGY,
    max_passes: int = DEFAULT_MAX_PASSES,
    channels=None,
    runtime: str | None = None,
) -> dict

Finds spikes by subtracting the best-fitting template, pass after pass, on the device.

Parameters

• data : array_like
  Signal (channels, samples) in µV, converted to float32 on the host.
• templates : array_like
(units, rows, samples), or (units, samples) for one row each.
• min_amplitude_scale : float, default DEFAULT_MIN_AMPLITUDE_SCALE (0.65)
  Range a template may be scaled by to fit.
• max_amplitude_scale : float, default DEFAULT_MAX_AMPLITUDE_SCALE (1.45)
  Range a template may be scaled by to fit.
• min_explained_energy : float, default DEFAULT_MIN_EXPLAINED_ENERGY (500.0)
  Least energy (µV²) a fit must remove to count; rescale it with the data’s unit.
• max_passes : int, default DEFAULT_MAX_PASSES (4)
  Passes over the data.
• channels : array_like, default None
(units, rows): the recording channel of each template row; by default rows are channels 0..rows. Only rows on shared channels are compared.
• runtime : str, default None
  A runtime from runtime.available; by default the current one.

Returns

• dict of np.ndarray — samples (troughs), units, amplitudes (scales), scores.

suggest_merges

suggest_merges(
    templates,
    *,
    max_lag_samples: int = DEFAULT_MAX_LAG_SAMPLES,
    threshold: float = DEFAULT_MERGE_THRESHOLD,
    channels=None,
) -> list[tuple[int, int, float]]

Pairs of units whose templates are alike enough to be one unit.

Parameters

• templates : array_like
(units, rows, samples), or (units, samples) for one row each.
• max_lag_samples : int, default DEFAULT_MAX_LAG_SAMPLES
  Lags tried, up to this many samples each way.
• threshold : float, default DEFAULT_MERGE_THRESHOLD
  Least similarity of a suggested pair.
• channels : array_like, default None
(units, rows): the recording channel of each template row; by default rows are channels 0..rows. Only rows on shared channels are compared.

Returns

• list of (int, int, float) — (i, j, similarity) of each pair.

template_similarity

template_similarity(
    templates,
    *,
    max_lag_samples: int = DEFAULT_MAX_LAG_SAMPLES,
    channels=None,
) -> np.ndarray

Cosine similarity of every pair of templates, each at its best lag.

Parameters

• templates : array_like
(units, rows, samples), or (units, samples) for one row each.
• max_lag_samples : int, default DEFAULT_MAX_LAG_SAMPLES
  Lags tried, up to this many samples each way.
• channels : array_like, default None
(units, rows): the recording channel of each template row; by default rows are channels 0..rows. Only rows on shared channels are compared.

Returns

• np.ndarray — (units, units), in [-1, 1].

Examples

>>> import numpy as np
>>> import dspk
>>> t = np.sin(np.linspace(0, 6, 60, dtype=np.float32))
>>> sim = dspk.synapse.matching.template_similarity(np.stack([t, np.roll(t, 3)]))
>>> bool(sim[0, 1] > 0.9)
True

Constants

Name	Type	Value	Description
DEFAULT_MAX_AMPLITUDE_SCALE	float	1.45
DEFAULT_MAX_LAG_SAMPLES	int	10
DEFAULT_MAX_PASSES	int	4
DEFAULT_MERGE_THRESHOLD	float	0.9
DEFAULT_MIN_AMPLITUDE_SCALE	float	0.65
DEFAULT_MIN_EXPLAINED_ENERGY	float	500.0