Refactor metrics into its own module #4183

alejoe91 · 2025-10-22T10:31:38Z

This PR includes a major refactor of the metrics concept.

It defines a BaseMetric, with core metadata of individual metrics including dtypes, column names, extension dependance, and a compute function.
Another BaseMetricExtension contains a collection of BaseMetrics and deals with most of the machinery, including:

setting params
checking dependencies and removing metrics based on it
computing metrics
deleting, merging, splitting metrics
preparing data that can be shared across metrics (e.g., pca for pca metrics, peaks info and templates for template metrics)

The template_metrics, quality_metrics, and a new spiketrain_metrics extensions are now in the metrics module. The latter only includes num_spikes and firing_rate, which are also imported as quality metrics.

Still finalizing tests, but this should be 90% done

src/spikeinterface/metrics/quality/__init__.py

src/spikeinterface/metrics/quality/misc_metrics.py

src/spikeinterface/core/analyzer_extension_core.py

src/spikeinterface/core/sortinganalyzer.py

src/spikeinterface/metrics/quality/misc_metrics.py

src/spikeinterface/qualitymetrics/misc_metrics.py

src/spikeinterface/metrics/quality/__init__.py

src/spikeinterface/postprocessing/__init__.py

src/spikeinterface/qualitymetrics/__init__.py

chrishalcrow · 2025-10-22T15:01:58Z

This looks great - love the prepare_data idea! And this refactor will make it less awkward to develop new metrics. And the pca file is much neater now - nice.

I think this is a good chance to remove compute_{metric_name} stuff from the docs (modules/qualitymetrics) and replace with analyzer.compute("quality_metrics", metric_names={metric_name}) as our recommended method. More awkward, but much better for provenance etc.

I'd vote to take the chance to make multi channel template metrics included by default: they're very helpful.

alejoe91 · 2025-10-22T15:26:44Z

I'd vote to take the chance to make multi channel template metrics included by default: they're very helpful.

I agree! Maybe we can make it default for number of channel > 64?

doc/modules/metrics.rst

src/spikeinterface/qualitymetrics/__init__.py

src/spikeinterface/core/analyzer_extension_core.py

src/spikeinterface/core/sortinganalyzer.py

src/spikeinterface/metrics/template/template_metrics.py

src/spikeinterface/core/analyzer_extension_core.py

…refactor-metrics

samuelgarcia · 2025-12-01T09:47:25Z

doc/modules/metrics/qualitymetrics/firing_rate.rst

 .. code-block:: python

-    import spikeinterface.qualitymetrics as sqm
+    from spikeinterface.metrics.spiketrain import compute_firing_rates


More easy no ?

Suggested change

from spikeinterface.metrics.spiketrain import compute_firing_rates

from spikeinterface.metrics import compute_firing_rates

samuelgarcia · 2025-12-01T09:49:57Z

src/spikeinterface/core/analyzer_extension_core.py

+    metric_params = {}  # to be defined in subclass
+    metric_columns = {}  # column names and their dtypes of the dataframe
+    needs_recording = False  # to be defined in subclass
+    needs_tmp_data = False  # to be defined in subclass


I think this diserve more comments to explain the concept

samuelgarcia · 2025-12-01T15:07:30Z

src/spikeinterface/metrics/conftest.py

@@ -0,0 +1,8 @@
+import pytest


why do have this file in sources ?
Better in tests sub folder no ?

it needs to be at the module level, so that config are shared across submodules

samuelgarcia · 2025-12-01T15:09:32Z

src/spikeinterface/metrics/spiketrain/metrics.py

@@ -0,0 +1,84 @@
+import numpy as np
+from spikeinterface.core.analyzer_extension_core import BaseMetric
+


How do we prevent previous users to not do
analyzer.get_extension("quality_metics").get_data()["firing_rates"] is it duplicated ?

I think that it should work!

samuelgarcia · 2025-12-01T15:13:10Z

src/spikeinterface/core/analyzer_extension_core.py

+
+    def _compute_metrics(
+        self,
+        sorting_analyzer: SortingAnalyzer,


An extension is aware of the analyzer no ?

this is because the same function is also used for merge/splits, where you provide a new analyzer!

samuelgarcia · 2025-12-01T15:18:40Z

src/spikeinterface/metrics/template/template_metrics.py

+        if not include_multi_channel_metrics and num_channels >= MIN_CHANNELS_FOR_MULTI_CHANNEL_METRICS:
+            include_multi_channel_metrics = True


Not sure to like the hidden magic choices.

That was Chris's idea :) then we should make it True by default. These are really useful

They are the best template metrics. I would vote True by default -- but am a little worried that tetrode people will get loads of warnings about nan results. Maybe we can discuss how to deal with these better?

samuelgarcia · 2025-12-01T15:22:36Z

src/spikeinterface/core/analyzer_extension_core.py

+        )
+        return params
+
+    def _prepare_data(self, sorting_analyzer, unit_ids=None):


this deserve also more explcation and how this cache this propagated on other other class

samuelgarcia · 2025-12-01T15:38:37Z

This mostly almost OK for me.
thanks camarade for this hudge effort.
I am pretty sure that we will face some none backward compatibility for this lets fix then when they arrive.

alejoe91 added 8 commits October 8, 2025 14:54

wip: start big metric refactoring

8793229

wip

f71ae91

template metrics done!

b7445be

remove template_metrics_old

83b8de2

wip quality metrics

a38cfa2

wip

bbdd974

Fix metric dtypes and template metric tests

bf4e24c

update tests

50bf11f

alejoe91 requested review from chrishalcrow and samuelgarcia October 22, 2025 10:31

alejoe91 added the qualitymetrics Related to qualitymetrics module label Oct 22, 2025