Bombcell integration #4306

Julie-Fabre · 2026-01-08T11:36:27Z

This PR ports bombcell-style unit classification to SpikeInterface.

Template metrics

Rewrote peak/trough detection with a new get_trough_and_peak_idx() function that uses scipy.signal.find_peaks(). Since SpikeInterface stores templates based on raw data rather than the heavily smoothed templates used in template matching, the waveforms can be noisy—so you can optionally apply Savitzky-Golay smoothing before detection. The function returns dicts for troughs, peaks before, and peaks after, each containing indices, values, prominences, and widths.

from spikeinterface.postprocessing import get_trough_and_peak_idx

troughs, peaks_before, peaks_after = get_trough_and_peak_idx(
    templates,
    sampling_frequency,
    smooth=True,
    min_thresh_detect_peaks_troughs=0.4,
)

New metrics: peak_before_to_trough_ratio, peak_after_to_trough_ratio, waveform_baseline_flatness, peak_before_width, trough_width, main_peak_to_trough_ratio.
Renamed peak_to_valley to peak_to_trough_duration.

analyzer.compute("template_metrics", metric_names=[
    "peak_before_to_trough_ratio",
    "waveform_baseline_flatness",
    "trough_width",
])

Quality metrics

Added snr_bombcell—peak amplitude over baseline MAD.

analyzer.compute("quality_metrics", metric_names=["snr_bombcell"])

amplitude_cutoff now has parameters for controlling the histogram fitting:

analyzer.compute("quality_metrics", metric_names=["amplitude_cutoff"], qm_params={
    "amplitude_cutoff": {
        "num_histogram_bins": 100,
        "histogram_smoothing_value": 3,
    }
})

Unit classification

New in spikeinterface.curation:

import spikeinterface.comparison as sc

thresholds = sc.bombcell_get_default_thresholds()
unit_type, unit_type_string = sc.bombcell_classify_units(
    quality_metrics,
    thresholds=thresholds,
    classify_non_somatic=True,
)
summary = sc.get_classification_summary(unit_type, unit_type_string)

Units get classified as NOISE → MUA → GOOD based on successive threshold checks. Optional NON_SOMA category for non-somatic waveforms.

Plots

Added plots for classification summaries, metric histograms with threshold lines, waveform overlays by category, and UpSet plots.

from spikeinterface.widgets import (
    plot_unit_classification,
    plot_classification_histograms,
    plot_waveform_overlay,
    plot_upset,
)

plot_unit_classification(analyzer, unit_type, unit_type_string)
plot_classification_histograms(quality_metrics, thresholds=thresholds)
plot_waveform_overlay(analyzer, unit_type, unit_type_string)
plot_upset(quality_metrics, unit_type, unit_type_string)

or a wrapper for all plots:

plots = plot_unit_classification_all(
    sorting_analyzer,
    unit_type,
    unit_type_string,
    quality_metrics=quality_metrics,  # optional, will try to get from analyzer
    thresholds=thresholds,            # optional, uses defaults
    split_non_somatic=False,
    include_upset=True,
)

…s and add more template metrics

…ault params

…verlay and histograms

…uration, add amplitude_median, bombcell_snr and fix non-somatic classification rules

for more information, see https://pre-commit.ci

into bombcell

… for name changes

…ell_

for more information, see https://pre-commit.ci

into bombcell

for more information, see https://pre-commit.ci

…ve template and quality metrics (this way it is clear what to input)

into bombcell

for more information, see https://pre-commit.ci

into bombcell

samuelgarcia · 2026-01-09T10:57:25Z

Salut Julie,
I read this super quickly. This is super impressive what you did during the hackahton!
I was not aware that you also did the widgets stuff. Waou.

I will be back with more carefully reading.

But some main stuff:

we avoid to push ipynb in the repo because in saturate the history so we use jupytext instead and push only the resulting generated rst,if the notebook is fast to generate (with simulate data) we also have the tutorial way to push doc through notebooks which is a py file run and generated by the documentaion build.
I would prefer to not have json directly in the code to handle parameters. I think simple python file with the same contents. lets discuss more
I would be courious to see the correlation between the basic snr and the one median based you did. I will try to make some plot on this.

alejoe91 · 2026-01-09T11:41:04Z

src/spikeinterface/metrics/template/template_metrics.py

 import numpy as np
 import warnings
 from copy import deepcopy
+from scipy.signal import find_peaks


Can you move this to the function?

The core module has minimal dependencies, and all additional imports should be local :)

alejoe91 · 2026-01-09T11:41:47Z

src/spikeinterface/curation/unit_labelling.py

@@ -0,0 +1,430 @@
+"""
+Unit labelling based on quality metrics (Bombcell).


Suggested change

Unit labelling based on quality metrics (Bombcell).

Unit labeling based on quality metrics (Bombcell).

In general, we adopted american english (@chrishalcrow is not happy about it!).

Could you rename this and the files to labeling?

The file could be called bombcell_curation (similar to model_based_curation)

alejoe91 · 2026-01-16T15:40:31Z

src/spikeinterface/curation/default_thresholds.json

@@ -0,0 +1,74 @@
+{


We can remove this file

alejoe91

@Julie-Fabre massive effort! Thanks!

I did a first round of reviewing and I'm happy to discuss some details and also work on it :)

alejoe91 · 2026-01-16T15:40:47Z

src/spikeinterface/curation/unit_labelling.py

+from typing import Optional
+
+
+WAVEFORM_METRICS = [


Suggested change

WAVEFORM_METRICS = [

NOISE_METRICS = [

?

alejoe91 · 2026-01-16T15:41:34Z

src/spikeinterface/curation/unit_labelling.py

+    # bombcell
+    return {
+        # Waveform quality (failures -> NOISE)
+        "num_positive_peaks": {"min": np.nan, "max": 2},


Suggested change

"num_positive_peaks": {"min": np.nan, "max": 2},

"num_positive_peaks": {"min": None, "max": 2},

I would just keep None and deal with it in the function instead of NaN, so you can save/load to JSON without any custom fields

alejoe91 · 2026-01-16T15:41:50Z

src/spikeinterface/curation/unit_labelling.py

+    quality_metrics=None,
+    template_metrics=None,


use sorting_analyzer instead

alejoe91 · 2026-01-16T15:42:13Z

src/spikeinterface/curation/unit_labelling.py

+    unit_type_string : np.ndarray
+        String labels.
+    """
+    combined_metrics = _combine_metrics(quality_metrics, template_metrics)


Suggested change

combined_metrics = _combine_metrics(quality_metrics, template_metrics)

combined_metrics = sorting_analyzer.get_metrics_extension_data()

;)

alejoe91 · 2026-01-16T15:42:40Z

src/spikeinterface/curation/unit_labelling.py

+            values = np.abs(values)
+        thresh = thresholds[metric_name]
+        noise_mask |= np.isnan(values)
+        if not np.isnan(thresh["min"]):


Suggested change

if not np.isnan(thresh["min"]):

if thresh["min"] is not None:

and so on

alejoe91 · 2026-01-16T16:04:09Z

src/spikeinterface/metrics/template/metrics.py

-class PeakToValley(BaseMetric):
-    metric_name = "peak_to_valley"
+class PeakToTroughDuration(BaseMetric):
+    metric_name = "peak_to_trough_duration"


I'm thinking it could be useful to add a deprecated_column_names, so we could automate backward compatibility :)

alejoe91 · 2026-01-16T16:07:04Z

src/spikeinterface/metrics/template/metrics.py

    num_positive_peaks_dict = {}
    num_negative_peaks_dict = {}
-    sampling_frequency = sorting_analyzer.sampling_frequency
+    sampling_frequency = tmp_data["sampling_frequency"]


goooooood catch @Julie-Fabre !!!!!!

alejoe91 · 2026-01-16T16:08:42Z

src/spikeinterface/metrics/template/metrics.py

+class WaveformDuration(BaseMetric):
+    metric_name = "waveform_duration"


I think that the name doesn't convey the actual computation

Suggested change

class WaveformDuration(BaseMetric):

metric_name = "waveform_duration"

class MainToNextPeakDuration(BaseMetric):

metric_name = "main_to_next_peak_duration"

?

alejoe91 · 2026-01-16T16:11:39Z

src/spikeinterface/metrics/template/metrics.py

+        "trough_width": "Width of the main trough in microseconds",
+        "peak_before_width": "Width of the main peak before trough in microseconds",
+        "peak_after_width": "Width of the main peak after trough in microseconds",


I would be consistent and output everything in the same unit. For now we have been doing seconds for the durations. The bombcell curation could still accept thresholds in us and do the conversion on the fly.

Alternatively, we could add a unit field to the BaseMetric, to specify units for each column. I think I would go with this, but it requires an additional refactoring. @chrishalcrow what do you think?

alejoe91 · 2026-01-16T16:12:34Z

src/spikeinterface/widgets/unit_labelling.py

+        quality_metrics=None,
+        template_metrics=None,


Suggested change

quality_metrics=None,

template_metrics=None,

sorting_analyzer

same reasons as curation module

Julie-Fabre and others added 20 commits January 7, 2026 01:15

template metrics from bombcell - use scipy findpeaks() to detect peak…

98de1f9

…s and add more template metrics

template denoising - SVD option and bombcell baseline flatness metric

71d35a4

woops remove kilosort4_output folder

788e8be

woops remove kilosort4_output folder

4b79f55

remove SVD option - was not performing well - and add sane tested def…

b391456

…ault params

bombcell unit type classification logic and output plots - waveform o…

c9306df

…verlay and histograms

bombcell unit type classification logic and output plots - waveform o…

44d8192

…verlay and histograms

bombcell snr

a29d3e1

fix: use peak_valley code to get duration, rename to peak_to_trough_d…

4514a51

…uration, add amplitude_median, bombcell_snr and fix non-somatic classification rules

upset plots

5b4cafb

[pre-commit.ci] auto fixes from pre-commit.com hooks

515ed36

for more information, see https://pre-commit.ci

cleanup

8467177

Merge branch 'bombcell' of https://github.com/Julie-Fabre/spikeinterface

41fde99

into bombcell

cleanup

2e8d6ea

cleanup

ed770bb

cleanup old template metric functions and ensure backward compaiblity…

c81898f

… for name changes

move bombcell functions to curation and rename bombcell ones to bombc…

71063dc

…ell_

remove upset plot warnings for now

5a2416e

bombcell plot wrapper

afe4e1b

[pre-commit.ci] auto fixes from pre-commit.com hooks

6fb5b13

for more information, see https://pre-commit.ci

alejoe91 added the curation Related to curation module label Jan 8, 2026

Julie-Fabre and others added 9 commits January 8, 2026 15:25

users can input bombcell parameters as JSON

52a58b2

Merge branch 'bombcell' of https://github.com/Julie-Fabre/spikeinterface

103ba7a

into bombcell

[pre-commit.ci] auto fixes from pre-commit.com hooks

aa35ac8

for more information, see https://pre-commit.ci

optionally save plots and metrics, explicit inputs to functions to ha…

eb130e9

…ve template and quality metrics (this way it is clear what to input)

Merge branch 'bombcell' of https://github.com/Julie-Fabre/spikeinterface

3b609b5

into bombcell

[pre-commit.ci] auto fixes from pre-commit.com hooks

01480b3

for more information, see https://pre-commit.ci

example jupyter notebook

af36259

example jupyter notebook

7045c43

Merge branch 'bombcell' of https://github.com/Julie-Fabre/spikeinterface

91a333e

into bombcell

alejoe91 reviewed Jan 9, 2026

View reviewed changes

alejoe91 reviewed Jan 16, 2026

View reviewed changes

src/spikeinterface/curation/default_thresholds.json

@@ -0,0 +1,74 @@

{

Copy link

Member

alejoe91 Jan 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can remove this file

alejoe91 requested changes Jan 16, 2026

View reviewed changes

		@@ -0,0 +1,430 @@
		"""
		Unit labelling based on quality metrics (Bombcell).

	Unit labelling based on quality metrics (Bombcell).
	Unit labeling based on quality metrics (Bombcell).

	"num_positive_peaks": {"min": np.nan, "max": 2},
	"num_positive_peaks": {"min": None, "max": 2},

	combined_metrics = _combine_metrics(quality_metrics, template_metrics)
	combined_metrics = sorting_analyzer.get_metrics_extension_data()

	if not np.isnan(thresh["min"]):
	if thresh["min"] is not None:

		class WaveformDuration(BaseMetric):
		metric_name = "waveform_duration"

Bombcell integration #4306

Are you sure you want to change the base?

Bombcell integration #4306

Uh oh!

Conversation

Julie-Fabre commented Jan 8, 2026

Template metrics

Quality metrics

Unit classification

Plots

Uh oh!

samuelgarcia commented Jan 9, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alejoe91 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants