Skip to content
dsp-kitchen

dspk.synapse.metrics

Unit quality and spike-train analyses. Spike trains are sample indices (any integer array); sample_rate is in Hz. Defaults follow SpikeInterface / the cited papers.
acg_refractory Kilosort4’s test of whether a unit’s auto-correlogram shows a refractory period.
amplitude_cutoff Estimated fraction of a unit’s spikes missed below the detection threshold.
autocorrelogram Auto-correlogram of a spike train, zero lag excluded.
bursts Epochs where the smoothed firing rate stays above a threshold.
ccg_refractory Kilosort4’s test of a refractory cross-correlogram.
compare_sortings Compares two sortings unit by unit, such as a sorter’s against ground truth.
compare_trains Matches two spike trains one to one, within a tolerance.
composite_score EMUsort’s composite quality score of a unit.
crosscorrelogram Cross-correlogram of b around a.
d_prime Linear-discriminant d′ between two clusters.
firing_range Spread of a unit’s firing rate.
firing_rate Instantaneous firing rate over the recording, smoothed with a Gaussian.
isi_histogram Histogram of inter-spike intervals.
isi_violations Inter-spike-interval violations (Hill et al., 2011), as SpikeInterface’s isi_violations_ratio.
isolation_distance Isolation distance of one unit (Schmitzer-Torbert et al., 2005).
llobet_contamination Refractory-period contamination (Llobet et al., 2022).
presence_ratio Fraction of the recording in which the unit fires.
psth Peri-stimulus time histogram.
refractory_violations Pairs of spikes at most refractory_samples apart (all pairs, not only consecutive ones).
silhouette Silhouette score of one unit among labelled features.
snr Signal-to-noise ratio.
stimulus_average Stimulus-triggered average of a signal, and the evoked response on each channel.

Functions

Section titled “Functions”

acg_refractory

Section titled “acg_refractory”
acg_refractory(
    train,
    sample_rate: float,
    *,
    bin_ms: float = DEFAULT_REFRACTORY_BIN_MS,
    window_ms: float = DEFAULT_REFRACTORY_WINDOW_MS,
    ratio: float = DEFAULT_ACG_RATIO,
    probability: float = DEFAULT_ACG_PROBABILITY,
) -> dict

Kilosort4’s test of whether a unit’s auto-correlogram shows a refractory period.

Parameters

  • train : array_like
    Spike times, as sample indices.
  • sample_rate : float
    Sample rate in Hz.
  • bin_ms : float, default DEFAULT_REFRACTORY_BIN_MS (1.0)
    Bin width.
  • window_ms : float, default DEFAULT_REFRACTORY_WINDOW_MS (500.0)
    Lags counted.
  • ratio : float, default DEFAULT_ACG_RATIO (0.2)
    Refractory when the dip’s ratio to the baseline (R) is below this…
  • probability : float, default DEFAULT_ACG_PROBABILITY (0.2)
    …and its probability under a Poisson model (Q) is below this.

Returns

  • dict — ratio, probability, baseline, refractory (the verdict).

amplitude_cutoff

Section titled “amplitude_cutoff”
amplitude_cutoff(
    amplitudes,
    *,
    bins: int = AMPLITUDE_CUTOFF_BINS,
    smoothing_bins: float = AMPLITUDE_CUTOFF_SMOOTHING,
    min_ratio: float = AMPLITUDE_CUTOFF_MIN_RATIO,
) -> float

Estimated fraction of a unit’s spikes missed below the detection threshold.

From the histogram of its amplitudes, assuming it is symmetric around its peak.

Parameters

  • amplitudes : array_like
    The unit’s spike amplitudes.
  • bins : int, default AMPLITUDE_CUTOFF_BINS (100)
    Histogram bins.
  • smoothing_bins : float, default AMPLITUDE_CUTOFF_SMOOTHING (3.0)
    Gaussian smoothing of the histogram, in bins.
  • min_ratio : float, default AMPLITUDE_CUTOFF_MIN_RATIO (5.0)
    Fewer spikes than this per bin: the estimate is not made (NaN).

Returns

  • float — In [0, 0.5].

autocorrelogram

Section titled “autocorrelogram”
autocorrelogram(
    train,
    sample_rate: float,
    *,
    bin_ms: float = DEFAULT_CORRELOGRAM_BIN_MS,
    window_ms: float = DEFAULT_CORRELOGRAM_WINDOW_MS,
) -> dict

Auto-correlogram of a spike train, zero lag excluded.

Parameters

  • train : array_like
    Spike times, as sample indices.
  • sample_rate : float
    Sample rate in Hz.
  • bin_ms : float, default DEFAULT_CORRELOGRAM_BIN_MS (1.0)
    Bin width.
  • window_ms : float, default DEFAULT_CORRELOGRAM_WINDOW_MS (50.0)
    Lags counted, -window_ms to window_ms.

Returns

  • dict of np.ndarray — lags_ms and counts.

bursts

Section titled “bursts”
bursts(
    train,
    total_samples: int,
    sample_rate: float,
    *,
    threshold_hz: float,
    min_duration_ms: float = 50.0,
    bin_ms: float = 10.0,
    sigma_ms: float = 50.0,
) -> dict

Epochs where the smoothed firing rate stays above a threshold.

Parameters

  • train : array_like
    Spike times, as sample indices.
  • total_samples : int
    Samples in the recording.
  • sample_rate : float
    Sample rate in Hz.
  • threshold_hz : float
    Rate a burst exceeds.
  • min_duration_ms : float, default 50.0
    Shorter epochs are not bursts.
  • bin_ms : float, default 10.0
    Bin width of the rate.
  • sigma_ms : float, default 50.0
    Smoothing of the rate.

Returns

  • dict of np.ndarray — onset_s, offset_s and peak_hz of each burst.

ccg_refractory

Section titled “ccg_refractory”
ccg_refractory(
    a,
    b,
    sample_rate: float,
    *,
    bin_ms: float = DEFAULT_REFRACTORY_BIN_MS,
    window_ms: float = DEFAULT_REFRACTORY_WINDOW_MS,
    ratio: float = DEFAULT_CCG_RATIO,
    probability: float = DEFAULT_CCG_PROBABILITY,
) -> dict

Kilosort4’s test of a refractory cross-correlogram: two trains that are likely one unit.

Parameters

  • a : array_like
    Spike times, as sample indices.
  • b : array_like
    Spike times, as sample indices.
  • sample_rate : float
    Sample rate in Hz.
  • bin_ms : float, default DEFAULT_REFRACTORY_BIN_MS (1.0)
    Bin width.
  • window_ms : float, default DEFAULT_REFRACTORY_WINDOW_MS (500.0)
    Lags counted.
  • ratio : float, default DEFAULT_CCG_RATIO (0.25)
    Refractory when the dip’s ratio to the baseline (R) is below this…
  • probability : float, default DEFAULT_CCG_PROBABILITY (0.05)
    …and its probability under a Poisson model (Q) is below this.

Returns

  • dict — ratio, probability, baseline, refractory (the verdict).

compare_sortings

Section titled “compare_sortings”
compare_sortings(
    a,
    b,
    *,
    delta_ms: float = DEFAULT_MATCH_DELTA_MS,
    threshold: float = DEFAULT_AGREEMENT_THRESHOLD,
) -> dict

Compares two sortings unit by unit, such as a sorter’s against ground truth.

Parameters

  • a : Sorting
    The sortings (a taken as the truth).
  • b : Sorting
    The sortings (a taken as the truth).
  • delta_ms : float, default DEFAULT_MATCH_DELTA_MS (0.4)
    Spikes this close are a match.
  • threshold : float, default DEFAULT_AGREEMENT_THRESHOLD (0.5)
    Least agreement of a matched pair.

Returns

  • dict — agreement (units_a, units_b), unit_ids_a, unit_ids_b, matched ((a, b, agreement) pairs) and well_detected (units of a).

compare_trains

Section titled “compare_trains”
compare_trains(a, b, *, tolerance_samples: int) -> dict

Matches two spike trains one to one, within a tolerance.

Parameters

  • a : array_like
    Spike times, as sample indices (a taken as the truth).
  • b : array_like
    Spike times, as sample indices (a taken as the truth).
  • tolerance_samples : int
    Spikes this close are a match.

Returns

  • dict — matches, false_negatives, false_positives, agreement, precision, recall.

Examples

>>> import dspk
>>> out = dspk.synapse.metrics.compare_trains([100, 500, 900], [102, 500, 1300], tolerance_samples=5)
>>> out["matches"], out["false_negatives"], out["false_positives"]
(2, 1, 1)

composite_score

Section titled “composite_score”
composite_score(
    train,
    amplitudes,
    snr: float,
    total_samples: int,
    sample_rate: float,
) -> dict

EMUsort’s composite quality score of a unit.

Parameters

  • train : array_like
    Spike times, as sample indices.
  • amplitudes : array_like
    The unit’s spike amplitudes.
  • snr : float
    The unit’s signal-to-noise ratio.
  • total_samples : int
    Samples in the recording.
  • sample_rate : float
    Sample rate in Hz.

Returns

  • dict — score in [0, 1] and the parts it combines.

crosscorrelogram

Section titled “crosscorrelogram”
crosscorrelogram(
    a,
    b,
    sample_rate: float,
    *,
    bin_ms: float = DEFAULT_CORRELOGRAM_BIN_MS,
    window_ms: float = DEFAULT_CORRELOGRAM_WINDOW_MS,
) -> dict

Cross-correlogram of b around a: lags t_b - t_a.

Parameters

  • a : array_like
    Spike times, as sample indices.
  • b : array_like
    Spike times, as sample indices.
  • sample_rate : float
    Sample rate in Hz.
  • bin_ms : float, default DEFAULT_CORRELOGRAM_BIN_MS (1.0)
    Bin width.
  • window_ms : float, default DEFAULT_CORRELOGRAM_WINDOW_MS (50.0)
    Lags counted, -window_ms to window_ms.

Returns

  • dict of np.ndarray — lags_ms and counts.

d_prime

Section titled “d_prime”
d_prime(a, b) -> float

Linear-discriminant d′ between two clusters: how well a line separates them.

Parameters

  • a : array_like
    Features of one cluster (n_a, d).
  • b : array_like
    Features of the other (n_b, d).

Returns

  • float

firing_range

Section titled “firing_range”
firing_range(
    train,
    total_samples: int,
    sample_rate: float,
    *,
    bin_s: float = 0.5,
    percentiles: tuple[float, float] = (5.0, 95.0),
) -> float

Spread of a unit’s firing rate: between two percentiles of its rate in short bins.

Parameters

  • train : array_like
    Spike times, as sample indices.
  • total_samples : int
    Samples in the recording.
  • sample_rate : float
    Sample rate in Hz.
  • bin_s : float, default 0.5
    Bin length.
  • percentiles : float, float, default (5.0, 95.0)
    Lower and upper percentile.

Returns

  • float — In Hz.

firing_rate

Section titled “firing_rate”
firing_rate(
    train,
    total_samples: int,
    sample_rate: float,
    *,
    bin_ms: float = 10.0,
    sigma_ms: float = 50.0,
) -> dict

Instantaneous firing rate over the recording, smoothed with a Gaussian.

Parameters

  • train : array_like
    Spike times, as sample indices.
  • total_samples : int
    Samples in the recording.
  • sample_rate : float
    Sample rate in Hz.
  • bin_ms : float, default 10.0
    Bin width.
  • sigma_ms : float, default 50.0
    Standard deviation of the smoothing.

Returns

  • dict of np.ndarray — time_s and rate_hz.

isi_histogram

Section titled “isi_histogram”
isi_histogram(
    train,
    sample_rate: float,
    *,
    bin_ms: float = 1.0,
    max_ms: float = 100.0,
) -> dict

Histogram of inter-spike intervals.

Parameters

  • train : array_like
    Spike times, as sample indices.
  • sample_rate : float
    Sample rate in Hz.
  • bin_ms : float, default 1.0
    Bin width.
  • max_ms : float, default 100.0
    Longest interval counted.

Returns

  • dict of np.ndarray — bin_ms (left edges) and counts.

isi_violations

Section titled “isi_violations”
isi_violations(
    train,
    total_samples: int,
    sample_rate: float,
    *,
    threshold_ms: float = DEFAULT_ISI_THRESHOLD_MS,
    min_isi_ms: float = DEFAULT_MIN_ISI_MS,
) -> dict

Inter-spike-interval violations (Hill et al., 2011), as SpikeInterface’s isi_violations_ratio.

Parameters

  • train : array_like
    Spike times, as sample indices.
  • total_samples : int
    Samples in the recording.
  • sample_rate : float
    Sample rate in Hz.
  • threshold_ms : float, default DEFAULT_ISI_THRESHOLD_MS (1.5)
    Intervals shorter than this violate the refractory period.
  • min_isi_ms : float, default DEFAULT_MIN_ISI_MS (0.0)
    Intervals shorter than this cannot occur (censored by detection).

Returns

  • dict — violations, ratio, rate_pct, per_second, firing_rate_hz, spikes.

Examples

>>> import dspk
>>> out = dspk.synapse.metrics.isi_violations([0, 10, 3_000, 6_000], 30_000, 30_000.0)
>>> out["violations"]
1

isolation_distance

Section titled “isolation_distance”
isolation_distance(features, labels, unit: int) -> float

Isolation distance of one unit (Schmitzer-Torbert et al., 2005).

Parameters

  • features : array_like
    (n, d).
  • labels : array_like
    Unit of every point.
  • unit : int
    The unit scored.

Returns

  • float — Higher is better isolated.

llobet_contamination

Section titled “llobet_contamination”
llobet_contamination(
    train,
    total_samples: int,
    sample_rate: float,
    *,
    refractory_ms: float = DEFAULT_ISI_THRESHOLD_MS,
    censored_ms: float = DEFAULT_MIN_ISI_MS,
) -> float

Refractory-period contamination (Llobet et al., 2022): the estimated fraction of spikes from other neurons.

Parameters

  • train : array_like
    Spike times, as sample indices.
  • total_samples : int
    Samples in the recording.
  • sample_rate : float
    Sample rate in Hz.
  • refractory_ms : float, default DEFAULT_ISI_THRESHOLD_MS (1.5)
    The refractory period.
  • censored_ms : float, default DEFAULT_MIN_ISI_MS (0.0)
    Intervals shorter than this cannot occur (censored by detection).

Returns

  • float

presence_ratio

Section titled “presence_ratio”
presence_ratio(
    train,
    total_samples: int,
    sample_rate: float,
    *,
    bin_s: float = DEFAULT_PRESENCE_BIN_S,
    mean_rate_ratio: float = DEFAULT_PRESENCE_MEAN_RATE_RATIO,
) -> float

Fraction of the recording in which the unit fires.

Parameters

  • train : array_like
    Spike times, as sample indices.
  • total_samples : int
    Samples in the recording.
  • sample_rate : float
    Sample rate in Hz.
  • bin_s : float, default DEFAULT_PRESENCE_BIN_S (60.0)
    Bin length.
  • mean_rate_ratio : float, default DEFAULT_PRESENCE_MEAN_RATE_RATIO (0.0)
    A bin counts when the unit fires above this times its mean rate there (0: at all).

Returns

  • float — In [0, 1].

psth

Section titled “psth”
psth(
    train,
    stimulus_samples,
    sample_rate: float,
    *,
    pre_ms: float = DEFAULT_PSTH_PRE_MS,
    post_ms: float = DEFAULT_PSTH_POST_MS,
    bin_ms: float = DEFAULT_PSTH_BIN_MS,
) -> dict

Peri-stimulus time histogram: the firing rate around stimuli, averaged over trials.

Parameters

  • train : array_like
    Spike times, as sample indices.
  • stimulus_samples : array_like
    Stimulus times, as sample indices.
  • sample_rate : float
    Sample rate in Hz.
  • pre_ms : float, default DEFAULT_PSTH_PRE_MS (100.0)
    Window before and after each stimulus.
  • post_ms : float, default DEFAULT_PSTH_POST_MS (500.0)
    Window before and after each stimulus.
  • bin_ms : float, default DEFAULT_PSTH_BIN_MS (10.0)
    Bin width.

Returns

  • dict of np.ndarray — time_ms, rate_hz (mean over trials), se_hz, trials.

refractory_violations

Section titled “refractory_violations”
refractory_violations(train, refractory_samples: int) -> int

Pairs of spikes at most refractory_samples apart (all pairs, not only consecutive ones).

Parameters

  • train : array_like
    Spike times, as sample indices.
  • refractory_samples : int
    The refractory period, in samples.

Returns

  • int

silhouette

Section titled “silhouette”
silhouette(features, labels, unit: int) -> float

Silhouette score of one unit among labelled features.

Parameters

  • features : array_like
    (n, d).
  • labels : array_like
    Unit of every point.
  • unit : int
    The unit scored.

Returns

  • float — In [-1, 1]; higher is better separated.

snr

Section titled “snr”
snr(peak_uv: float, noise_std_uv: float) -> float

Signal-to-noise ratio: |peak| / noise_std.

Parameters

  • peak_uv : float
    The template’s peak.
  • noise_std_uv : float
    The channel’s noise.

Returns

  • float — NaN when the noise is not positive.

stimulus_average

Section titled “stimulus_average”
stimulus_average(
    data,
    stimulus_samples,
    sample_rate: float,
    *,
    pre_ms: float = 10.0,
    post_ms: float = 50.0,
    response_ms: tuple[float, float] = (2.0, 40.0),
    threshold_sigma: float = 3.0,
) -> dict

Stimulus-triggered average of a signal, and the evoked response on each channel.

Parameters

  • data : array_like
    Signal (channels, samples) in µV, converted to float32 on the host.
  • stimulus_samples : array_like
    Stimulus times, as sample indices.
  • sample_rate : float
    Sample rate in Hz.
  • pre_ms : float, default 10.0
    Window before and after each stimulus.
  • post_ms : float, default 50.0
    Window before and after each stimulus.
  • response_ms : float, float, default (2.0, 40.0)
    Where the evoked response is measured, after the stimulus.
  • threshold_sigma : float, default 3.0
    The response starts where it first exceeds this many baseline standard deviations.

Returns

  • dict — time_ms, mean / std / se (channels, samples), trials; per channel the evoked potential: mep_onset_ms, mep_peak_to_peak_uv, mep_rms_uv, mep_area_uv_ms.

Constants

Section titled “Constants”
Name Type Value Description
AMPLITUDE_CUTOFF_BINS int 100
AMPLITUDE_CUTOFF_MIN_RATIO float 5.0
AMPLITUDE_CUTOFF_SMOOTHING float 3.0
DEFAULT_ACG_PROBABILITY float 0.2
DEFAULT_ACG_RATIO float 0.2
DEFAULT_AGREEMENT_THRESHOLD float 0.5
DEFAULT_CCG_PROBABILITY float 0.05
DEFAULT_CCG_RATIO float 0.25
DEFAULT_CORRELOGRAM_BIN_MS float 1.0
DEFAULT_CORRELOGRAM_WINDOW_MS float 50.0
DEFAULT_ISI_THRESHOLD_MS float 1.5
DEFAULT_MATCH_DELTA_MS float 0.4
DEFAULT_PSTH_BIN_MS float 10.0
DEFAULT_PSTH_POST_MS float 500.0
DEFAULT_PSTH_PRE_MS float 100.0
DEFAULT_MIN_ISI_MS float 0.0
DEFAULT_PRESENCE_BIN_S float 60.0
DEFAULT_PRESENCE_MEAN_RATE_RATIO float 0.0
DEFAULT_REFRACTORY_BIN_MS float 1.0
DEFAULT_REFRACTORY_WINDOW_MS float 500.0