From 6c612e64b9ce37b5b491c8c243993aec77a1abae Mon Sep 17 00:00:00 2001 From: Graham Findlay Date: Tue, 17 Nov 2026 20:20:09 -0600 Subject: [PATCH 1/2] Subtract wobble spikes at their fitted amplitude With scale_amplitudes on, a detected spike was removed from the objective at its fitted amplitude but from the normalized objective at amplitude 1. For a spike larger or smaller than its template, the difference stayed in the normalized objective and could be detected again as a spike of another unit. Both objectives now use the fitted amplitude. The fitted amplitude itself was read from the wrong row. The best jitter is a position within the jitter window, but it was used to index the scalings array, which spans the whole upsampled window. It now goes through jitter_window first. Add a test with three noiseless spikes at 2, 4 and 0.6 times their templates, which must come back as exactly those three spikes. --- .../matching/tests/test_wobble.py | 30 ++++++++++++++++++- .../sortingcomponents/matching/wobble.py | 6 ++-- 2 files changed, 33 insertions(+), 3 deletions(-) diff --git a/src/spikeinterface/sortingcomponents/matching/tests/test_wobble.py b/src/spikeinterface/sortingcomponents/matching/tests/test_wobble.py index f3a7a2e4f9..87e4ca3f54 100644 --- a/src/spikeinterface/sortingcomponents/matching/tests/test_wobble.py +++ b/src/spikeinterface/sortingcomponents/matching/tests/test_wobble.py @@ -2,7 +2,8 @@ import numpy as np -from spikeinterface.sortingcomponents.matching import wobble +from spikeinterface import NumpyRecording, Templates +from spikeinterface.sortingcomponents.matching import find_spikes_from_templates, wobble def test_compute_template_norm(): @@ -341,6 +342,33 @@ def test_compute_scale_amplitudes(): assert scale_amplitudes.shape == (peak_window_size, num_spikes) +def test_wobble_scaled_spikes(): + # noiseless spikes away from their template's amplitude. Each must come off at its fitted amplitude, or what is + # left of it is detected again as a spike of another unit + sampling_frequency, nbefore, num_samples, num_channels = 30000.0, 20, 60, 4 + t = np.arange(num_samples) - nbefore + templates_array = np.zeros((3, num_samples, num_channels), dtype=np.float32) + for unit in range(3): + width = 3 + 1.5 * unit + waveform = -np.exp(-0.5 * (t / width) ** 2) + 0.4 * np.exp(-0.5 * ((t - 2.5 * width) / (2 * width)) ** 2) + profile = np.exp(-0.5 * ((np.arange(num_channels) - 1.5 * unit) / 1.5) ** 2) + # rank 1, so the matcher's compression keeps the templates exactly + templates_array[unit] = 10 * np.outer(waveform, profile) + + units, times, amplitudes = [1, 0, 2], [120, 260, 400], [2.0, 4.0, 0.6] + traces = np.zeros((540, num_channels), dtype=np.float32) + for unit, time, amplitude in zip(units, times, amplitudes): + traces[time - nbefore : time - nbefore + num_samples] += amplitude * templates_array[unit] + recording = NumpyRecording([traces], sampling_frequency) + templates = Templates( + templates_array, sampling_frequency, nbefore, channel_ids=recording.channel_ids, unit_ids=np.arange(3) + ) + + spikes = find_spikes_from_templates(recording, templates, method="wobble", job_kwargs=dict(n_jobs=1)) + assert spikes["cluster_index"].tolist() == units + assert spikes["sample_index"].tolist() == times + + if __name__ == "__main__": test_compute_template_norm() test_compress_templates() diff --git a/src/spikeinterface/sortingcomponents/matching/wobble.py b/src/spikeinterface/sortingcomponents/matching/wobble.py index 9a42f3d9b3..27b282442f 100644 --- a/src/spikeinterface/sortingcomponents/matching/wobble.py +++ b/src/spikeinterface/sortingcomponents/matching/wobble.py @@ -735,10 +735,12 @@ def subtract_spike_train( # TODO: If optimizing for speed -- check this loop for spike_start_index, spike_scaling in zip(id_spiketrain, id_scaling): spike_stop_index = spike_start_index + convolution_resolution_len - objective_normalized[overlapping_templates, spike_start_index:spike_stop_index] -= 2 * pconv if params.scale_amplitudes: pconv_scaled = pconv * spike_scaling + objective_normalized[overlapping_templates, spike_start_index:spike_stop_index] -= 2 * pconv_scaled objective[overlapping_templates, spike_start_index:spike_stop_index] -= pconv_scaled + else: + objective_normalized[overlapping_templates, spike_start_index:spike_stop_index] -= 2 * pconv objective, objective_normalized = cls.enforce_refractory( spike_train, objective, objective_normalized, params, template_meta @@ -831,7 +833,7 @@ def calculate_high_res_shift( high_resolution_conv, norm_peaks, params.scale_min, params.scale_max, params.amplitude_variance ) jitter = np.argmax(high_res_objective[template_meta.jitter_window, :], axis=0) - scalings = scalings[jitter, np.arange(len(non_refractory_indices))] + scalings = scalings[template_meta.jitter_window[jitter], np.arange(len(non_refractory_indices))] # Extract outputs from jitter template_shift = template_meta.jitter2template_shift[jitter] From 151d2f307c89bcf4cdd7316ea0c83c8c0182fc21 Mon Sep 17 00:00:00 2001 From: Graham Findlay Date: Tue, 17 Nov 2026 20:31:17 -0600 Subject: [PATCH 2/2] Add joint fitting of overlapping spikes to wobble Wobble fits each spike's amplitude once, when it is found. If a second spike overlapping it is found later, the first amplitude has already absorbed part of the second spike, which is then missed or misplaced. With the new parameter joint_fit, each new spike's start, jitter and amplitude are fitted together with the spikes it overlaps, by least squares with the amplitude prior. Those spikes are then placed and fitted again while any of them moves. A spike is fitted with at most 8 others, the ones most coupled to it, which bounds the work in dense stretches. A spike whose amplitude is refitted to zero is dropped. joint_fit is off by default. It needs amplitude scaling (amplitude_variance > 0) and numba; the kernels are in _wobble_numba.py. test_wobble_scaled_spikes now also runs with joint_fit, with two overlapping spikes added. --- .../matching/_wobble_numba.py | 435 ++++++++++++++++++ .../matching/tests/test_wobble.py | 21 +- .../sortingcomponents/matching/wobble.py | 209 ++++++++- 3 files changed, 649 insertions(+), 16 deletions(-) create mode 100644 src/spikeinterface/sortingcomponents/matching/_wobble_numba.py diff --git a/src/spikeinterface/sortingcomponents/matching/_wobble_numba.py b/src/spikeinterface/sortingcomponents/matching/_wobble_numba.py new file mode 100644 index 0000000000..7516370322 --- /dev/null +++ b/src/spikeinterface/sortingcomponents/matching/_wobble_numba.py @@ -0,0 +1,435 @@ +"""Numba kernels for wobble's joint fit of overlapping spikes (see wobble._JointFit). + +The kernels' arguments include three tuples: +- state: the residual (channels by samples, float32); each spike's start, jittered template index and amplitude; + the spikes in each bin of num_samples samples, as linked lists (head, tail and next); whether each spike changed + since the objectives were last updated and, if so, the start, jittered template index and amplitude they have for + it; the number of spikes and of changed spikes; and the changed spikes in order; +- templates: each jittered template's waveform on its template's visible channels (padded to the most visible + channels of any template), those channels and how many there are, each channel's position among a template's + visible channels (-1 where it is not visible), the squared norms, the template overlap and each template's unit; +- params: jitter factor, 1 / amplitude variance, scale bounds, refractory period, re-placements per spike and the most + spikes a spike is fitted together with. +""" + +import numpy as np +from numba import njit + +# cache=True keeps the compiled code on disk, so it compiles on first use rather than in every session. + + +@njit(cache=True, fastmath={"reassoc", "contract"}) +def add_spikes(spike_train, state, templates, params): + """Place and fit new spikes (one batch, too far apart to overlap), taking out and placing again the spikes each + overlaps while any of them moves; their rows of spike_train are updated.""" + starts, jittered = state[1], state[2] + max_replacements = params[5] + for row in range(spike_train.shape[0]): + slot, near = _place(spike_train[row, 0], spike_train[row, 1], -1, state, templates, params) + involved = [np.int64(i) for i in near] + involved.append(slot) + queue = [np.int64(i) for i in near] + budget = max_replacements * len(involved) + while len(queue) > 0 and budget > 0: + i = queue.pop(0) + budget -= 1 + start, jittered_index = starts[i], jittered[i] + _change(i, 0.0, state, templates, params) + _place(start, jittered_index, i, state, templates, params) + if starts[i] != start or jittered[i] != jittered_index: + for j in involved: + if j != i and j not in queue: + queue.append(j) + spike_train[row, 0] = starts[slot] + spike_train[row, 1] = jittered[slot] + + +@njit(cache=True, fastmath={"reassoc", "contract"}) +def _place(start, jittered_index, slot, state, templates, params): + """Refine a spike's start and jitter, then fit it with the spikes it overlaps (at most the params[6] most coupled to + it); returns its index and those.""" + num_samples = templates[0].shape[2] + near = _overlapping(start, jittered_index, num_samples + 1, slot, state, templates, params) + if len(near) > params[6]: + near = _most_coupled(start, jittered_index, near, state, templates, params) + gram, rhs, amplitudes = _near_system(near, state, templates, params) + start, jittered_index = _refine(start, jittered_index, near, gram, rhs, amplitudes, state, templates, params) + slot = _fit(start, jittered_index, near, gram, rhs, amplitudes, slot, state, templates, params) + return slot, near + + +@njit(cache=True, fastmath={"reassoc", "contract"}) +def _overlapping(start, jittered_index, reach, exclude, state, templates, params): + """Spikes other than exclude starting less than reach samples from start, on channels the template shares.""" + starts, jittered, bin_head, bin_next = state[1], state[2], state[4], state[6] + unit_overlap, jitter_factor = templates[5], params[0] + num_samples = templates[0].shape[2] + found = np.empty(0, dtype=np.int64) + for counting in (True, False): + count = 0 + center = start // num_samples + for b in range(max(center - 1, 0), min(center + 2, bin_head.shape[0])): + i = bin_head[b] + while i >= 0: + if ( + i != exclude + and abs(starts[i] - start) < reach + and unit_overlap[jittered_index, jittered[i] // jitter_factor] + ): + if not counting: + found[count] = i + count += 1 + i = bin_next[i] + if counting: + found = np.empty(count, dtype=np.int64) + return found + + +@njit(cache=True, fastmath={"reassoc", "contract"}) +def _most_coupled(start, jittered_index, near, state, templates, params): + """The spikes of near whose amplitudes are most coupled to the spike's (their inner product over the smaller squared + norm), as many as params allows, with any of the same unit within the refractory period first; in their order.""" + starts, jittered = state[1], state[2] + norms, unit_of = templates[4], templates[6] + jitter_factor, inv_lambda, refractory_period = params[0], params[1], params[4] + unit = unit_of[jittered_index // jitter_factor] + coupling = np.empty(len(near)) + for p in range(len(near)): + i = near[p] + if unit_of[jittered[i] // jitter_factor] == unit and abs(starts[i] - start) <= refractory_period: + coupling[p] = np.inf + else: + product = _template_product(start, jittered_index, starts[i], jittered[i], templates, params) + coupling[p] = abs(product) / (min(norms[jittered_index], norms[jittered[i]]) + inv_lambda) + kept = np.sort(np.argsort(-coupling, kind="mergesort")[: params[6]]) + return near[kept] + + +@njit(cache=True, fastmath={"reassoc", "contract"}) +def _residual_product(start, jittered_index, state, templates, params): + """Inner product of a jittered template starting at start with the residual, which is zero outside the chunk.""" + residual = state[0] + waveforms, channels, num_visible = templates[0], templates[1], templates[2] + template_index = jittered_index // params[0] + num_samples = waveforms.shape[2] + lo, hi = max(0, -start), min(num_samples, residual.shape[1] - start) + total = 0.0 + for p in range(num_visible[template_index]): + # sliced first, so that indices are known to be non-negative + waveform = waveforms[jittered_index, p, lo:hi] + trace = residual[channels[template_index, p], start + lo : start + hi] + for t in range(hi - lo): + total += np.float64(waveform[t]) * trace[t] + return total + + +@njit(cache=True, fastmath={"reassoc", "contract"}) +def _template_product(start, jittered_index, other_start, other_jittered_index, templates, params): + """Inner product of two jittered templates at their starts.""" + waveforms, channels, num_visible, channel_position = templates[0], templates[1], templates[2], templates[3] + num_samples = waveforms.shape[2] + lag = other_start - start + if lag <= -num_samples or lag >= num_samples: + return 0.0 + template_index, other_template_index = jittered_index // params[0], other_jittered_index // params[0] + lo, hi = max(0, lag), min(num_samples, num_samples + lag) + total = 0.0 + for p in range(num_visible[template_index]): + q = channel_position[other_template_index, channels[template_index, p]] + if q < 0: + continue + waveform = waveforms[jittered_index, p, lo:hi] + other_waveform = waveforms[other_jittered_index, q, lo - lag : hi - lag] + for t in range(hi - lo): + total += np.float64(waveform[t]) * other_waveform[t] + return total + + +@njit(cache=True, fastmath={"reassoc", "contract"}) +def _near_system(near, state, templates, params): + """Gram matrix (with the prior) of the spikes near, their least-squares right-hand side with them added back to + the residual, and their amplitudes.""" + starts, jittered, amplitudes = state[1], state[2], state[3] + inv_lambda = params[1] + k = len(near) + gram = np.zeros((k, k)) + rhs = np.empty(k) + near_amplitudes = np.empty(k) + for p in range(k): + i = near[p] + near_amplitudes[p] = amplitudes[i] + rhs[p] = _residual_product(starts[i], jittered[i], state, templates, params) + for q in range(p, k): + j = near[q] + gram[p, q] = _template_product(starts[i], jittered[i], starts[j], jittered[j], templates, params) + gram[q, p] = gram[p, q] + for p in range(k): + rhs[p] += inv_lambda + for q in range(k): + rhs[p] += gram[p, q] * near_amplitudes[q] + for p in range(k): + gram[p, p] += inv_lambda + return gram, rhs, near_amplitudes + + +@njit(cache=True, fastmath={"reassoc", "contract"}) +def _refine(start, jittered_index, near, gram, rhs, near_amplitudes, state, templates, params): + """The start (within a sample) and jitter with the largest fitted gain, the spikes near refitted with it, that is + not within the refractory period of a spike of the same unit.""" + residual, starts, jittered = state[0], state[1], state[2] + norms, unit_of = templates[4], templates[6] + jitter_factor, inv_lambda, refractory_period = params[0], params[1], params[4] + num_samples = templates[0].shape[2] + template_index = jittered_index // jitter_factor + first_jittered = template_index * jitter_factor + first = start - 1 + corr = np.empty((3, jitter_factor)) + denominator = np.empty((3, jitter_factor)) + allowed = np.empty(3, dtype=np.bool_) + for o in range(3): + allowed[o] = first + o >= 0 and first + o + num_samples <= residual.shape[1] + for j in range(jitter_factor): + corr[o, j] = _residual_product(first + o, first_jittered + j, state, templates, params) + denominator[o, j] = norms[first_jittered + j] + inv_lambda + k = len(near) + if k > 0: + gram_inverse = np.linalg.inv(gram) + change = near_amplitudes.copy() + for p in range(k): + for q in range(k): + change[p] -= gram_inverse[p, q] * rhs[q] + # inner products of every candidate with each spike near + cross = np.zeros((3, jitter_factor, k)) + for q in range(k): + i = near[q] + same_unit = unit_of[jittered[i] // jitter_factor] == unit_of[template_index] + for o in range(3): + lag = starts[i] - (first + o) + if same_unit and abs(lag) < refractory_period: + allowed[o] = False + if abs(lag) < num_samples: + for j in range(jitter_factor): + cross[o, j, q] = _template_product( + first + o, first_jittered + j, starts[i], jittered[i], templates, params + ) + for o in range(3): + for j in range(jitter_factor): + for p in range(k): + corr[o, j] += cross[o, j, p] * change[p] + quadratic = 0.0 + for q in range(k): + quadratic += gram_inverse[p, q] * cross[o, j, q] + denominator[o, j] -= cross[o, j, p] * quadratic + best, best_offset, best_jitter = -np.inf, -1, -1 + for o in range(3): + if not allowed[o]: + continue + for j in range(jitter_factor): + c = corr[o, j] + inv_lambda + if c > 0 and denominator[o, j] > 1e-6 * norms[first_jittered + j]: + score = c * c / denominator[o, j] + if score > best: + best, best_offset, best_jitter = score, o, j + if best_offset < 0: + return start, jittered_index + return first + best_offset, first_jittered + best_jitter + + +@njit(cache=True, fastmath={"reassoc", "contract"}) +def _fit(start, jittered_index, near, gram, rhs, near_amplitudes, slot, state, templates, params): + """Fit a spike (new, or taken out at slot) and the spikes near together, update the residual, and record it; + returns its index.""" + starts, jittered, bin_head, bin_tail, bin_next, counts = state[1], state[2], state[4], state[5], state[6], state[11] + norms = templates[4] + inv_lambda, scale_min, scale_max = params[1], params[2], params[3] + num_samples = templates[0].shape[2] + k = len(near) + new_rhs = _residual_product(start, jittered_index, state, templates, params) + inv_lambda + if k > 0: + full_gram = np.empty((k + 1, k + 1)) + full_gram[:k, :k] = gram + full_rhs = np.empty(k + 1) + full_rhs[:k] = rhs + for q in range(k): + i = near[q] + cross = _template_product(start, jittered_index, starts[i], jittered[i], templates, params) + full_gram[q, k] = cross + full_gram[k, q] = cross + # the new spike's inner product with the residual, the spikes near added back + new_rhs += cross * near_amplitudes[q] + full_gram[k, k] = norms[jittered_index] + inv_lambda + full_rhs[k] = new_rhs + fitted = _bounded_solve(full_gram, full_rhs, scale_min, scale_max) + else: + fitted = np.array([min(max(new_rhs / (norms[jittered_index] + inv_lambda), scale_min), scale_max)]) + for q in range(k): + _change(near[q], fitted[q], state, templates, params) + if slot < 0: + slot = counts[0] + counts[0] += 1 + starts[slot], jittered[slot], state[3][slot] = start, jittered_index, 0.0 + _bin_append(slot, start // num_samples, bin_head, bin_tail, bin_next) + _record(slot, state) + else: + # taken out, so at amplitude 0 + if start // num_samples != starts[slot] // num_samples: + _bin_remove(slot, starts[slot] // num_samples, bin_head, bin_tail, bin_next) + _bin_append(slot, start // num_samples, bin_head, bin_tail, bin_next) + starts[slot], jittered[slot] = start, jittered_index + _change(slot, fitted[k], state, templates, params) + return slot + + +@njit(cache=True, fastmath={"reassoc", "contract"}) +def _change(i, amplitude, state, templates, params): + """Set a spike's amplitude and update the residual (only).""" + residual, starts, jittered, amplitudes = state[0], state[1], state[2], state[3] + waveforms, channels, num_visible = templates[0], templates[1], templates[2] + change = amplitude - amplitudes[i] + if change == 0: + return + _record(i, state) + template_index = jittered[i] // params[0] + start, num_samples = starts[i], waveforms.shape[2] + scale = np.float32(change) + for p in range(num_visible[template_index]): + waveform = waveforms[jittered[i], p] + trace = residual[channels[template_index, p], start : start + num_samples] + for t in range(num_samples): + trace[t] -= scale * waveform[t] + amplitudes[i] = amplitude + + +@njit(cache=True, fastmath={"reassoc", "contract"}) +def _record(i, state): + """Keep a spike's start, jittered index and amplitude as the objectives have them, if not kept already.""" + stale, counts, changed = state[7], state[11], state[12] + if not stale[i]: + stale[i] = True + state[8][i], state[9][i], state[10][i] = state[1][i], state[2][i], state[3][i] + changed[counts[1]] = i + counts[1] += 1 + + +@njit(cache=True, fastmath={"reassoc", "contract"}) +def _bin_append(i, b, bin_head, bin_tail, bin_next): + bin_next[i] = -1 + if bin_head[b] < 0: + bin_head[b] = i + else: + bin_next[bin_tail[b]] = i + bin_tail[b] = i + + +@njit(cache=True, fastmath={"reassoc", "contract"}) +def _bin_remove(i, b, bin_head, bin_tail, bin_next): + previous, j = -1, bin_head[b] + while j != i: + previous, j = j, bin_next[j] + if previous < 0: + bin_head[b] = bin_next[i] + else: + bin_next[previous] = bin_next[i] + if bin_tail[b] == i: + bin_tail[b] = previous + + +@njit(cache=True, fastmath={"reassoc", "contract"}) +def _bounded_solve(gram, rhs, lower, upper): + """Solve gram @ x = rhs for lower <= x <= upper: entries out of bounds are fixed at them and the rest solved + again.""" + x = np.linalg.solve(gram, rhs) + m = len(x) + fixed = np.zeros(m, dtype=np.bool_) + while True: + out = False + for i in range(m): + if not fixed[i] and (x[i] < lower or x[i] > upper): + x[i] = min(max(x[i], lower), upper) + fixed[i] = True + out = True + if not out: + return x + free = np.flatnonzero(~fixed) + if len(free) == 0: + return x + sub_gram = np.empty((len(free), len(free))) + sub_rhs = np.empty(len(free)) + for a in range(len(free)): + sub_rhs[a] = rhs[free[a]] + for i in range(m): + if fixed[i]: + sub_rhs[a] -= gram[free[a], i] * x[i] + for b in range(len(free)): + sub_gram[a, b] = gram[free[a], free[b]] + solved = np.linalg.solve(sub_gram, sub_rhs) + for a in range(len(free)): + x[free[a]] = solved[a] + + +# The objectives are updated with the same float32 operations as subtract_spike_train uses, so without fastmath. + + +@njit(cache=True) +def sync_objectives(objective, objective_normalized, state, convolutions): + """Update the objectives for the spikes changed since the last update.""" + starts, jittered, amplitudes = state[1], state[2], state[3] + stale, synced_starts, synced_jittered, synced_amplitudes = state[7], state[8], state[9], state[10] + counts, changed = state[11], state[12] + for c in range(counts[1]): + i = changed[c] + stale[i] = False + if synced_starts[i] == starts[i] and synced_jittered[i] == jittered[i]: + _subtract( + objective, + objective_normalized, + starts[i], + jittered[i], + amplitudes[i] - synced_amplitudes[i], + convolutions, + ) + else: + _subtract( + objective, + objective_normalized, + synced_starts[i], + synced_jittered[i], + -synced_amplitudes[i], + convolutions, + ) + _subtract(objective, objective_normalized, starts[i], jittered[i], amplitudes[i], convolutions) + counts[1] = 0 + + +@njit(cache=True) +def _subtract(objective, objective_normalized, start, jittered_index, change, convolutions): + """Subtract a jittered template's pairwise convolutions at change times its amplitude from the objectives.""" + if change == 0: + return + pairwise_convolution, overlapping, num_overlapping = convolutions + scale, scale_normalized = np.float32(change), np.float32(2 * change) + for k in range(num_overlapping[jittered_index]): + convolution = pairwise_convolution[jittered_index, k] + row = objective[overlapping[jittered_index, k], start : start + len(convolution)] + row_normalized = objective_normalized[overlapping[jittered_index, k], start : start + len(convolution)] + for t in range(len(convolution)): + row[t] -= scale * convolution[t] + row_normalized[t] -= scale_normalized * convolution[t] + + +@njit(cache=True) +def credit_projections(spike_train, projection, objective_normalized, convolutions, norms, inv_lambda): + """Credit the templates near each new spike with their projection onto it, where it is the largest yet.""" + pairwise_convolution, overlapping, num_overlapping = convolutions + for row in range(spike_train.shape[0]): + start, jittered_index = spike_train[row, 0], spike_train[row, 1] + denominator = np.float32(norms[jittered_index] + inv_lambda) + for k in range(num_overlapping[jittered_index]): + convolution = pairwise_convolution[jittered_index, k] + largest = projection[overlapping[jittered_index, k], start : start + len(convolution)] + row_normalized = objective_normalized[overlapping[jittered_index, k], start : start + len(convolution)] + for t in range(len(convolution)): + increase = convolution[t] * convolution[t] / denominator - largest[t] + if increase > 0: + largest[t] += increase + row_normalized[t] += increase diff --git a/src/spikeinterface/sortingcomponents/matching/tests/test_wobble.py b/src/spikeinterface/sortingcomponents/matching/tests/test_wobble.py index 87e4ca3f54..781b644a95 100644 --- a/src/spikeinterface/sortingcomponents/matching/tests/test_wobble.py +++ b/src/spikeinterface/sortingcomponents/matching/tests/test_wobble.py @@ -1,5 +1,6 @@ from types import SimpleNamespace +import pytest import numpy as np from spikeinterface import NumpyRecording, Templates @@ -342,7 +343,11 @@ def test_compute_scale_amplitudes(): assert scale_amplitudes.shape == (peak_window_size, num_spikes) -def test_wobble_scaled_spikes(): +@pytest.mark.parametrize( + "joint_fit", + [False, pytest.param(True, marks=pytest.mark.skipif(not wobble.HAVE_NUMBA, reason="joint_fit needs numba"))], +) +def test_wobble_scaled_spikes(joint_fit): # noiseless spikes away from their template's amplitude. Each must come off at its fitted amplitude, or what is # left of it is detected again as a spike of another unit sampling_frequency, nbefore, num_samples, num_channels = 30000.0, 20, 60, 4 @@ -356,7 +361,11 @@ def test_wobble_scaled_spikes(): templates_array[unit] = 10 * np.outer(waveform, profile) units, times, amplitudes = [1, 0, 2], [120, 260, 400], [2.0, 4.0, 0.6] - traces = np.zeros((540, num_channels), dtype=np.float32) + if joint_fit: + # two that overlap: the first one found must be refitted when the second is, or its amplitude absorbs the + # second and hides it + units, times, amplitudes = units + [2, 1], times + [540, 542], amplitudes + [1.5, 0.7] + traces = np.zeros((680, num_channels), dtype=np.float32) for unit, time, amplitude in zip(units, times, amplitudes): traces[time - nbefore : time - nbefore + num_samples] += amplitude * templates_array[unit] recording = NumpyRecording([traces], sampling_frequency) @@ -364,7 +373,13 @@ def test_wobble_scaled_spikes(): templates_array, sampling_frequency, nbefore, channel_ids=recording.channel_ids, unit_ids=np.arange(3) ) - spikes = find_spikes_from_templates(recording, templates, method="wobble", job_kwargs=dict(n_jobs=1)) + spikes = find_spikes_from_templates( + recording, + templates, + method="wobble", + method_kwargs=dict(parameters=dict(joint_fit=joint_fit)), + job_kwargs=dict(n_jobs=1), + ) assert spikes["cluster_index"].tolist() == units assert spikes["sample_index"].tolist() == times diff --git a/src/spikeinterface/sortingcomponents/matching/wobble.py b/src/spikeinterface/sortingcomponents/matching/wobble.py index 27b282442f..97d6d5fac1 100644 --- a/src/spikeinterface/sortingcomponents/matching/wobble.py +++ b/src/spikeinterface/sortingcomponents/matching/wobble.py @@ -18,6 +18,8 @@ else: HAVE_TORCH = False +HAVE_NUMBA = importlib.util.find_spec("numba") is not None + @dataclass class WobbleParameters: @@ -51,6 +53,10 @@ class WobbleParameters: Maximum value for ampltiude scaling of templates. scale_amplitudes : bool If True, scale amplitudes of templates to match spikes. + joint_fit : bool, default False + If True, fit each spike's start, jitter and amplitude together with those of the spikes it overlaps, instead of + on its own. This finds more of the spikes that overlap, most of all on few channels (tetrodes). Needs amplitude + scaling (amplitude_variance > 0) and numba. engine : string in ["numpy", "torch", "auto"]. Default "auto" The engine to use for the convolutions torch_device : string in ["cpu", "cuda", None]. Default "cpu" @@ -79,6 +85,7 @@ class WobbleParameters: scale_min: float = 0 scale_max: float = np.inf scale_amplitudes: bool = False + joint_fit: bool = False engine: str = "numpy" torch_device: str = "cpu" shared_memory: bool = True @@ -373,6 +380,8 @@ class WobbleMatch(BaseTemplateMatching): removing detected spikes from the traces 6. Enforce a refractory period around each spike by setting the objective to -inf 7. Repeat Steps 3-6 until no more spikes are detected above the threshold OR max_iter is reached + With joint_fit, steps 4 and 5 fit each new spike's start, jitter and amplitude together with the spikes it overlaps, + against the residual traces, and a detected spike whose amplitude is fitted to zero is dropped (see _JointFit). Notes ----- @@ -420,6 +429,10 @@ def __init__( # Aggregate useful parameters/variables for handy access in downstream functions params = WobbleParameters(**parameters) + if params.joint_fit: + assert params.scale_amplitudes, "joint_fit needs amplitude scaling (amplitude_variance > 0)" + if not HAVE_NUMBA: + raise ModuleNotFoundError('"wobble" needs numba for joint_fit') assert engine in ["numpy", "torch", "auto"], "engine should be numpy, torch or auto" if engine == "auto": @@ -501,7 +514,8 @@ def clean(self): self.shm = None def __del__(self): - if self.shared_memory and self.shm is not None: + # __init__ may have raised before the shared memory was set up + if getattr(self, "shared_memory", False) and self.shm is not None: self.template_meta = None self.shm.close() self.shm = None @@ -539,6 +553,7 @@ def compute_matching(self, traces, start_frame, end_frame, segment_index): traces, self.template_data, self.params.approx_rank, self.engine, self.torch_device ) objective_normalized = 2 * objective - self.template_data.norm_squared[:, np.newaxis] + joint_fit = _JointFit(self, traces, objective) if self.params.joint_fit else None # Compute spike train spike_trains, scalings, distance_metrics = [], [], [] @@ -555,26 +570,40 @@ def compute_matching(self, traces, start_frame, end_frame, segment_index): if len(spike_train) == 0: break + if joint_fit is not None: + # fit the new spikes together with the spikes they overlap, which may move them + joint_fit.add(spike_train, objective, objective_normalized) + objective, objective_normalized = self.enforce_refractory( + spike_train, objective, objective_normalized, self.params, self.template_meta + ) + joint_fit.credit_projections(spike_train, objective_normalized) + else: + # subtract newly detected spike train from traces (via the objective) + objective, objective_normalized = self.subtract_spike_train( + spike_train, + scaling, + self.template_data, + objective, + objective_normalized, + self.params, + self.template_meta, + self.sparsity, + ) + # update spike_train, scaling, distance metrics with new values spike_trains.extend(list(spike_train)) scalings.extend(list(scaling)) distance_metrics.extend(list(distance_metric)) - # subtract newly detected spike train from traces (via the objective) - objective, objective_normalized = self.subtract_spike_train( - spike_train, - scaling, - self.template_data, - objective, - objective_normalized, - self.params, - self.template_meta, - self.sparsity, - ) - spike_train = np.array(spike_trains) scalings = np.array(scalings) distance_metric = np.array(distance_metrics) + if joint_fit is not None and len(spike_train): + # spikes may have moved when later ones were fitted, and one refitted to zero explains nothing + spike_train = np.column_stack((joint_fit.starts, joint_fit.jittered_indices)) + scalings = np.array(joint_fit.amplitudes) + keep = scalings > 0 + spike_train, scalings, distance_metric = spike_train[keep], scalings[keep], distance_metric[keep] if len(spike_train) == 0: # no spikes found return np.zeros(0, dtype=_base_matching_dtype) @@ -840,6 +869,64 @@ def calculate_high_res_shift( time_shift = template_meta.jitter2spike_time_shift[jitter] return template_shift, time_shift, non_refractory_indices, scalings + def _joint_fit_templates(self): + """Jittered templates as _JointFit subtracts them: waveforms (channels by samples) on their template's visible + channels, padded to the most any template has, those channels and how many there are, each channel's position + among a template's visible channels (-1 where not visible), squared norms, template overlap and each template's + unit.""" + if "_joint_fit_templates_cache" not in self.__dict__: + visible = self.sparsity.visible_channels + num_templates, num_channels = visible.shape + jitter_factor = self.params.jitter_factor + num_visible = visible.sum(axis=1).astype(np.int64) + channels = np.zeros((num_templates, max(int(num_visible.max()), 1)), dtype=np.int64) + channel_position = np.full((num_templates, num_channels), -1, dtype=np.int64) + waveforms = np.zeros( + (num_templates * jitter_factor, channels.shape[1], self.template_meta.num_samples), dtype=np.float32 + ) + norms = np.zeros(num_templates * jitter_factor) + for template_index in range(num_templates): + visible_channels = np.flatnonzero(visible[template_index]) + channels[template_index, : len(visible_channels)] = visible_channels + channel_position[template_index, visible_channels] = np.arange(len(visible_channels)) + singular = self.template_data.singular[:, template_index, 0] + spatial = self.template_data.spatial[:, template_index][:, visible_channels] + for jittered_index in range(template_index * jitter_factor, (template_index + 1) * jitter_factor): + temporal = self.template_data.temporal_jittered[jittered_index] + waveform = np.ascontiguousarray(np.flipud((temporal * singular) @ spatial), dtype=np.float32) + waveforms[jittered_index, : len(visible_channels)] = waveform.T + norms[jittered_index] = np.sum(np.square(waveform, dtype=np.float64)) + unit_of = np.asarray(self.template_meta.template_indices2unit_indices, dtype=np.int64) + unit_overlap = np.ascontiguousarray(self.sparsity.unit_overlap, dtype=np.bool_) + self._joint_fit_templates_cache = ( + waveforms, + channels, + num_visible, + channel_position, + norms, + unit_overlap, + unit_of, + ) + return self._joint_fit_templates_cache + + def _convolution_tables(self): + """Each jittered template's pairwise convolutions with the templates it overlaps, those templates and how many + there are, padded to the most any jittered template overlaps.""" + if "_convolution_tables_cache" not in self.__dict__: + num_overlapping = self.sparsity.unit_overlap.sum(axis=1).astype(np.int64) + overlapping = np.zeros((len(num_overlapping), max(int(num_overlapping.max()), 1)), dtype=np.int64) + for jittered_index, row in enumerate(self.sparsity.unit_overlap): + overlapping[jittered_index, : num_overlapping[jittered_index]] = np.flatnonzero(row) + if self.shared_memory: + pairwise_convolution = self.template_data.pairwise_convolution[0] + else: + convolutions = self.template_data.pairwise_convolution + pairwise_convolution = np.zeros(overlapping.shape + convolutions[0].shape[1:], dtype=np.float32) + for jittered_index, convolution in enumerate(convolutions): + pairwise_convolution[jittered_index, : len(convolution)] = convolution + self._convolution_tables_cache = (pairwise_convolution, overlapping, num_overlapping) + return self._convolution_tables_cache + @classmethod def enforce_refractory( cls, spike_train, objective, objective_normalized, params, template_meta @@ -890,6 +977,102 @@ def enforce_refractory( return objective, objective_normalized +class _JointFit: + """The spikes found so far in a chunk, fitted together against an explicit residual (used with joint_fit). + + A new spike first gets the start (within a sample of its peak) and jitter whose fit, together with the spikes it + overlaps, explains the most of the residual; its amplitude and theirs are then fitted together by least squares + (with the amplitude prior). Where more than max_near spikes overlap it, as in an artifact, it is fitted only with + those whose amplitudes are most coupled to its own, which bounds the work per spike. The spikes it overlaps were + placed before it was found, so each is then taken out and placed and fitted again in the same way, and so on while + any of them moves (coordinate descent on the starts and jitters). The objectives are brought up to date with the + residual once per batch of new spikes. + + Templates near a spike are credited in the detection objective with their projection onto it, so that a peak there + is the gain of adding a spike at unit amplitude with the spike it overlaps refitted, instead of with that spike's + amplitude fixed at one fitted before the new spike was found. + + The work is done by the numba kernels in _wobble_numba; this class holds their arrays. + """ + + # re-placements allowed per spike involved, after a new spike is placed + max_replacements = 10 + # the most spikes a spike is fitted together with: those whose amplitudes are most coupled to its own + max_near = 8 + + def __init__(self, matcher, traces, objective): + self.inv_lambda = 1 / matcher.params.amplitude_variance + # largest projection of each template, at each time, onto a spike found so far + self.projection = np.zeros_like(objective) + self.templates = matcher._joint_fit_templates() + self.convolutions = matcher._convolution_tables() + params = matcher.params + self.params = ( + np.int64(params.jitter_factor), + float(self.inv_lambda), + float(params.scale_min), + float(params.scale_max), + np.int64(params.refractory_period_frames), + np.int64(self.max_replacements), + np.int64(self.max_near), + ) + num_bins = traces.shape[0] // matcher.template_meta.num_samples + 1 + # laid out as _wobble_numba describes; the arrays for each spike grow in add + self.state = ( + np.ascontiguousarray(traces.T), + np.zeros(0, dtype=np.int64), + np.zeros(0, dtype=np.int64), + np.zeros(0), + np.full(num_bins, -1, dtype=np.int64), + np.full(num_bins, -1, dtype=np.int64), + np.zeros(0, dtype=np.int64), + np.zeros(0, dtype=np.bool_), + np.zeros(0, dtype=np.int64), + np.zeros(0, dtype=np.int64), + np.zeros(0), + np.zeros(2, dtype=np.int64), + np.zeros(0, dtype=np.int64), + ) + + @property + def starts(self): + return self.state[1][: self.state[11][0]] + + @property + def jittered_indices(self): + return self.state[2][: self.state[11][0]] + + @property + def amplitudes(self): + return self.state[3][: self.state[11][0]] + + def add(self, spike_train, objective, objective_normalized): + """Place and fit new spikes (one batch, too far apart to overlap) and update the objectives; their rows of + spike_train are updated.""" + from ._wobble_numba import add_spikes, sync_objectives + + state = list(self.state) + needed = state[11][0] + len(spike_train) + if needed > len(state[1]): + capacity = max(2 * len(state[1]), needed, 64) + for k in (1, 2, 3, 6, 7, 8, 9, 10, 12): + state[k] = np.concatenate((state[k], np.zeros(capacity - len(state[k]), dtype=state[k].dtype))) + self.state = tuple(state) + rows = np.ascontiguousarray(spike_train, dtype=np.int64) + add_spikes(rows, self.state, self.templates, self.params) + spike_train[:] = rows + sync_objectives(objective, objective_normalized, self.state, self.convolutions) + + def credit_projections(self, spike_train, objective_normalized): + """Credit the templates near each new spike with their projection onto it, where it is the largest yet.""" + from ._wobble_numba import credit_projections + + rows = np.ascontiguousarray(spike_train, dtype=np.int64) + credit_projections( + rows, self.projection, objective_normalized, self.convolutions, self.templates[4], self.inv_lambda + ) + + def compute_template_norm(visible_channels, templates): """Computes squared norm of each template.