From f3fbd5d4017f9ea0888c0a1846ed513c4a1fbe9f Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Thu, 29 Aug 2024 15:59:44 +0200
Subject: [PATCH 001/344] nodepipeline : skip chunks when no peaks inside

---
 src/spikeinterface/core/node_pipeline.py      | 162 +++++++++++-------
 .../core/tests/test_node_pipeline.py          |  15 +-
 2 files changed, 114 insertions(+), 63 deletions(-)

diff --git a/src/spikeinterface/core/node_pipeline.py b/src/spikeinterface/core/node_pipeline.py
index ceff8577d3..e72f87f794 100644
--- a/src/spikeinterface/core/node_pipeline.py
+++ b/src/spikeinterface/core/node_pipeline.py
@@ -103,6 +103,9 @@ def get_trace_margin(self):
     def get_dtype(self):
         return base_peak_dtype
 
+    def get_peak_slice(self, segment_index, start_frame, end_frame, ):
+        # not needed for PeakDetector
+        raise NotImplementedError
 
 # this is used in sorting components
 class PeakDetector(PeakSource):
@@ -127,11 +130,18 @@ def get_trace_margin(self):
     def get_dtype(self):
         return base_peak_dtype
 
-    def compute(self, traces, start_frame, end_frame, segment_index, max_margin):
-        # get local peaks
+    def get_peak_slice(self, segment_index, start_frame, end_frame, max_margin):
         sl = self.segment_slices[segment_index]
         peaks_in_segment = self.peaks[sl]
         i0, i1 = np.searchsorted(peaks_in_segment["sample_index"], [start_frame, end_frame])
+        return i0, i1
+
+    def compute(self, traces, start_frame, end_frame, segment_index, max_margin, peak_slice):
+        # get local peaks
+        sl = self.segment_slices[segment_index]
+        peaks_in_segment = self.peaks[sl]
+        # i0, i1 = np.searchsorted(peaks_in_segment["sample_index"], [start_frame, end_frame])
+        i0, i1 = peak_slice
         local_peaks = peaks_in_segment[i0:i1]
 
         # make sample index local to traces
@@ -212,8 +222,7 @@ def get_trace_margin(self):
     def get_dtype(self):
         return self._dtype
 
-    def compute(self, traces, start_frame, end_frame, segment_index, max_margin):
-        # get local peaks
+    def get_peak_slice(self, segment_index, start_frame, end_frame, max_margin):
         sl = self.segment_slices[segment_index]
         peaks_in_segment = self.peaks[sl]
         if self.include_spikes_in_margin:
@@ -222,6 +231,20 @@ def compute(self, traces, start_frame, end_frame, segment_index, max_margin):
             )
         else:
             i0, i1 = np.searchsorted(peaks_in_segment["sample_index"], [start_frame, end_frame])
+        return i0, i1
+
+    def compute(self, traces, start_frame, end_frame, segment_index, max_margin, peak_slice):
+        # get local peaks
+        sl = self.segment_slices[segment_index]
+        peaks_in_segment = self.peaks[sl]
+        # if self.include_spikes_in_margin:
+        #     i0, i1 = np.searchsorted(
+        #         peaks_in_segment["sample_index"], [start_frame - max_margin, end_frame + max_margin]
+        #     )
+        # else:
+        #     i0, i1 = np.searchsorted(peaks_in_segment["sample_index"], [start_frame, end_frame])
+        i0, i1 = peak_slice
+
         local_peaks = peaks_in_segment[i0:i1]
 
         # make sample index local to traces
@@ -525,64 +548,79 @@ def _compute_peak_pipeline_chunk(segment_index, start_frame, end_frame, worker_c
     nodes = worker_ctx["nodes"]
 
     recording_segment = recording._recording_segments[segment_index]
-    traces_chunk, left_margin, right_margin = get_chunk_with_margin(
-        recording_segment, start_frame, end_frame, None, max_margin, add_zeros=True
-    )
-
-    # compute the graph
-    pipeline_outputs = {}
-    for node in nodes:
-        node_parents = node.parents if node.parents else list()
-        node_input_args = tuple()
-        for parent in node_parents:
-            parent_output = pipeline_outputs[parent]
-            parent_outputs_tuple = parent_output if isinstance(parent_output, tuple) else (parent_output,)
-            node_input_args += parent_outputs_tuple
-        if isinstance(node, PeakDetector):
-            # to handle compatibility peak detector is a special case
-            # with specific margin
-            #  TODO later when in master: change this later
-            extra_margin = max_margin - node.get_trace_margin()
-            if extra_margin:
-                trace_detection = traces_chunk[extra_margin:-extra_margin]
+    node0 = nodes[0]
+    
+    if isinstance(node0, (SpikeRetriever, PeakRetriever)):
+        # in this case PeakSource could have no peaks and so no need to load traces just skip
+        peak_slice = i0, i1 = node0.get_peak_slice(segment_index, start_frame, end_frame, max_margin)
+        load_trace_and_compute = i0 < i1
+    else:
+        # PeakDetector always need traces
+        load_trace_and_compute = True
+    
+    if load_trace_and_compute:
+        traces_chunk, left_margin, right_margin = get_chunk_with_margin(
+            recording_segment, start_frame, end_frame, None, max_margin, add_zeros=True
+        )
+        # compute the graph
+        pipeline_outputs = {}
+        for node in nodes:
+            node_parents = node.parents if node.parents else list()
+            node_input_args = tuple()
+            for parent in node_parents:
+                parent_output = pipeline_outputs[parent]
+                parent_outputs_tuple = parent_output if isinstance(parent_output, tuple) else (parent_output,)
+                node_input_args += parent_outputs_tuple
+            if isinstance(node, PeakDetector):
+                # to handle compatibility peak detector is a special case
+                # with specific margin
+                #  TODO later when in master: change this later
+                extra_margin = max_margin - node.get_trace_margin()
+                if extra_margin:
+                    trace_detection = traces_chunk[extra_margin:-extra_margin]
+                else:
+                    trace_detection = traces_chunk
+                node_output = node.compute(trace_detection, start_frame, end_frame, segment_index, max_margin)
+                # set sample index to local
+                node_output[0]["sample_index"] += extra_margin
+            elif isinstance(node, PeakSource):
+                node_output = node.compute(traces_chunk, start_frame, end_frame, segment_index, max_margin, peak_slice)
             else:
-                trace_detection = traces_chunk
-            node_output = node.compute(trace_detection, start_frame, end_frame, segment_index, max_margin)
-            # set sample index to local
-            node_output[0]["sample_index"] += extra_margin
-        elif isinstance(node, PeakSource):
-            node_output = node.compute(traces_chunk, start_frame, end_frame, segment_index, max_margin)
-        else:
-            # TODO later when in master: change the signature of all nodes (or maybe not!)
-            node_output = node.compute(traces_chunk, *node_input_args)
-        pipeline_outputs[node] = node_output
-
-    # propagate the output
-    pipeline_outputs_tuple = tuple()
-    for node in nodes:
-        # handle which buffer are given to the output
-        # this is controlled by node.return_output being a bool or tuple of bool
-        out = pipeline_outputs[node]
-        if isinstance(out, tuple):
-            if isinstance(node.return_output, bool) and node.return_output:
-                pipeline_outputs_tuple += out
-            elif isinstance(node.return_output, tuple):
-                for flag, e in zip(node.return_output, out):
-                    if flag:
-                        pipeline_outputs_tuple += (e,)
-        else:
-            if isinstance(node.return_output, bool) and node.return_output:
-                pipeline_outputs_tuple += (out,)
-            elif isinstance(node.return_output, tuple):
-                # this should not apppend : maybe a checker somewhere before ?
-                pass
+                # TODO later when in master: change the signature of all nodes (or maybe not!)
+                node_output = node.compute(traces_chunk, *node_input_args)
+            pipeline_outputs[node] = node_output
+
+        # propagate the output
+        pipeline_outputs_tuple = tuple()
+        for node in nodes:
+            # handle which buffer are given to the output
+            # this is controlled by node.return_output being a bool or tuple of bool
+            out = pipeline_outputs[node]
+            if isinstance(out, tuple):
+                if isinstance(node.return_output, bool) and node.return_output:
+                    pipeline_outputs_tuple += out
+                elif isinstance(node.return_output, tuple):
+                    for flag, e in zip(node.return_output, out):
+                        if flag:
+                            pipeline_outputs_tuple += (e,)
+            else:
+                if isinstance(node.return_output, bool) and node.return_output:
+                    pipeline_outputs_tuple += (out,)
+                elif isinstance(node.return_output, tuple):
+                    # this should not apppend : maybe a checker somewhere before ?
+                    pass
+
+        if isinstance(nodes[0], PeakDetector):
+            # the first out element is the peak vector
+            # we need to go back to absolut sample index
+            pipeline_outputs_tuple[0]["sample_index"] += start_frame - left_margin
+
+        return pipeline_outputs_tuple
 
-    if isinstance(nodes[0], PeakDetector):
-        # the first out element is the peak vector
-        # we need to go back to absolut sample index
-        pipeline_outputs_tuple[0]["sample_index"] += start_frame - left_margin
+    else:
+        # the gather will skip this output and not concatenate it
+        return
 
-    return pipeline_outputs_tuple
 
 
 class GatherToMemory:
@@ -595,6 +633,9 @@ def __init__(self):
         self.tuple_mode = None
 
     def __call__(self, res):
+        if res is None:
+            return
+
         if self.tuple_mode is None:
             # first loop only
             self.tuple_mode = isinstance(res, tuple)
@@ -655,6 +696,9 @@ def __init__(self, folder, names, npy_header_size=1024, exist_ok=False):
             self.final_shapes.append(None)
 
     def __call__(self, res):
+        if res is None:
+            return
+
         if self.tuple_mode is None:
             # first loop only
             self.tuple_mode = isinstance(res, tuple)
diff --git a/src/spikeinterface/core/tests/test_node_pipeline.py b/src/spikeinterface/core/tests/test_node_pipeline.py
index 8d788acbad..a2919f5673 100644
--- a/src/spikeinterface/core/tests/test_node_pipeline.py
+++ b/src/spikeinterface/core/tests/test_node_pipeline.py
@@ -83,8 +83,12 @@ def test_run_node_pipeline(cache_folder_creation):
     extremum_channel_inds = get_template_extremum_channel(sorting_analyzer, peak_sign="neg", outputs="index")
 
     peaks = sorting_to_peaks(sorting, extremum_channel_inds, spike_peak_dtype)
+    print(peaks.size)
 
     peak_retriever = PeakRetriever(recording, peaks)
+    # this test when no spikes in last chunks
+    peak_retriever_few = PeakRetriever(recording, peaks[:peaks.size//2])
+
     # channel index is from template
     spike_retriever_T = SpikeRetriever(
         sorting, recording, channel_from_template=True, extremum_channel_inds=extremum_channel_inds
@@ -100,7 +104,7 @@ def test_run_node_pipeline(cache_folder_creation):
     )
 
     # test with 3 differents first nodes
-    for loop, peak_source in enumerate((peak_retriever, spike_retriever_T, spike_retriever_S)):
+    for loop, peak_source in enumerate((peak_retriever, peak_retriever_few, spike_retriever_T, spike_retriever_S)):
         # one step only : squeeze output
         nodes = [
             peak_source,
@@ -139,10 +143,12 @@ def test_run_node_pipeline(cache_folder_creation):
 
         num_peaks = peaks.shape[0]
         num_channels = recording.get_num_channels()
-        assert waveforms_rms.shape[0] == num_peaks
+        if peak_source != peak_retriever_few:
+            assert waveforms_rms.shape[0] == num_peaks
         assert waveforms_rms.shape[1] == num_channels
 
-        assert waveforms_rms.shape[0] == num_peaks
+        if peak_source != peak_retriever_few:
+            assert waveforms_rms.shape[0] == num_peaks
         assert waveforms_rms.shape[1] == num_channels
 
         # gather npy mode
@@ -186,4 +192,5 @@ def test_run_node_pipeline(cache_folder_creation):
 
 
 if __name__ == "__main__":
-    test_run_node_pipeline()
+    folder = Path("./cache_folder/core")
+    test_run_node_pipeline(folder)

From 36474a8cea03c9905dd21931af2c9de418d37798 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Mon, 2 Sep 2024 17:36:23 +0200
Subject: [PATCH 002/344] Refactor the get_random_data_chunks with an internal
 function. to allow more methods

---
 src/spikeinterface/core/job_tools.py          |  28 +--
 src/spikeinterface/core/recording_tools.py    | 163 ++++++++++++++----
 .../core/tests/test_recording_tools.py        |  16 +-
 3 files changed, 154 insertions(+), 53 deletions(-)

diff --git a/src/spikeinterface/core/job_tools.py b/src/spikeinterface/core/job_tools.py
index a5279247f5..1aa9ac9333 100644
--- a/src/spikeinterface/core/job_tools.py
+++ b/src/spikeinterface/core/job_tools.py
@@ -187,6 +187,21 @@ def ensure_n_jobs(recording, n_jobs=1):
 
     return n_jobs
 
+def chunk_duration_to_chunk_size(chunk_duration, recording):
+    if isinstance(chunk_duration, float):
+        chunk_size = int(chunk_duration * recording.get_sampling_frequency())
+    elif isinstance(chunk_duration, str):
+        if chunk_duration.endswith("ms"):
+            chunk_duration = float(chunk_duration.replace("ms", "")) / 1000.0
+        elif chunk_duration.endswith("s"):
+            chunk_duration = float(chunk_duration.replace("s", ""))
+        else:
+            raise ValueError("chunk_duration must ends with s or ms")
+        chunk_size = int(chunk_duration * recording.get_sampling_frequency())
+    else:
+        raise ValueError("chunk_duration must be str or float")    
+    return chunk_size
+
 
 def ensure_chunk_size(
     recording, total_memory=None, chunk_size=None, chunk_memory=None, chunk_duration=None, n_jobs=1, **other_kwargs
@@ -234,18 +249,7 @@ def ensure_chunk_size(
         num_channels = recording.get_num_channels()
         chunk_size = int(total_memory / (num_channels * n_bytes * n_jobs))
     elif chunk_duration is not None:
-        if isinstance(chunk_duration, float):
-            chunk_size = int(chunk_duration * recording.get_sampling_frequency())
-        elif isinstance(chunk_duration, str):
-            if chunk_duration.endswith("ms"):
-                chunk_duration = float(chunk_duration.replace("ms", "")) / 1000.0
-            elif chunk_duration.endswith("s"):
-                chunk_duration = float(chunk_duration.replace("s", ""))
-            else:
-                raise ValueError("chunk_duration must ends with s or ms")
-            chunk_size = int(chunk_duration * recording.get_sampling_frequency())
-        else:
-            raise ValueError("chunk_duration must be str or float")
+        chunk_size = chunk_duration_to_chunk_size(chunk_duration, recording)
     else:
         # Edge case to define single chunk per segment for n_jobs=1.
         # All chunking parameters equal None mean single chunk per segment
diff --git a/src/spikeinterface/core/recording_tools.py b/src/spikeinterface/core/recording_tools.py
index 2c7e75668f..764b6f0c66 100644
--- a/src/spikeinterface/core/recording_tools.py
+++ b/src/spikeinterface/core/recording_tools.py
@@ -18,6 +18,7 @@
     fix_job_kwargs,
     ChunkRecordingExecutor,
     _shared_job_kwargs_doc,
+    chunk_duration_to_chunk_size,
 )
 
 
@@ -509,6 +510,87 @@ def determine_cast_unsigned(recording, dtype):
     return cast_unsigned
 
 
+
+
+def get_random_recording_slices(recording,
+                                method="legacy",
+                                num_chunks_per_segment=20,
+                                chunk_duration="500ms",
+                                chunk_size=None,
+                                margin_frames=0,
+                                seed=None):
+    """
+    Get random slice of a recording across segments.
+
+    This is used for instance in get_noise_levels() and get_random_data_chunks() to estimate noise on traces.
+
+    Parameters
+    ----------
+    recording : BaseRecording
+        The recording to get random chunks from
+    methid : "legacy"
+        The method used.
+    num_chunks_per_segment : int, default: 20
+        Number of chunks per segment
+    chunk_duration : str | float | None, default "500ms"
+        The duration of each chunk in 's' or 'ms'
+    chunk_size : int | None
+        Size of a chunk in number of frames
+    
+    concatenated : bool, default: True
+        If True chunk are concatenated along time axis
+    seed : int, default: 0
+        Random seed
+    margin_frames : int, default: 0
+        Margin in number of frames to avoid edge effects
+
+    Returns
+    -------
+    chunk_list : np.array
+        Array of concatenate chunks per segment
+
+
+    """
+    # TODO: if segment have differents length make another sampling that dependant on the length of the segment
+    # Should be done by changing kwargs with total_num_chunks=XXX and total_duration=YYYY
+    # And randomize the number of chunk per segment weighted by segment duration
+
+    if method == "legacy":
+        if chunk_size is None:
+            if chunk_duration is not None:
+                chunk_size = chunk_duration_to_chunk_size(chunk_duration, recording)
+            else:
+                raise ValueError("get_random_recording_slices need chunk_size or chunk_duration")
+
+        # check chunk size
+        num_segments = recording.get_num_segments()
+        for segment_index in range(num_segments):
+            chunk_size_limit = recording.get_num_frames(segment_index) - 2 * margin_frames
+            if chunk_size > chunk_size_limit:
+                chunk_size = chunk_size_limit - 1
+                warnings.warn(
+                    f"chunk_size is greater than the number "
+                    f"of samples for segment index {segment_index}. "
+                    f"Using {chunk_size}."
+                )
+        rng = np.random.default_rng(seed)
+        recording_slices = []
+        low = margin_frames
+        size = num_chunks_per_segment
+        for segment_index in range(num_segments):
+            num_frames = recording.get_num_frames(segment_index)
+            high = num_frames - chunk_size - margin_frames
+            random_starts = rng.integers(low=low, high=high, size=size)
+            random_starts = np.sort(random_starts)
+            recording_slices += [
+                (segment_index, start_frame, (start_frame + chunk_size)) for start_frame in random_starts
+            ]
+    else:
+        raise ValueError(f"get_random_recording_slices : wrong method {method}")
+    
+    return recording_slices
+
+
 def get_random_data_chunks(
     recording,
     return_scaled=False,
@@ -545,41 +627,56 @@ def get_random_data_chunks(
     chunk_list : np.array
         Array of concatenate chunks per segment
     """
-    # TODO: if segment have differents length make another sampling that dependant on the length of the segment
-    # Should be done by changing kwargs with total_num_chunks=XXX and total_duration=YYYY
-    # And randomize the number of chunk per segment weighted by segment duration
-
-    # check chunk size
-    num_segments = recording.get_num_segments()
-    for segment_index in range(num_segments):
-        chunk_size_limit = recording.get_num_frames(segment_index) - 2 * margin_frames
-        if chunk_size > chunk_size_limit:
-            chunk_size = chunk_size_limit - 1
-            warnings.warn(
-                f"chunk_size is greater than the number "
-                f"of samples for segment index {segment_index}. "
-                f"Using {chunk_size}."
-            )
+    # # check chunk size
+    # num_segments = recording.get_num_segments()
+    # for segment_index in range(num_segments):
+    #     chunk_size_limit = recording.get_num_frames(segment_index) - 2 * margin_frames
+    #     if chunk_size > chunk_size_limit:
+    #         chunk_size = chunk_size_limit - 1
+    #         warnings.warn(
+    #             f"chunk_size is greater than the number "
+    #             f"of samples for segment index {segment_index}. "
+    #             f"Using {chunk_size}."
+    #         )
+
+    # rng = np.random.default_rng(seed)
+    # chunk_list = []
+    # low = margin_frames
+    # size = num_chunks_per_segment
+    # for segment_index in range(num_segments):
+    #     num_frames = recording.get_num_frames(segment_index)
+    #     high = num_frames - chunk_size - margin_frames
+    #     random_starts = rng.integers(low=low, high=high, size=size)
+    #     segment_trace_chunk = [
+    #         recording.get_traces(
+    #             start_frame=start_frame,
+    #             end_frame=(start_frame + chunk_size),
+    #             segment_index=segment_index,
+    #             return_scaled=return_scaled,
+    #         )
+    #         for start_frame in random_starts
+    #     ]
+
+    #     chunk_list.extend(segment_trace_chunk)
+
+    recording_slices = get_random_recording_slices(recording,
+                                method="legacy",
+                                num_chunks_per_segment=num_chunks_per_segment,
+                                chunk_size=chunk_size,
+                                # chunk_duration=chunk_duration,
+                                margin_frames=margin_frames,
+                                seed=seed)
+    print(recording_slices)
 
-    rng = np.random.default_rng(seed)
     chunk_list = []
-    low = margin_frames
-    size = num_chunks_per_segment
-    for segment_index in range(num_segments):
-        num_frames = recording.get_num_frames(segment_index)
-        high = num_frames - chunk_size - margin_frames
-        random_starts = rng.integers(low=low, high=high, size=size)
-        segment_trace_chunk = [
-            recording.get_traces(
-                start_frame=start_frame,
-                end_frame=(start_frame + chunk_size),
-                segment_index=segment_index,
-                return_scaled=return_scaled,
-            )
-            for start_frame in random_starts
-        ]
-
-        chunk_list.extend(segment_trace_chunk)
+    for segment_index, start_frame, stop_frame in recording_slices:
+        traces_chunk = recording.get_traces(
+            start_frame=start_frame,
+            end_frame=(start_frame + chunk_size),
+            segment_index=segment_index,
+            return_scaled=return_scaled,
+        )
+        chunk_list.append(traces_chunk)
 
     if concatenated:
         return np.concatenate(chunk_list, axis=0)
diff --git a/src/spikeinterface/core/tests/test_recording_tools.py b/src/spikeinterface/core/tests/test_recording_tools.py
index 23a1574f2a..e54981744d 100644
--- a/src/spikeinterface/core/tests/test_recording_tools.py
+++ b/src/spikeinterface/core/tests/test_recording_tools.py
@@ -333,14 +333,14 @@ def test_do_recording_attributes_match():
 
 if __name__ == "__main__":
     # Create a temporary folder using the standard library
-    import tempfile
+    # import tempfile
 
-    with tempfile.TemporaryDirectory() as tmpdirname:
-        tmp_path = Path(tmpdirname)
-        test_write_binary_recording(tmp_path)
-    test_write_memory_recording()
+    # with tempfile.TemporaryDirectory() as tmpdirname:
+    #     tmp_path = Path(tmpdirname)
+    #     test_write_binary_recording(tmp_path)
+    # test_write_memory_recording()
 
     test_get_random_data_chunks()
-    test_get_closest_channels()
-    test_get_noise_levels()
-    test_order_channels_by_depth()
+    # test_get_closest_channels()
+    # test_get_noise_levels()
+    # test_order_channels_by_depth()

From 63574ef6a45b948f228bae94dbf090a6486279e7 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Tue, 3 Sep 2024 17:08:10 +0200
Subject: [PATCH 003/344] Noise level in parallel

---
 src/spikeinterface/core/job_tools.py          |  6 +-
 src/spikeinterface/core/recording_tools.py    | 71 ++++++++++++++++---
 .../core/tests/test_recording_tools.py        | 21 +++---
 3 files changed, 78 insertions(+), 20 deletions(-)

diff --git a/src/spikeinterface/core/job_tools.py b/src/spikeinterface/core/job_tools.py
index 1aa9ac9333..45d04e83df 100644
--- a/src/spikeinterface/core/job_tools.py
+++ b/src/spikeinterface/core/job_tools.py
@@ -389,11 +389,13 @@ def __init__(
                 f"chunk_duration={chunk_duration_str}",
             )
 
-    def run(self):
+    def run(self, all_chunks=None):
         """
         Runs the defined jobs.
         """
-        all_chunks = divide_recording_into_chunks(self.recording, self.chunk_size)
+
+        if all_chunks is None:
+            all_chunks = divide_recording_into_chunks(self.recording, self.chunk_size)
 
         if self.handle_returns:
             returns = []
diff --git a/src/spikeinterface/core/recording_tools.py b/src/spikeinterface/core/recording_tools.py
index 764b6f0c66..37fcd9714a 100644
--- a/src/spikeinterface/core/recording_tools.py
+++ b/src/spikeinterface/core/recording_tools.py
@@ -19,6 +19,7 @@
     ChunkRecordingExecutor,
     _shared_job_kwargs_doc,
     chunk_duration_to_chunk_size,
+    split_job_kwargs,
 )
 
 
@@ -666,7 +667,6 @@ def get_random_data_chunks(
                                 # chunk_duration=chunk_duration,
                                 margin_frames=margin_frames,
                                 seed=seed)
-    print(recording_slices)
 
     chunk_list = []
     for segment_index, start_frame, stop_frame in recording_slices:
@@ -731,12 +731,42 @@ def get_closest_channels(recording, channel_ids=None, num_channels=None):
     return np.array(closest_channels_inds), np.array(dists)
 
 
+def _noise_level_chunk(segment_index, start_frame, end_frame, worker_ctx):
+    recording = worker_ctx["recording"]
+    
+    one_chunk = recording.get_traces(
+        start_frame=start_frame,
+        end_frame=end_frame,
+        segment_index=segment_index,
+        return_scaled=worker_ctx["return_scaled"],
+    )
+
+
+    if worker_ctx["method"] == "mad":
+        med = np.median(one_chunk, axis=0, keepdims=True)
+        # hard-coded so that core doesn't depend on scipy
+        noise_levels = np.median(np.abs(one_chunk - med), axis=0) / 0.6744897501960817
+    elif worker_ctx["method"] == "std":
+        noise_levels = np.std(one_chunk, axis=0)
+
+    return noise_levels
+
+
+def _noise_level_chunk_init(recording, return_scaled, method):
+    worker_ctx = {}
+    worker_ctx["recording"] = recording
+    worker_ctx["return_scaled"] = return_scaled
+    worker_ctx["method"] = method
+    return worker_ctx
+
 def get_noise_levels(
     recording: "BaseRecording",
     return_scaled: bool = True,
     method: Literal["mad", "std"] = "mad",
     force_recompute: bool = False,
-    **random_chunk_kwargs,
+    **kwargs,
+    # **random_chunk_kwargs,
+    # **job_kwargs
 ):
     """
     Estimate noise for each channel using MAD methods.
@@ -773,19 +803,40 @@ def get_noise_levels(
     if key in recording.get_property_keys() and not force_recompute:
         noise_levels = recording.get_property(key=key)
     else:
-        random_chunks = get_random_data_chunks(recording, return_scaled=return_scaled, **random_chunk_kwargs)
-
-        if method == "mad":
-            med = np.median(random_chunks, axis=0, keepdims=True)
-            # hard-coded so that core doesn't depend on scipy
-            noise_levels = np.median(np.abs(random_chunks - med), axis=0) / 0.6744897501960817
-        elif method == "std":
-            noise_levels = np.std(random_chunks, axis=0)
+        # random_chunks = get_random_data_chunks(recording, return_scaled=return_scaled, **random_chunk_kwargs)
+
+        # if method == "mad":
+        #     med = np.median(random_chunks, axis=0, keepdims=True)
+        #     # hard-coded so that core doesn't depend on scipy
+        #     noise_levels = np.median(np.abs(random_chunks - med), axis=0) / 0.6744897501960817
+        # elif method == "std":
+        #     noise_levels = np.std(random_chunks, axis=0)
+
+        random_slices_kwargs, job_kwargs = split_job_kwargs(kwargs)
+        recording_slices = get_random_recording_slices(recording,**random_slices_kwargs)
+
+        noise_levels_chunks = []
+        def append_noise_chunk(res):
+            noise_levels_chunks.append(res)
+
+        func = _noise_level_chunk
+        init_func = _noise_level_chunk_init
+        init_args = (recording, return_scaled, method)
+        executor = ChunkRecordingExecutor(
+            recording, func, init_func, init_args, job_name="noise_level", verbose=False,
+            gather_func=append_noise_chunk, **job_kwargs
+        )
+        executor.run(all_chunks=recording_slices)
+        noise_levels_chunks = np.stack(noise_levels_chunks)
+        noise_levels = np.mean(noise_levels_chunks, axis=0)
+
+        # set property
         recording.set_property(key, noise_levels)
 
     return noise_levels
 
 
+
 def get_chunk_with_margin(
     rec_segment,
     start_frame,
diff --git a/src/spikeinterface/core/tests/test_recording_tools.py b/src/spikeinterface/core/tests/test_recording_tools.py
index e54981744d..918e15803a 100644
--- a/src/spikeinterface/core/tests/test_recording_tools.py
+++ b/src/spikeinterface/core/tests/test_recording_tools.py
@@ -166,6 +166,9 @@ def test_write_memory_recording():
     for shm in shms:
         shm.unlink()
 
+def test_get_random_recording_slices():
+    # TODO
+    pass
 
 def test_get_random_data_chunks():
     rec = generate_recording(num_channels=1, sampling_frequency=1000.0, durations=[10.0, 20.0])
@@ -182,16 +185,17 @@ def test_get_closest_channels():
 
 
 def test_get_noise_levels():
+    job_kwargs = dict(n_jobs=1, progress_bar=True)
     rec = generate_recording(num_channels=2, sampling_frequency=1000.0, durations=[60.0])
 
-    noise_levels_1 = get_noise_levels(rec, return_scaled=False)
-    noise_levels_2 = get_noise_levels(rec, return_scaled=False)
+    noise_levels_1 = get_noise_levels(rec, return_scaled=False, **job_kwargs)
+    noise_levels_2 = get_noise_levels(rec, return_scaled=False, **job_kwargs)
 
     rec.set_channel_gains(0.1)
     rec.set_channel_offsets(0)
-    noise_levels = get_noise_levels(rec, return_scaled=True, force_recompute=True)
+    noise_levels = get_noise_levels(rec, return_scaled=True, force_recompute=True, **job_kwargs)
 
-    noise_levels = get_noise_levels(rec, return_scaled=True, method="std")
+    noise_levels = get_noise_levels(rec, return_scaled=True, method="std", **job_kwargs)
 
     # Generate a recording following a gaussian distribution to check the result of get_noise.
     std = 6.0
@@ -201,8 +205,8 @@ def test_get_noise_levels():
     recording = NumpyRecording(traces, 30000)
 
     assert np.all(noise_levels_1 == noise_levels_2)
-    assert np.allclose(get_noise_levels(recording, return_scaled=False), [std, std], rtol=1e-2, atol=1e-3)
-    assert np.allclose(get_noise_levels(recording, method="std", return_scaled=False), [std, std], rtol=1e-2, atol=1e-3)
+    assert np.allclose(get_noise_levels(recording, return_scaled=False, **job_kwargs), [std, std], rtol=1e-2, atol=1e-3)
+    assert np.allclose(get_noise_levels(recording, method="std", return_scaled=False, **job_kwargs), [std, std], rtol=1e-2, atol=1e-3)
 
 
 def test_get_noise_levels_output():
@@ -340,7 +344,8 @@ def test_do_recording_attributes_match():
     #     test_write_binary_recording(tmp_path)
     # test_write_memory_recording()
 
-    test_get_random_data_chunks()
+    # test_get_random_recording_slices()
+    # test_get_random_data_chunks()
     # test_get_closest_channels()
-    # test_get_noise_levels()
+    test_get_noise_levels()
     # test_order_channels_by_depth()

From 6590e0f1845a62300d617d3896969ec303bebc46 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Fri, 6 Sep 2024 14:24:16 +0200
Subject: [PATCH 004/344] nodepipeline add skip_after_n_peaks option

---
 src/spikeinterface/core/node_pipeline.py      | 22 +++++++++--
 .../core/tests/test_node_pipeline.py          | 37 +++++++++++++++++--
 2 files changed, 53 insertions(+), 6 deletions(-)

diff --git a/src/spikeinterface/core/node_pipeline.py b/src/spikeinterface/core/node_pipeline.py
index e72f87f794..d04ad59f46 100644
--- a/src/spikeinterface/core/node_pipeline.py
+++ b/src/spikeinterface/core/node_pipeline.py
@@ -497,6 +497,7 @@ def run_node_pipeline(
     folder=None,
     names=None,
     verbose=False,
+    skip_after_n_peaks=None,
 ):
     """
     Common function to run pipeline with peak detector or already detected peak.
@@ -507,6 +508,11 @@ def run_node_pipeline(
     job_kwargs = fix_job_kwargs(job_kwargs)
     assert all(isinstance(node, PipelineNode) for node in nodes)
 
+    if skip_after_n_peaks is not None:
+        skip_after_n_peaks_per_worker = skip_after_n_peaks / job_kwargs["n_jobs"]
+    else:
+        skip_after_n_peaks_per_worker = None
+
     if gather_mode == "memory":
         gather_func = GatherToMemory()
     elif gather_mode == "npy":
@@ -514,7 +520,7 @@ def run_node_pipeline(
     else:
         raise ValueError(f"wrong gather_mode : {gather_mode}")
 
-    init_args = (recording, nodes)
+    init_args = (recording, nodes, skip_after_n_peaks_per_worker)
 
     processor = ChunkRecordingExecutor(
         recording,
@@ -533,12 +539,14 @@ def run_node_pipeline(
     return outs
 
 
-def _init_peak_pipeline(recording, nodes):
+def _init_peak_pipeline(recording, nodes, skip_after_n_peaks_per_worker):
     # create a local dict per worker
     worker_ctx = {}
     worker_ctx["recording"] = recording
     worker_ctx["nodes"] = nodes
     worker_ctx["max_margin"] = max(node.get_trace_margin() for node in nodes)
+    worker_ctx["skip_after_n_peaks_per_worker"] = skip_after_n_peaks_per_worker
+    worker_ctx["num_peaks"] = 0
     return worker_ctx
 
 
@@ -546,6 +554,7 @@ def _compute_peak_pipeline_chunk(segment_index, start_frame, end_frame, worker_c
     recording = worker_ctx["recording"]
     max_margin = worker_ctx["max_margin"]
     nodes = worker_ctx["nodes"]
+    skip_after_n_peaks_per_worker = worker_ctx["skip_after_n_peaks_per_worker"]
 
     recording_segment = recording._recording_segments[segment_index]
     node0 = nodes[0]
@@ -557,7 +566,11 @@ def _compute_peak_pipeline_chunk(segment_index, start_frame, end_frame, worker_c
     else:
         # PeakDetector always need traces
         load_trace_and_compute = True
-    
+
+    if skip_after_n_peaks_per_worker is not None:
+        if worker_ctx["num_peaks"] > skip_after_n_peaks_per_worker:
+            load_trace_and_compute = False
+
     if load_trace_and_compute:
         traces_chunk, left_margin, right_margin = get_chunk_with_margin(
             recording_segment, start_frame, end_frame, None, max_margin, add_zeros=True
@@ -590,6 +603,9 @@ def _compute_peak_pipeline_chunk(segment_index, start_frame, end_frame, worker_c
                 node_output = node.compute(traces_chunk, *node_input_args)
             pipeline_outputs[node] = node_output
 
+            if skip_after_n_peaks_per_worker is not None and isinstance(node, PeakSource):
+                worker_ctx["num_peaks"] += node_output[0].size
+
         # propagate the output
         pipeline_outputs_tuple = tuple()
         for node in nodes:
diff --git a/src/spikeinterface/core/tests/test_node_pipeline.py b/src/spikeinterface/core/tests/test_node_pipeline.py
index a2919f5673..f31757d6bc 100644
--- a/src/spikeinterface/core/tests/test_node_pipeline.py
+++ b/src/spikeinterface/core/tests/test_node_pipeline.py
@@ -83,7 +83,7 @@ def test_run_node_pipeline(cache_folder_creation):
     extremum_channel_inds = get_template_extremum_channel(sorting_analyzer, peak_sign="neg", outputs="index")
 
     peaks = sorting_to_peaks(sorting, extremum_channel_inds, spike_peak_dtype)
-    print(peaks.size)
+    # print(peaks.size)
 
     peak_retriever = PeakRetriever(recording, peaks)
     # this test when no spikes in last chunks
@@ -191,6 +191,37 @@ def test_run_node_pipeline(cache_folder_creation):
             unpickled_node = pickle.loads(pickled_node)
 
 
+def test_skip_after_n_peaks():
+    recording, sorting = generate_ground_truth_recording(num_channels=10, num_units=10, durations=[10.0])
+
+    # job_kwargs = dict(chunk_duration="0.5s", n_jobs=2, progress_bar=False)
+    job_kwargs = dict(chunk_duration="0.5s", n_jobs=1, progress_bar=False)
+
+    spikes = sorting.to_spike_vector()
+
+    # create peaks from spikes
+    sorting_analyzer = create_sorting_analyzer(sorting, recording, format="memory")
+    sorting_analyzer.compute(["random_spikes", "templates"], **job_kwargs)
+    extremum_channel_inds = get_template_extremum_channel(sorting_analyzer, peak_sign="neg", outputs="index")
+
+    peaks = sorting_to_peaks(sorting, extremum_channel_inds, spike_peak_dtype)
+    # print(peaks.size)
+
+    node0 = PeakRetriever(recording, peaks)
+    node1 = AmplitudeExtractionNode(recording, parents=[node0], param0=6.6, return_output=True)
+    nodes = [node0, node1]
+
+    skip_after_n_peaks = 30
+    some_amplitudes = run_node_pipeline(recording, nodes, job_kwargs, gather_mode="memory", skip_after_n_peaks=skip_after_n_peaks)
+
+    assert some_amplitudes.size >= skip_after_n_peaks
+    assert some_amplitudes.size < spikes.size
+
+
+
+
 if __name__ == "__main__":
-    folder = Path("./cache_folder/core")
-    test_run_node_pipeline(folder)
+    # folder = Path("./cache_folder/core")
+    # test_run_node_pipeline(folder)
+
+    test_skip_after_n_peaks()

From 9111c13f1994afc6a970353424015ae8be465d2a Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Fri, 6 Sep 2024 14:48:20 +0200
Subject: [PATCH 005/344] make Zach happy

---
 src/spikeinterface/core/node_pipeline.py | 78 ++++++++++++++++++------
 1 file changed, 58 insertions(+), 20 deletions(-)

diff --git a/src/spikeinterface/core/node_pipeline.py b/src/spikeinterface/core/node_pipeline.py
index d04ad59f46..9b53f08520 100644
--- a/src/spikeinterface/core/node_pipeline.py
+++ b/src/spikeinterface/core/node_pipeline.py
@@ -1,22 +1,6 @@
 """
-Pipeline on spikes/peaks/detected peaks
-
-Functions that can be chained:
-  * after peak detection
-  * already detected peaks
-  * spikes (labeled peaks)
-to compute some additional features on-the-fly:
-  * peak localization
-  * peak-to-peak
-  * pca
-  * amplitude
-  * amplitude scaling
-  * ...
-
-There are two ways for using theses "plugin nodes":
-  * during `peak_detect()`
-  * when peaks are already detected and reduced with `select_peaks()`
-  * on a sorting object
+
+
 """
 
 from __future__ import annotations
@@ -490,7 +474,7 @@ def run_node_pipeline(
     nodes,
     job_kwargs,
     job_name="pipeline",
-    mp_context=None,
+    #mp_context=None,
     gather_mode="memory",
     gather_kwargs={},
     squeeze_output=True,
@@ -500,7 +484,61 @@ def run_node_pipeline(
     skip_after_n_peaks=None,
 ):
     """
-    Common function to run pipeline with peak detector or already detected peak.
+    Machinery to compute in paralell operations on peaks and traces.
+
+    This usefull in several use cases:
+    * in sortingcomponents : detect peaks and make some computation on then (localize, pca, ...)
+    * in sortingcomponents : replay some peaks and make some computation on then (localize, pca, ...)
+    * postprocessing : replay some spikes and make some computation on then (localize, pca, ...)
+
+    Here a "peak" is a spike without any labels just a "detected".
+    Here a "spike" is a spike with any a label so already sorted.
+
+    The main idea is to have a graph of nodes.
+    Every node is doing a computaion of some peaks and related traces.
+    The first node is PeakSource so either a peak detector PeakDetector or peak/spike replay (PeakRetriever/SpikeRetriever)
+
+    Every can have one or several output that can be directed to other nodes (aka nodes have parents).
+
+    Every node can optionaly have an global output that will be globaly gather by the main process.
+    This is controlled by return_output = True.
+
+    The gather consists of concatenating features related to peaks (localization, pca, scaling, ...) into a single big vector.
+    Theses vector can be in "memory" or in file ("npy")
+
+    
+    Parameters
+    ----------
+
+    recording: Recording
+
+    nodes: a list of PipelineNode
+
+    job_kwargs: dict
+        The classical job_kwargs
+    job_name : str
+        The name of the pipeline used for the progress_bar
+    gather_mode : "memory" | "npz"
+
+    gather_kwargs : dict
+        OPtions to control the "gather engine". See GatherToMemory or GatherToNpy.
+    squeeze_output : bool, default True
+        If only one output node, the, squeeze the tuple
+    folder : str | Path | None
+        Used for gather_mode="npz"
+    names : list of str
+        Names of outputs.
+    verbose : bool, default False
+        Verbosity.
+    skip_after_n_peaks : None | int
+        Skip the computaion after n_peaks.
+        This is not an exact because internally this skip is done per worker in average.
+    
+    Returns
+    -------
+    outputs: tuple of np.array | np.array
+        a tuple of vector for the output of nodes having return_output=True.
+        If squeeze_output=True and only one output then directly np.array.
     """
 
     check_graph(nodes)

From 1f527153dc909f93e25bb85c178579d56c624913 Mon Sep 17 00:00:00 2001
From: Garcia Samuel <sam.garcia.die@gmail.com>
Date: Mon, 9 Sep 2024 10:25:16 +0200
Subject: [PATCH 006/344] Merci Zach

Co-authored-by: Zach McKenzie <92116279+zm711@users.noreply.github.com>
---
 src/spikeinterface/core/node_pipeline.py           | 14 +++++++-------
 .../core/tests/test_node_pipeline.py               |  2 +-
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/src/spikeinterface/core/node_pipeline.py b/src/spikeinterface/core/node_pipeline.py
index 9b53f08520..a617272753 100644
--- a/src/spikeinterface/core/node_pipeline.py
+++ b/src/spikeinterface/core/node_pipeline.py
@@ -484,9 +484,9 @@ def run_node_pipeline(
     skip_after_n_peaks=None,
 ):
     """
-    Machinery to compute in paralell operations on peaks and traces.
+    Machinery to compute in parallel operations on peaks and traces.
 
-    This usefull in several use cases:
+    This useful in several use cases:
     * in sortingcomponents : detect peaks and make some computation on then (localize, pca, ...)
     * in sortingcomponents : replay some peaks and make some computation on then (localize, pca, ...)
     * postprocessing : replay some spikes and make some computation on then (localize, pca, ...)
@@ -498,13 +498,13 @@ def run_node_pipeline(
     Every node is doing a computaion of some peaks and related traces.
     The first node is PeakSource so either a peak detector PeakDetector or peak/spike replay (PeakRetriever/SpikeRetriever)
 
-    Every can have one or several output that can be directed to other nodes (aka nodes have parents).
+    Every node can have one or several output that can be directed to other nodes (aka nodes have parents).
 
-    Every node can optionaly have an global output that will be globaly gather by the main process.
+    Every node can optionally have a global output that will be gathered by the main process.
     This is controlled by return_output = True.
 
     The gather consists of concatenating features related to peaks (localization, pca, scaling, ...) into a single big vector.
-    Theses vector can be in "memory" or in file ("npy")
+    These vectors can be in "memory" or in files ("npy")
 
     
     Parameters
@@ -523,7 +523,7 @@ def run_node_pipeline(
     gather_kwargs : dict
         OPtions to control the "gather engine". See GatherToMemory or GatherToNpy.
     squeeze_output : bool, default True
-        If only one output node, the, squeeze the tuple
+        If only one output node then squeeze the tuple
     folder : str | Path | None
         Used for gather_mode="npz"
     names : list of str
@@ -531,7 +531,7 @@ def run_node_pipeline(
     verbose : bool, default False
         Verbosity.
     skip_after_n_peaks : None | int
-        Skip the computaion after n_peaks.
+        Skip the computation after n_peaks.
         This is not an exact because internally this skip is done per worker in average.
     
     Returns
diff --git a/src/spikeinterface/core/tests/test_node_pipeline.py b/src/spikeinterface/core/tests/test_node_pipeline.py
index f31757d6bc..3d3a642371 100644
--- a/src/spikeinterface/core/tests/test_node_pipeline.py
+++ b/src/spikeinterface/core/tests/test_node_pipeline.py
@@ -219,7 +219,7 @@ def test_skip_after_n_peaks():
 
 
 
-
+# the following is for testing locally with python or ipython. It is not used in ci or with pytest.
 if __name__ == "__main__":
     # folder = Path("./cache_folder/core")
     # test_run_node_pipeline(folder)

From 9f13c74694e75de1ca81ed7f5edb4642d7bce610 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 11 Sep 2024 17:45:57 +0200
Subject: [PATCH 007/344] Start a new module for benchmark. Implement
 SorterStudy that replace GroundTruthStudy

---
 src/spikeinterface/benchmark/__init__.py      |   7 +
 .../benchmark/benchmark_base.py               | 465 +++++++++++++++++
 .../benchmark/benchmark_plot_tools.py         |   9 +
 .../benchmark/benchmark_sorter.py             | 125 +++++
 .../benchmark/tests/test_benchmark_sorter.py  |  90 ++++
 .../comparison/groundtruthstudy.py            | 447 +----------------
 .../benchmark/benchmark_tools.py              | 473 +-----------------
 7 files changed, 712 insertions(+), 904 deletions(-)
 create mode 100644 src/spikeinterface/benchmark/__init__.py
 create mode 100644 src/spikeinterface/benchmark/benchmark_base.py
 create mode 100644 src/spikeinterface/benchmark/benchmark_plot_tools.py
 create mode 100644 src/spikeinterface/benchmark/benchmark_sorter.py
 create mode 100644 src/spikeinterface/benchmark/tests/test_benchmark_sorter.py

diff --git a/src/spikeinterface/benchmark/__init__.py b/src/spikeinterface/benchmark/__init__.py
new file mode 100644
index 0000000000..951a865ff9
--- /dev/null
+++ b/src/spikeinterface/benchmark/__init__.py
@@ -0,0 +1,7 @@
+"""
+Module to benchmark:
+  * sorters
+  * some sorting components (clustering, motion, template matching)
+"""
+
+from .benchmark_sorter import SorterStudy
\ No newline at end of file
diff --git a/src/spikeinterface/benchmark/benchmark_base.py b/src/spikeinterface/benchmark/benchmark_base.py
new file mode 100644
index 0000000000..2dfe2b3448
--- /dev/null
+++ b/src/spikeinterface/benchmark/benchmark_base.py
@@ -0,0 +1,465 @@
+from __future__ import annotations
+
+from pathlib import Path
+import shutil
+import json
+import numpy as np
+
+
+import time
+
+
+from spikeinterface.core import SortingAnalyzer
+
+from spikeinterface import load_extractor, create_sorting_analyzer, load_sorting_analyzer
+from spikeinterface.widgets import get_some_colors
+
+
+import pickle
+
+_key_separator = "_-°°-_"
+
+
+class BenchmarkStudy:
+    """
+    Generic study for sorting components.
+    This manage a list of Benchmark.
+    This manage a dict of "cases" every case is one Benchmark.
+
+    Benchmark is responsible for run() and compute_result()
+    BenchmarkStudy is the main API for:
+      * running (re-running) some cases
+      * save (run + compute_result) in results dict
+      * make some plots in inherited classes.
+
+
+    """
+
+    benchmark_class = None
+
+    def __init__(self, study_folder):
+        self.folder = Path(study_folder)
+        self.datasets = {}
+        self.analyzers = {}
+        self.cases = {}
+        self.benchmarks = {}
+        self.scan_folder()
+        self.colors = None
+
+    @classmethod
+    def create(cls, study_folder, datasets={}, cases={}, levels=None):
+        # check that cases keys are homogeneous
+        key0 = list(cases.keys())[0]
+        if isinstance(key0, str):
+            assert all(isinstance(key, str) for key in cases.keys()), "Keys for cases are not homogeneous"
+            if levels is None:
+                levels = "level0"
+            else:
+                assert isinstance(levels, str)
+        elif isinstance(key0, tuple):
+            assert all(isinstance(key, tuple) for key in cases.keys()), "Keys for cases are not homogeneous"
+            num_levels = len(key0)
+            assert all(
+                len(key) == num_levels for key in cases.keys()
+            ), "Keys for cases are not homogeneous, tuple negth differ"
+            if levels is None:
+                levels = [f"level{i}" for i in range(num_levels)]
+            else:
+                levels = list(levels)
+                assert len(levels) == num_levels
+        else:
+            raise ValueError("Keys for cases must str or tuple")
+
+        study_folder = Path(study_folder)
+        study_folder.mkdir(exist_ok=False, parents=True)
+
+        # (study_folder / "datasets").mkdir()
+        # (study_folder / "datasets" / "recordings").mkdir()
+        # (study_folder / "datasets" / "gt_sortings").mkdir()
+        (study_folder / "run_logs").mkdir()
+        # (study_folder / "metrics").mkdir()
+        (study_folder / "results").mkdir()
+        (study_folder / "sorting_analyzer").mkdir()
+
+        analyzers_path = {}
+        # for key, (rec, gt_sorting) in datasets.items():
+        for key, data in datasets.items():
+            assert "/" not in key, "'/' cannot be in the key name!"
+            assert "\\" not in key, "'\\' cannot be in the key name!"
+
+            local_analyzer_folder = study_folder / "sorting_analyzer" / key
+
+            if isinstance(data, tuple):
+                # old case : rec + sorting
+                rec, gt_sorting = data
+                analyzer = create_sorting_analyzer(
+                    gt_sorting, rec, sparse=True, format="binary_folder", folder=local_analyzer_folder
+                )
+                analyzer.compute("random_spikes")
+                analyzer.compute("templates")
+                analyzer.compute("noise_levels")
+            else:
+                # new case : analzyer
+                assert isinstance(data, SortingAnalyzer)
+                analyzer = data
+                if data.format == "memory":
+                    # then copy a local copy in the folder
+                    analyzer = data.save_as(format="binary_folder", folder=local_analyzer_folder)
+                else:
+                    analyzer = data
+
+                rec, gt_sorting = analyzer.recording, analyzer.sorting
+
+            analyzers_path[key] = str(analyzer.folder.resolve())
+
+            # recordings are pickled
+            # rec.dump_to_pickle(study_folder / f"datasets/recordings/{key}.pickle")
+
+            # sortings are pickled + saved as NumpyFolderSorting
+            # gt_sorting.dump_to_pickle(study_folder / f"datasets/gt_sortings/{key}.pickle")
+            # gt_sorting.save(format="numpy_folder", folder=study_folder / f"datasets/gt_sortings/{key}")
+
+        # analyzer path (local or external)
+        (study_folder / "analyzers_path.json").write_text(json.dumps(analyzers_path, indent=4), encoding="utf8")
+
+        info = {}
+        info["levels"] = levels
+        (study_folder / "info.json").write_text(json.dumps(info, indent=4), encoding="utf8")
+
+        # cases is dumped to a pickle file, json is not possible because of the tuple key
+        (study_folder / "cases.pickle").write_bytes(pickle.dumps(cases))
+
+        return cls(study_folder)
+
+    def create_benchmark(self, key):
+        raise NotImplementedError
+
+    def scan_folder(self):
+        if not (self.folder / "sorting_analyzer").exists():
+            raise ValueError(f"This is folder is not a BenchmarkStudy : {self.folder.absolute()}")
+
+        with open(self.folder / "info.json", "r") as f:
+            self.info = json.load(f)
+
+        with open(self.folder / "analyzers_path.json", "r") as f:
+            self.analyzers_path = json.load(f)
+
+        self.levels = self.info["levels"]
+
+        for key, folder in self.analyzers_path.items():
+            analyzer = load_sorting_analyzer(folder)
+            self.analyzers[key] = analyzer
+            # the sorting is in memory here we take the saved one because comparisons need to pickle it later
+            sorting = load_extractor(analyzer.folder / "sorting")
+            self.datasets[key] = analyzer.recording, sorting
+
+        # for rec_file in (self.folder / "datasets" / "recordings").glob("*.pickle"):
+        #     key = rec_file.stem
+        #     rec = load_extractor(rec_file)
+        #     gt_sorting = load_extractor(self.folder / f"datasets" / "gt_sortings" / key)
+        #     self.datasets[key] = (rec, gt_sorting)
+
+        with open(self.folder / "cases.pickle", "rb") as f:
+            self.cases = pickle.load(f)
+
+        self.benchmarks = {}
+        for key in self.cases:
+            result_folder = self.folder / "results" / self.key_to_str(key)
+            if result_folder.exists():
+                result = self.benchmark_class.load_folder(result_folder)
+                benchmark = self.create_benchmark(key)
+                benchmark.result.update(result)
+                self.benchmarks[key] = benchmark
+            else:
+                self.benchmarks[key] = None
+
+    def __repr__(self):
+        t = f"{self.__class__.__name__} {self.folder.stem} \n"
+        t += f"  datasets: {len(self.datasets)} {list(self.datasets.keys())}\n"
+        t += f"  cases: {len(self.cases)} {list(self.cases.keys())}\n"
+        num_computed = sum([1 for benchmark in self.benchmarks.values() if benchmark is not None])
+        t += f"  computed: {num_computed}\n"
+        return t
+
+    def key_to_str(self, key):
+        if isinstance(key, str):
+            return key
+        elif isinstance(key, tuple):
+            return _key_separator.join([str(k) for k in key])
+        else:
+            raise ValueError("Keys for cases must str or tuple")
+
+    def remove_benchmark(self, key):
+        result_folder = self.folder / "results" / self.key_to_str(key)
+        log_file = self.folder / "run_logs" / f"{self.key_to_str(key)}.json"
+
+        if result_folder.exists():
+            shutil.rmtree(result_folder)
+        for f in (log_file,):
+            if f.exists():
+                f.unlink()
+        self.benchmarks[key] = None
+
+    def run(self, case_keys=None, keep=True, verbose=False, **job_kwargs):
+        if case_keys is None:
+            case_keys = list(self.cases.keys())
+
+        job_keys = []
+        for key in case_keys:
+
+            result_folder = self.folder / "results" / self.key_to_str(key)
+
+            if keep and result_folder.exists():
+                continue
+            elif not keep and result_folder.exists():
+                self.remove_benchmark(key)
+            job_keys.append(key)
+
+        for key in job_keys:
+            benchmark = self.create_benchmark(key)
+            t0 = time.perf_counter()
+            benchmark.run()
+            t1 = time.perf_counter()
+            self.benchmarks[key] = benchmark
+            bench_folder = self.folder / "results" / self.key_to_str(key)
+            bench_folder.mkdir(exist_ok=True)
+            benchmark.save_run(bench_folder)
+            benchmark.result["run_time"] = float(t1 - t0)
+            benchmark.save_main(bench_folder)
+
+    def set_colors(self, colors=None, map_name="tab20"):
+        if colors is None:
+            case_keys = list(self.cases.keys())
+            self.colors = get_some_colors(
+                case_keys, map_name=map_name, color_engine="matplotlib", shuffle=False, margin=0
+            )
+        else:
+            self.colors = colors
+
+    def get_colors(self):
+        if self.colors is None:
+            self.set_colors()
+        return self.colors
+
+    def get_run_times(self, case_keys=None):
+        if case_keys is None:
+            case_keys = list(self.cases.keys())
+
+        run_times = {}
+        for key in case_keys:
+            benchmark = self.benchmarks[key]
+            assert benchmark is not None
+            run_times[key] = benchmark.result["run_time"]
+        import pandas as pd
+
+        df = pd.DataFrame(dict(run_times=run_times))
+        if not isinstance(self.levels, str):
+            df.index.names = self.levels
+        return df
+
+    def plot_run_times(self, case_keys=None):
+        if case_keys is None:
+            case_keys = list(self.cases.keys())
+        run_times = self.get_run_times(case_keys=case_keys)
+
+        colors = self.get_colors()
+        import matplotlib.pyplot as plt
+
+        fig, ax = plt.subplots()
+        labels = []
+        for i, key in enumerate(case_keys):
+            labels.append(self.cases[key]["label"])
+            rt = run_times.at[key, "run_times"]
+            ax.bar(i, rt, width=0.8, color=colors[key])
+        ax.set_xticks(np.arange(len(case_keys)))
+        ax.set_xticklabels(labels, rotation=45.0)
+        return fig
+
+        # ax = run_times.plot(kind="bar")
+        # return ax.figure
+
+    def compute_results(self, case_keys=None, verbose=False, **result_params):
+        if case_keys is None:
+            case_keys = list(self.cases.keys())
+
+        job_keys = []
+        for key in case_keys:
+            benchmark = self.benchmarks[key]
+            assert benchmark is not None
+            benchmark.compute_result(**result_params)
+            benchmark.save_result(self.folder / "results" / self.key_to_str(key))
+
+    def create_sorting_analyzer_gt(self, case_keys=None, return_scaled=True, random_params={}, **job_kwargs):
+        print("###### Study.create_sorting_analyzer_gt() is not used anymore!!!!!!")
+        # if case_keys is None:
+        #     case_keys = self.cases.keys()
+
+        # base_folder = self.folder / "sorting_analyzer"
+        # base_folder.mkdir(exist_ok=True)
+
+        # dataset_keys = [self.cases[key]["dataset"] for key in case_keys]
+        # dataset_keys = set(dataset_keys)
+        # for dataset_key in dataset_keys:
+        #     # the waveforms depend on the dataset key
+        #     folder = base_folder / self.key_to_str(dataset_key)
+        #     recording, gt_sorting = self.datasets[dataset_key]
+        #     sorting_analyzer = create_sorting_analyzer(
+        #         gt_sorting, recording, format="binary_folder", folder=folder, return_scaled=return_scaled
+        #     )
+        #     sorting_analyzer.compute("random_spikes", **random_params)
+        #     sorting_analyzer.compute("templates", **job_kwargs)
+        #     sorting_analyzer.compute("noise_levels")
+
+    def get_sorting_analyzer(self, case_key=None, dataset_key=None):
+        if case_key is not None:
+            dataset_key = self.cases[case_key]["dataset"]
+        return self.analyzers[dataset_key]
+
+        # folder = self.folder / "sorting_analyzer" / self.key_to_str(dataset_key)
+        # sorting_analyzer = load_sorting_analyzer(folder)
+        # return sorting_analyzer
+
+    def get_templates(self, key, operator="average"):
+        sorting_analyzer = self.get_sorting_analyzer(case_key=key)
+        templates = sorting_analyzer.get_extenson("templates").get_data(operator=operator)
+        return templates
+
+    def compute_metrics(self, case_keys=None, metric_names=["snr", "firing_rate"], force=False):
+        if case_keys is None:
+            case_keys = self.cases.keys()
+
+        done = []
+        for key in case_keys:
+            dataset_key = self.cases[key]["dataset"]
+            if dataset_key in done:
+                # some case can share the same analyzer
+                continue
+            done.append(dataset_key)
+            # filename = self.folder / "metrics" / f"{self.key_to_str(dataset_key)}.csv"
+            # if filename.exists():
+            #     if force:
+            #         os.remove(filename)
+            #     else:
+            #         continue
+            sorting_analyzer = self.get_sorting_analyzer(key)
+            qm_ext = sorting_analyzer.get_extension("quality_metrics")
+            if qm_ext is None or force:
+                qm_ext = sorting_analyzer.compute("quality_metrics", metric_names=metric_names)
+
+            # TODO remove this metics CSV file!!!!
+            metrics = qm_ext.get_data()
+            # metrics.to_csv(filename, sep="\t", index=True)
+
+    def get_metrics(self, key):
+        import pandas as pd
+
+        dataset_key = self.cases[key]["dataset"]
+
+        analyzer = self.get_sorting_analyzer(key)
+        ext = analyzer.get_extension("quality_metrics")
+        if ext is None:
+            # TODO au to compute ????
+            return None
+
+        metrics = ext.get_data()
+        return metrics
+
+        # filename = self.folder / "metrics" / f"{self.key_to_str(dataset_key)}.csv"
+        # if not filename.exists():
+        #     return
+        # metrics = pd.read_csv(filename, sep="\t", index_col=0)
+        # dataset_key = self.cases[key]["dataset"]
+        # recording, gt_sorting = self.datasets[dataset_key]
+        # metrics.index = gt_sorting.unit_ids
+        # return metrics
+
+    def get_units_snr(self, key):
+        """ """
+        return self.get_metrics(key)["snr"]
+
+    def get_result(self, key):
+        return self.benchmarks[key].result
+
+
+class Benchmark:
+    """
+    Responsible to make a unique run() and compute_result() for one case.
+    """
+
+    def __init__(self):
+        self.result = {}
+
+    # this must not be changed in inherited
+    _main_key_saved = [
+        ("run_time", "pickle"),
+    ]
+    # this must be updated in hirerited
+    _run_key_saved = []
+    _result_key_saved = []
+
+    def _save_keys(self, saved_keys, folder):
+        for k, format in saved_keys:
+            if k not in self.result or self.result[k] is None:
+                continue
+            if format == "npy":
+                np.save(folder / f"{k}.npy", self.result[k])
+            elif format == "pickle":
+                with open(folder / f"{k}.pickle", mode="wb") as f:
+                    pickle.dump(self.result[k], f)
+            elif format == "sorting":
+                self.result[k].save(folder=folder / k, format="numpy_folder", overwrite=True)
+            elif format == "Motion":
+                self.result[k].save(folder=folder / k)
+            elif format == "zarr_templates":
+                self.result[k].to_zarr(folder / k)
+            elif format == "sorting_analyzer":
+                pass
+            else:
+                raise ValueError(f"Save error {k} {format}")
+
+    def save_main(self, folder):
+        # used for run time
+        self._save_keys(self._main_key_saved, folder)
+
+    def save_run(self, folder):
+        self._save_keys(self._run_key_saved, folder)
+
+    def save_result(self, folder):
+        self._save_keys(self._result_key_saved, folder)
+
+    @classmethod
+    def load_folder(cls, folder):
+        result = {}
+        for k, format in cls._run_key_saved + cls._result_key_saved + cls._main_key_saved:
+            if format == "npy":
+                file = folder / f"{k}.npy"
+                if file.exists():
+                    result[k] = np.load(file)
+            elif format == "pickle":
+                file = folder / f"{k}.pickle"
+                if file.exists():
+                    with open(file, mode="rb") as f:
+                        result[k] = pickle.load(f)
+            elif format == "sorting":
+                from spikeinterface.core import load_extractor
+
+                result[k] = load_extractor(folder / k)
+            elif format == "Motion":
+                from spikeinterface.sortingcomponents.motion import Motion
+
+                result[k] = Motion.load(folder / k)
+            elif format == "zarr_templates":
+                from spikeinterface.core.template import Templates
+
+                result[k] = Templates.from_zarr(folder / k)
+
+        return result
+
+    def run(self):
+        # run method
+        raise NotImplementedError
+
+    def compute_result(self):
+        # run becnhmark result
+        raise NotImplementedError
+
diff --git a/src/spikeinterface/benchmark/benchmark_plot_tools.py b/src/spikeinterface/benchmark/benchmark_plot_tools.py
new file mode 100644
index 0000000000..ee9d2947d6
--- /dev/null
+++ b/src/spikeinterface/benchmark/benchmark_plot_tools.py
@@ -0,0 +1,9 @@
+
+
+
+
+def _simpleaxis(ax):
+    ax.spines["top"].set_visible(False)
+    ax.spines["right"].set_visible(False)
+    ax.get_xaxis().tick_bottom()
+    ax.get_yaxis().tick_left()
diff --git a/src/spikeinterface/benchmark/benchmark_sorter.py b/src/spikeinterface/benchmark/benchmark_sorter.py
new file mode 100644
index 0000000000..d08775561a
--- /dev/null
+++ b/src/spikeinterface/benchmark/benchmark_sorter.py
@@ -0,0 +1,125 @@
+"""
+This replace the previous `GroundTruthStudy`
+"""
+
+
+import numpy as np
+from ..core import NumpySorting
+from .benchmark_base import Benchmark, BenchmarkStudy
+from ..sorters import run_sorter
+from spikeinterface.comparison import compare_sorter_to_ground_truth
+
+# from spikeinterface.widgets import (
+#     plot_agreement_matrix,
+#     plot_comparison_collision_by_similarity,
+# )
+
+
+
+
+
+class SorterBenchmark(Benchmark):
+    def __init__(self, recording, gt_sorting, params, sorter_folder):
+        self.recording = recording
+        self.gt_sorting = gt_sorting
+        self.params = params
+        self.sorter_folder = sorter_folder
+        self.result = {}
+
+    def run(self):
+        # run one sorter sorter_name is must be in params
+        raw_sorting = run_sorter(recording=self.recording, folder=self.sorter_folder, **self.params)
+        sorting = NumpySorting.from_sorting(raw_sorting)
+        self.result = {"sorting": sorting}
+
+    def compute_result(self):
+        # run becnhmark result
+        sorting = self.result["sorting"]
+        comp = compare_sorter_to_ground_truth(self.gt_sorting, sorting, exhaustive_gt=True)
+        self.result["gt_comparison"] = comp
+
+    _run_key_saved = [
+        ("sorting", "sorting"),
+    ]
+    _result_key_saved = [
+        ("gt_comparison", "pickle"),
+    ]
+
+class SorterStudy(BenchmarkStudy):
+    """
+    This class is used to tests several sorter in several situtation.
+    This replace the previous GroundTruthStudy with more flexibility.
+    """
+
+    benchmark_class = SorterBenchmark
+
+    def create_benchmark(self, key):
+        dataset_key = self.cases[key]["dataset"]
+        recording, gt_sorting = self.datasets[dataset_key]
+        params = self.cases[key]["params"]
+        sorter_folder = self.folder / "sorters" / self.key_to_str(key)
+        benchmark = SorterBenchmark(recording, gt_sorting, params, sorter_folder)
+        return benchmark
+
+    def get_performance_by_unit(self, case_keys=None):
+        import pandas as pd
+
+        if case_keys is None:
+            case_keys = self.cases.keys()
+
+        perf_by_unit = []
+        for key in case_keys:
+            comp = self.get_result(key)["gt_comparison"]
+
+            perf = comp.get_performance(method="by_unit", output="pandas")
+
+            if isinstance(key, str):
+                perf[self.levels] = key
+            elif isinstance(key, tuple):
+                for col, k in zip(self.levels, key):
+                    perf[col] = k
+
+            perf = perf.reset_index()
+            perf_by_unit.append(perf)
+
+        perf_by_unit = pd.concat(perf_by_unit)
+        perf_by_unit = perf_by_unit.set_index(self.levels)
+        perf_by_unit = perf_by_unit.sort_index()
+        return perf_by_unit
+
+    def get_count_units(self, case_keys=None, well_detected_score=None, redundant_score=None, overmerged_score=None):
+        import pandas as pd
+
+        if case_keys is None:
+            case_keys = list(self.cases.keys())
+
+        if isinstance(case_keys[0], str):
+            index = pd.Index(case_keys, name=self.levels)
+        else:
+            index = pd.MultiIndex.from_tuples(case_keys, names=self.levels)
+
+        columns = ["num_gt", "num_sorter", "num_well_detected"]
+        key0 = case_keys[0]
+        comp = self.get_result(key0)["gt_comparison"]
+        if comp.exhaustive_gt:
+            columns.extend(["num_false_positive", "num_redundant", "num_overmerged", "num_bad"])
+        count_units = pd.DataFrame(index=index, columns=columns, dtype=int)
+
+        for key in case_keys:
+            comp = self.get_result(key)["gt_comparison"]
+
+            gt_sorting = comp.sorting1
+            sorting = comp.sorting2
+
+            count_units.loc[key, "num_gt"] = len(gt_sorting.get_unit_ids())
+            count_units.loc[key, "num_sorter"] = len(sorting.get_unit_ids())
+            count_units.loc[key, "num_well_detected"] = comp.count_well_detected_units(well_detected_score)
+
+            if comp.exhaustive_gt:
+                count_units.loc[key, "num_redundant"] = comp.count_redundant_units(redundant_score)
+                count_units.loc[key, "num_overmerged"] = comp.count_overmerged_units(overmerged_score)
+                count_units.loc[key, "num_false_positive"] = comp.count_false_positive_units(redundant_score)
+                count_units.loc[key, "num_bad"] = comp.count_bad_units()
+
+        return count_units
+
diff --git a/src/spikeinterface/benchmark/tests/test_benchmark_sorter.py b/src/spikeinterface/benchmark/tests/test_benchmark_sorter.py
new file mode 100644
index 0000000000..7fad1b6e8b
--- /dev/null
+++ b/src/spikeinterface/benchmark/tests/test_benchmark_sorter.py
@@ -0,0 +1,90 @@
+import shutil
+import pytest
+from pathlib import Path
+
+from spikeinterface import generate_ground_truth_recording
+from spikeinterface.preprocessing import bandpass_filter
+from spikeinterface.benchmark import SorterStudy
+
+
+@pytest.fixture(scope="module")
+def setup_module(tmp_path_factory):
+    study_folder = tmp_path_factory.mktemp("sorter_study_folder")
+    if study_folder.is_dir():
+        shutil.rmtree(study_folder)
+    create_a_study(study_folder)
+    return study_folder
+
+def simple_preprocess(rec):
+    return bandpass_filter(rec)
+
+
+def create_a_study(study_folder):
+    rec0, gt_sorting0 = generate_ground_truth_recording(num_channels=4, durations=[30.0], seed=42)
+    rec1, gt_sorting1 = generate_ground_truth_recording(num_channels=4, durations=[30.0], seed=91)
+
+    datasets = {
+        "toy_tetrode": (rec0, gt_sorting0),
+        "toy_probe32": (rec1, gt_sorting1),
+        "toy_probe32_preprocess": (simple_preprocess(rec1), gt_sorting1),
+    }
+
+    # cases can also be generated via simple loops
+    cases = {
+        #
+        ("tdc2", "no-preprocess", "tetrode"): {
+            "label": "tridesclous2 without preprocessing and standard params",
+            "dataset": "toy_tetrode",
+            "params": {
+                "sorter_name": "tridesclous2",
+            },
+        },
+        #
+        ("tdc2", "with-preprocess", "probe32"): {
+            "label": "tridesclous2 with preprocessing standar params",
+            "dataset": "toy_probe32_preprocess",
+            "params": {
+                "sorter_name": "tridesclous2",
+            },
+        },
+    }
+
+    study = SorterStudy.create(
+        study_folder, datasets=datasets, cases=cases, levels=["sorter_name", "processing", "probe_type"]
+    )
+    # print(study)
+
+
+def test_SorterStudy(setup_module):
+    # job_kwargs = dict(n_jobs=2, chunk_duration="1s")
+
+    study_folder = setup_module
+    study = SorterStudy(study_folder)
+    print(study)
+
+    # # this run the sorters
+    study.run()
+
+    # # this run comparisons
+    study.compute_results()
+    print(study)
+
+    # this is from the base class
+    rt = study.get_run_times()
+    # rt = study.plot_run_times()
+    # import matplotlib.pyplot as plt
+    # plt.show()
+
+
+    perf_by_unit = study.get_performance_by_unit()
+    # print(perf_by_unit)
+    count_units = study.get_count_units()
+    # print(count_units)
+
+    
+
+
+if __name__ == "__main__":
+    study_folder = Path(__file__).resolve().parents[4] / "cache_folder" / "benchmarks" / "test_SorterStudy"
+    # create_a_study(study_folder)
+    test_SorterStudy(study_folder)
diff --git a/src/spikeinterface/comparison/groundtruthstudy.py b/src/spikeinterface/comparison/groundtruthstudy.py
index 8929d6983c..c662ca38da 100644
--- a/src/spikeinterface/comparison/groundtruthstudy.py
+++ b/src/spikeinterface/comparison/groundtruthstudy.py
@@ -1,441 +1,22 @@
-from __future__ import annotations
 
-from pathlib import Path
-import shutil
-import os
-import json
-import pickle
-
-import numpy as np
-
-from spikeinterface.core import load_extractor, create_sorting_analyzer, load_sorting_analyzer
-from spikeinterface.sorters import run_sorter_jobs, read_sorter_folder
-
-from spikeinterface.qualitymetrics import compute_quality_metrics
-
-from .paircomparisons import compare_sorter_to_ground_truth, GroundTruthComparison
-
-
-# TODO later : save comparison in folders when comparison object will be able to serialize
-
-
-# This is to separate names when the key are tuples when saving folders
-# _key_separator = "_##_"
-_key_separator = "_-°°-_"
 
+_txt_error_message = """
+GroundTruthStudy has been replaced by SorterStudy with similar API but not back compatible folder loading.
+You can do:
+from spikeinterface.benchmark import SorterStudy
+study = SorterStudy.create(study_folder, datasets=..., cases=..., levels=...)
+study.run() # this run sorters
+study.compute_results() # this run the comparisons
+# and then some ploting
+study.plot_agreements()
+study.plot_performances_vs_snr()
+...
+"""
 
 class GroundTruthStudy:
-    """
-    This class is an helper function to run any comparison on several "cases" for many ground-truth dataset.
-
-    "cases" refer to:
-      * several sorters for comparisons
-      * same sorter with differents parameters
-      * any combination of these (and more)
-
-    For increased flexibility, cases keys can be a tuple so that we can vary complexity along several
-    "levels" or "axis" (paremeters or sorters).
-    In this case, the result dataframes will have `MultiIndex` to handle the different levels.
-
-    A ground-truth dataset is made of a `Recording` and a `Sorting` object. For example, it can be a simulated dataset with MEArec or internally generated (see
-    :py:func:`~spikeinterface.core.generate.generate_ground_truth_recording()`).
-
-    This GroundTruthStudy have been refactor in version 0.100 to be more flexible than previous versions.
-    Note that the underlying folder structure is not backward compatible!
-
-    Parameters
-    ----------
-    study_folder : str | Path
-        Path to folder containing `GroundTruthStudy`
-    """
-
     def __init__(self, study_folder):
-        self.folder = Path(study_folder)
-
-        self.datasets = {}
-        self.cases = {}
-        self.sortings = {}
-        self.comparisons = {}
-        self.colors = None
-
-        self.scan_folder()
+        raise RuntimeError(_txt_error_message)
 
     @classmethod
     def create(cls, study_folder, datasets={}, cases={}, levels=None):
-        # check that cases keys are homogeneous
-        key0 = list(cases.keys())[0]
-        if isinstance(key0, str):
-            assert all(isinstance(key, str) for key in cases.keys()), "Keys for cases are not homogeneous"
-            if levels is None:
-                levels = "level0"
-            else:
-                assert isinstance(levels, str)
-        elif isinstance(key0, tuple):
-            assert all(isinstance(key, tuple) for key in cases.keys()), "Keys for cases are not homogeneous"
-            num_levels = len(key0)
-            assert all(
-                len(key) == num_levels for key in cases.keys()
-            ), "Keys for cases are not homogeneous, tuple negth differ"
-            if levels is None:
-                levels = [f"level{i}" for i in range(num_levels)]
-            else:
-                levels = list(levels)
-                assert len(levels) == num_levels
-        else:
-            raise ValueError("Keys for cases must str or tuple")
-
-        study_folder = Path(study_folder)
-        study_folder.mkdir(exist_ok=False, parents=True)
-
-        (study_folder / "datasets").mkdir()
-        (study_folder / "datasets" / "recordings").mkdir()
-        (study_folder / "datasets" / "gt_sortings").mkdir()
-        (study_folder / "sorters").mkdir()
-        (study_folder / "sortings").mkdir()
-        (study_folder / "sortings" / "run_logs").mkdir()
-        (study_folder / "metrics").mkdir()
-        (study_folder / "comparisons").mkdir()
-
-        for key, (rec, gt_sorting) in datasets.items():
-            assert "/" not in key, "'/' cannot be in the key name!"
-            assert "\\" not in key, "'\\' cannot be in the key name!"
-
-            # recordings are pickled
-            rec.dump_to_pickle(study_folder / f"datasets/recordings/{key}.pickle")
-
-            # sortings are pickled + saved as NumpyFolderSorting
-            gt_sorting.dump_to_pickle(study_folder / f"datasets/gt_sortings/{key}.pickle")
-            gt_sorting.save(format="numpy_folder", folder=study_folder / f"datasets/gt_sortings/{key}")
-
-        info = {}
-        info["levels"] = levels
-        (study_folder / "info.json").write_text(json.dumps(info, indent=4), encoding="utf8")
-
-        # cases is dumped to a pickle file, json is not possible because of the tuple key
-        (study_folder / "cases.pickle").write_bytes(pickle.dumps(cases))
-
-        return cls(study_folder)
-
-    def scan_folder(self):
-        if not (self.folder / "datasets").exists():
-            raise ValueError(f"This is folder is not a GroundTruthStudy : {self.folder.absolute()}")
-
-        with open(self.folder / "info.json", "r") as f:
-            self.info = json.load(f)
-
-        self.levels = self.info["levels"]
-
-        for rec_file in (self.folder / "datasets" / "recordings").glob("*.pickle"):
-            key = rec_file.stem
-            rec = load_extractor(rec_file)
-            gt_sorting = load_extractor(self.folder / f"datasets" / "gt_sortings" / key)
-            self.datasets[key] = (rec, gt_sorting)
-
-        with open(self.folder / "cases.pickle", "rb") as f:
-            self.cases = pickle.load(f)
-
-        self.sortings = {k: None for k in self.cases}
-        self.comparisons = {k: None for k in self.cases}
-        for key in self.cases:
-            sorting_folder = self.folder / "sortings" / self.key_to_str(key)
-            if sorting_folder.exists():
-                self.sortings[key] = load_extractor(sorting_folder)
-
-            comparison_file = self.folder / "comparisons" / (self.key_to_str(key) + ".pickle")
-            if comparison_file.exists():
-                with open(comparison_file, mode="rb") as f:
-                    try:
-                        self.comparisons[key] = pickle.load(f)
-                    except Exception:
-                        pass
-
-    def __repr__(self):
-        t = f"{self.__class__.__name__} {self.folder.stem} \n"
-        t += f"  datasets: {len(self.datasets)} {list(self.datasets.keys())}\n"
-        t += f"  cases: {len(self.cases)} {list(self.cases.keys())}\n"
-        num_computed = sum([1 for sorting in self.sortings.values() if sorting is not None])
-        t += f"  computed: {num_computed}\n"
-
-        return t
-
-    def key_to_str(self, key):
-        if isinstance(key, str):
-            return key
-        elif isinstance(key, tuple):
-            return _key_separator.join(key)
-        else:
-            raise ValueError("Keys for cases must str or tuple")
-
-    def remove_sorting(self, key):
-        sorting_folder = self.folder / "sortings" / self.key_to_str(key)
-        log_file = self.folder / "sortings" / "run_logs" / f"{self.key_to_str(key)}.json"
-        comparison_file = self.folder / "comparisons" / self.key_to_str(key)
-        self.sortings[key] = None
-        self.comparisons[key] = None
-        if sorting_folder.exists():
-            shutil.rmtree(sorting_folder)
-        for f in (log_file, comparison_file):
-            if f.exists():
-                f.unlink()
-
-    def set_colors(self, colors=None, map_name="tab20"):
-        from spikeinterface.widgets import get_some_colors
-
-        if colors is None:
-            case_keys = list(self.cases.keys())
-            self.colors = get_some_colors(
-                case_keys, map_name=map_name, color_engine="matplotlib", shuffle=False, margin=0
-            )
-        else:
-            self.colors = colors
-
-    def get_colors(self):
-        if self.colors is None:
-            self.set_colors()
-        return self.colors
-
-    def run_sorters(self, case_keys=None, engine="loop", engine_kwargs={}, keep=True, verbose=False):
-        if case_keys is None:
-            case_keys = self.cases.keys()
-
-        job_list = []
-        for key in case_keys:
-            sorting_folder = self.folder / "sortings" / self.key_to_str(key)
-            sorting_exists = sorting_folder.exists()
-
-            sorter_folder = self.folder / "sorters" / self.key_to_str(key)
-            sorter_folder_exists = sorter_folder.exists()
-
-            if keep:
-                if sorting_exists:
-                    continue
-                if sorter_folder_exists:
-                    # the sorter folder exists but havent been copied to sortings folder
-                    sorting = read_sorter_folder(sorter_folder, raise_error=False)
-                    if sorting is not None:
-                        # save and skip
-                        self.copy_sortings(case_keys=[key])
-                        continue
-
-            self.remove_sorting(key)
-
-            if sorter_folder_exists:
-                shutil.rmtree(sorter_folder)
-
-            params = self.cases[key]["run_sorter_params"].copy()
-            # this ensure that sorter_name is given
-            recording, _ = self.datasets[self.cases[key]["dataset"]]
-            sorter_name = params.pop("sorter_name")
-            job = dict(
-                sorter_name=sorter_name,
-                recording=recording,
-                output_folder=sorter_folder,
-            )
-            job.update(params)
-            # the verbose is overwritten and global to all run_sorters
-            job["verbose"] = verbose
-            job["with_output"] = False
-            job_list.append(job)
-
-        run_sorter_jobs(job_list, engine=engine, engine_kwargs=engine_kwargs, return_output=False)
-
-        # TODO later create a list in laucher for engine blocking and non-blocking
-        if engine not in ("slurm",):
-            self.copy_sortings(case_keys)
-
-    def copy_sortings(self, case_keys=None, force=True):
-        if case_keys is None:
-            case_keys = self.cases.keys()
-
-        for key in case_keys:
-            sorting_folder = self.folder / "sortings" / self.key_to_str(key)
-            sorter_folder = self.folder / "sorters" / self.key_to_str(key)
-            log_file = self.folder / "sortings" / "run_logs" / f"{self.key_to_str(key)}.json"
-
-            if (sorter_folder / "spikeinterface_log.json").exists():
-                sorting = read_sorter_folder(
-                    sorter_folder, raise_error=False, register_recording=False, sorting_info=False
-                )
-            else:
-                sorting = None
-
-            if sorting is not None:
-                if sorting_folder.exists():
-                    if force:
-                        self.remove_sorting(key)
-                    else:
-                        continue
-
-                sorting = sorting.save(format="numpy_folder", folder=sorting_folder)
-                self.sortings[key] = sorting
-
-                # copy logs
-                shutil.copyfile(sorter_folder / "spikeinterface_log.json", log_file)
-
-    def run_comparisons(self, case_keys=None, comparison_class=GroundTruthComparison, **kwargs):
-        if case_keys is None:
-            case_keys = self.cases.keys()
-
-        for key in case_keys:
-            dataset_key = self.cases[key]["dataset"]
-            _, gt_sorting = self.datasets[dataset_key]
-            sorting = self.sortings[key]
-            if sorting is None:
-                self.comparisons[key] = None
-                continue
-            comp = comparison_class(gt_sorting, sorting, **kwargs)
-            self.comparisons[key] = comp
-
-            comparison_file = self.folder / "comparisons" / (self.key_to_str(key) + ".pickle")
-            with open(comparison_file, mode="wb") as f:
-                pickle.dump(comp, f)
-
-    def get_run_times(self, case_keys=None):
-        import pandas as pd
-
-        if case_keys is None:
-            case_keys = self.cases.keys()
-
-        log_folder = self.folder / "sortings" / "run_logs"
-
-        run_times = {}
-        for key in case_keys:
-            log_file = log_folder / f"{self.key_to_str(key)}.json"
-            with open(log_file, mode="r") as logfile:
-                log = json.load(logfile)
-                run_time = log.get("run_time", None)
-            run_times[key] = run_time
-
-        return pd.Series(run_times, name="run_time")
-
-    def create_sorting_analyzer_gt(self, case_keys=None, random_params={}, waveforms_params={}, **job_kwargs):
-        if case_keys is None:
-            case_keys = self.cases.keys()
-
-        base_folder = self.folder / "sorting_analyzer"
-        base_folder.mkdir(exist_ok=True)
-
-        dataset_keys = [self.cases[key]["dataset"] for key in case_keys]
-        dataset_keys = set(dataset_keys)
-        for dataset_key in dataset_keys:
-            # the waveforms depend on the dataset key
-            folder = base_folder / self.key_to_str(dataset_key)
-            recording, gt_sorting = self.datasets[dataset_key]
-            sorting_analyzer = create_sorting_analyzer(gt_sorting, recording, format="binary_folder", folder=folder)
-            sorting_analyzer.compute("random_spikes", **random_params)
-            sorting_analyzer.compute("templates", **job_kwargs)
-            sorting_analyzer.compute("noise_levels")
-
-    def get_sorting_analyzer(self, case_key=None, dataset_key=None):
-        if case_key is not None:
-            dataset_key = self.cases[case_key]["dataset"]
-
-        folder = self.folder / "sorting_analyzer" / self.key_to_str(dataset_key)
-        sorting_analyzer = load_sorting_analyzer(folder)
-        return sorting_analyzer
-
-    # def get_templates(self, key, mode="average"):
-    #     analyzer = self.get_sorting_analyzer(case_key=key)
-    #     templates = sorting_analyzer.get_all_templates(mode=mode)
-    #     return templates
-
-    def compute_metrics(self, case_keys=None, metric_names=["snr", "firing_rate"], force=False):
-        if case_keys is None:
-            case_keys = self.cases.keys()
-
-        done = []
-        for key in case_keys:
-            dataset_key = self.cases[key]["dataset"]
-            if dataset_key in done:
-                # some case can share the same waveform extractor
-                continue
-            done.append(dataset_key)
-            filename = self.folder / "metrics" / f"{self.key_to_str(dataset_key)}.csv"
-            if filename.exists():
-                if force:
-                    os.remove(filename)
-                else:
-                    continue
-            analyzer = self.get_sorting_analyzer(key)
-            metrics = compute_quality_metrics(analyzer, metric_names=metric_names)
-            metrics.to_csv(filename, sep="\t", index=True)
-
-    def get_metrics(self, key):
-        import pandas as pd
-
-        dataset_key = self.cases[key]["dataset"]
-
-        filename = self.folder / "metrics" / f"{self.key_to_str(dataset_key)}.csv"
-        if not filename.exists():
-            return
-        metrics = pd.read_csv(filename, sep="\t", index_col=0)
-        dataset_key = self.cases[key]["dataset"]
-        recording, gt_sorting = self.datasets[dataset_key]
-        metrics.index = gt_sorting.unit_ids
-        return metrics
-
-    def get_units_snr(self, key):
-        return self.get_metrics(key)["snr"]
-
-    def get_performance_by_unit(self, case_keys=None):
-        import pandas as pd
-
-        if case_keys is None:
-            case_keys = self.cases.keys()
-
-        perf_by_unit = []
-        for key in case_keys:
-            comp = self.comparisons.get(key, None)
-            assert comp is not None, "You need to do study.run_comparisons() first"
-
-            perf = comp.get_performance(method="by_unit", output="pandas")
-
-            if isinstance(key, str):
-                perf[self.levels] = key
-            elif isinstance(key, tuple):
-                for col, k in zip(self.levels, key):
-                    perf[col] = k
-
-            perf = perf.reset_index()
-            perf_by_unit.append(perf)
-
-        perf_by_unit = pd.concat(perf_by_unit)
-        perf_by_unit = perf_by_unit.set_index(self.levels)
-        perf_by_unit = perf_by_unit.sort_index()
-        return perf_by_unit
-
-    def get_count_units(self, case_keys=None, well_detected_score=None, redundant_score=None, overmerged_score=None):
-        import pandas as pd
-
-        if case_keys is None:
-            case_keys = list(self.cases.keys())
-
-        if isinstance(case_keys[0], str):
-            index = pd.Index(case_keys, name=self.levels)
-        else:
-            index = pd.MultiIndex.from_tuples(case_keys, names=self.levels)
-
-        columns = ["num_gt", "num_sorter", "num_well_detected"]
-        comp = self.comparisons[case_keys[0]]
-        if comp.exhaustive_gt:
-            columns.extend(["num_false_positive", "num_redundant", "num_overmerged", "num_bad"])
-        count_units = pd.DataFrame(index=index, columns=columns, dtype=int)
-
-        for key in case_keys:
-            comp = self.comparisons.get(key, None)
-            assert comp is not None, "You need to do study.run_comparisons() first"
-
-            gt_sorting = comp.sorting1
-            sorting = comp.sorting2
-
-            count_units.loc[key, "num_gt"] = len(gt_sorting.get_unit_ids())
-            count_units.loc[key, "num_sorter"] = len(sorting.get_unit_ids())
-            count_units.loc[key, "num_well_detected"] = comp.count_well_detected_units(well_detected_score)
-
-            if comp.exhaustive_gt:
-                count_units.loc[key, "num_redundant"] = comp.count_redundant_units(redundant_score)
-                count_units.loc[key, "num_overmerged"] = comp.count_overmerged_units(overmerged_score)
-                count_units.loc[key, "num_false_positive"] = comp.count_false_positive_units(redundant_score)
-                count_units.loc[key, "num_bad"] = comp.count_bad_units()
-
-        return count_units
+        raise RuntimeError(_txt_error_message)
diff --git a/src/spikeinterface/sortingcomponents/benchmark/benchmark_tools.py b/src/spikeinterface/sortingcomponents/benchmark/benchmark_tools.py
index 4d6dd43bce..171745ac2f 100644
--- a/src/spikeinterface/sortingcomponents/benchmark/benchmark_tools.py
+++ b/src/spikeinterface/sortingcomponents/benchmark/benchmark_tools.py
@@ -1,471 +1,2 @@
-from __future__ import annotations
-
-from pathlib import Path
-import shutil
-import json
-import numpy as np
-
-
-import time
-
-
-from spikeinterface.core import SortingAnalyzer
-
-from spikeinterface import load_extractor, create_sorting_analyzer, load_sorting_analyzer
-from spikeinterface.widgets import get_some_colors
-
-
-import pickle
-
-_key_separator = "_-°°-_"
-
-
-class BenchmarkStudy:
-    """
-    Generic study for sorting components.
-    This manage a list of Benchmark.
-    This manage a dict of "cases" every case is one Benchmark.
-
-    Benchmark is responsible for run() and compute_result()
-    BenchmarkStudy is the main API for:
-      * running (re-running) some cases
-      * save (run + compute_result) in results dict
-      * make some plots in inherited classes.
-
-
-    """
-
-    benchmark_class = None
-
-    def __init__(self, study_folder):
-        self.folder = Path(study_folder)
-        self.datasets = {}
-        self.analyzers = {}
-        self.cases = {}
-        self.benchmarks = {}
-        self.scan_folder()
-        self.colors = None
-
-    @classmethod
-    def create(cls, study_folder, datasets={}, cases={}, levels=None):
-        # check that cases keys are homogeneous
-        key0 = list(cases.keys())[0]
-        if isinstance(key0, str):
-            assert all(isinstance(key, str) for key in cases.keys()), "Keys for cases are not homogeneous"
-            if levels is None:
-                levels = "level0"
-            else:
-                assert isinstance(levels, str)
-        elif isinstance(key0, tuple):
-            assert all(isinstance(key, tuple) for key in cases.keys()), "Keys for cases are not homogeneous"
-            num_levels = len(key0)
-            assert all(
-                len(key) == num_levels for key in cases.keys()
-            ), "Keys for cases are not homogeneous, tuple negth differ"
-            if levels is None:
-                levels = [f"level{i}" for i in range(num_levels)]
-            else:
-                levels = list(levels)
-                assert len(levels) == num_levels
-        else:
-            raise ValueError("Keys for cases must str or tuple")
-
-        study_folder = Path(study_folder)
-        study_folder.mkdir(exist_ok=False, parents=True)
-
-        # (study_folder / "datasets").mkdir()
-        # (study_folder / "datasets" / "recordings").mkdir()
-        # (study_folder / "datasets" / "gt_sortings").mkdir()
-        (study_folder / "run_logs").mkdir()
-        # (study_folder / "metrics").mkdir()
-        (study_folder / "results").mkdir()
-        (study_folder / "sorting_analyzer").mkdir()
-
-        analyzers_path = {}
-        # for key, (rec, gt_sorting) in datasets.items():
-        for key, data in datasets.items():
-            assert "/" not in key, "'/' cannot be in the key name!"
-            assert "\\" not in key, "'\\' cannot be in the key name!"
-
-            local_analyzer_folder = study_folder / "sorting_analyzer" / key
-
-            if isinstance(data, tuple):
-                # old case : rec + sorting
-                rec, gt_sorting = data
-                analyzer = create_sorting_analyzer(
-                    gt_sorting, rec, sparse=True, format="binary_folder", folder=local_analyzer_folder
-                )
-                analyzer.compute("random_spikes")
-                analyzer.compute("templates")
-                analyzer.compute("noise_levels")
-            else:
-                # new case : analzyer
-                assert isinstance(data, SortingAnalyzer)
-                analyzer = data
-                if data.format == "memory":
-                    # then copy a local copy in the folder
-                    analyzer = data.save_as(format="binary_folder", folder=local_analyzer_folder)
-                else:
-                    analyzer = data
-
-                rec, gt_sorting = analyzer.recording, analyzer.sorting
-
-            analyzers_path[key] = str(analyzer.folder.resolve())
-
-            # recordings are pickled
-            # rec.dump_to_pickle(study_folder / f"datasets/recordings/{key}.pickle")
-
-            # sortings are pickled + saved as NumpyFolderSorting
-            # gt_sorting.dump_to_pickle(study_folder / f"datasets/gt_sortings/{key}.pickle")
-            # gt_sorting.save(format="numpy_folder", folder=study_folder / f"datasets/gt_sortings/{key}")
-
-        # analyzer path (local or external)
-        (study_folder / "analyzers_path.json").write_text(json.dumps(analyzers_path, indent=4), encoding="utf8")
-
-        info = {}
-        info["levels"] = levels
-        (study_folder / "info.json").write_text(json.dumps(info, indent=4), encoding="utf8")
-
-        # cases is dumped to a pickle file, json is not possible because of the tuple key
-        (study_folder / "cases.pickle").write_bytes(pickle.dumps(cases))
-
-        return cls(study_folder)
-
-    def create_benchmark(self):
-        raise NotImplementedError
-
-    def scan_folder(self):
-        if not (self.folder / "sorting_analyzer").exists():
-            raise ValueError(f"This is folder is not a BenchmarkStudy : {self.folder.absolute()}")
-
-        with open(self.folder / "info.json", "r") as f:
-            self.info = json.load(f)
-
-        with open(self.folder / "analyzers_path.json", "r") as f:
-            self.analyzers_path = json.load(f)
-
-        self.levels = self.info["levels"]
-
-        for key, folder in self.analyzers_path.items():
-            analyzer = load_sorting_analyzer(folder)
-            self.analyzers[key] = analyzer
-            # the sorting is in memory here we take the saved one because comparisons need to pickle it later
-            sorting = load_extractor(analyzer.folder / "sorting")
-            self.datasets[key] = analyzer.recording, sorting
-
-        # for rec_file in (self.folder / "datasets" / "recordings").glob("*.pickle"):
-        #     key = rec_file.stem
-        #     rec = load_extractor(rec_file)
-        #     gt_sorting = load_extractor(self.folder / f"datasets" / "gt_sortings" / key)
-        #     self.datasets[key] = (rec, gt_sorting)
-
-        with open(self.folder / "cases.pickle", "rb") as f:
-            self.cases = pickle.load(f)
-
-        self.benchmarks = {}
-        for key in self.cases:
-            result_folder = self.folder / "results" / self.key_to_str(key)
-            if result_folder.exists():
-                result = self.benchmark_class.load_folder(result_folder)
-                benchmark = self.create_benchmark(key)
-                benchmark.result.update(result)
-                self.benchmarks[key] = benchmark
-            else:
-                self.benchmarks[key] = None
-
-    def __repr__(self):
-        t = f"{self.__class__.__name__} {self.folder.stem} \n"
-        t += f"  datasets: {len(self.datasets)} {list(self.datasets.keys())}\n"
-        t += f"  cases: {len(self.cases)} {list(self.cases.keys())}\n"
-        num_computed = sum([1 for benchmark in self.benchmarks.values() if benchmark is not None])
-        t += f"  computed: {num_computed}\n"
-        return t
-
-    def key_to_str(self, key):
-        if isinstance(key, str):
-            return key
-        elif isinstance(key, tuple):
-            return _key_separator.join([str(k) for k in key])
-        else:
-            raise ValueError("Keys for cases must str or tuple")
-
-    def remove_benchmark(self, key):
-        result_folder = self.folder / "results" / self.key_to_str(key)
-        log_file = self.folder / "run_logs" / f"{self.key_to_str(key)}.json"
-
-        if result_folder.exists():
-            shutil.rmtree(result_folder)
-        for f in (log_file,):
-            if f.exists():
-                f.unlink()
-        self.benchmarks[key] = None
-
-    def run(self, case_keys=None, keep=True, verbose=False, **job_kwargs):
-        if case_keys is None:
-            case_keys = list(self.cases.keys())
-
-        job_keys = []
-        for key in case_keys:
-
-            result_folder = self.folder / "results" / self.key_to_str(key)
-
-            if keep and result_folder.exists():
-                continue
-            elif not keep and result_folder.exists():
-                self.remove_benchmark(key)
-            job_keys.append(key)
-
-        for key in job_keys:
-            benchmark = self.create_benchmark(key)
-            t0 = time.perf_counter()
-            benchmark.run()
-            t1 = time.perf_counter()
-            self.benchmarks[key] = benchmark
-            bench_folder = self.folder / "results" / self.key_to_str(key)
-            bench_folder.mkdir(exist_ok=True)
-            benchmark.save_run(bench_folder)
-            benchmark.result["run_time"] = float(t1 - t0)
-            benchmark.save_main(bench_folder)
-
-    def set_colors(self, colors=None, map_name="tab20"):
-        if colors is None:
-            case_keys = list(self.cases.keys())
-            self.colors = get_some_colors(
-                case_keys, map_name=map_name, color_engine="matplotlib", shuffle=False, margin=0
-            )
-        else:
-            self.colors = colors
-
-    def get_colors(self):
-        if self.colors is None:
-            self.set_colors()
-        return self.colors
-
-    def get_run_times(self, case_keys=None):
-        if case_keys is None:
-            case_keys = list(self.cases.keys())
-
-        run_times = {}
-        for key in case_keys:
-            benchmark = self.benchmarks[key]
-            assert benchmark is not None
-            run_times[key] = benchmark.result["run_time"]
-        import pandas as pd
-
-        df = pd.DataFrame(dict(run_times=run_times))
-        if not isinstance(self.levels, str):
-            df.index.names = self.levels
-        return df
-
-    def plot_run_times(self, case_keys=None):
-        if case_keys is None:
-            case_keys = list(self.cases.keys())
-        run_times = self.get_run_times(case_keys=case_keys)
-
-        colors = self.get_colors()
-        import matplotlib.pyplot as plt
-
-        fig, ax = plt.subplots()
-        labels = []
-        for i, key in enumerate(case_keys):
-            labels.append(self.cases[key]["label"])
-            rt = run_times.at[key, "run_times"]
-            ax.bar(i, rt, width=0.8, color=colors[key])
-        ax.set_xticks(np.arange(len(case_keys)))
-        ax.set_xticklabels(labels, rotation=45.0)
-        return fig
-
-        # ax = run_times.plot(kind="bar")
-        # return ax.figure
-
-    def compute_results(self, case_keys=None, verbose=False, **result_params):
-        if case_keys is None:
-            case_keys = list(self.cases.keys())
-
-        job_keys = []
-        for key in case_keys:
-            benchmark = self.benchmarks[key]
-            assert benchmark is not None
-            benchmark.compute_result(**result_params)
-            benchmark.save_result(self.folder / "results" / self.key_to_str(key))
-
-    def create_sorting_analyzer_gt(self, case_keys=None, return_scaled=True, random_params={}, **job_kwargs):
-        print("###### Study.create_sorting_analyzer_gt() is not used anymore!!!!!!")
-        # if case_keys is None:
-        #     case_keys = self.cases.keys()
-
-        # base_folder = self.folder / "sorting_analyzer"
-        # base_folder.mkdir(exist_ok=True)
-
-        # dataset_keys = [self.cases[key]["dataset"] for key in case_keys]
-        # dataset_keys = set(dataset_keys)
-        # for dataset_key in dataset_keys:
-        #     # the waveforms depend on the dataset key
-        #     folder = base_folder / self.key_to_str(dataset_key)
-        #     recording, gt_sorting = self.datasets[dataset_key]
-        #     sorting_analyzer = create_sorting_analyzer(
-        #         gt_sorting, recording, format="binary_folder", folder=folder, return_scaled=return_scaled
-        #     )
-        #     sorting_analyzer.compute("random_spikes", **random_params)
-        #     sorting_analyzer.compute("templates", **job_kwargs)
-        #     sorting_analyzer.compute("noise_levels")
-
-    def get_sorting_analyzer(self, case_key=None, dataset_key=None):
-        if case_key is not None:
-            dataset_key = self.cases[case_key]["dataset"]
-        return self.analyzers[dataset_key]
-
-        # folder = self.folder / "sorting_analyzer" / self.key_to_str(dataset_key)
-        # sorting_analyzer = load_sorting_analyzer(folder)
-        # return sorting_analyzer
-
-    def get_templates(self, key, operator="average"):
-        sorting_analyzer = self.get_sorting_analyzer(case_key=key)
-        templates = sorting_analyzer.get_extenson("templates").get_data(operator=operator)
-        return templates
-
-    def compute_metrics(self, case_keys=None, metric_names=["snr", "firing_rate"], force=False):
-        if case_keys is None:
-            case_keys = self.cases.keys()
-
-        done = []
-        for key in case_keys:
-            dataset_key = self.cases[key]["dataset"]
-            if dataset_key in done:
-                # some case can share the same analyzer
-                continue
-            done.append(dataset_key)
-            # filename = self.folder / "metrics" / f"{self.key_to_str(dataset_key)}.csv"
-            # if filename.exists():
-            #     if force:
-            #         os.remove(filename)
-            #     else:
-            #         continue
-            sorting_analyzer = self.get_sorting_analyzer(key)
-            qm_ext = sorting_analyzer.get_extension("quality_metrics")
-            if qm_ext is None or force:
-                qm_ext = sorting_analyzer.compute("quality_metrics", metric_names=metric_names)
-
-            # TODO remove this metics CSV file!!!!
-            metrics = qm_ext.get_data()
-            # metrics.to_csv(filename, sep="\t", index=True)
-
-    def get_metrics(self, key):
-        import pandas as pd
-
-        dataset_key = self.cases[key]["dataset"]
-
-        analyzer = self.get_sorting_analyzer(key)
-        ext = analyzer.get_extension("quality_metrics")
-        if ext is None:
-            # TODO au to compute ????
-            return None
-
-        metrics = ext.get_data()
-        return metrics
-
-        # filename = self.folder / "metrics" / f"{self.key_to_str(dataset_key)}.csv"
-        # if not filename.exists():
-        #     return
-        # metrics = pd.read_csv(filename, sep="\t", index_col=0)
-        # dataset_key = self.cases[key]["dataset"]
-        # recording, gt_sorting = self.datasets[dataset_key]
-        # metrics.index = gt_sorting.unit_ids
-        # return metrics
-
-    def get_units_snr(self, key):
-        """ """
-        return self.get_metrics(key)["snr"]
-
-    def get_result(self, key):
-        return self.benchmarks[key].result
-
-
-class Benchmark:
-    """
-    Responsible to make a unique run() and compute_result() for one case.
-    """
-
-    def __init__(self):
-        self.result = {}
-
-    # this must not be changed in inherited
-    _main_key_saved = [
-        ("run_time", "pickle"),
-    ]
-    # this must be updated in hirerited
-    _run_key_saved = []
-    _result_key_saved = []
-
-    def _save_keys(self, saved_keys, folder):
-        for k, format in saved_keys:
-            if k not in self.result or self.result[k] is None:
-                continue
-            if format == "npy":
-                np.save(folder / f"{k}.npy", self.result[k])
-            elif format == "pickle":
-                with open(folder / f"{k}.pickle", mode="wb") as f:
-                    pickle.dump(self.result[k], f)
-            elif format == "sorting":
-                self.result[k].save(folder=folder / k, format="numpy_folder", overwrite=True)
-            elif format == "Motion":
-                self.result[k].save(folder=folder / k)
-            elif format == "zarr_templates":
-                self.result[k].to_zarr(folder / k)
-            elif format == "sorting_analyzer":
-                pass
-            else:
-                raise ValueError(f"Save error {k} {format}")
-
-    def save_main(self, folder):
-        # used for run time
-        self._save_keys(self._main_key_saved, folder)
-
-    def save_run(self, folder):
-        self._save_keys(self._run_key_saved, folder)
-
-    def save_result(self, folder):
-        self._save_keys(self._result_key_saved, folder)
-
-    @classmethod
-    def load_folder(cls, folder):
-        result = {}
-        for k, format in cls._run_key_saved + cls._result_key_saved + cls._main_key_saved:
-            if format == "npy":
-                file = folder / f"{k}.npy"
-                if file.exists():
-                    result[k] = np.load(file)
-            elif format == "pickle":
-                file = folder / f"{k}.pickle"
-                if file.exists():
-                    with open(file, mode="rb") as f:
-                        result[k] = pickle.load(f)
-            elif format == "sorting":
-                from spikeinterface.core import load_extractor
-
-                result[k] = load_extractor(folder / k)
-            elif format == "Motion":
-                from spikeinterface.sortingcomponents.motion import Motion
-
-                result[k] = Motion.load(folder / k)
-            elif format == "zarr_templates":
-                from spikeinterface.core.template import Templates
-
-                result[k] = Templates.from_zarr(folder / k)
-
-        return result
-
-    def run(self):
-        # run method
-        raise NotImplementedError
-
-    def compute_result(self):
-        # run becnhmark result
-        raise NotImplementedError
-
-
-def _simpleaxis(ax):
-    ax.spines["top"].set_visible(False)
-    ax.spines["right"].set_visible(False)
-    ax.get_xaxis().tick_bottom()
-    ax.get_yaxis().tick_left()
+from spikeinterface.benchmark.benchmark_base import Benchmark, BenchmarkStudy
+from spikeinterface.benchmark.benchmark_plot_tools import _simpleaxis
\ No newline at end of file

From 6cff8fa87ab89c7450523e66ebb502d06182fedb Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 11 Sep 2024 18:06:04 +0200
Subject: [PATCH 008/344] rm test

---
 .../comparison/tests/test_groundtruthstudy.py | 98 -------------------
 1 file changed, 98 deletions(-)
 delete mode 100644 src/spikeinterface/comparison/tests/test_groundtruthstudy.py

diff --git a/src/spikeinterface/comparison/tests/test_groundtruthstudy.py b/src/spikeinterface/comparison/tests/test_groundtruthstudy.py
deleted file mode 100644
index a92d6e9f77..0000000000
--- a/src/spikeinterface/comparison/tests/test_groundtruthstudy.py
+++ /dev/null
@@ -1,98 +0,0 @@
-import shutil
-import pytest
-from pathlib import Path
-
-from spikeinterface import generate_ground_truth_recording
-from spikeinterface.preprocessing import bandpass_filter
-from spikeinterface.comparison import GroundTruthStudy
-
-
-@pytest.fixture(scope="module")
-def setup_module(tmp_path_factory):
-    study_folder = tmp_path_factory.mktemp("study_folder")
-    if study_folder.is_dir():
-        shutil.rmtree(study_folder)
-    create_a_study(study_folder)
-    return study_folder
-
-
-def simple_preprocess(rec):
-    return bandpass_filter(rec)
-
-
-def create_a_study(study_folder):
-    rec0, gt_sorting0 = generate_ground_truth_recording(num_channels=4, durations=[30.0], seed=42)
-    rec1, gt_sorting1 = generate_ground_truth_recording(num_channels=4, durations=[30.0], seed=91)
-
-    datasets = {
-        "toy_tetrode": (rec0, gt_sorting0),
-        "toy_probe32": (rec1, gt_sorting1),
-        "toy_probe32_preprocess": (simple_preprocess(rec1), gt_sorting1),
-    }
-
-    # cases can also be generated via simple loops
-    cases = {
-        #
-        ("tdc2", "no-preprocess", "tetrode"): {
-            "label": "tridesclous2 without preprocessing and standard params",
-            "dataset": "toy_tetrode",
-            "run_sorter_params": {
-                "sorter_name": "tridesclous2",
-            },
-            "comparison_params": {},
-        },
-        #
-        ("tdc2", "with-preprocess", "probe32"): {
-            "label": "tridesclous2 with preprocessing standar params",
-            "dataset": "toy_probe32_preprocess",
-            "run_sorter_params": {
-                "sorter_name": "tridesclous2",
-            },
-            "comparison_params": {},
-        },
-        # we comment this at the moement because SC2 is quite slow for testing
-        # ("sc2", "no-preprocess", "tetrode"): {
-        #     "label": "spykingcircus2 without preprocessing standar params",
-        #     "dataset": "toy_tetrode",
-        #     "run_sorter_params": {
-        #         "sorter_name": "spykingcircus2",
-        #     },
-        #     "comparison_params": {
-        #     },
-        # },
-    }
-
-    study = GroundTruthStudy.create(
-        study_folder, datasets=datasets, cases=cases, levels=["sorter_name", "processing", "probe_type"]
-    )
-    # print(study)
-
-
-def test_GroundTruthStudy(setup_module):
-    study_folder = setup_module
-    study = GroundTruthStudy(study_folder)
-    print(study)
-
-    study.run_sorters(verbose=True)
-
-    print(study.sortings)
-
-    print(study.comparisons)
-    study.run_comparisons()
-    print(study.comparisons)
-
-    study.create_sorting_analyzer_gt(n_jobs=-1)
-
-    study.compute_metrics()
-
-    for key in study.cases:
-        metrics = study.get_metrics(key)
-        print(metrics)
-
-    study.get_performance_by_unit()
-    study.get_count_units()
-
-
-if __name__ == "__main__":
-    setup_module()
-    test_GroundTruthStudy()

From 066caa038f2048393d33e82e10dfbd1786794c25 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 11 Sep 2024 18:17:27 +0200
Subject: [PATCH 009/344] Move components benchmarks

---
 .../benchmark/benchmark_clustering.py                    | 3 +--
 .../benchmark/benchmark_matching.py                      | 5 +----
 .../benchmark/benchmark_motion_estimation.py             | 3 ++-
 .../benchmark/benchmark_motion_interpolation.py          | 2 +-
 .../benchmark/benchmark_peak_detection.py                | 3 +--
 .../benchmark/benchmark_peak_localization.py             | 2 +-
 .../benchmark/benchmark_peak_selection.py                | 9 +--------
 .../{sortingcomponents => }/benchmark/benchmark_tools.py | 0
 .../benchmark/tests/common_benchmark_testing.py          | 0
 .../benchmark/tests/test_benchmark_clustering.py         | 0
 .../benchmark/tests/test_benchmark_matching.py           | 0
 .../benchmark/tests/test_benchmark_motion_estimation.py  | 0
 .../tests/test_benchmark_motion_interpolation.py         | 0
 .../benchmark/tests/test_benchmark_peak_detection.py     | 0
 .../benchmark/tests/test_benchmark_peak_localization.py  | 0
 .../benchmark/tests/test_benchmark_peak_selection.py     | 0
 .../sortingcomponents/benchmark/__init__.py              | 6 ------
 17 files changed, 8 insertions(+), 25 deletions(-)
 rename src/spikeinterface/{sortingcomponents => }/benchmark/benchmark_clustering.py (99%)
 rename src/spikeinterface/{sortingcomponents => }/benchmark/benchmark_matching.py (97%)
 rename src/spikeinterface/{sortingcomponents => }/benchmark/benchmark_motion_estimation.py (99%)
 rename src/spikeinterface/{sortingcomponents => }/benchmark/benchmark_motion_interpolation.py (98%)
 rename src/spikeinterface/{sortingcomponents => }/benchmark/benchmark_peak_detection.py (98%)
 rename src/spikeinterface/{sortingcomponents => }/benchmark/benchmark_peak_localization.py (99%)
 rename src/spikeinterface/{sortingcomponents => }/benchmark/benchmark_peak_selection.py (98%)
 rename src/spikeinterface/{sortingcomponents => }/benchmark/benchmark_tools.py (100%)
 rename src/spikeinterface/{sortingcomponents => }/benchmark/tests/common_benchmark_testing.py (100%)
 rename src/spikeinterface/{sortingcomponents => }/benchmark/tests/test_benchmark_clustering.py (100%)
 rename src/spikeinterface/{sortingcomponents => }/benchmark/tests/test_benchmark_matching.py (100%)
 rename src/spikeinterface/{sortingcomponents => }/benchmark/tests/test_benchmark_motion_estimation.py (100%)
 rename src/spikeinterface/{sortingcomponents => }/benchmark/tests/test_benchmark_motion_interpolation.py (100%)
 rename src/spikeinterface/{sortingcomponents => }/benchmark/tests/test_benchmark_peak_detection.py (100%)
 rename src/spikeinterface/{sortingcomponents => }/benchmark/tests/test_benchmark_peak_localization.py (100%)
 rename src/spikeinterface/{sortingcomponents => }/benchmark/tests/test_benchmark_peak_selection.py (100%)
 delete mode 100644 src/spikeinterface/sortingcomponents/benchmark/__init__.py

diff --git a/src/spikeinterface/sortingcomponents/benchmark/benchmark_clustering.py b/src/spikeinterface/benchmark/benchmark_clustering.py
similarity index 99%
rename from src/spikeinterface/sortingcomponents/benchmark/benchmark_clustering.py
rename to src/spikeinterface/benchmark/benchmark_clustering.py
index 92fcda35d9..94fcafef6e 100644
--- a/src/spikeinterface/sortingcomponents/benchmark/benchmark_clustering.py
+++ b/src/spikeinterface/benchmark/benchmark_clustering.py
@@ -11,8 +11,7 @@
 
 import numpy as np
 
-
-from .benchmark_tools import BenchmarkStudy, Benchmark
+from .benchmark_base import Benchmark, BenchmarkStudy
 from spikeinterface.core.sortinganalyzer import create_sorting_analyzer
 from spikeinterface.core.template_tools import get_template_extremum_channel
 
diff --git a/src/spikeinterface/sortingcomponents/benchmark/benchmark_matching.py b/src/spikeinterface/benchmark/benchmark_matching.py
similarity index 97%
rename from src/spikeinterface/sortingcomponents/benchmark/benchmark_matching.py
rename to src/spikeinterface/benchmark/benchmark_matching.py
index ab1523d13a..6edb504a84 100644
--- a/src/spikeinterface/sortingcomponents/benchmark/benchmark_matching.py
+++ b/src/spikeinterface/benchmark/benchmark_matching.py
@@ -9,11 +9,8 @@
 )
 
 import numpy as np
-from spikeinterface.sortingcomponents.benchmark.benchmark_tools import Benchmark, BenchmarkStudy
+from .benchmark_base import Benchmark, BenchmarkStudy
 from spikeinterface.core.basesorting import minimum_spike_dtype
-from spikeinterface.sortingcomponents.tools import remove_empty_templates
-from spikeinterface.core.recording_tools import get_noise_levels
-from spikeinterface.core.sparsity import compute_sparsity
 
 
 class MatchingBenchmark(Benchmark):
diff --git a/src/spikeinterface/sortingcomponents/benchmark/benchmark_motion_estimation.py b/src/spikeinterface/benchmark/benchmark_motion_estimation.py
similarity index 99%
rename from src/spikeinterface/sortingcomponents/benchmark/benchmark_motion_estimation.py
rename to src/spikeinterface/benchmark/benchmark_motion_estimation.py
index ec7e1e24a8..abb2a51bae 100644
--- a/src/spikeinterface/sortingcomponents/benchmark/benchmark_motion_estimation.py
+++ b/src/spikeinterface/benchmark/benchmark_motion_estimation.py
@@ -8,7 +8,8 @@
 import numpy as np
 
 from spikeinterface.core import get_noise_levels
-from spikeinterface.sortingcomponents.benchmark.benchmark_tools import Benchmark, BenchmarkStudy, _simpleaxis
+from .benchmark_base import Benchmark, BenchmarkStudy
+from .benchmark_plot_tools import _simpleaxis
 from spikeinterface.sortingcomponents.motion import estimate_motion
 from spikeinterface.sortingcomponents.peak_detection import detect_peaks
 from spikeinterface.sortingcomponents.peak_selection import select_peaks
diff --git a/src/spikeinterface/sortingcomponents/benchmark/benchmark_motion_interpolation.py b/src/spikeinterface/benchmark/benchmark_motion_interpolation.py
similarity index 98%
rename from src/spikeinterface/sortingcomponents/benchmark/benchmark_motion_interpolation.py
rename to src/spikeinterface/benchmark/benchmark_motion_interpolation.py
index 38365adfd1..ab72a1f9bd 100644
--- a/src/spikeinterface/sortingcomponents/benchmark/benchmark_motion_interpolation.py
+++ b/src/spikeinterface/benchmark/benchmark_motion_interpolation.py
@@ -10,7 +10,7 @@
 from spikeinterface.curation import MergeUnitsSorting
 
 
-from spikeinterface.sortingcomponents.benchmark.benchmark_tools import Benchmark, BenchmarkStudy, _simpleaxis
+from .benchmark_base import Benchmark, BenchmarkStudy
 
 
 class MotionInterpolationBenchmark(Benchmark):
diff --git a/src/spikeinterface/sortingcomponents/benchmark/benchmark_peak_detection.py b/src/spikeinterface/benchmark/benchmark_peak_detection.py
similarity index 98%
rename from src/spikeinterface/sortingcomponents/benchmark/benchmark_peak_detection.py
rename to src/spikeinterface/benchmark/benchmark_peak_detection.py
index 7d862343d2..77b5e0025c 100644
--- a/src/spikeinterface/sortingcomponents/benchmark/benchmark_peak_detection.py
+++ b/src/spikeinterface/benchmark/benchmark_peak_detection.py
@@ -12,10 +12,9 @@
 
 import numpy as np
 
-from spikeinterface.sortingcomponents.benchmark.benchmark_tools import Benchmark, BenchmarkStudy
+from .benchmark_base import Benchmark, BenchmarkStudy
 from spikeinterface.core.basesorting import minimum_spike_dtype
 from spikeinterface.core.sortinganalyzer import create_sorting_analyzer
-from spikeinterface.core.template_tools import get_template_extremum_channel
 
 
 class PeakDetectionBenchmark(Benchmark):
diff --git a/src/spikeinterface/sortingcomponents/benchmark/benchmark_peak_localization.py b/src/spikeinterface/benchmark/benchmark_peak_localization.py
similarity index 99%
rename from src/spikeinterface/sortingcomponents/benchmark/benchmark_peak_localization.py
rename to src/spikeinterface/benchmark/benchmark_peak_localization.py
index 05d142113b..399729fa29 100644
--- a/src/spikeinterface/sortingcomponents/benchmark/benchmark_peak_localization.py
+++ b/src/spikeinterface/benchmark/benchmark_peak_localization.py
@@ -6,7 +6,7 @@
     compute_grid_convolution,
 )
 import numpy as np
-from spikeinterface.sortingcomponents.benchmark.benchmark_tools import Benchmark, BenchmarkStudy
+from .benchmark_base import Benchmark, BenchmarkStudy
 from spikeinterface.core.sortinganalyzer import create_sorting_analyzer
 
 
diff --git a/src/spikeinterface/sortingcomponents/benchmark/benchmark_peak_selection.py b/src/spikeinterface/benchmark/benchmark_peak_selection.py
similarity index 98%
rename from src/spikeinterface/sortingcomponents/benchmark/benchmark_peak_selection.py
rename to src/spikeinterface/benchmark/benchmark_peak_selection.py
index 008de2d931..7abeaaacc9 100644
--- a/src/spikeinterface/sortingcomponents/benchmark/benchmark_peak_selection.py
+++ b/src/spikeinterface/benchmark/benchmark_peak_selection.py
@@ -6,16 +6,9 @@
 from spikeinterface.comparison.comparisontools import make_matching_events
 from spikeinterface.core import get_noise_levels
 
-import time
-import string, random
-import pylab as plt
-import os
 import numpy as np
 
-from spikeinterface.sortingcomponents.benchmark.benchmark_tools import Benchmark, BenchmarkStudy
-from spikeinterface.core.basesorting import minimum_spike_dtype
-from spikeinterface.core.sortinganalyzer import create_sorting_analyzer
-
+from .benchmark_base import Benchmark, BenchmarkStudy
 
 class PeakSelectionBenchmark(Benchmark):
 
diff --git a/src/spikeinterface/sortingcomponents/benchmark/benchmark_tools.py b/src/spikeinterface/benchmark/benchmark_tools.py
similarity index 100%
rename from src/spikeinterface/sortingcomponents/benchmark/benchmark_tools.py
rename to src/spikeinterface/benchmark/benchmark_tools.py
diff --git a/src/spikeinterface/sortingcomponents/benchmark/tests/common_benchmark_testing.py b/src/spikeinterface/benchmark/tests/common_benchmark_testing.py
similarity index 100%
rename from src/spikeinterface/sortingcomponents/benchmark/tests/common_benchmark_testing.py
rename to src/spikeinterface/benchmark/tests/common_benchmark_testing.py
diff --git a/src/spikeinterface/sortingcomponents/benchmark/tests/test_benchmark_clustering.py b/src/spikeinterface/benchmark/tests/test_benchmark_clustering.py
similarity index 100%
rename from src/spikeinterface/sortingcomponents/benchmark/tests/test_benchmark_clustering.py
rename to src/spikeinterface/benchmark/tests/test_benchmark_clustering.py
diff --git a/src/spikeinterface/sortingcomponents/benchmark/tests/test_benchmark_matching.py b/src/spikeinterface/benchmark/tests/test_benchmark_matching.py
similarity index 100%
rename from src/spikeinterface/sortingcomponents/benchmark/tests/test_benchmark_matching.py
rename to src/spikeinterface/benchmark/tests/test_benchmark_matching.py
diff --git a/src/spikeinterface/sortingcomponents/benchmark/tests/test_benchmark_motion_estimation.py b/src/spikeinterface/benchmark/tests/test_benchmark_motion_estimation.py
similarity index 100%
rename from src/spikeinterface/sortingcomponents/benchmark/tests/test_benchmark_motion_estimation.py
rename to src/spikeinterface/benchmark/tests/test_benchmark_motion_estimation.py
diff --git a/src/spikeinterface/sortingcomponents/benchmark/tests/test_benchmark_motion_interpolation.py b/src/spikeinterface/benchmark/tests/test_benchmark_motion_interpolation.py
similarity index 100%
rename from src/spikeinterface/sortingcomponents/benchmark/tests/test_benchmark_motion_interpolation.py
rename to src/spikeinterface/benchmark/tests/test_benchmark_motion_interpolation.py
diff --git a/src/spikeinterface/sortingcomponents/benchmark/tests/test_benchmark_peak_detection.py b/src/spikeinterface/benchmark/tests/test_benchmark_peak_detection.py
similarity index 100%
rename from src/spikeinterface/sortingcomponents/benchmark/tests/test_benchmark_peak_detection.py
rename to src/spikeinterface/benchmark/tests/test_benchmark_peak_detection.py
diff --git a/src/spikeinterface/sortingcomponents/benchmark/tests/test_benchmark_peak_localization.py b/src/spikeinterface/benchmark/tests/test_benchmark_peak_localization.py
similarity index 100%
rename from src/spikeinterface/sortingcomponents/benchmark/tests/test_benchmark_peak_localization.py
rename to src/spikeinterface/benchmark/tests/test_benchmark_peak_localization.py
diff --git a/src/spikeinterface/sortingcomponents/benchmark/tests/test_benchmark_peak_selection.py b/src/spikeinterface/benchmark/tests/test_benchmark_peak_selection.py
similarity index 100%
rename from src/spikeinterface/sortingcomponents/benchmark/tests/test_benchmark_peak_selection.py
rename to src/spikeinterface/benchmark/tests/test_benchmark_peak_selection.py
diff --git a/src/spikeinterface/sortingcomponents/benchmark/__init__.py b/src/spikeinterface/sortingcomponents/benchmark/__init__.py
deleted file mode 100644
index ad6d444bdb..0000000000
--- a/src/spikeinterface/sortingcomponents/benchmark/__init__.py
+++ /dev/null
@@ -1,6 +0,0 @@
-"""
-Module to benchmark some sorting components:
-  * clustering
-  * motion
-  * template matching
-"""

From d8229db234a0081d321ab4fac1ff52e5f2d1502e Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 11 Sep 2024 19:10:35 +0200
Subject: [PATCH 010/344] Fix tests.

---
 .../benchmark/benchmark_matching.py           |  1 +
 .../benchmark/benchmark_tools.py              |  2 --
 .../tests/test_benchmark_clustering.py        |  9 ++++++---
 .../tests/test_benchmark_matching.py          |  8 +++++---
 .../tests/test_benchmark_motion_estimation.py |  8 +++++---
 .../test_benchmark_motion_interpolation.py    | 11 +++++-----
 .../tests/test_benchmark_peak_detection.py    | 10 +++++-----
 .../tests/test_benchmark_peak_localization.py | 20 ++++++++++---------
 .../tests/test_benchmark_peak_selection.py    |  5 +++--
 .../benchmark/tests/test_benchmark_sorter.py  |  2 +-
 src/spikeinterface/full.py                    |  1 +
 11 files changed, 44 insertions(+), 33 deletions(-)

diff --git a/src/spikeinterface/benchmark/benchmark_matching.py b/src/spikeinterface/benchmark/benchmark_matching.py
index 6edb504a84..784b369d7f 100644
--- a/src/spikeinterface/benchmark/benchmark_matching.py
+++ b/src/spikeinterface/benchmark/benchmark_matching.py
@@ -77,6 +77,7 @@ def plot_performances_vs_snr(self, case_keys=None, figsize=None, metrics=["accur
         if case_keys is None:
             case_keys = list(self.cases.keys())
 
+        import matplotlib.pyplot as plt
         fig, axs = plt.subplots(ncols=1, nrows=len(metrics), figsize=figsize, squeeze=False)
 
         for count, k in enumerate(metrics):
diff --git a/src/spikeinterface/benchmark/benchmark_tools.py b/src/spikeinterface/benchmark/benchmark_tools.py
index 171745ac2f..e69de29bb2 100644
--- a/src/spikeinterface/benchmark/benchmark_tools.py
+++ b/src/spikeinterface/benchmark/benchmark_tools.py
@@ -1,2 +0,0 @@
-from spikeinterface.benchmark.benchmark_base import Benchmark, BenchmarkStudy
-from spikeinterface.benchmark.benchmark_plot_tools import _simpleaxis
\ No newline at end of file
diff --git a/src/spikeinterface/benchmark/tests/test_benchmark_clustering.py b/src/spikeinterface/benchmark/tests/test_benchmark_clustering.py
index bc36fb607c..3f574fd058 100644
--- a/src/spikeinterface/benchmark/tests/test_benchmark_clustering.py
+++ b/src/spikeinterface/benchmark/tests/test_benchmark_clustering.py
@@ -3,11 +3,13 @@
 
 import shutil
 
-from spikeinterface.sortingcomponents.benchmark.tests.common_benchmark_testing import make_dataset
-from spikeinterface.sortingcomponents.benchmark.benchmark_clustering import ClusteringStudy
+from spikeinterface.benchmark.tests.common_benchmark_testing import make_dataset
+from spikeinterface.benchmark.benchmark_clustering import ClusteringStudy
 from spikeinterface.core.sortinganalyzer import create_sorting_analyzer
 from spikeinterface.core.template_tools import get_template_extremum_channel
 
+from pathlib import Path
+
 
 @pytest.mark.skip()
 def test_benchmark_clustering(create_cache_folder):
@@ -78,4 +80,5 @@ def test_benchmark_clustering(create_cache_folder):
 
 
 if __name__ == "__main__":
-    test_benchmark_clustering()
+    cache_folder = Path(__file__).resolve().parents[4] / "cache_folder" / "benchmarks"
+    test_benchmark_clustering(cache_folder)
diff --git a/src/spikeinterface/benchmark/tests/test_benchmark_matching.py b/src/spikeinterface/benchmark/tests/test_benchmark_matching.py
index aa9b16bb97..eacef848f4 100644
--- a/src/spikeinterface/benchmark/tests/test_benchmark_matching.py
+++ b/src/spikeinterface/benchmark/tests/test_benchmark_matching.py
@@ -1,6 +1,7 @@
 import pytest
 
 import shutil
+from pathlib import Path
 
 
 from spikeinterface.core import (
@@ -8,11 +9,11 @@
     compute_sparsity,
 )
 
-from spikeinterface.sortingcomponents.benchmark.tests.common_benchmark_testing import (
+from spikeinterface.benchmark.tests.common_benchmark_testing import (
     make_dataset,
     compute_gt_templates,
 )
-from spikeinterface.sortingcomponents.benchmark.benchmark_matching import MatchingStudy
+from spikeinterface.benchmark.benchmark_matching import MatchingStudy
 
 
 @pytest.mark.skip()
@@ -72,4 +73,5 @@ def test_benchmark_matching(create_cache_folder):
 
 
 if __name__ == "__main__":
-    test_benchmark_matching()
+    cache_folder = Path(__file__).resolve().parents[4] / "cache_folder" / "benchmarks"
+    test_benchmark_matching(cache_folder)
diff --git a/src/spikeinterface/benchmark/tests/test_benchmark_motion_estimation.py b/src/spikeinterface/benchmark/tests/test_benchmark_motion_estimation.py
index 78a9eb7dbc..65cacfc8a0 100644
--- a/src/spikeinterface/benchmark/tests/test_benchmark_motion_estimation.py
+++ b/src/spikeinterface/benchmark/tests/test_benchmark_motion_estimation.py
@@ -2,12 +2,13 @@
 
 
 import shutil
+from pathlib import Path
 
-from spikeinterface.sortingcomponents.benchmark.tests.common_benchmark_testing import (
+from spikeinterface.benchmark.tests.common_benchmark_testing import (
     make_drifting_dataset,
 )
 
-from spikeinterface.sortingcomponents.benchmark.benchmark_motion_estimation import MotionEstimationStudy
+from spikeinterface.benchmark.benchmark_motion_estimation import MotionEstimationStudy
 
 
 @pytest.mark.skip()
@@ -75,4 +76,5 @@ def test_benchmark_motion_estimaton(create_cache_folder):
 
 
 if __name__ == "__main__":
-    test_benchmark_motion_estimaton()
+    cache_folder = Path(__file__).resolve().parents[4] / "cache_folder" / "benchmarks"
+    test_benchmark_motion_estimaton(cache_folder)
diff --git a/src/spikeinterface/benchmark/tests/test_benchmark_motion_interpolation.py b/src/spikeinterface/benchmark/tests/test_benchmark_motion_interpolation.py
index 18def37d54..f7afd7a8bc 100644
--- a/src/spikeinterface/benchmark/tests/test_benchmark_motion_interpolation.py
+++ b/src/spikeinterface/benchmark/tests/test_benchmark_motion_interpolation.py
@@ -4,14 +4,14 @@
 import numpy as np
 
 import shutil
+from pathlib import Path
 
-
-from spikeinterface.sortingcomponents.benchmark.tests.common_benchmark_testing import (
+from spikeinterface.benchmark.tests.common_benchmark_testing import (
     make_drifting_dataset,
 )
 
-from spikeinterface.sortingcomponents.benchmark.benchmark_motion_interpolation import MotionInterpolationStudy
-from spikeinterface.sortingcomponents.benchmark.benchmark_motion_estimation import (
+from spikeinterface.benchmark.benchmark_motion_interpolation import MotionInterpolationStudy
+from spikeinterface.benchmark.benchmark_motion_estimation import (
     # get_unit_displacement,
     get_gt_motion_from_unit_displacement,
 )
@@ -139,4 +139,5 @@ def test_benchmark_motion_interpolation(create_cache_folder):
 
 
 if __name__ == "__main__":
-    test_benchmark_motion_interpolation()
+    cache_folder = Path(__file__).resolve().parents[4] / "cache_folder" / "benchmarks"
+    test_benchmark_motion_interpolation(cache_folder)
diff --git a/src/spikeinterface/benchmark/tests/test_benchmark_peak_detection.py b/src/spikeinterface/benchmark/tests/test_benchmark_peak_detection.py
index dffe1529b7..d45ac0b4ce 100644
--- a/src/spikeinterface/benchmark/tests/test_benchmark_peak_detection.py
+++ b/src/spikeinterface/benchmark/tests/test_benchmark_peak_detection.py
@@ -1,10 +1,10 @@
 import pytest
 
 import shutil
+from pathlib import Path
 
-
-from spikeinterface.sortingcomponents.benchmark.tests.common_benchmark_testing import make_dataset
-from spikeinterface.sortingcomponents.benchmark.benchmark_peak_detection import PeakDetectionStudy
+from spikeinterface.benchmark.tests.common_benchmark_testing import make_dataset
+from spikeinterface.benchmark.benchmark_peak_detection import PeakDetectionStudy
 from spikeinterface.core.sortinganalyzer import create_sorting_analyzer
 from spikeinterface.core.template_tools import get_template_extremum_channel
 
@@ -69,5 +69,5 @@ def test_benchmark_peak_detection(create_cache_folder):
 
 
 if __name__ == "__main__":
-    # test_benchmark_peak_localization()
-    test_benchmark_peak_detection()
+    cache_folder = Path(__file__).resolve().parents[4] / "cache_folder" / "benchmarks"
+    test_benchmark_peak_detection(cache_folder)
diff --git a/src/spikeinterface/benchmark/tests/test_benchmark_peak_localization.py b/src/spikeinterface/benchmark/tests/test_benchmark_peak_localization.py
index 23060c4ddb..3b6240cb10 100644
--- a/src/spikeinterface/benchmark/tests/test_benchmark_peak_localization.py
+++ b/src/spikeinterface/benchmark/tests/test_benchmark_peak_localization.py
@@ -1,12 +1,12 @@
 import pytest
 
 import shutil
+from pathlib import Path
 
+from spikeinterface.benchmark.tests.common_benchmark_testing import make_dataset
 
-from spikeinterface.sortingcomponents.benchmark.tests.common_benchmark_testing import make_dataset
-
-from spikeinterface.sortingcomponents.benchmark.benchmark_peak_localization import PeakLocalizationStudy
-from spikeinterface.sortingcomponents.benchmark.benchmark_peak_localization import UnitLocalizationStudy
+from spikeinterface.benchmark.benchmark_peak_localization import PeakLocalizationStudy
+from spikeinterface.benchmark.benchmark_peak_localization import UnitLocalizationStudy
 
 
 @pytest.mark.skip()
@@ -28,7 +28,8 @@ def test_benchmark_peak_localization(create_cache_folder):
             "init_kwargs": {"gt_positions": gt_sorting.get_property("gt_unit_locations")},
             "params": {
                 "method": method,
-                "method_kwargs": {"ms_before": 2},
+                "ms_before": 2.0,
+                "method_kwargs": {},
             },
         }
 
@@ -60,7 +61,7 @@ def test_benchmark_unit_locations(create_cache_folder):
     cache_folder = create_cache_folder
     job_kwargs = dict(n_jobs=0.8, chunk_duration="100ms")
 
-    recording, gt_sorting = make_dataset()
+    recording, gt_sorting, gt_analyzer = make_dataset()
 
     # create study
     study_folder = cache_folder / "study_unit_locations"
@@ -71,7 +72,7 @@ def test_benchmark_unit_locations(create_cache_folder):
             "label": f"{method} on toy",
             "dataset": "toy",
             "init_kwargs": {"gt_positions": gt_sorting.get_property("gt_unit_locations")},
-            "params": {"method": method, "method_kwargs": {"ms_before": 2}},
+            "params": {"method": method, "ms_before": 2.0, "method_kwargs": {}},
         }
 
     if study_folder.exists():
@@ -99,5 +100,6 @@ def test_benchmark_unit_locations(create_cache_folder):
 
 
 if __name__ == "__main__":
-    # test_benchmark_peak_localization()
-    test_benchmark_unit_locations()
+    cache_folder = Path(__file__).resolve().parents[4] / "cache_folder" / "benchmarks"
+    # test_benchmark_peak_localization(cache_folder)
+    test_benchmark_unit_locations(cache_folder)
diff --git a/src/spikeinterface/benchmark/tests/test_benchmark_peak_selection.py b/src/spikeinterface/benchmark/tests/test_benchmark_peak_selection.py
index a9e404292d..92ed0f94ae 100644
--- a/src/spikeinterface/benchmark/tests/test_benchmark_peak_selection.py
+++ b/src/spikeinterface/benchmark/tests/test_benchmark_peak_selection.py
@@ -1,11 +1,12 @@
 import pytest
 
+from pathlib import Path
 
 @pytest.mark.skip()
 def test_benchmark_peak_selection(create_cache_folder):
     cache_folder = create_cache_folder
-    pass
 
 
 if __name__ == "__main__":
-    test_benchmark_peak_selection()
+    cache_folder = Path(__file__).resolve().parents[4] / "cache_folder" / "benchmarks"
+    test_benchmark_peak_selection(cache_folder)
diff --git a/src/spikeinterface/benchmark/tests/test_benchmark_sorter.py b/src/spikeinterface/benchmark/tests/test_benchmark_sorter.py
index 7fad1b6e8b..50308f8df7 100644
--- a/src/spikeinterface/benchmark/tests/test_benchmark_sorter.py
+++ b/src/spikeinterface/benchmark/tests/test_benchmark_sorter.py
@@ -86,5 +86,5 @@ def test_SorterStudy(setup_module):
 
 if __name__ == "__main__":
     study_folder = Path(__file__).resolve().parents[4] / "cache_folder" / "benchmarks" / "test_SorterStudy"
-    # create_a_study(study_folder)
+    create_a_study(study_folder)
     test_SorterStudy(study_folder)
diff --git a/src/spikeinterface/full.py b/src/spikeinterface/full.py
index 0cd0fb0fb5..b9410bc021 100644
--- a/src/spikeinterface/full.py
+++ b/src/spikeinterface/full.py
@@ -25,3 +25,4 @@
 from .widgets import *
 from .exporters import *
 from .generation import *
+from .benchmark import *

From ce7338e1bef86448c8c94bbde070745a83070592 Mon Sep 17 00:00:00 2001
From: Heberto Mayorquin <h.mayorquin@gmail.com>
Date: Thu, 12 Sep 2024 09:28:09 -0600
Subject: [PATCH 011/344] expose reading attempts

---
 .../extractors/neoextractors/plexon2.py           | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/src/spikeinterface/extractors/neoextractors/plexon2.py b/src/spikeinterface/extractors/neoextractors/plexon2.py
index 2f360ed864..7a5f463fef 100644
--- a/src/spikeinterface/extractors/neoextractors/plexon2.py
+++ b/src/spikeinterface/extractors/neoextractors/plexon2.py
@@ -28,6 +28,10 @@ class Plexon2RecordingExtractor(NeoBaseRecordingExtractor):
             ids: ["source3.1" , "source3.2", "source3.3", "source3.4"]
     all_annotations : bool, default: False
         Load exhaustively all annotations from neo.
+    readding_attemps : int, default: 25
+        Number of attempts to read the file before raising an error
+        This opening process is somewhat unreliable and might fail occasionally. Adjust this higher
+        if you encounter problems in opening the file.
 
     Examples
     --------
@@ -37,7 +41,15 @@ class Plexon2RecordingExtractor(NeoBaseRecordingExtractor):
 
     NeoRawIOClass = "Plexon2RawIO"
 
-    def __init__(self, file_path, stream_id=None, stream_name=None, use_names_as_ids=True, all_annotations=False):
+    def __init__(
+        self,
+        file_path,
+        stream_id=None,
+        stream_name=None,
+        use_names_as_ids=True,
+        all_annotations=False,
+        readding_attemps: int = 25,
+    ):
         neo_kwargs = self.map_to_neo_kwargs(file_path)
         NeoBaseRecordingExtractor.__init__(
             self,
@@ -45,6 +57,7 @@ def __init__(self, file_path, stream_id=None, stream_name=None, use_names_as_ids
             stream_name=stream_name,
             all_annotations=all_annotations,
             use_names_as_ids=use_names_as_ids,
+            readding_attemps=readding_attemps,
             **neo_kwargs,
         )
         self._kwargs.update({"file_path": str(file_path)})

From 98cd18d7d7dca067a20eb626067fd90ae784a7b8 Mon Sep 17 00:00:00 2001
From: Heberto Mayorquin <h.mayorquin@gmail.com>
Date: Thu, 12 Sep 2024 10:06:22 -0600
Subject: [PATCH 012/344] take into account neo version

---
 .../extractors/neoextractors/plexon2.py         | 17 +++++++++++++----
 .../extractors/tests/test_neoextractors.py      |  2 +-
 2 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/src/spikeinterface/extractors/neoextractors/plexon2.py b/src/spikeinterface/extractors/neoextractors/plexon2.py
index 7a5f463fef..1f0d40a253 100644
--- a/src/spikeinterface/extractors/neoextractors/plexon2.py
+++ b/src/spikeinterface/extractors/neoextractors/plexon2.py
@@ -48,23 +48,32 @@ def __init__(
         stream_name=None,
         use_names_as_ids=True,
         all_annotations=False,
-        readding_attemps: int = 25,
+        reading_attempts: int = 25,
     ):
-        neo_kwargs = self.map_to_neo_kwargs(file_path)
+        neo_kwargs = self.map_to_neo_kwargs(file_path, reading_attempts=reading_attempts)
         NeoBaseRecordingExtractor.__init__(
             self,
             stream_id=stream_id,
             stream_name=stream_name,
             all_annotations=all_annotations,
             use_names_as_ids=use_names_as_ids,
-            readding_attemps=readding_attemps,
             **neo_kwargs,
         )
         self._kwargs.update({"file_path": str(file_path)})
 
     @classmethod
-    def map_to_neo_kwargs(cls, file_path):
+    def map_to_neo_kwargs(cls, file_path, reading_attempts: int = 25):
+
         neo_kwargs = {"filename": str(file_path)}
+
+        from packaging.version import Version
+        import neo
+
+        neo_version = Version(neo.__version__)
+
+        if neo_version > Version("0.13.3"):
+            neo_kwargs["reading_attempts"] = reading_attempts
+
         return neo_kwargs
 
 
diff --git a/src/spikeinterface/extractors/tests/test_neoextractors.py b/src/spikeinterface/extractors/tests/test_neoextractors.py
index acd7ebe8ad..33d02fbde2 100644
--- a/src/spikeinterface/extractors/tests/test_neoextractors.py
+++ b/src/spikeinterface/extractors/tests/test_neoextractors.py
@@ -359,7 +359,7 @@ class Plexon2RecordingTest(RecordingCommonTestSuite, unittest.TestCase):
     ExtractorClass = Plexon2RecordingExtractor
     downloads = ["plexon"]
     entities = [
-        ("plexon/4chDemoPL2.pl2", {"stream_id": "3"}),
+        ("plexon/4chDemoPL2.pl2", {"stream_name": "WB-Wideband"}),
     ]
 
 

From 68d143add708dc935cdeb67e2de9e86ead97ab28 Mon Sep 17 00:00:00 2001
From: Sebastien <pierre.yger@gmail.com>
Date: Fri, 13 Sep 2024 10:55:23 +0200
Subject: [PATCH 013/344] WIP

---
 .../postprocessing/template_similarity.py     | 207 +++++++++++++-----
 1 file changed, 152 insertions(+), 55 deletions(-)

diff --git a/src/spikeinterface/postprocessing/template_similarity.py b/src/spikeinterface/postprocessing/template_similarity.py
index 0e70b1f494..1f1325cf10 100644
--- a/src/spikeinterface/postprocessing/template_similarity.py
+++ b/src/spikeinterface/postprocessing/template_similarity.py
@@ -7,6 +7,13 @@
 from ..core.template_tools import get_dense_templates_array
 from ..core.sparsity import ChannelSparsity
 
+try:
+    import numba
+
+    HAVE_NUMBA = True
+except ImportError:
+    HAVE_NUMBA = False
+
 
 class ComputeTemplateSimilarity(AnalyzerExtension):
     """Compute similarity between templates with several methods.
@@ -147,10 +154,149 @@ def _get_data(self):
 compute_template_similarity = ComputeTemplateSimilarity.function_factory()
 
 
+if HAVE_NUMBA:
+    
+    from numba import prange
+
+
+    @numba.jit(nopython=True, parallel=True, fastmath=True, cache=True, nogil=True)
+    def _compute_similarity_matrix(
+        templates_array, other_templates_array, num_shifts, mask, method 
+    ):
+        num_templates = templates_array.shape[0]
+        num_samples = templates_array.shape[1]
+        other_num_templates = other_templates_array.shape[0]
+
+        num_shifts_both_sides = 2 * num_shifts + 1
+        distances = np.ones((num_shifts_both_sides, num_templates, other_num_templates), dtype=np.float32)
+        same_array = np.array_equal(templates_array, other_templates_array)
+
+        # We can use the fact that dist[i,j] at lag t is equal to dist[j,i] at time -t
+        # So the matrix can be computed only for negative lags and be transposed
+
+        if same_array:
+            # optimisation when array are the same because of symetry in shift
+            shift_loop = range(-num_shifts, 1)
+        else:
+            shift_loop = range(-num_shifts, num_shifts + 1)
+        
+        for count, shift in enumerate(shift_loop):
+            src_sliced_templates = templates_array[:, num_shifts : num_samples - num_shifts]
+            tgt_sliced_templates = other_templates_array[:, num_shifts + shift : num_samples - num_shifts + shift]
+            for i in prange(num_templates):
+                src_template = src_sliced_templates[i]
+                overlapping_templates = np.flatnonzero(np.sum(mask[i], 1))
+                tgt_templates = tgt_sliced_templates[overlapping_templates]
+                for gcount, j in enumerate(overlapping_templates):
+
+                    # symmetric values are handled later
+                    if same_array and j < i:
+                        # no need exhaustive looping when same template
+                        continue
+                    src = src_template[:, mask[i, j]].flatten()
+                    tgt = (tgt_templates[gcount][:, mask[i, j]]).flatten()
+
+                    norm_i = 0
+                    norm_j = 0
+
+                    for k in range(len(src)):
+                        if method == "l1":
+                            norm_i += abs(src[k])
+                            norm_j += abs(tgt[k])
+                            distances[count, i, j] += abs(src[k] - tgt[k])
+                        elif method == "l2":
+                            norm_i += src[k]**2
+                            norm_j += tgt[k]**2
+                            distances[count, i, j] += (src[k] - tgt[k])**2
+                        elif method == "cosine":
+                            distances[count, i, j] += src[k]*tgt[k]
+                            norm_i += src[k]**2
+                            norm_j += tgt[k]**2
+
+                    if method == "l1":
+                        distances[count, i, j] /= (norm_i + norm_j)
+                    elif method == "l2":
+                        norm_i = np.sqrt(norm_i)
+                        norm_j = np.sqrt(norm_j)
+                        distances[count, i, j] = np.sqrt(distances[count, i, j])
+                        distances[count, i, j] /= (norm_i + norm_j)
+                    elif method == "cosine":
+                        norm_i = np.sqrt(norm_i)
+                        norm_j = np.sqrt(norm_j)
+                        distances[count, i, j] /= (norm_i*norm_j)
+
+                    if same_array:
+                        distances[count, j, i] = distances[count, i, j]
+
+            if same_array and num_shifts != 0:
+                distances[num_shifts_both_sides - count - 1] = distances[count].T
+        return distances
+
+else:
+    def _compute_similarity_matrix(
+        templates_array, other_templates_array, num_shifts, mask, method 
+    ):
+        import sklearn.metrics.pairwise
+        num_templates = templates_array.shape[0]
+        num_samples = templates_array.shape[1]
+        other_num_templates = other_templates_array.shape[0]
+
+        num_shifts_both_sides = 2 * num_shifts + 1
+        distances = np.ones((num_shifts_both_sides, num_templates, other_num_templates), dtype=np.float32)
+        same_array = np.array_equal(templates_array, other_templates_array)
+
+        # We can use the fact that dist[i,j] at lag t is equal to dist[j,i] at time -t
+        # So the matrix can be computed only for negative lags and be transposed
+
+        if same_array:
+            # optimisation when array are the same because of symetry in shift
+            shift_loop = range(-num_shifts, 1)
+        else:
+            shift_loop = range(-num_shifts, num_shifts + 1)
+
+        for count, shift in enumerate(shift_loop):
+            src_sliced_templates = templates_array[:, num_shifts : num_samples - num_shifts]
+            tgt_sliced_templates = other_templates_array[:, num_shifts + shift : num_samples - num_shifts + shift]
+            for i in range(num_templates):
+                src_template = src_sliced_templates[i]
+                overlapping_templates = np.flatnonzero(np.sum(mask[i], 1))
+                tgt_templates = tgt_sliced_templates[overlapping_templates]
+                for gcount, j in enumerate(overlapping_templates):
+                    # symmetric values are handled later
+                    if same_array and j < i:
+                        # no need exhaustive looping when same template
+                        continue
+                    src = src_template[:, mask[i, j]].reshape(1, -1)
+                    tgt = (tgt_templates[gcount][:, mask[i, j]]).reshape(1, -1)
+
+                    if method == "l1":
+                        norm_i = np.sum(np.abs(src))
+                        norm_j = np.sum(np.abs(tgt))
+                        distances[count, i, j] = sklearn.metrics.pairwise.pairwise_distances(src, tgt, metric="l1").item()
+                        distances[count, i, j] /= norm_i + norm_j
+                    elif method == "l2":
+                        norm_i = np.linalg.norm(src, ord=2)
+                        norm_j = np.linalg.norm(tgt, ord=2)
+                        distances[count, i, j] = sklearn.metrics.pairwise.pairwise_distances(src, tgt, metric="l2").item()
+                        distances[count, i, j] /= norm_i + norm_j
+                    elif method == "cosine":
+                        distances[count, i, j] = sklearn.metrics.pairwise.pairwise_distances(
+                            src, tgt, metric="cosine"
+                        ).item()
+
+                    if same_array:
+                        distances[count, j, i] = distances[count, i, j]
+
+            if same_array and num_shifts != 0:
+                distances[num_shifts_both_sides - count - 1] = distances[count].T
+        return distances
+
+
+
 def compute_similarity_with_templates_array(
     templates_array, other_templates_array, method, support="union", num_shifts=0, sparsity=None, other_sparsity=None
 ):
-    import sklearn.metrics.pairwise
+    
 
     if method == "cosine_similarity":
         method = "cosine"
@@ -171,8 +317,6 @@ def compute_similarity_with_templates_array(
     num_channels = templates_array.shape[2]
     other_num_templates = other_templates_array.shape[0]
 
-    same_array = np.array_equal(templates_array, other_templates_array)
-
     mask = None
     if sparsity is not None and other_sparsity is not None:
         if support == "intersection":
@@ -182,63 +326,16 @@ def compute_similarity_with_templates_array(
             units_overlaps = np.sum(mask, axis=2) > 0
             mask = np.logical_or(sparsity.mask[:, np.newaxis, :], other_sparsity.mask[np.newaxis, :, :])
             mask[~units_overlaps] = False
-    if mask is not None:
-        units_overlaps = np.sum(mask, axis=2) > 0
-        overlapping_templates = {}
-        for i in range(num_templates):
-            overlapping_templates[i] = np.flatnonzero(units_overlaps[i])
     else:
         # here we make a dense mask and overlapping templates
-        overlapping_templates = {i: np.arange(other_num_templates) for i in range(num_templates)}
         mask = np.ones((num_templates, other_num_templates, num_channels), dtype=bool)
 
     assert num_shifts < num_samples, "max_lag is too large"
-    num_shifts_both_sides = 2 * num_shifts + 1
-    distances = np.ones((num_shifts_both_sides, num_templates, other_num_templates), dtype=np.float32)
-
-    # We can use the fact that dist[i,j] at lag t is equal to dist[j,i] at time -t
-    # So the matrix can be computed only for negative lags and be transposed
-
-    if same_array:
-        # optimisation when array are the same because of symetry in shift
-        shift_loop = range(-num_shifts, 1)
-    else:
-        shift_loop = range(-num_shifts, num_shifts + 1)
-
-    for count, shift in enumerate(shift_loop):
-        src_sliced_templates = templates_array[:, num_shifts : num_samples - num_shifts]
-        tgt_sliced_templates = other_templates_array[:, num_shifts + shift : num_samples - num_shifts + shift]
-        for i in range(num_templates):
-            src_template = src_sliced_templates[i]
-            tgt_templates = tgt_sliced_templates[overlapping_templates[i]]
-            for gcount, j in enumerate(overlapping_templates[i]):
-                # symmetric values are handled later
-                if same_array and j < i:
-                    # no need exhaustive looping when same template
-                    continue
-                src = src_template[:, mask[i, j]].reshape(1, -1)
-                tgt = (tgt_templates[gcount][:, mask[i, j]]).reshape(1, -1)
-
-                if method == "l1":
-                    norm_i = np.sum(np.abs(src))
-                    norm_j = np.sum(np.abs(tgt))
-                    distances[count, i, j] = sklearn.metrics.pairwise.pairwise_distances(src, tgt, metric="l1").item()
-                    distances[count, i, j] /= norm_i + norm_j
-                elif method == "l2":
-                    norm_i = np.linalg.norm(src, ord=2)
-                    norm_j = np.linalg.norm(tgt, ord=2)
-                    distances[count, i, j] = sklearn.metrics.pairwise.pairwise_distances(src, tgt, metric="l2").item()
-                    distances[count, i, j] /= norm_i + norm_j
-                else:
-                    distances[count, i, j] = sklearn.metrics.pairwise.pairwise_distances(
-                        src, tgt, metric="cosine"
-                    ).item()
-
-                if same_array:
-                    distances[count, j, i] = distances[count, i, j]
-
-        if same_array and num_shifts != 0:
-            distances[num_shifts_both_sides - count - 1] = distances[count].T
+    distances = _compute_similarity_matrix(templates_array, 
+                                           other_templates_array, 
+                                           num_shifts, 
+                                           mask, 
+                                           method)
 
     distances = np.min(distances, axis=0)
     similarity = 1 - distances

From 9184a34bfae5717699c7835a94acc5cda0c162f1 Mon Sep 17 00:00:00 2001
From: Sebastien <pierre.yger@gmail.com>
Date: Fri, 13 Sep 2024 11:11:43 +0200
Subject: [PATCH 014/344] prange and parallelism in numba

---
 src/spikeinterface/postprocessing/correlograms.py        | 3 ++-
 src/spikeinterface/postprocessing/isi.py                 | 1 +
 src/spikeinterface/postprocessing/template_similarity.py | 5 +----
 src/spikeinterface/sortingcomponents/matching/tdc.py     | 2 +-
 4 files changed, 5 insertions(+), 6 deletions(-)

diff --git a/src/spikeinterface/postprocessing/correlograms.py b/src/spikeinterface/postprocessing/correlograms.py
index ba12a5c462..88d664f059 100644
--- a/src/spikeinterface/postprocessing/correlograms.py
+++ b/src/spikeinterface/postprocessing/correlograms.py
@@ -439,6 +439,7 @@ def _compute_correlograms_numba(sorting, window_size, bin_size):
         nopython=True,
         nogil=True,
         cache=False,
+        parallel=True
     )
     def _compute_correlograms_one_segment_numba(
         correlograms, spike_times, spike_unit_indices, window_size, bin_size, num_half_bins
@@ -472,7 +473,7 @@ def _compute_correlograms_one_segment_numba(
             The size of which to bin lags, in samples.
         """
         start_j = 0
-        for i in range(spike_times.size):
+        for i in numba.prange(spike_times.size):
             for j in range(start_j, spike_times.size):
 
                 if i == j:
diff --git a/src/spikeinterface/postprocessing/isi.py b/src/spikeinterface/postprocessing/isi.py
index 542f829f21..b526a54413 100644
--- a/src/spikeinterface/postprocessing/isi.py
+++ b/src/spikeinterface/postprocessing/isi.py
@@ -186,6 +186,7 @@ def compute_isi_histograms_numba(sorting, window_ms: float = 50.0, bin_ms: float
         nopython=True,
         nogil=True,
         cache=False,
+        parallel=True
     )
     def _compute_isi_histograms_numba(ISIs, spike_trains, spike_clusters, bins):
         n_units = ISIs.shape[0]
diff --git a/src/spikeinterface/postprocessing/template_similarity.py b/src/spikeinterface/postprocessing/template_similarity.py
index 1f1325cf10..99824f3f43 100644
--- a/src/spikeinterface/postprocessing/template_similarity.py
+++ b/src/spikeinterface/postprocessing/template_similarity.py
@@ -155,9 +155,6 @@ def _get_data(self):
 
 
 if HAVE_NUMBA:
-    
-    from numba import prange
-
 
     @numba.jit(nopython=True, parallel=True, fastmath=True, cache=True, nogil=True)
     def _compute_similarity_matrix(
@@ -183,7 +180,7 @@ def _compute_similarity_matrix(
         for count, shift in enumerate(shift_loop):
             src_sliced_templates = templates_array[:, num_shifts : num_samples - num_shifts]
             tgt_sliced_templates = other_templates_array[:, num_shifts + shift : num_samples - num_shifts + shift]
-            for i in prange(num_templates):
+            for i in numba.prange(num_templates):
                 src_template = src_sliced_templates[i]
                 overlapping_templates = np.flatnonzero(np.sum(mask[i], 1))
                 tgt_templates = tgt_sliced_templates[overlapping_templates]
diff --git a/src/spikeinterface/sortingcomponents/matching/tdc.py b/src/spikeinterface/sortingcomponents/matching/tdc.py
index e66929e2b1..5c145d1f25 100644
--- a/src/spikeinterface/sortingcomponents/matching/tdc.py
+++ b/src/spikeinterface/sortingcomponents/matching/tdc.py
@@ -348,7 +348,7 @@ def _tdc_find_spikes(traces, d, level=0):
 
 if HAVE_NUMBA:
 
-    @jit(nopython=True)
+    @jit(nopython=True, parallel=True)
     def numba_sparse_dist(wf, templates, union_channels, possible_clusters):
         """
         numba implementation that compute distance from template with sparsity

From 90cebc34c985dcbff6ea7de14924454a2c252342 Mon Sep 17 00:00:00 2001
From: Sebastien <pierre.yger@gmail.com>
Date: Fri, 13 Sep 2024 11:22:07 +0200
Subject: [PATCH 015/344] WIP

---
 src/spikeinterface/postprocessing/template_similarity.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/spikeinterface/postprocessing/template_similarity.py b/src/spikeinterface/postprocessing/template_similarity.py
index 99824f3f43..cf49010efd 100644
--- a/src/spikeinterface/postprocessing/template_similarity.py
+++ b/src/spikeinterface/postprocessing/template_similarity.py
@@ -221,6 +221,7 @@ def _compute_similarity_matrix(
                         norm_i = np.sqrt(norm_i)
                         norm_j = np.sqrt(norm_j)
                         distances[count, i, j] /= (norm_i*norm_j)
+                        distances[count, i, j] = 1 - distances[count, i, j]
 
                     if same_array:
                         distances[count, j, i] = distances[count, i, j]

From 04c7b02480a363c365fc36987d8b08e429daa5a1 Mon Sep 17 00:00:00 2001
From: Sebastien <pierre.yger@gmail.com>
Date: Fri, 13 Sep 2024 11:40:22 +0200
Subject: [PATCH 016/344] Removing dependencies

---
 .../postprocessing/template_similarity.py      | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/src/spikeinterface/postprocessing/template_similarity.py b/src/spikeinterface/postprocessing/template_similarity.py
index cf49010efd..25173b618c 100644
--- a/src/spikeinterface/postprocessing/template_similarity.py
+++ b/src/spikeinterface/postprocessing/template_similarity.py
@@ -10,7 +10,7 @@
 try:
     import numba
 
-    HAVE_NUMBA = True
+    HAVE_NUMBA = False
 except ImportError:
     HAVE_NUMBA = False
 
@@ -156,7 +156,7 @@ def _get_data(self):
 
 if HAVE_NUMBA:
 
-    @numba.jit(nopython=True, parallel=True, fastmath=True, cache=True, nogil=True)
+    @numba.jit(nopython=True, parallel=True, fastmath=True, nogil=True)
     def _compute_similarity_matrix(
         templates_array, other_templates_array, num_shifts, mask, method 
     ):
@@ -234,7 +234,7 @@ def _compute_similarity_matrix(
     def _compute_similarity_matrix(
         templates_array, other_templates_array, num_shifts, mask, method 
     ):
-        import sklearn.metrics.pairwise
+
         num_templates = templates_array.shape[0]
         num_samples = templates_array.shape[1]
         other_num_templates = other_templates_array.shape[0]
@@ -270,17 +270,19 @@ def _compute_similarity_matrix(
                     if method == "l1":
                         norm_i = np.sum(np.abs(src))
                         norm_j = np.sum(np.abs(tgt))
-                        distances[count, i, j] = sklearn.metrics.pairwise.pairwise_distances(src, tgt, metric="l1").item()
+                        distances[count, i, j] = np.sum(np.abs(src - tgt))
                         distances[count, i, j] /= norm_i + norm_j
                     elif method == "l2":
                         norm_i = np.linalg.norm(src, ord=2)
                         norm_j = np.linalg.norm(tgt, ord=2)
-                        distances[count, i, j] = sklearn.metrics.pairwise.pairwise_distances(src, tgt, metric="l2").item()
+                        distances[count, i, j] = np.linalg.norm(src - tgt, ord=2)
                         distances[count, i, j] /= norm_i + norm_j
                     elif method == "cosine":
-                        distances[count, i, j] = sklearn.metrics.pairwise.pairwise_distances(
-                            src, tgt, metric="cosine"
-                        ).item()
+                        norm_i = np.linalg.norm(src, ord=2)
+                        norm_j = np.linalg.norm(tgt, ord=2)
+                        distances[count, i, j] = np.sum(src*tgt)
+                        distances[count, i, j] /= norm_i * norm_j
+                        distances[count, i, j] = 1 - distances[count, i, j]
 
                     if same_array:
                         distances[count, j, i] = distances[count, i, j]

From e6e6487d369135304d247760cab84b111c9faaa9 Mon Sep 17 00:00:00 2001
From: Sebastien <pierre.yger@gmail.com>
Date: Fri, 13 Sep 2024 11:46:01 +0200
Subject: [PATCH 017/344] Default mask for dense case

---
 src/spikeinterface/postprocessing/template_similarity.py | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/src/spikeinterface/postprocessing/template_similarity.py b/src/spikeinterface/postprocessing/template_similarity.py
index 25173b618c..8540896ac3 100644
--- a/src/spikeinterface/postprocessing/template_similarity.py
+++ b/src/spikeinterface/postprocessing/template_similarity.py
@@ -10,7 +10,7 @@
 try:
     import numba
 
-    HAVE_NUMBA = False
+    HAVE_NUMBA = True
 except ImportError:
     HAVE_NUMBA = False
 
@@ -317,7 +317,8 @@ def compute_similarity_with_templates_array(
     num_channels = templates_array.shape[2]
     other_num_templates = other_templates_array.shape[0]
 
-    mask = None
+    mask = np.ones((num_templates, other_num_templates, num_channels), dtype=bool)
+
     if sparsity is not None and other_sparsity is not None:
         if support == "intersection":
             mask = np.logical_and(sparsity.mask[:, np.newaxis, :], other_sparsity.mask[np.newaxis, :, :])
@@ -326,9 +327,7 @@ def compute_similarity_with_templates_array(
             units_overlaps = np.sum(mask, axis=2) > 0
             mask = np.logical_or(sparsity.mask[:, np.newaxis, :], other_sparsity.mask[np.newaxis, :, :])
             mask[~units_overlaps] = False
-    else:
-        # here we make a dense mask and overlapping templates
-        mask = np.ones((num_templates, other_num_templates, num_channels), dtype=bool)
+        
 
     assert num_shifts < num_samples, "max_lag is too large"
     distances = _compute_similarity_matrix(templates_array, 

From 2e3a77b927691dc7418f6f72aa42d9ef0ea3a202 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Fri, 13 Sep 2024 09:50:01 +0000
Subject: [PATCH 018/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 .../postprocessing/correlograms.py            |  7 +---
 src/spikeinterface/postprocessing/isi.py      |  7 +---
 .../postprocessing/template_similarity.py     | 40 +++++++------------
 3 files changed, 17 insertions(+), 37 deletions(-)

diff --git a/src/spikeinterface/postprocessing/correlograms.py b/src/spikeinterface/postprocessing/correlograms.py
index 88d664f059..8a12e9b853 100644
--- a/src/spikeinterface/postprocessing/correlograms.py
+++ b/src/spikeinterface/postprocessing/correlograms.py
@@ -435,12 +435,7 @@ def _compute_correlograms_numba(sorting, window_size, bin_size):
 
 if HAVE_NUMBA:
 
-    @numba.jit(
-        nopython=True,
-        nogil=True,
-        cache=False,
-        parallel=True
-    )
+    @numba.jit(nopython=True, nogil=True, cache=False, parallel=True)
     def _compute_correlograms_one_segment_numba(
         correlograms, spike_times, spike_unit_indices, window_size, bin_size, num_half_bins
     ):
diff --git a/src/spikeinterface/postprocessing/isi.py b/src/spikeinterface/postprocessing/isi.py
index b526a54413..5c9e5f0346 100644
--- a/src/spikeinterface/postprocessing/isi.py
+++ b/src/spikeinterface/postprocessing/isi.py
@@ -182,12 +182,7 @@ def compute_isi_histograms_numba(sorting, window_ms: float = 50.0, bin_ms: float
 
 if HAVE_NUMBA:
 
-    @numba.jit(
-        nopython=True,
-        nogil=True,
-        cache=False,
-        parallel=True
-    )
+    @numba.jit(nopython=True, nogil=True, cache=False, parallel=True)
     def _compute_isi_histograms_numba(ISIs, spike_trains, spike_clusters, bins):
         n_units = ISIs.shape[0]
 
diff --git a/src/spikeinterface/postprocessing/template_similarity.py b/src/spikeinterface/postprocessing/template_similarity.py
index 8540896ac3..2d94746ce7 100644
--- a/src/spikeinterface/postprocessing/template_similarity.py
+++ b/src/spikeinterface/postprocessing/template_similarity.py
@@ -157,9 +157,7 @@ def _get_data(self):
 if HAVE_NUMBA:
 
     @numba.jit(nopython=True, parallel=True, fastmath=True, nogil=True)
-    def _compute_similarity_matrix(
-        templates_array, other_templates_array, num_shifts, mask, method 
-    ):
+    def _compute_similarity_matrix(templates_array, other_templates_array, num_shifts, mask, method):
         num_templates = templates_array.shape[0]
         num_samples = templates_array.shape[1]
         other_num_templates = other_templates_array.shape[0]
@@ -176,7 +174,7 @@ def _compute_similarity_matrix(
             shift_loop = range(-num_shifts, 1)
         else:
             shift_loop = range(-num_shifts, num_shifts + 1)
-        
+
         for count, shift in enumerate(shift_loop):
             src_sliced_templates = templates_array[:, num_shifts : num_samples - num_shifts]
             tgt_sliced_templates = other_templates_array[:, num_shifts + shift : num_samples - num_shifts + shift]
@@ -202,25 +200,25 @@ def _compute_similarity_matrix(
                             norm_j += abs(tgt[k])
                             distances[count, i, j] += abs(src[k] - tgt[k])
                         elif method == "l2":
-                            norm_i += src[k]**2
-                            norm_j += tgt[k]**2
-                            distances[count, i, j] += (src[k] - tgt[k])**2
+                            norm_i += src[k] ** 2
+                            norm_j += tgt[k] ** 2
+                            distances[count, i, j] += (src[k] - tgt[k]) ** 2
                         elif method == "cosine":
-                            distances[count, i, j] += src[k]*tgt[k]
-                            norm_i += src[k]**2
-                            norm_j += tgt[k]**2
+                            distances[count, i, j] += src[k] * tgt[k]
+                            norm_i += src[k] ** 2
+                            norm_j += tgt[k] ** 2
 
                     if method == "l1":
-                        distances[count, i, j] /= (norm_i + norm_j)
+                        distances[count, i, j] /= norm_i + norm_j
                     elif method == "l2":
                         norm_i = np.sqrt(norm_i)
                         norm_j = np.sqrt(norm_j)
                         distances[count, i, j] = np.sqrt(distances[count, i, j])
-                        distances[count, i, j] /= (norm_i + norm_j)
+                        distances[count, i, j] /= norm_i + norm_j
                     elif method == "cosine":
                         norm_i = np.sqrt(norm_i)
                         norm_j = np.sqrt(norm_j)
-                        distances[count, i, j] /= (norm_i*norm_j)
+                        distances[count, i, j] /= norm_i * norm_j
                         distances[count, i, j] = 1 - distances[count, i, j]
 
                     if same_array:
@@ -231,9 +229,8 @@ def _compute_similarity_matrix(
         return distances
 
 else:
-    def _compute_similarity_matrix(
-        templates_array, other_templates_array, num_shifts, mask, method 
-    ):
+
+    def _compute_similarity_matrix(templates_array, other_templates_array, num_shifts, mask, method):
 
         num_templates = templates_array.shape[0]
         num_samples = templates_array.shape[1]
@@ -280,7 +277,7 @@ def _compute_similarity_matrix(
                     elif method == "cosine":
                         norm_i = np.linalg.norm(src, ord=2)
                         norm_j = np.linalg.norm(tgt, ord=2)
-                        distances[count, i, j] = np.sum(src*tgt)
+                        distances[count, i, j] = np.sum(src * tgt)
                         distances[count, i, j] /= norm_i * norm_j
                         distances[count, i, j] = 1 - distances[count, i, j]
 
@@ -292,11 +289,9 @@ def _compute_similarity_matrix(
         return distances
 
 
-
 def compute_similarity_with_templates_array(
     templates_array, other_templates_array, method, support="union", num_shifts=0, sparsity=None, other_sparsity=None
 ):
-    
 
     if method == "cosine_similarity":
         method = "cosine"
@@ -327,14 +322,9 @@ def compute_similarity_with_templates_array(
             units_overlaps = np.sum(mask, axis=2) > 0
             mask = np.logical_or(sparsity.mask[:, np.newaxis, :], other_sparsity.mask[np.newaxis, :, :])
             mask[~units_overlaps] = False
-        
 
     assert num_shifts < num_samples, "max_lag is too large"
-    distances = _compute_similarity_matrix(templates_array, 
-                                           other_templates_array, 
-                                           num_shifts, 
-                                           mask, 
-                                           method)
+    distances = _compute_similarity_matrix(templates_array, other_templates_array, num_shifts, mask, method)
 
     distances = np.min(distances, axis=0)
     similarity = 1 - distances

From 1195022cc885458a0cf69de5539cdb437f3d418b Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Fri, 13 Sep 2024 14:11:04 +0200
Subject: [PATCH 019/344] WIP

---
 src/spikeinterface/postprocessing/correlograms.py    | 4 ++--
 src/spikeinterface/postprocessing/isi.py             | 2 +-
 src/spikeinterface/sortingcomponents/matching/tdc.py | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/spikeinterface/postprocessing/correlograms.py b/src/spikeinterface/postprocessing/correlograms.py
index 8a12e9b853..27d5703c9e 100644
--- a/src/spikeinterface/postprocessing/correlograms.py
+++ b/src/spikeinterface/postprocessing/correlograms.py
@@ -435,7 +435,7 @@ def _compute_correlograms_numba(sorting, window_size, bin_size):
 
 if HAVE_NUMBA:
 
-    @numba.jit(nopython=True, nogil=True, cache=False, parallel=True)
+    @numba.jit(nopython=True, nogil=True, cache=False)
     def _compute_correlograms_one_segment_numba(
         correlograms, spike_times, spike_unit_indices, window_size, bin_size, num_half_bins
     ):
@@ -468,7 +468,7 @@ def _compute_correlograms_one_segment_numba(
             The size of which to bin lags, in samples.
         """
         start_j = 0
-        for i in numba.prange(spike_times.size):
+        for i in range(spike_times.size):
             for j in range(start_j, spike_times.size):
 
                 if i == j:
diff --git a/src/spikeinterface/postprocessing/isi.py b/src/spikeinterface/postprocessing/isi.py
index 5c9e5f0346..1f635a8c84 100644
--- a/src/spikeinterface/postprocessing/isi.py
+++ b/src/spikeinterface/postprocessing/isi.py
@@ -182,7 +182,7 @@ def compute_isi_histograms_numba(sorting, window_ms: float = 50.0, bin_ms: float
 
 if HAVE_NUMBA:
 
-    @numba.jit(nopython=True, nogil=True, cache=False, parallel=True)
+    @numba.jit(nopython=True, nogil=True, cache=False)
     def _compute_isi_histograms_numba(ISIs, spike_trains, spike_clusters, bins):
         n_units = ISIs.shape[0]
 
diff --git a/src/spikeinterface/sortingcomponents/matching/tdc.py b/src/spikeinterface/sortingcomponents/matching/tdc.py
index 5c145d1f25..e66929e2b1 100644
--- a/src/spikeinterface/sortingcomponents/matching/tdc.py
+++ b/src/spikeinterface/sortingcomponents/matching/tdc.py
@@ -348,7 +348,7 @@ def _tdc_find_spikes(traces, d, level=0):
 
 if HAVE_NUMBA:
 
-    @jit(nopython=True, parallel=True)
+    @jit(nopython=True)
     def numba_sparse_dist(wf, templates, union_channels, possible_clusters):
         """
         numba implementation that compute distance from template with sparsity

From f4ca8fafc162ab0539440ad66f29b430311cf50c Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Fri, 13 Sep 2024 14:11:04 +0200
Subject: [PATCH 020/344] WIP

---
 src/spikeinterface/postprocessing/correlograms.py    | 8 ++++++--
 src/spikeinterface/postprocessing/isi.py             | 6 +++++-
 src/spikeinterface/sortingcomponents/matching/tdc.py | 2 +-
 3 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/src/spikeinterface/postprocessing/correlograms.py b/src/spikeinterface/postprocessing/correlograms.py
index 8a12e9b853..ba12a5c462 100644
--- a/src/spikeinterface/postprocessing/correlograms.py
+++ b/src/spikeinterface/postprocessing/correlograms.py
@@ -435,7 +435,11 @@ def _compute_correlograms_numba(sorting, window_size, bin_size):
 
 if HAVE_NUMBA:
 
-    @numba.jit(nopython=True, nogil=True, cache=False, parallel=True)
+    @numba.jit(
+        nopython=True,
+        nogil=True,
+        cache=False,
+    )
     def _compute_correlograms_one_segment_numba(
         correlograms, spike_times, spike_unit_indices, window_size, bin_size, num_half_bins
     ):
@@ -468,7 +472,7 @@ def _compute_correlograms_one_segment_numba(
             The size of which to bin lags, in samples.
         """
         start_j = 0
-        for i in numba.prange(spike_times.size):
+        for i in range(spike_times.size):
             for j in range(start_j, spike_times.size):
 
                 if i == j:
diff --git a/src/spikeinterface/postprocessing/isi.py b/src/spikeinterface/postprocessing/isi.py
index 5c9e5f0346..542f829f21 100644
--- a/src/spikeinterface/postprocessing/isi.py
+++ b/src/spikeinterface/postprocessing/isi.py
@@ -182,7 +182,11 @@ def compute_isi_histograms_numba(sorting, window_ms: float = 50.0, bin_ms: float
 
 if HAVE_NUMBA:
 
-    @numba.jit(nopython=True, nogil=True, cache=False, parallel=True)
+    @numba.jit(
+        nopython=True,
+        nogil=True,
+        cache=False,
+    )
     def _compute_isi_histograms_numba(ISIs, spike_trains, spike_clusters, bins):
         n_units = ISIs.shape[0]
 
diff --git a/src/spikeinterface/sortingcomponents/matching/tdc.py b/src/spikeinterface/sortingcomponents/matching/tdc.py
index 5c145d1f25..e66929e2b1 100644
--- a/src/spikeinterface/sortingcomponents/matching/tdc.py
+++ b/src/spikeinterface/sortingcomponents/matching/tdc.py
@@ -348,7 +348,7 @@ def _tdc_find_spikes(traces, d, level=0):
 
 if HAVE_NUMBA:
 
-    @jit(nopython=True, parallel=True)
+    @jit(nopython=True)
     def numba_sparse_dist(wf, templates, union_channels, possible_clusters):
         """
         numba implementation that compute distance from template with sparsity

From de2904b9e673d5587603c3c73e59deedc1af3031 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 18 Sep 2024 17:33:07 +0200
Subject: [PATCH 021/344] Refactor plotting for GTSTudy

---
 .../benchmark/benchmark_base.py               |  21 +-
 .../benchmark/benchmark_plot_tools.py         | 212 ++++++++++++++-
 .../benchmark/tests/test_benchmark_sorter.py  |   4 +-
 src/spikeinterface/widgets/gtstudy.py         | 249 ++++--------------
 4 files changed, 262 insertions(+), 224 deletions(-)

diff --git a/src/spikeinterface/benchmark/benchmark_base.py b/src/spikeinterface/benchmark/benchmark_base.py
index 2dfe2b3448..7d5f17e948 100644
--- a/src/spikeinterface/benchmark/benchmark_base.py
+++ b/src/spikeinterface/benchmark/benchmark_base.py
@@ -258,25 +258,8 @@ def get_run_times(self, case_keys=None):
         return df
 
     def plot_run_times(self, case_keys=None):
-        if case_keys is None:
-            case_keys = list(self.cases.keys())
-        run_times = self.get_run_times(case_keys=case_keys)
-
-        colors = self.get_colors()
-        import matplotlib.pyplot as plt
-
-        fig, ax = plt.subplots()
-        labels = []
-        for i, key in enumerate(case_keys):
-            labels.append(self.cases[key]["label"])
-            rt = run_times.at[key, "run_times"]
-            ax.bar(i, rt, width=0.8, color=colors[key])
-        ax.set_xticks(np.arange(len(case_keys)))
-        ax.set_xticklabels(labels, rotation=45.0)
-        return fig
-
-        # ax = run_times.plot(kind="bar")
-        # return ax.figure
+        from .benchmark_plot_tools import plot_run_times
+        return plot_run_times(self, case_keys=case_keys)
 
     def compute_results(self, case_keys=None, verbose=False, **result_params):
         if case_keys is None:
diff --git a/src/spikeinterface/benchmark/benchmark_plot_tools.py b/src/spikeinterface/benchmark/benchmark_plot_tools.py
index ee9d2947d6..ae9009521f 100644
--- a/src/spikeinterface/benchmark/benchmark_plot_tools.py
+++ b/src/spikeinterface/benchmark/benchmark_plot_tools.py
@@ -1,4 +1,4 @@
-
+import numpy as np
 
 
 
@@ -7,3 +7,213 @@ def _simpleaxis(ax):
     ax.spines["right"].set_visible(False)
     ax.get_xaxis().tick_bottom()
     ax.get_yaxis().tick_left()
+
+
+def plot_run_times(study, case_keys=None):
+    """
+    Plot run times for a BenchmarkStudy.
+
+    Parameters
+    ----------
+    study : SorterStudy
+        A study object.
+    case_keys : list or None
+        A selection of cases to plot, if None, then all.
+    """
+    import matplotlib.pyplot as plt
+
+    if case_keys is None:
+        case_keys = list(study.cases.keys())
+
+    run_times = study.get_run_times(case_keys=case_keys)
+
+    colors = study.get_colors()
+    
+
+    fig, ax = plt.subplots()
+    labels = []
+    for i, key in enumerate(case_keys):
+        labels.append(study.cases[key]["label"])
+        rt = run_times.at[key, "run_times"]
+        ax.bar(i, rt, width=0.8, color=colors[key])
+    ax.set_xticks(np.arange(len(case_keys)))
+    ax.set_xticklabels(labels, rotation=45.0)
+    return fig
+
+
+def plot_unit_counts(study, case_keys=None):
+    """
+    Plot unit counts for a study: "num_well_detected", "num_false_positive", "num_redundant", "num_overmerged"
+
+    Parameters
+    ----------
+    study : SorterStudy
+        A study object.
+    case_keys : list or None
+        A selection of cases to plot, if None, then all.
+    """
+    import matplotlib.pyplot as plt
+    from spikeinterface.widgets.utils import get_some_colors
+
+    if case_keys is None:
+        case_keys = list(study.cases.keys())
+
+
+    count_units = study.get_count_units(case_keys=case_keys)
+
+    fig, ax = plt.subplots()
+
+    columns = count_units.columns.tolist()
+    columns.remove("num_gt")
+    columns.remove("num_sorter")
+
+    ncol = len(columns)
+
+    colors = get_some_colors(columns, color_engine="auto", map_name="hot")
+    colors["num_well_detected"] = "green"
+
+    xticklabels = []
+    for i, key in enumerate(case_keys):
+        for c, col in enumerate(columns):
+            x = i + 1 + c / (ncol + 1)
+            y = count_units.loc[key, col]
+            if not "well_detected" in col:
+                y = -y
+
+            if i == 0:
+                label = col.replace("num_", "").replace("_", " ").title()
+            else:
+                label = None
+
+            ax.bar([x], [y], width=1 / (ncol + 2), label=label, color=colors[col])
+
+        xticklabels.append(study.cases[key]["label"])
+
+    ax.set_xticks(np.arange(len(case_keys)) + 1)
+    ax.set_xticklabels(xticklabels)
+    ax.legend()
+
+    return fig
+
+def plot_performances(study, mode="ordered", performance_names=("accuracy", "precision", "recall"), case_keys=None):
+    """
+    Plot performances over case for a study.
+
+    Parameters
+    ----------
+    study : GroundTruthStudy
+        A study object.
+    mode : "ordered" | "snr" | "swarm", default: "ordered"
+        Which plot mode to use:
+
+        * "ordered": plot performance metrics vs unit indices ordered by decreasing accuracy
+        * "snr": plot performance metrics vs snr
+        * "swarm": plot performance metrics as a swarm plot (see seaborn.swarmplot for details)
+    performance_names : list or tuple, default: ("accuracy", "precision", "recall")
+        Which performances to plot ("accuracy", "precision", "recall")
+    case_keys : list or None
+        A selection of cases to plot, if None, then all.
+    """
+    import matplotlib.pyplot as plt
+    import pandas as pd
+    import seaborn as sns
+
+    if case_keys is None:
+        case_keys = list(study.cases.keys())
+
+    perfs=study.get_performance_by_unit(case_keys=case_keys)
+    colors = study.get_colors()
+
+
+    if mode in ("ordered", "snr"):
+        num_axes = len(performance_names)
+        fig, axs = plt.subplots(ncols=num_axes)
+    else:
+        fig, ax = plt.subplots()
+
+    if mode == "ordered":
+        for count, performance_name in enumerate(performance_names):
+            ax = axs.flatten()[count]
+            for key in case_keys:
+                label = study.cases[key]["label"]
+                val = perfs.xs(key).loc[:, performance_name].values
+                val = np.sort(val)[::-1]
+                ax.plot(val, label=label, c=colors[key])
+            ax.set_title(performance_name)
+            if count == len(performance_names) - 1:
+                ax.legend(bbox_to_anchor=(0.05, 0.05), loc="lower left", framealpha=0.8)
+
+    elif mode == "snr":
+        metric_name = mode
+        for count, performance_name in enumerate(performance_names):
+            ax = axs.flatten()[count]
+
+            max_metric = 0
+            for key in case_keys:
+                x = study.get_metrics(key).loc[:, metric_name].values
+                y = perfs.xs(key).loc[:, performance_name].values
+                label = study.cases[key]["label"]
+                ax.scatter(x, y, s=10, label=label, color=colors[key])
+                max_metric = max(max_metric, np.max(x))
+            ax.set_title(performance_name)
+            ax.set_xlim(0, max_metric * 1.05)
+            ax.set_ylim(0, 1.05)
+            if count == 0:
+                ax.legend(loc="lower right")
+
+    elif mode == "swarm":
+        levels = perfs.index.names
+        df = pd.melt(
+            perfs.reset_index(),
+            id_vars=levels,
+            var_name="Metric",
+            value_name="Score",
+            value_vars=performance_names,
+        )
+        df["x"] = df.apply(lambda r: " ".join([r[col] for col in levels]), axis=1)
+        sns.swarmplot(data=df, x="x", y="Score", hue="Metric", dodge=True, ax=ax)
+
+
+def plot_agreement_matrix(study, ordered=True, case_keys=None):
+    """
+    Plot agreement matri ces for cases in a study.
+
+    Parameters
+    ----------
+    study : GroundTruthStudy
+        A study object.
+    case_keys : list or None
+        A selection of cases to plot, if None, then all.
+    ordered : bool
+        Order units with best agreement scores.
+        This enable to see agreement on a diagonal.
+    """
+
+    import matplotlib.pyplot as plt
+    from spikeinterface.widgets import AgreementMatrixWidget
+
+    if case_keys is None:
+        case_keys = list(study.cases.keys())
+
+
+    num_axes = len(case_keys)
+    fig, axs = plt.subplots(ncols=num_axes)
+
+    for count, key in enumerate(case_keys):
+        ax = axs.flatten()[count]
+        comp = study.get_result(key)["gt_comparison"]
+
+        unit_ticks = len(comp.sorting1.unit_ids) <= 16
+        count_text = len(comp.sorting1.unit_ids) <= 16
+
+        AgreementMatrixWidget(
+            comp, ordered=ordered, count_text=count_text, unit_ticks=unit_ticks, backend="matplotlib", ax=ax
+        )
+        label = study.cases[key]["label"]
+        ax.set_xlabel(label)
+
+        if count > 0:
+            ax.set_ylabel(None)
+            ax.set_yticks([])
+        ax.set_xticks([])
+
diff --git a/src/spikeinterface/benchmark/tests/test_benchmark_sorter.py b/src/spikeinterface/benchmark/tests/test_benchmark_sorter.py
index 50308f8df7..03ac86d715 100644
--- a/src/spikeinterface/benchmark/tests/test_benchmark_sorter.py
+++ b/src/spikeinterface/benchmark/tests/test_benchmark_sorter.py
@@ -63,10 +63,10 @@ def test_SorterStudy(setup_module):
     print(study)
 
     # # this run the sorters
-    study.run()
+    # study.run()
 
     # # this run comparisons
-    study.compute_results()
+    # study.compute_results()
     print(study)
 
     # this is from the base class
diff --git a/src/spikeinterface/widgets/gtstudy.py b/src/spikeinterface/widgets/gtstudy.py
index 85043d0d12..f32a15e429 100644
--- a/src/spikeinterface/widgets/gtstudy.py
+++ b/src/spikeinterface/widgets/gtstudy.py
@@ -1,127 +1,60 @@
-from __future__ import annotations
+"""
+This module will be deprecated and will be removed in 0.102.0
+
+All ploting for the previous GTStudy is now centralized in spikeinterface.benchmark.benchmark_plot_tools
+Please not that GTStudy is replaced by SorterStudy wich is based more generic BenchmarkStudy.
+"""
 
-import numpy as np
+from __future__ import annotations
 
-from .base import BaseWidget, to_attr
+from .base import BaseWidget
 
+import warnings
 
 class StudyRunTimesWidget(BaseWidget):
     """
-    Plot sorter run times for a GroundTruthStudy
-
+    Plot sorter run times for a SorterStudy.
 
     Parameters
     ----------
-    study : GroundTruthStudy
+    study : SorterStudy
         A study object.
     case_keys : list or None
         A selection of cases to plot, if None, then all.
 
     """
 
-    def __init__(
-        self,
-        study,
-        case_keys=None,
-        backend=None,
-        **backend_kwargs,
-    ):
-        if case_keys is None:
-            case_keys = list(study.cases.keys())
-
-        plot_data = dict(
-            study=study, run_times=study.get_run_times(case_keys), case_keys=case_keys, colors=study.get_colors()
-        )
-
+    def __init__(self, study, case_keys=None, backend=None, **backend_kwargs):
+        warnings.warn("plot_study_run_times is to be deprecated. Use spikeinterface.benchmark.benchmark_plot_tools instead.")
+        plot_data = dict(study=study, case_keys=case_keys)
         BaseWidget.__init__(self, plot_data, backend=backend, **backend_kwargs)
 
     def plot_matplotlib(self, data_plot, **backend_kwargs):
-        import matplotlib.pyplot as plt
-        from .utils_matplotlib import make_mpl_figure
-
-        dp = to_attr(data_plot)
+        from spikeinterface.benchmark.benchmark_plot_tools import plot_run_times
+        plot_run_times(data_plot["study"], case_keys=data_plot["case_keys"])
 
-        self.figure, self.axes, self.ax = make_mpl_figure(**backend_kwargs)
 
-        for i, key in enumerate(dp.case_keys):
-            label = dp.study.cases[key]["label"]
-            rt = dp.run_times.loc[key]
-            self.ax.bar(i, rt, width=0.8, label=label, facecolor=dp.colors[key])
-        self.ax.set_ylabel("run time (s)")
-        self.ax.legend()
-
-
-# TODO : plot optionally average on some levels using group by
 class StudyUnitCountsWidget(BaseWidget):
     """
     Plot unit counts for a study: "num_well_detected", "num_false_positive", "num_redundant", "num_overmerged"
 
-
     Parameters
     ----------
-    study : GroundTruthStudy
+    study : SorterStudy
         A study object.
     case_keys : list or None
         A selection of cases to plot, if None, then all.
 
     """
 
-    def __init__(
-        self,
-        study,
-        case_keys=None,
-        backend=None,
-        **backend_kwargs,
-    ):
-        if case_keys is None:
-            case_keys = list(study.cases.keys())
-
-        plot_data = dict(
-            study=study,
-            count_units=study.get_count_units(case_keys=case_keys),
-            case_keys=case_keys,
-        )
-
+    def __init__(self, study, case_keys=None, backend=None, **backend_kwargs):
+        warnings.warn("plot_study_unit_counts is to be deprecated. Use spikeinterface.benchmark.benchmark_plot_tools instead.")
+        plot_data = dict(study=study, case_keys=case_keys)
         BaseWidget.__init__(self, plot_data, backend=backend, **backend_kwargs)
 
     def plot_matplotlib(self, data_plot, **backend_kwargs):
-        import matplotlib.pyplot as plt
-        from .utils_matplotlib import make_mpl_figure
-        from .utils import get_some_colors
-
-        dp = to_attr(data_plot)
-
-        self.figure, self.axes, self.ax = make_mpl_figure(**backend_kwargs)
-
-        columns = dp.count_units.columns.tolist()
-        columns.remove("num_gt")
-        columns.remove("num_sorter")
-
-        ncol = len(columns)
-
-        colors = get_some_colors(columns, color_engine="auto", map_name="hot")
-        colors["num_well_detected"] = "green"
-
-        xticklabels = []
-        for i, key in enumerate(dp.case_keys):
-            for c, col in enumerate(columns):
-                x = i + 1 + c / (ncol + 1)
-                y = dp.count_units.loc[key, col]
-                if not "well_detected" in col:
-                    y = -y
-
-                if i == 0:
-                    label = col.replace("num_", "").replace("_", " ").title()
-                else:
-                    label = None
-
-                self.ax.bar([x], [y], width=1 / (ncol + 2), label=label, color=colors[col])
-
-            xticklabels.append(dp.study.cases[key]["label"])
-
-        self.ax.set_xticks(np.arange(len(dp.case_keys)) + 1)
-        self.ax.set_xticklabels(xticklabels)
-        self.ax.legend()
+        from spikeinterface.benchmark.benchmark_plot_tools import plot_unit_counts
+        plot_unit_counts(data_plot["study"], case_keys=data_plot["case_keys"])
 
 
 class StudyPerformances(BaseWidget):
@@ -154,79 +87,23 @@ def __init__(
         backend=None,
         **backend_kwargs,
     ):
-        if case_keys is None:
-            case_keys = list(study.cases.keys())
-
+        warnings.warn("plot_study_performances is to be deprecated. Use spikeinterface.benchmark.benchmark_plot_tools instead.")
         plot_data = dict(
             study=study,
-            perfs=study.get_performance_by_unit(case_keys=case_keys),
             mode=mode,
             performance_names=performance_names,
             case_keys=case_keys,
         )
-
-        self.colors = study.get_colors()
-
         BaseWidget.__init__(self, plot_data, backend=backend, **backend_kwargs)
 
     def plot_matplotlib(self, data_plot, **backend_kwargs):
-        import matplotlib.pyplot as plt
-        from .utils_matplotlib import make_mpl_figure
-        from .utils import get_some_colors
-
-        import pandas as pd
-        import seaborn as sns
-
-        dp = to_attr(data_plot)
-        perfs = dp.perfs
-        study = dp.study
-
-        if dp.mode in ("ordered", "snr"):
-            backend_kwargs["num_axes"] = len(dp.performance_names)
-        self.figure, self.axes, self.ax = make_mpl_figure(**backend_kwargs)
-
-        if dp.mode == "ordered":
-            for count, performance_name in enumerate(dp.performance_names):
-                ax = self.axes.flatten()[count]
-                for key in dp.case_keys:
-                    label = study.cases[key]["label"]
-                    val = perfs.xs(key).loc[:, performance_name].values
-                    val = np.sort(val)[::-1]
-                    ax.plot(val, label=label, c=self.colors[key])
-                ax.set_title(performance_name)
-                if count == len(dp.performance_names) - 1:
-                    ax.legend(bbox_to_anchor=(0.05, 0.05), loc="lower left", framealpha=0.8)
-
-        elif dp.mode == "snr":
-            metric_name = dp.mode
-            for count, performance_name in enumerate(dp.performance_names):
-                ax = self.axes.flatten()[count]
-
-                max_metric = 0
-                for key in dp.case_keys:
-                    x = study.get_metrics(key).loc[:, metric_name].values
-                    y = perfs.xs(key).loc[:, performance_name].values
-                    label = study.cases[key]["label"]
-                    ax.scatter(x, y, s=10, label=label, color=self.colors[key])
-                    max_metric = max(max_metric, np.max(x))
-                ax.set_title(performance_name)
-                ax.set_xlim(0, max_metric * 1.05)
-                ax.set_ylim(0, 1.05)
-                if count == 0:
-                    ax.legend(loc="lower right")
-
-        elif dp.mode == "swarm":
-            levels = perfs.index.names
-            df = pd.melt(
-                perfs.reset_index(),
-                id_vars=levels,
-                var_name="Metric",
-                value_name="Score",
-                value_vars=dp.performance_names,
-            )
-            df["x"] = df.apply(lambda r: " ".join([r[col] for col in levels]), axis=1)
-            sns.swarmplot(data=df, x="x", y="Score", hue="Metric", dodge=True)
-
+        from spikeinterface.benchmark.benchmark_plot_tools import plot_performances
+        plot_performances(
+            data_plot["study"],
+            mode=data_plot["mode"],
+            performance_names=data_plot["performance_names"],
+            case_keys=data_plot["case_keys"]
+        )
 
 class StudyAgreementMatrix(BaseWidget):
     """
@@ -251,9 +128,7 @@ def __init__(
         backend=None,
         **backend_kwargs,
     ):
-        if case_keys is None:
-            case_keys = list(study.cases.keys())
-
+        warnings.warn("plot_study_agreement_matrix is to be deprecated. Use spikeinterface.benchmark.benchmark_plot_tools instead.")
         plot_data = dict(
             study=study,
             case_keys=case_keys,
@@ -263,36 +138,12 @@ def __init__(
         BaseWidget.__init__(self, plot_data, backend=backend, **backend_kwargs)
 
     def plot_matplotlib(self, data_plot, **backend_kwargs):
-        import matplotlib.pyplot as plt
-        from .utils_matplotlib import make_mpl_figure
-        from .comparison import AgreementMatrixWidget
-
-        dp = to_attr(data_plot)
-        study = dp.study
-
-        backend_kwargs["num_axes"] = len(dp.case_keys)
-        self.figure, self.axes, self.ax = make_mpl_figure(**backend_kwargs)
-
-        for count, key in enumerate(dp.case_keys):
-            ax = self.axes.flatten()[count]
-            comp = study.comparisons[key]
-            unit_ticks = len(comp.sorting1.unit_ids) <= 16
-            count_text = len(comp.sorting1.unit_ids) <= 16
-
-            AgreementMatrixWidget(
-                comp, ordered=dp.ordered, count_text=count_text, unit_ticks=unit_ticks, backend="matplotlib", ax=ax
-            )
-            label = study.cases[key]["label"]
-            ax.set_xlabel(label)
-
-            if count > 0:
-                ax.set_ylabel(None)
-                ax.set_yticks([])
-            ax.set_xticks([])
-
-        # ax0 = self.axes.flatten()[0]
-        # for ax in self.axes.flatten()[1:]:
-        #     ax.sharey(ax0)
+        from spikeinterface.benchmark.benchmark_plot_tools import plot_agreement_matrix
+        plot_agreement_matrix(
+            data_plot["study"],
+            ordered=data_plot["ordered"],
+            case_keys=data_plot["case_keys"]
+        )
 
 
 class StudySummary(BaseWidget):
@@ -320,25 +171,19 @@ def __init__(
         backend=None,
         **backend_kwargs,
     ):
-        if case_keys is None:
-            case_keys = list(study.cases.keys())
-
-        plot_data = dict(
-            study=study,
-            case_keys=case_keys,
-        )
-
+        
+        warnings.warn("plot_study_summary is to be deprecated. Use spikeinterface.benchmark.benchmark_plot_tools instead.")
+        plot_data = dict(study=study, case_keys=case_keys)
         BaseWidget.__init__(self, plot_data, backend=backend, **backend_kwargs)
 
     def plot_matplotlib(self, data_plot, **backend_kwargs):
-        import matplotlib.pyplot as plt
-        from .utils_matplotlib import make_mpl_figure
-
         study = data_plot["study"]
         case_keys = data_plot["case_keys"]
 
-        StudyPerformances(study=study, case_keys=case_keys, mode="ordered", backend="matplotlib", **backend_kwargs)
-        StudyPerformances(study=study, case_keys=case_keys, mode="snr", backend="matplotlib", **backend_kwargs)
-        StudyAgreementMatrix(study=study, case_keys=case_keys, backend="matplotlib", **backend_kwargs)
-        StudyRunTimesWidget(study=study, case_keys=case_keys, backend="matplotlib", **backend_kwargs)
-        StudyUnitCountsWidget(study=study, case_keys=case_keys, backend="matplotlib", **backend_kwargs)
+        from spikeinterface.benchmark.benchmark_plot_tools import plot_agreement_matrix, plot_performances, plot_unit_counts, plot_run_times
+
+        plot_performances(study=study, case_keys=case_keys, mode="ordered")
+        plot_performances(study=study, case_keys=case_keys, mode="snr")
+        plot_agreement_matrix(study=study, case_keys=case_keys)
+        plot_run_times(study=study, case_keys=case_keys)
+        plot_unit_counts(study=study, case_keys=case_keys)

From 68a8691e21e17a4026aa549de2078dc305e5211c Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 18 Sep 2024 19:32:31 +0200
Subject: [PATCH 022/344] Common function between
 benchlark_clustering/benchmark_matching/benchmark_sorter

---
 .../benchmark/benchmark_clustering.py         | 50 ++++---------------
 .../benchmark/benchmark_matching.py           | 40 +++------------
 .../benchmark/benchmark_plot_tools.py         | 28 +++++++++++
 .../benchmark/benchmark_sorter.py             | 15 ++++++
 4 files changed, 59 insertions(+), 74 deletions(-)

diff --git a/src/spikeinterface/benchmark/benchmark_clustering.py b/src/spikeinterface/benchmark/benchmark_clustering.py
index 94fcafef6e..36010e6065 100644
--- a/src/spikeinterface/benchmark/benchmark_clustering.py
+++ b/src/spikeinterface/benchmark/benchmark_clustering.py
@@ -160,49 +160,19 @@ def get_count_units(self, case_keys=None, well_detected_score=None, redundant_sc
 
         return count_units
 
-    def plot_unit_counts(self, case_keys=None, figsize=None, **extra_kwargs):
-        from spikeinterface.widgets.widget_list import plot_study_unit_counts
+    # plotting by methods
+    def plot_unit_counts(self, **kwargs):
+        from .benchmark_plot_tools import plot_unit_counts
+        return plot_unit_counts(self, **kwargs)
 
-        plot_study_unit_counts(self, case_keys, figsize=figsize, **extra_kwargs)
+    def plot_agreement_matrix(self, **kwargs):
+        from .benchmark_plot_tools import plot_agreement_matrix
+        return plot_agreement_matrix(self, **kwargs)
 
-    def plot_agreements(self, case_keys=None, figsize=(15, 15)):
-        if case_keys is None:
-            case_keys = list(self.cases.keys())
-        import pylab as plt
-
-        fig, axs = plt.subplots(ncols=len(case_keys), nrows=1, figsize=figsize, squeeze=False)
-
-        for count, key in enumerate(case_keys):
-            ax = axs[0, count]
-            ax.set_title(self.cases[key]["label"])
-            plot_agreement_matrix(self.get_result(key)["gt_comparison"], ax=ax)
-
-        return fig
-
-    def plot_performances_vs_snr(self, case_keys=None, figsize=(15, 15)):
-        if case_keys is None:
-            case_keys = list(self.cases.keys())
-        import pylab as plt
-
-        fig, axes = plt.subplots(ncols=1, nrows=3, figsize=figsize)
-
-        for count, k in enumerate(("accuracy", "recall", "precision")):
+    def plot_performances_vs_snr(self, **kwargs):
+        from .benchmark_plot_tools import plot_performances_vs_snr
+        return plot_performances_vs_snr(self, **kwargs)
 
-            ax = axes[count]
-            for key in case_keys:
-                label = self.cases[key]["label"]
-
-                analyzer = self.get_sorting_analyzer(key)
-                metrics = analyzer.get_extension("quality_metrics").get_data()
-                x = metrics["snr"].values
-                y = self.get_result(key)["gt_comparison"].get_performance()[k].values
-                ax.scatter(x, y, marker=".", label=label)
-                ax.set_title(k)
-
-            if count == 2:
-                ax.legend()
-
-        return fig
 
     def plot_error_metrics(self, metric="cosine", case_keys=None, figsize=(15, 5)):
 
diff --git a/src/spikeinterface/benchmark/benchmark_matching.py b/src/spikeinterface/benchmark/benchmark_matching.py
index 784b369d7f..db5a00dc1a 100644
--- a/src/spikeinterface/benchmark/benchmark_matching.py
+++ b/src/spikeinterface/benchmark/benchmark_matching.py
@@ -61,42 +61,14 @@ def create_benchmark(self, key):
         benchmark = MatchingBenchmark(recording, gt_sorting, params)
         return benchmark
 
-    def plot_agreements(self, case_keys=None, figsize=None):
-        if case_keys is None:
-            case_keys = list(self.cases.keys())
-        import pylab as plt
-
-        fig, axs = plt.subplots(ncols=len(case_keys), nrows=1, figsize=figsize, squeeze=False)
-
-        for count, key in enumerate(case_keys):
-            ax = axs[0, count]
-            ax.set_title(self.cases[key]["label"])
-            plot_agreement_matrix(self.get_result(key)["gt_comparison"], ax=ax)
+    def plot_agreement_matrix(self, **kwargs):
+        from .benchmark_plot_tools import plot_agreement_matrix
+        return plot_agreement_matrix(self, **kwargs)
 
-    def plot_performances_vs_snr(self, case_keys=None, figsize=None, metrics=["accuracy", "recall", "precision"]):
-        if case_keys is None:
-            case_keys = list(self.cases.keys())
-
-        import matplotlib.pyplot as plt
-        fig, axs = plt.subplots(ncols=1, nrows=len(metrics), figsize=figsize, squeeze=False)
-
-        for count, k in enumerate(metrics):
+    def plot_performances_vs_snr(self, **kwargs):
+        from .benchmark_plot_tools import plot_performances_vs_snr
+        return plot_performances_vs_snr(self, **kwargs)
 
-            ax = axs[count, 0]
-            for key in case_keys:
-                label = self.cases[key]["label"]
-
-                analyzer = self.get_sorting_analyzer(key)
-                metrics = analyzer.get_extension("quality_metrics").get_data()
-                x = metrics["snr"].values
-                y = self.get_result(key)["gt_comparison"].get_performance()[k].values
-                ax.scatter(x, y, marker=".", label=label)
-                ax.set_title(k)
-
-            if count == 2:
-                ax.legend()
-
-        return fig
 
     def plot_collisions(self, case_keys=None, figsize=None):
         if case_keys is None:
diff --git a/src/spikeinterface/benchmark/benchmark_plot_tools.py b/src/spikeinterface/benchmark/benchmark_plot_tools.py
index ae9009521f..c1683c6360 100644
--- a/src/spikeinterface/benchmark/benchmark_plot_tools.py
+++ b/src/spikeinterface/benchmark/benchmark_plot_tools.py
@@ -217,3 +217,31 @@ def plot_agreement_matrix(study, ordered=True, case_keys=None):
             ax.set_yticks([])
         ax.set_xticks([])
 
+
+def plot_performances_vs_snr(study, case_keys=None, figsize=None, metrics=["accuracy", "recall", "precision"]):
+    import matplotlib.pyplot as plt
+
+    if case_keys is None:
+        case_keys = list(study.cases.keys())
+
+    fig, axs = plt.subplots(ncols=1, nrows=len(metrics), figsize=figsize, squeeze=False)
+
+    for count, k in enumerate(metrics):
+
+        ax = axs[count, 0]
+        for key in case_keys:
+            label = study.cases[key]["label"]
+
+            analyzer = study.get_sorting_analyzer(key)
+            metrics = analyzer.get_extension("quality_metrics").get_data()
+            x = metrics["snr"].values
+            y = study.get_result(key)["gt_comparison"].get_performance()[k].values
+            ax.scatter(x, y, marker=".", label=label)
+            ax.set_title(k)
+        
+        ax.set_ylim(0, 1.05)
+        
+        if count == 2:
+            ax.legend()
+
+    return fig
diff --git a/src/spikeinterface/benchmark/benchmark_sorter.py b/src/spikeinterface/benchmark/benchmark_sorter.py
index d08775561a..5f3e584b20 100644
--- a/src/spikeinterface/benchmark/benchmark_sorter.py
+++ b/src/spikeinterface/benchmark/benchmark_sorter.py
@@ -123,3 +123,18 @@ def get_count_units(self, case_keys=None, well_detected_score=None, redundant_sc
 
         return count_units
 
+    # plotting as methods
+    def plot_unit_counts(self, **kwargs):
+        from .benchmark_plot_tools import plot_unit_counts
+        return plot_unit_counts(self, **kwargs)
+
+    def plot_performances(self, **kwargs):
+        from .benchmark_plot_tools import plot_performances
+        return plot_performances(self, **kwargs)
+
+    def plot_agreement_matrix(self, **kwargs):
+        from .benchmark_plot_tools import plot_agreement_matrix
+        return plot_agreement_matrix(self, **kwargs)
+
+
+

From ae5edd6e717a2e030886079c278b67fc2de6a0b4 Mon Sep 17 00:00:00 2001
From: Heberto Mayorquin <h.mayorquin@gmail.com>
Date: Thu, 19 Sep 2024 11:55:01 -0600
Subject: [PATCH 023/344] Update
 src/spikeinterface/extractors/neoextractors/plexon2.py

Co-authored-by: Zach McKenzie <92116279+zm711@users.noreply.github.com>
---
 src/spikeinterface/extractors/neoextractors/plexon2.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/extractors/neoextractors/plexon2.py b/src/spikeinterface/extractors/neoextractors/plexon2.py
index 1f0d40a253..e0604f7496 100644
--- a/src/spikeinterface/extractors/neoextractors/plexon2.py
+++ b/src/spikeinterface/extractors/neoextractors/plexon2.py
@@ -28,7 +28,7 @@ class Plexon2RecordingExtractor(NeoBaseRecordingExtractor):
             ids: ["source3.1" , "source3.2", "source3.3", "source3.4"]
     all_annotations : bool, default: False
         Load exhaustively all annotations from neo.
-    readding_attemps : int, default: 25
+    reading_attempts : int, default: 25
         Number of attempts to read the file before raising an error
         This opening process is somewhat unreliable and might fail occasionally. Adjust this higher
         if you encounter problems in opening the file.

From 9ddc7ce06119fd8c624d88ea560441d517d2e76b Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Mon, 23 Sep 2024 15:04:38 +0200
Subject: [PATCH 024/344] Add max_threads_per_process to pca fit_by_channel

---
 .../postprocessing/principal_component.py     | 37 +++++++++++++------
 .../tests/test_principal_component.py         | 12 ++++++
 2 files changed, 37 insertions(+), 12 deletions(-)

diff --git a/src/spikeinterface/postprocessing/principal_component.py b/src/spikeinterface/postprocessing/principal_component.py
index f1f89403c7..ff1801c1b0 100644
--- a/src/spikeinterface/postprocessing/principal_component.py
+++ b/src/spikeinterface/postprocessing/principal_component.py
@@ -1,12 +1,13 @@
 from __future__ import annotations
 
-import shutil
-import pickle
 import warnings
-import tempfile
 from pathlib import Path
 from tqdm.auto import tqdm
 
+from concurrent.futures import ProcessPoolExecutor
+import multiprocessing as mp
+from threadpoolctl import threadpool_limits
+
 import numpy as np
 
 from spikeinterface.core.sortinganalyzer import register_result_extension, AnalyzerExtension
@@ -314,11 +315,13 @@ def _run(self, verbose=False, **job_kwargs):
         job_kwargs = fix_job_kwargs(job_kwargs)
         n_jobs = job_kwargs["n_jobs"]
         progress_bar = job_kwargs["progress_bar"]
+        max_threads_per_process = job_kwargs["max_threads_per_process"]
+        mp_context = job_kwargs["mp_context"]
 
         # fit model/models
         # TODO : make parralel  for by_channel_global and concatenated
         if mode == "by_channel_local":
-            pca_models = self._fit_by_channel_local(n_jobs, progress_bar)
+            pca_models = self._fit_by_channel_local(n_jobs, progress_bar, max_threads_per_process, mp_context)
             for chan_ind, chan_id in enumerate(self.sorting_analyzer.channel_ids):
                 self.data[f"pca_model_{mode}_{chan_id}"] = pca_models[chan_ind]
             pca_model = pca_models
@@ -410,9 +413,8 @@ def run_for_all_spikes(self, file_path=None, verbose=False, **job_kwargs):
         )
         processor.run()
 
-    def _fit_by_channel_local(self, n_jobs, progress_bar):
+    def _fit_by_channel_local(self, n_jobs, progress_bar, max_threads_per_process, mp_context):
         from sklearn.decomposition import IncrementalPCA
-        from concurrent.futures import ProcessPoolExecutor
 
         p = self.params
 
@@ -435,13 +437,18 @@ def _fit_by_channel_local(self, n_jobs, progress_bar):
                     pca = pca_models[chan_ind]
                     pca.partial_fit(wfs[:, :, wf_ind])
             else:
-                # parallel
+                # create list of args to parallelize. For convenience, the max_threads_per_process is passed
+                # as last argument
                 items = [
-                    (chan_ind, pca_models[chan_ind], wfs[:, :, wf_ind]) for wf_ind, chan_ind in enumerate(channel_inds)
+                    (chan_ind, pca_models[chan_ind], wfs[:, :, wf_ind], max_threads_per_process)
+                    for wf_ind, chan_ind in enumerate(channel_inds)
                 ]
                 n_jobs = min(n_jobs, len(items))
 
-                with ProcessPoolExecutor(max_workers=n_jobs) as executor:
+                with ProcessPoolExecutor(
+                    max_workers=n_jobs,
+                    mp_context=mp.get_context(mp_context),
+                ) as executor:
                     results = executor.map(_partial_fit_one_channel, items)
                     for chan_ind, pca_model_updated in results:
                         pca_models[chan_ind] = pca_model_updated
@@ -675,6 +682,12 @@ def _init_work_all_pc_extractor(recording, sorting, all_pcs_args, nbefore, nafte
 
 
 def _partial_fit_one_channel(args):
-    chan_ind, pca_model, wf_chan = args
-    pca_model.partial_fit(wf_chan)
-    return chan_ind, pca_model
+    chan_ind, pca_model, wf_chan, max_threads_per_process = args
+
+    if max_threads_per_process is None:
+        pca_model.partial_fit(wf_chan)
+        return chan_ind, pca_model
+    else:
+        with threadpool_limits(limits=int(max_threads_per_process)):
+            pca_model.partial_fit(wf_chan)
+            return chan_ind, pca_model
diff --git a/src/spikeinterface/postprocessing/tests/test_principal_component.py b/src/spikeinterface/postprocessing/tests/test_principal_component.py
index 4de86be32b..328b72f72c 100644
--- a/src/spikeinterface/postprocessing/tests/test_principal_component.py
+++ b/src/spikeinterface/postprocessing/tests/test_principal_component.py
@@ -18,6 +18,18 @@ class TestPrincipalComponentsExtension(AnalyzerExtensionCommonTestSuite):
     def test_extension(self, params):
         self.run_extension_tests(ComputePrincipalComponents, params=params)
 
+    def test_multi_processing(self):
+        """
+        Test the extension works with multiple processes.
+        """
+        sorting_analyzer = self._prepare_sorting_analyzer(
+            format="memory", sparse=False, extension_class=ComputePrincipalComponents
+        )
+        sorting_analyzer.compute("principal_components", mode="by_channel_local", n_jobs=2, mp_context="fork")
+        sorting_analyzer.compute(
+            "principal_components", mode="by_channel_local", n_jobs=2, max_threads_per_process=4, mp_context="spawn"
+        )
+
     def test_mode_concatenated(self):
         """
         Replicate the "extension_function_params_list" test outside of

From 59bb1e747db7b2bc6879720f27ec83e4ce66df31 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Mon, 23 Sep 2024 17:21:17 +0200
Subject: [PATCH 025/344] Add mp_context check

---
 src/spikeinterface/postprocessing/principal_component.py    | 6 ++++++
 .../postprocessing/tests/test_principal_component.py        | 2 +-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/src/spikeinterface/postprocessing/principal_component.py b/src/spikeinterface/postprocessing/principal_component.py
index ff1801c1b0..a713070982 100644
--- a/src/spikeinterface/postprocessing/principal_component.py
+++ b/src/spikeinterface/postprocessing/principal_component.py
@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import warnings
+import platform
 from pathlib import Path
 from tqdm.auto import tqdm
 
@@ -418,6 +419,11 @@ def _fit_by_channel_local(self, n_jobs, progress_bar, max_threads_per_process, m
 
         p = self.params
 
+        if mp_context is not None and platform.system() == "Windows":
+            assert mp_context != "fork", "'fork' mp_context not supported on Windows!"
+        elif mp_context == "fork" and platform.system() == "Darwin":
+            warnings.warn('As of Python 3.8 "fork" is no longer considered safe on macOS')
+
         unit_ids = self.sorting_analyzer.unit_ids
         channel_ids = self.sorting_analyzer.channel_ids
         # there is one PCA per channel for independent fit per channel
diff --git a/src/spikeinterface/postprocessing/tests/test_principal_component.py b/src/spikeinterface/postprocessing/tests/test_principal_component.py
index 328b72f72c..7a509c410f 100644
--- a/src/spikeinterface/postprocessing/tests/test_principal_component.py
+++ b/src/spikeinterface/postprocessing/tests/test_principal_component.py
@@ -25,7 +25,7 @@ def test_multi_processing(self):
         sorting_analyzer = self._prepare_sorting_analyzer(
             format="memory", sparse=False, extension_class=ComputePrincipalComponents
         )
-        sorting_analyzer.compute("principal_components", mode="by_channel_local", n_jobs=2, mp_context="fork")
+        sorting_analyzer.compute("principal_components", mode="by_channel_local", n_jobs=2)
         sorting_analyzer.compute(
             "principal_components", mode="by_channel_local", n_jobs=2, max_threads_per_process=4, mp_context="spawn"
         )

From 5a02a269667baa70cb4761d4d91c0e51af65fe76 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Mon, 23 Sep 2024 17:53:02 +0200
Subject: [PATCH 026/344] Add mp_context and max_threads_per_process to pca
 metrics

---
 .../qualitymetrics/pca_metrics.py             | 60 +++++++++----------
 .../qualitymetrics/tests/test_pca_metrics.py  | 25 +++++++-
 2 files changed, 49 insertions(+), 36 deletions(-)

diff --git a/src/spikeinterface/qualitymetrics/pca_metrics.py b/src/spikeinterface/qualitymetrics/pca_metrics.py
index 7c099a2f74..4c68dfea59 100644
--- a/src/spikeinterface/qualitymetrics/pca_metrics.py
+++ b/src/spikeinterface/qualitymetrics/pca_metrics.py
@@ -2,15 +2,16 @@
 
 from __future__ import annotations
 
-
+import warnings
 from copy import deepcopy
-
-import numpy as np
+import platform
 from tqdm.auto import tqdm
-from concurrent.futures import ProcessPoolExecutor
 
+import numpy as np
 
-import warnings
+import multiprocessing as mp
+from concurrent.futures import ProcessPoolExecutor
+from threadpoolctl import threadpool_limits
 
 from .misc_metrics import compute_num_spikes, compute_firing_rates
 
@@ -56,6 +57,8 @@ def compute_pc_metrics(
     seed=None,
     n_jobs=1,
     progress_bar=False,
+    mp_context=None,
+    max_threads_per_process=None,
 ) -> dict:
     """
     Calculate principal component derived metrics.
@@ -144,17 +147,7 @@ def compute_pc_metrics(
         pcs = dense_projections[np.isin(all_labels, neighbor_unit_ids)][:, :, neighbor_channel_indices]
         pcs_flat = pcs.reshape(pcs.shape[0], -1)
 
-        func_args = (
-            pcs_flat,
-            labels,
-            non_nn_metrics,
-            unit_id,
-            unit_ids,
-            qm_params,
-            seed,
-            n_spikes_all_units,
-            fr_all_units,
-        )
+        func_args = (pcs_flat, labels, non_nn_metrics, unit_id, unit_ids, qm_params, max_threads_per_process)
         items.append(func_args)
 
     if not run_in_parallel and non_nn_metrics:
@@ -167,7 +160,15 @@ def compute_pc_metrics(
             for metric_name, metric in pca_metrics_unit.items():
                 pc_metrics[metric_name][unit_id] = metric
     elif run_in_parallel and non_nn_metrics:
-        with ProcessPoolExecutor(n_jobs) as executor:
+        if mp_context is not None and platform.system() == "Windows":
+            assert mp_context != "fork", "'fork' mp_context not supported on Windows!"
+        elif mp_context == "fork" and platform.system() == "Darwin":
+            warnings.warn('As of Python 3.8 "fork" is no longer considered safe on macOS')
+
+        with ProcessPoolExecutor(
+            max_workers=n_jobs,
+            mp_context=mp.get_context(mp_context),
+        ) as executor:
             results = executor.map(pca_metrics_one_unit, items)
             if progress_bar:
                 results = tqdm(results, total=len(unit_ids), desc="calculate_pc_metrics")
@@ -976,26 +977,19 @@ def _compute_isolation(pcs_target_unit, pcs_other_unit, n_neighbors: int):
 
 
 def pca_metrics_one_unit(args):
-    (
-        pcs_flat,
-        labels,
-        metric_names,
-        unit_id,
-        unit_ids,
-        qm_params,
-        seed,
-        # we_folder,
-        n_spikes_all_units,
-        fr_all_units,
-    ) = args
-
-    # if "nn_isolation" in metric_names or "nn_noise_overlap" in metric_names:
-    #     we = load_waveforms(we_folder)
+    (pcs_flat, labels, metric_names, unit_id, unit_ids, qm_params, max_threads_per_process) = args
+
+    if max_threads_per_process is None:
+        return _pca_metrics_one_unit(pcs_flat, labels, metric_names, unit_id, unit_ids, qm_params)
+    else:
+        with threadpool_limits(limits=int(max_threads_per_process)):
+            return _pca_metrics_one_unit(pcs_flat, labels, metric_names, unit_id, unit_ids, qm_params)
+
 
+def _pca_metrics_one_unit(pcs_flat, labels, metric_names, unit_id, unit_ids, qm_params):
     pc_metrics = {}
     # metrics
     if "isolation_distance" in metric_names or "l_ratio" in metric_names:
-
         try:
             isolation_distance, l_ratio = mahalanobis_metrics(pcs_flat, labels, unit_id)
         except:
diff --git a/src/spikeinterface/qualitymetrics/tests/test_pca_metrics.py b/src/spikeinterface/qualitymetrics/tests/test_pca_metrics.py
index 6ddeb02689..f2e912c6b4 100644
--- a/src/spikeinterface/qualitymetrics/tests/test_pca_metrics.py
+++ b/src/spikeinterface/qualitymetrics/tests/test_pca_metrics.py
@@ -1,9 +1,7 @@
 import pytest
 import numpy as np
 
-from spikeinterface.qualitymetrics import (
-    compute_pc_metrics,
-)
+from spikeinterface.qualitymetrics import compute_pc_metrics, get_quality_pca_metric_list
 
 
 def test_calculate_pc_metrics(small_sorting_analyzer):
@@ -22,3 +20,24 @@ def test_calculate_pc_metrics(small_sorting_analyzer):
             assert not np.all(np.isnan(res2[metric_name].values))
 
         assert np.array_equal(res1[metric_name].values, res2[metric_name].values)
+
+
+def test_pca_metrics_multi_processing(small_sorting_analyzer):
+    sorting_analyzer = small_sorting_analyzer
+
+    metric_names = get_quality_pca_metric_list()
+    metric_names.remove("nn_isolation")
+    metric_names.remove("nn_noise_overlap")
+
+    print(f"Computing PCA metrics with 1 thread per process")
+    res1 = compute_pc_metrics(
+        sorting_analyzer, n_jobs=-1, metric_names=metric_names, max_threads_per_process=1, progress_bar=True
+    )
+    print(f"Computing PCA metrics with 2 thread per process")
+    res2 = compute_pc_metrics(
+        sorting_analyzer, n_jobs=-1, metric_names=metric_names, max_threads_per_process=2, progress_bar=True
+    )
+    print("Computing PCA metrics with spawn context")
+    res2 = compute_pc_metrics(
+        sorting_analyzer, n_jobs=-1, metric_names=metric_names, max_threads_per_process=2, progress_bar=True
+    )

From 7d8ef31d927757fa1c36bbcf18fab16b01d827c4 Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Tue, 24 Sep 2024 10:18:40 +0200
Subject: [PATCH 027/344] WIP

---
 .../postprocessing/template_similarity.py     | 150 ++++++++++--------
 1 file changed, 81 insertions(+), 69 deletions(-)

diff --git a/src/spikeinterface/postprocessing/template_similarity.py b/src/spikeinterface/postprocessing/template_similarity.py
index 2d94746ce7..f2082150c9 100644
--- a/src/spikeinterface/postprocessing/template_similarity.py
+++ b/src/spikeinterface/postprocessing/template_similarity.py
@@ -153,11 +153,70 @@ def _get_data(self):
 register_result_extension(ComputeTemplateSimilarity)
 compute_template_similarity = ComputeTemplateSimilarity.function_factory()
 
+def _compute_similarity_matrix_numpy(templates_array, other_templates_array, num_shifts, mask, method):
+
+    num_templates = templates_array.shape[0]
+    num_samples = templates_array.shape[1]
+    other_num_templates = other_templates_array.shape[0]
+
+    num_shifts_both_sides = 2 * num_shifts + 1
+    distances = np.ones((num_shifts_both_sides, num_templates, other_num_templates), dtype=np.float32)
+    same_array = np.array_equal(templates_array, other_templates_array)
+
+    # We can use the fact that dist[i,j] at lag t is equal to dist[j,i] at time -t
+    # So the matrix can be computed only for negative lags and be transposed
+
+    if same_array:
+        # optimisation when array are the same because of symetry in shift
+        shift_loop = range(-num_shifts, 1)
+    else:
+        shift_loop = range(-num_shifts, num_shifts + 1)
+
+    for count, shift in enumerate(shift_loop):
+        src_sliced_templates = templates_array[:, num_shifts : num_samples - num_shifts]
+        tgt_sliced_templates = other_templates_array[:, num_shifts + shift : num_samples - num_shifts + shift]
+        for i in range(num_templates):
+            src_template = src_sliced_templates[i]
+            overlapping_templates = np.flatnonzero(np.sum(mask[i], 1))
+            tgt_templates = tgt_sliced_templates[overlapping_templates]
+            for gcount, j in enumerate(overlapping_templates):
+                # symmetric values are handled later
+                if same_array and j < i:
+                    # no need exhaustive looping when same template
+                    continue
+                src = src_template[:, mask[i, j]].reshape(1, -1)
+                tgt = (tgt_templates[gcount][:, mask[i, j]]).reshape(1, -1)
+
+                if method == "l1":
+                    norm_i = np.sum(np.abs(src))
+                    norm_j = np.sum(np.abs(tgt))
+                    distances[count, i, j] = np.sum(np.abs(src - tgt))
+                    distances[count, i, j] /= norm_i + norm_j
+                elif method == "l2":
+                    norm_i = np.linalg.norm(src, ord=2)
+                    norm_j = np.linalg.norm(tgt, ord=2)
+                    distances[count, i, j] = np.linalg.norm(src - tgt, ord=2)
+                    distances[count, i, j] /= norm_i + norm_j
+                elif method == "cosine":
+                    norm_i = np.linalg.norm(src, ord=2)
+                    norm_j = np.linalg.norm(tgt, ord=2)
+                    distances[count, i, j] = np.sum(src * tgt)
+                    distances[count, i, j] /= norm_i * norm_j
+                    distances[count, i, j] = 1 - distances[count, i, j]
+
+                if same_array:
+                    distances[count, j, i] = distances[count, i, j]
+
+        if same_array and num_shifts != 0:
+            distances[num_shifts_both_sides - count - 1] = distances[count].T
+    return distances
+
 
 if HAVE_NUMBA:
 
+    from math import sqrt
     @numba.jit(nopython=True, parallel=True, fastmath=True, nogil=True)
-    def _compute_similarity_matrix(templates_array, other_templates_array, num_shifts, mask, method):
+    def _compute_similarity_matrix_numba(templates_array, other_templates_array, num_shifts, mask, method):
         num_templates = templates_array.shape[0]
         num_samples = templates_array.shape[1]
         other_num_templates = other_templates_array.shape[0]
@@ -175,6 +234,13 @@ def _compute_similarity_matrix(templates_array, other_templates_array, num_shift
         else:
             shift_loop = range(-num_shifts, num_shifts + 1)
 
+        if method == 'l1':
+            metric = 0
+        elif method == 'l2':
+            metric = 1
+        elif method == 'cosine':
+            metric = 2
+
         for count, shift in enumerate(shift_loop):
             src_sliced_templates = templates_array[:, num_shifts : num_samples - num_shifts]
             tgt_sliced_templates = other_templates_array[:, num_shifts + shift : num_samples - num_shifts + shift]
@@ -195,29 +261,29 @@ def _compute_similarity_matrix(templates_array, other_templates_array, num_shift
                     norm_j = 0
 
                     for k in range(len(src)):
-                        if method == "l1":
+                        if metric == 0:
                             norm_i += abs(src[k])
                             norm_j += abs(tgt[k])
                             distances[count, i, j] += abs(src[k] - tgt[k])
-                        elif method == "l2":
+                        elif metric == 1:
                             norm_i += src[k] ** 2
                             norm_j += tgt[k] ** 2
                             distances[count, i, j] += (src[k] - tgt[k]) ** 2
-                        elif method == "cosine":
+                        elif metric == 2:
                             distances[count, i, j] += src[k] * tgt[k]
                             norm_i += src[k] ** 2
                             norm_j += tgt[k] ** 2
 
-                    if method == "l1":
+                    if metric == 0:
                         distances[count, i, j] /= norm_i + norm_j
-                    elif method == "l2":
-                        norm_i = np.sqrt(norm_i)
-                        norm_j = np.sqrt(norm_j)
-                        distances[count, i, j] = np.sqrt(distances[count, i, j])
+                    elif metric == 1:
+                        norm_i = sqrt(norm_i)
+                        norm_j = sqrt(norm_j)
+                        distances[count, i, j] = sqrt(distances[count, i, j])
                         distances[count, i, j] /= norm_i + norm_j
-                    elif method == "cosine":
-                        norm_i = np.sqrt(norm_i)
-                        norm_j = np.sqrt(norm_j)
+                    elif metric == 2:
+                        norm_i = sqrt(norm_i)
+                        norm_j = sqrt(norm_j)
                         distances[count, i, j] /= norm_i * norm_j
                         distances[count, i, j] = 1 - distances[count, i, j]
 
@@ -226,67 +292,13 @@ def _compute_similarity_matrix(templates_array, other_templates_array, num_shift
 
             if same_array and num_shifts != 0:
                 distances[num_shifts_both_sides - count - 1] = distances[count].T
+                
         return distances
 
+    _compute_similarity_matrix = _compute_similarity_matrix_numba
 else:
+    _compute_similarity_matrix = _compute_similarity_matrix_numpy
 
-    def _compute_similarity_matrix(templates_array, other_templates_array, num_shifts, mask, method):
-
-        num_templates = templates_array.shape[0]
-        num_samples = templates_array.shape[1]
-        other_num_templates = other_templates_array.shape[0]
-
-        num_shifts_both_sides = 2 * num_shifts + 1
-        distances = np.ones((num_shifts_both_sides, num_templates, other_num_templates), dtype=np.float32)
-        same_array = np.array_equal(templates_array, other_templates_array)
-
-        # We can use the fact that dist[i,j] at lag t is equal to dist[j,i] at time -t
-        # So the matrix can be computed only for negative lags and be transposed
-
-        if same_array:
-            # optimisation when array are the same because of symetry in shift
-            shift_loop = range(-num_shifts, 1)
-        else:
-            shift_loop = range(-num_shifts, num_shifts + 1)
-
-        for count, shift in enumerate(shift_loop):
-            src_sliced_templates = templates_array[:, num_shifts : num_samples - num_shifts]
-            tgt_sliced_templates = other_templates_array[:, num_shifts + shift : num_samples - num_shifts + shift]
-            for i in range(num_templates):
-                src_template = src_sliced_templates[i]
-                overlapping_templates = np.flatnonzero(np.sum(mask[i], 1))
-                tgt_templates = tgt_sliced_templates[overlapping_templates]
-                for gcount, j in enumerate(overlapping_templates):
-                    # symmetric values are handled later
-                    if same_array and j < i:
-                        # no need exhaustive looping when same template
-                        continue
-                    src = src_template[:, mask[i, j]].reshape(1, -1)
-                    tgt = (tgt_templates[gcount][:, mask[i, j]]).reshape(1, -1)
-
-                    if method == "l1":
-                        norm_i = np.sum(np.abs(src))
-                        norm_j = np.sum(np.abs(tgt))
-                        distances[count, i, j] = np.sum(np.abs(src - tgt))
-                        distances[count, i, j] /= norm_i + norm_j
-                    elif method == "l2":
-                        norm_i = np.linalg.norm(src, ord=2)
-                        norm_j = np.linalg.norm(tgt, ord=2)
-                        distances[count, i, j] = np.linalg.norm(src - tgt, ord=2)
-                        distances[count, i, j] /= norm_i + norm_j
-                    elif method == "cosine":
-                        norm_i = np.linalg.norm(src, ord=2)
-                        norm_j = np.linalg.norm(tgt, ord=2)
-                        distances[count, i, j] = np.sum(src * tgt)
-                        distances[count, i, j] /= norm_i * norm_j
-                        distances[count, i, j] = 1 - distances[count, i, j]
-
-                    if same_array:
-                        distances[count, j, i] = distances[count, i, j]
-
-            if same_array and num_shifts != 0:
-                distances[num_shifts_both_sides - count - 1] = distances[count].T
-        return distances
 
 
 def compute_similarity_with_templates_array(

From b77d0b088c545c8ed54a8511cf585a860735c276 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Tue, 24 Sep 2024 08:19:02 +0000
Subject: [PATCH 028/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 .../postprocessing/template_similarity.py             | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/src/spikeinterface/postprocessing/template_similarity.py b/src/spikeinterface/postprocessing/template_similarity.py
index f2082150c9..18f6f88dba 100644
--- a/src/spikeinterface/postprocessing/template_similarity.py
+++ b/src/spikeinterface/postprocessing/template_similarity.py
@@ -153,6 +153,7 @@ def _get_data(self):
 register_result_extension(ComputeTemplateSimilarity)
 compute_template_similarity = ComputeTemplateSimilarity.function_factory()
 
+
 def _compute_similarity_matrix_numpy(templates_array, other_templates_array, num_shifts, mask, method):
 
     num_templates = templates_array.shape[0]
@@ -215,6 +216,7 @@ def _compute_similarity_matrix_numpy(templates_array, other_templates_array, num
 if HAVE_NUMBA:
 
     from math import sqrt
+
     @numba.jit(nopython=True, parallel=True, fastmath=True, nogil=True)
     def _compute_similarity_matrix_numba(templates_array, other_templates_array, num_shifts, mask, method):
         num_templates = templates_array.shape[0]
@@ -234,11 +236,11 @@ def _compute_similarity_matrix_numba(templates_array, other_templates_array, num
         else:
             shift_loop = range(-num_shifts, num_shifts + 1)
 
-        if method == 'l1':
+        if method == "l1":
             metric = 0
-        elif method == 'l2':
+        elif method == "l2":
             metric = 1
-        elif method == 'cosine':
+        elif method == "cosine":
             metric = 2
 
         for count, shift in enumerate(shift_loop):
@@ -292,7 +294,7 @@ def _compute_similarity_matrix_numba(templates_array, other_templates_array, num
 
             if same_array and num_shifts != 0:
                 distances[num_shifts_both_sides - count - 1] = distances[count].T
-                
+
         return distances
 
     _compute_similarity_matrix = _compute_similarity_matrix_numba
@@ -300,7 +302,6 @@ def _compute_similarity_matrix_numba(templates_array, other_templates_array, num
     _compute_similarity_matrix = _compute_similarity_matrix_numpy
 
 
-
 def compute_similarity_with_templates_array(
     templates_array, other_templates_array, method, support="union", num_shifts=0, sparsity=None, other_sparsity=None
 ):

From e383292dfa2e1bf7d35d73369ad2c5457394febf Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Tue, 24 Sep 2024 10:42:11 +0200
Subject: [PATCH 029/344] WIP

---
 .../postprocessing/template_similarity.py              | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/src/spikeinterface/postprocessing/template_similarity.py b/src/spikeinterface/postprocessing/template_similarity.py
index 18f6f88dba..9bfe899840 100644
--- a/src/spikeinterface/postprocessing/template_similarity.py
+++ b/src/spikeinterface/postprocessing/template_similarity.py
@@ -232,9 +232,9 @@ def _compute_similarity_matrix_numba(templates_array, other_templates_array, num
 
         if same_array:
             # optimisation when array are the same because of symetry in shift
-            shift_loop = range(-num_shifts, 1)
+            shift_loop = list(range(-num_shifts, 1))
         else:
-            shift_loop = range(-num_shifts, num_shifts + 1)
+            shift_loop = list(range(-num_shifts, num_shifts + 1))
 
         if method == "l1":
             metric = 0
@@ -243,15 +243,17 @@ def _compute_similarity_matrix_numba(templates_array, other_templates_array, num
         elif method == "cosine":
             metric = 2
 
-        for count, shift in enumerate(shift_loop):
+        for count in range(len(shift_loop)):
+            shift = shift_loop[count]
             src_sliced_templates = templates_array[:, num_shifts : num_samples - num_shifts]
             tgt_sliced_templates = other_templates_array[:, num_shifts + shift : num_samples - num_shifts + shift]
             for i in numba.prange(num_templates):
                 src_template = src_sliced_templates[i]
                 overlapping_templates = np.flatnonzero(np.sum(mask[i], 1))
                 tgt_templates = tgt_sliced_templates[overlapping_templates]
-                for gcount, j in enumerate(overlapping_templates):
+                for gcount in range(len(overlapping_templates)):
 
+                    j = overlapping_templates[gcount]
                     # symmetric values are handled later
                     if same_array and j < i:
                         # no need exhaustive looping when same template

From f46d13e0810ea66193206e9c49dc7bb7cc388f7c Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Tue, 24 Sep 2024 12:01:36 +0200
Subject: [PATCH 030/344] Refactoring auto_merge

---
 src/spikeinterface/curation/auto_merge.py | 339 ++++++++++++++++------
 1 file changed, 251 insertions(+), 88 deletions(-)

diff --git a/src/spikeinterface/curation/auto_merge.py b/src/spikeinterface/curation/auto_merge.py
index 19336e5943..00c156094d 100644
--- a/src/spikeinterface/curation/auto_merge.py
+++ b/src/spikeinterface/curation/auto_merge.py
@@ -12,8 +12,6 @@
     HAVE_NUMBA = False
 
 from ..core import SortingAnalyzer, Templates
-from ..core.template_tools import get_template_extremum_channel
-from ..postprocessing import compute_correlograms
 from ..qualitymetrics import compute_refrac_period_violations, compute_firing_rates
 
 from .mergeunitssorting import MergeUnitsSorting
@@ -25,35 +23,43 @@
 _required_extensions = {
     "unit_locations": ["unit_locations"],
     "correlogram": ["correlograms"],
+    "min_snr": ["noise_levels", "templates"],
     "template_similarity": ["template_similarity"],
     "knn": ["spike_locations", "spike_amplitudes"],
 }
 
+_templates_needed = ["unit_locations", "min_snr", "template_similarity", "spike_locations", "spike_amplitudes"]
 
-def get_potential_auto_merge(
+
+def auto_merges(
     sorting_analyzer: SortingAnalyzer,
     preset: str | None = "similarity_correlograms",
     resolve_graph: bool = False,
-    min_spikes: int = 100,
-    min_snr: float = 2,
-    max_distance_um: float = 150.0,
-    corr_diff_thresh: float = 0.16,
-    template_diff_thresh: float = 0.25,
-    contamination_thresh: float = 0.2,
-    presence_distance_thresh: float = 100,
-    p_value: float = 0.2,
-    cc_thresh: float = 0.1,
-    censored_period_ms: float = 0.3,
-    refractory_period_ms: float = 1.0,
-    sigma_smooth_ms: float = 0.6,
-    adaptative_window_thresh: float = 0.5,
-    censor_correlograms_ms: float = 0.15,
-    firing_contamination_balance: float = 2.5,
-    k_nn: int = 10,
-    knn_kwargs: dict | None = None,
-    presence_distance_kwargs: dict | None = None,
+    num_spikes_kwargs={"min_spikes": 100},
+    snr_kwargs={"min_snr": 2},
+    remove_contaminated_kwargs={"contamination_thresh": 0.2, "refractory_period_ms": 1.0, "censored_period_ms": 0.3},
+    unit_locations_kwargs={"max_distance_um": 50},
+    correlogram_kwargs={
+        "corr_diff_thresh": 0.16,
+        "censor_correlograms_ms": 0.3,
+        "sigma_smooth_ms": 0.6,
+        "adaptative_window_thresh": 0.5,
+    },
+    template_similarity_kwargs={"template_diff_thresh": 0.25},
+    presence_distance_kwargs={"presence_distance_thresh": 100},
+    knn_kwargs={"k_nn": 10},
+    cross_contamination_kwargs={
+        "cc_thresh": 0.1,
+        "p_value": 0.2,
+        "refractory_period_ms": 1.0,
+        "censored_period_ms": 0.3,
+    },
+    quality_score_kwargs={"firing_contamination_balance": 2.5, "refractory_period_ms": 1.0, "censored_period_ms": 0.3},
+    compute_needed_extensions: bool = True,
     extra_outputs: bool = False,
     steps: list[str] | None = None,
+    force_copy: bool = True,
+    **job_kwargs,
 ) -> list[tuple[int | str, int | str]] | Tuple[tuple[int | str, int | str], dict]:
     """
     Algorithm to find and check potential merges between units.
@@ -98,56 +104,21 @@ def get_potential_auto_merge(
         * | "feature_neighbors": focused on finding unit pairs whose spikes are close in the feature space using kNN.
           | It uses the following steps: "num_spikes", "snr", "remove_contaminated", "unit_locations",
           | "knn", "quality_score"
-
         If `preset` is None, you can specify the steps manually with the `steps` parameter.
     resolve_graph : bool, default: False
         If True, the function resolves the potential unit pairs to be merged into multiple-unit merges.
-    min_spikes : int, default: 100
-        Minimum number of spikes for each unit to consider a potential merge.
-        Enough spikes are needed to estimate the correlogram
-    min_snr : float, default 2
-        Minimum Signal to Noise ratio for templates to be considered while merging
-    max_distance_um : float, default: 150
-        Maximum distance between units for considering a merge
-    corr_diff_thresh : float, default: 0.16
-        The threshold on the "correlogram distance metric" for considering a merge.
-        It needs to be between 0 and 1
-    template_diff_thresh : float, default: 0.25
-        The threshold on the "template distance metric" for considering a merge.
-        It needs to be between 0 and 1
-    contamination_thresh : float, default: 0.2
-        Threshold for not taking in account a unit when it is too contaminated.
-    presence_distance_thresh : float, default: 100
-        Parameter to control how present two units should be simultaneously.
-    p_value : float, default: 0.2
-        The p-value threshold for the cross-contamination test.
-    cc_thresh : float, default: 0.1
-        The threshold on the cross-contamination for considering a merge.
-    censored_period_ms : float, default: 0.3
-        Used to compute the refractory period violations aka "contamination".
-    refractory_period_ms : float, default: 1
-        Used to compute the refractory period violations aka "contamination".
-    sigma_smooth_ms : float, default: 0.6
-        Parameters to smooth the correlogram estimation.
-    adaptative_window_thresh : float, default: 0.5
-        Parameter to detect the window size in correlogram estimation.
-    censor_correlograms_ms : float, default: 0.15
-        The period to censor on the auto and cross-correlograms.
-    firing_contamination_balance : float, default: 2.5
-        Parameter to control the balance between firing rate and contamination in computing unit "quality score".
-    k_nn : int, default 5
-        The number of neighbors to consider for every spike in the recording.
-    knn_kwargs : dict, default None
-        The dict of extra params to be passed to knn.
+    compute_needed_extensions : bool, default : True
+        Should we force the computation of needed extensions?
     extra_outputs : bool, default: False
         If True, an additional dictionary (`outs`) with processed data is returned.
     steps : None or list of str, default: None
         Which steps to run, if no preset is used.
         Pontential steps : "num_spikes", "snr", "remove_contaminated", "unit_locations", "correlogram",
         "template_similarity", "presence_distance", "cross_contamination", "knn", "quality_score"
-        Please check steps explanations above!
-    presence_distance_kwargs : None|dict, default: None
-        A dictionary of kwargs to be passed to compute_presence_distance().
+        Please check steps explanations above!$
+    force_copy : boolean, default: True
+        When new extensions are computed, the default is to make a copy of the analyzer, to avoid overwriting
+        already computed extensions. False if you want to overwrite
 
     Returns
     -------
@@ -230,12 +201,24 @@ def get_potential_auto_merge(
                 "knn",
                 "quality_score",
             ]
+    if force_copy and compute_needed_extensions:
+        # To avoid erasing the extensions of the user
+        sorting_analyzer = sorting_analyzer.copy()
 
     for step in steps:
         if step in _required_extensions:
             for ext in _required_extensions[step]:
-                if not sorting_analyzer.has_extension(ext):
-                    raise ValueError(f"{step} requires {ext} extension")
+                if compute_needed_extensions:
+                    if step in _templates_needed:
+                        template_ext = sorting_analyzer.get_extension("templates")
+                        if template_ext is None:
+                            sorting_analyzer.compute(["random_spikes", "templates"], **job_kwargs)
+                    params = eval(f"{step}_kwargs")
+                    params = params.get(ext, dict())
+                    sorting_analyzer.compute(ext, **params, **job_kwargs)
+                else:
+                    if not sorting_analyzer.has_extension(ext):
+                        raise ValueError(f"{step} requires {ext} extension")
 
     n = unit_ids.size
     pair_mask = np.triu(np.arange(n)) > 0
@@ -248,33 +231,38 @@ def get_potential_auto_merge(
         # STEP : remove units with too few spikes
         if step == "num_spikes":
             num_spikes = sorting.count_num_spikes_per_unit(outputs="array")
-            to_remove = num_spikes < min_spikes
+            to_remove = num_spikes < num_spikes_kwargs["min_spikes"]
             pair_mask[to_remove, :] = False
             pair_mask[:, to_remove] = False
+            outs["num_spikes"] = to_remove
 
         # STEP : remove units with too small SNR
         elif step == "snr":
             qm_ext = sorting_analyzer.get_extension("quality_metrics")
             if qm_ext is None:
-                sorting_analyzer.compute("noise_levels")
-                sorting_analyzer.compute("quality_metrics", metric_names=["snr"])
+                sorting_analyzer.compute(["noise_levels"], **job_kwargs)
+                sorting_analyzer.compute("quality_metrics", metric_names=["snr"], **job_kwargs)
                 qm_ext = sorting_analyzer.get_extension("quality_metrics")
 
             snrs = qm_ext.get_data()["snr"].values
-            to_remove = snrs < min_snr
+            to_remove = snrs < snr_kwargs["min_snr"]
             pair_mask[to_remove, :] = False
             pair_mask[:, to_remove] = False
+            outs["snr"] = to_remove
 
         # STEP : remove contaminated auto corr
         elif step == "remove_contaminated":
             contaminations, nb_violations = compute_refrac_period_violations(
-                sorting_analyzer, refractory_period_ms=refractory_period_ms, censored_period_ms=censored_period_ms
+                sorting_analyzer,
+                refractory_period_ms=remove_contaminated_kwargs["refractory_period_ms"],
+                censored_period_ms=remove_contaminated_kwargs["censored_period_ms"],
             )
             nb_violations = np.array(list(nb_violations.values()))
             contaminations = np.array(list(contaminations.values()))
-            to_remove = contaminations > contamination_thresh
+            to_remove = contaminations > remove_contaminated_kwargs["contamination_thresh"]
             pair_mask[to_remove, :] = False
             pair_mask[:, to_remove] = False
+            outs["remove_contaminated"] = to_remove
 
         # STEP : unit positions are estimated roughly with channel
         elif step == "unit_locations" in steps:
@@ -282,21 +270,23 @@ def get_potential_auto_merge(
             unit_locations = location_ext.get_data()[:, :2]
 
             unit_distances = scipy.spatial.distance.cdist(unit_locations, unit_locations, metric="euclidean")
-            pair_mask = pair_mask & (unit_distances <= max_distance_um)
+            pair_mask = pair_mask & (unit_distances <= unit_locations_kwargs["max_distance_um"])
             outs["unit_distances"] = unit_distances
 
         # STEP : potential auto merge by correlogram
         elif step == "correlogram" in steps:
             correlograms_ext = sorting_analyzer.get_extension("correlograms")
             correlograms, bins = correlograms_ext.get_data()
-            mask = (bins[:-1] >= -censor_correlograms_ms) & (bins[:-1] < censor_correlograms_ms)
+            censor_ms = correlogram_kwargs["censor_correlograms_ms"]
+            sigma_smooth_ms = correlogram_kwargs["sigma_smooth_ms"]
+            mask = (bins[:-1] >= -censor_ms) & (bins[:-1] < censor_ms)
             correlograms[:, :, mask] = 0
             correlograms_smoothed = smooth_correlogram(correlograms, bins, sigma_smooth_ms=sigma_smooth_ms)
             # find correlogram window for each units
             win_sizes = np.zeros(n, dtype=int)
             for unit_ind in range(n):
                 auto_corr = correlograms_smoothed[unit_ind, unit_ind, :]
-                thresh = np.max(auto_corr) * adaptative_window_thresh
+                thresh = np.max(auto_corr) * correlogram_kwargs["adaptative_window_thresh"]
                 win_size = get_unit_adaptive_window(auto_corr, thresh)
                 win_sizes[unit_ind] = win_size
             correlogram_diff = compute_correlogram_diff(
@@ -306,7 +296,7 @@ def get_potential_auto_merge(
                 pair_mask=pair_mask,
             )
             # print(correlogram_diff)
-            pair_mask = pair_mask & (correlogram_diff < corr_diff_thresh)
+            pair_mask = pair_mask & (correlogram_diff < correlogram_kwargs["corr_diff_thresh"])
             outs["correlograms"] = correlograms
             outs["bins"] = bins
             outs["correlograms_smoothed"] = correlograms_smoothed
@@ -318,18 +308,17 @@ def get_potential_auto_merge(
             template_similarity_ext = sorting_analyzer.get_extension("template_similarity")
             templates_similarity = template_similarity_ext.get_data()
             templates_diff = 1 - templates_similarity
-            pair_mask = pair_mask & (templates_diff < template_diff_thresh)
+            pair_mask = pair_mask & (templates_diff < template_similarity_kwargs["template_diff_thresh"])
             outs["templates_diff"] = templates_diff
 
         # STEP : check the vicinity of the spikes
         elif step == "knn" in steps:
-            if knn_kwargs is None:
-                knn_kwargs = dict()
-            pair_mask = get_pairs_via_nntree(sorting_analyzer, k_nn, pair_mask, **knn_kwargs)
+            pair_mask = get_pairs_via_nntree(sorting_analyzer, **knn_kwargs, pair_mask=pair_mask)
 
         # STEP : check how the rates overlap in times
         elif step == "presence_distance" in steps:
-            presence_distance_kwargs = presence_distance_kwargs or dict()
+            presence_distance_kwargs = presence_distance_kwargs.copy()
+            presence_distance_thresh = presence_distance_kwargs.pop("presence_distance_thresh")
             num_samples = [
                 sorting_analyzer.get_num_samples(segment_index) for segment_index in range(sorting.get_num_segments())
             ]
@@ -341,11 +330,14 @@ def get_potential_auto_merge(
 
         # STEP : check if the cross contamination is significant
         elif step == "cross_contamination" in steps:
-            refractory = (censored_period_ms, refractory_period_ms)
+            refractory = (
+                cross_contamination_kwargs["censored_period_ms"],
+                cross_contamination_kwargs["refractory_period_ms"],
+            )
             CC, p_values = compute_cross_contaminations(
-                sorting_analyzer, pair_mask, cc_thresh, refractory, contaminations
+                sorting_analyzer, pair_mask, cross_contamination_kwargs["cc_thresh"], refractory, contaminations
             )
-            pair_mask = pair_mask & (p_values > p_value)
+            pair_mask = pair_mask & (p_values > cross_contamination_kwargs["p_value"])
             outs["cross_contaminations"] = CC, p_values
 
         # STEP : validate the potential merges with CC increase the contamination quality metrics
@@ -354,9 +346,9 @@ def get_potential_auto_merge(
                 sorting_analyzer,
                 pair_mask,
                 contaminations,
-                firing_contamination_balance,
-                refractory_period_ms,
-                censored_period_ms,
+                quality_score_kwargs["firing_contamination_balance"],
+                quality_score_kwargs["refractory_period_ms"],
+                quality_score_kwargs["censored_period_ms"],
             )
             outs["pairs_decreased_score"] = pairs_decreased_score
 
@@ -364,9 +356,6 @@ def get_potential_auto_merge(
     ind1, ind2 = np.nonzero(pair_mask)
     potential_merges = list(zip(unit_ids[ind1], unit_ids[ind2]))
 
-    # some methods return identities ie (1,1) which we can cleanup first.
-    potential_merges = [(ids[0], ids[1]) for ids in potential_merges if ids[0] != ids[1]]
-
     if resolve_graph:
         potential_merges = resolve_merging_graph(sorting, potential_merges)
 
@@ -376,6 +365,180 @@ def get_potential_auto_merge(
         return potential_merges
 
 
+def get_potential_auto_merge(
+    sorting_analyzer: SortingAnalyzer,
+    preset: str | None = "similarity_correlograms",
+    resolve_graph: bool = False,
+    min_spikes: int = 100,
+    min_snr: float = 2,
+    max_distance_um: float = 150.0,
+    corr_diff_thresh: float = 0.16,
+    template_diff_thresh: float = 0.25,
+    contamination_thresh: float = 0.2,
+    presence_distance_thresh: float = 100,
+    p_value: float = 0.2,
+    cc_thresh: float = 0.1,
+    censored_period_ms: float = 0.3,
+    refractory_period_ms: float = 1.0,
+    sigma_smooth_ms: float = 0.6,
+    adaptative_window_thresh: float = 0.5,
+    censor_correlograms_ms: float = 0.15,
+    firing_contamination_balance: float = 2.5,
+    k_nn: int = 10,
+    knn_kwargs: dict | None = None,
+    presence_distance_kwargs: dict | None = None,
+    extra_outputs: bool = False,
+    steps: list[str] | None = None,
+) -> list[tuple[int | str, int | str]] | Tuple[tuple[int | str, int | str], dict]:
+    """
+    Algorithm to find and check potential merges between units.
+
+    The merges are proposed based on a series of steps with different criteria:
+
+        * "num_spikes": enough spikes are found in each unit for computing the correlogram (`min_spikes`)
+        * "snr": the SNR of the units is above a threshold (`min_snr`)
+        * "remove_contaminated": each unit is not contaminated (by checking auto-correlogram - `contamination_thresh`)
+        * "unit_locations": estimated unit locations are close enough (`max_distance_um`)
+        * "correlogram": the cross-correlograms of the two units are similar to each auto-corrleogram (`corr_diff_thresh`)
+        * "template_similarity": the templates of the two units are similar (`template_diff_thresh`)
+        * "presence_distance": the presence of the units is complementary in time (`presence_distance_thresh`)
+        * "cross_contamination": the cross-contamination is not significant (`cc_thresh` and `p_value`)
+        * "knn": the two units are close in the feature space
+        * "quality_score": the unit "quality score" is increased after the merge
+
+    The "quality score" factors in the increase in firing rate (**f**) due to the merge and a possible increase in
+    contamination (**C**), wheighted by a factor **k** (`firing_contamination_balance`).
+
+    .. math::
+
+        Q = f(1 - (k + 1)C)
+
+
+    Parameters
+    ----------
+    sorting_analyzer : SortingAnalyzer
+        The SortingAnalyzer
+    preset : "similarity_correlograms" | "x_contaminations" | "temporal_splits" | "feature_neighbors" | None, default: "similarity_correlograms"
+        The preset to use for the auto-merge. Presets combine different steps into a recipe and focus on:
+
+        * | "similarity_correlograms": mainly focused on template similarity and correlograms.
+          | It uses the following steps: "num_spikes", "remove_contaminated", "unit_locations",
+          | "template_similarity", "correlogram", "quality_score"
+        * | "x_contaminations": similar to "similarity_correlograms", but checks for cross-contamination instead of correlograms.
+          | It uses the following steps: "num_spikes", "remove_contaminated", "unit_locations",
+          | "template_similarity", "cross_contamination", "quality_score"
+        * | "temporal_splits": focused on finding temporal splits using presence distance.
+          | It uses the following steps: "num_spikes", "remove_contaminated", "unit_locations",
+          | "template_similarity", "presence_distance", "quality_score"
+        * | "feature_neighbors": focused on finding unit pairs whose spikes are close in the feature space using kNN.
+          | It uses the following steps: "num_spikes", "snr", "remove_contaminated", "unit_locations",
+          | "knn", "quality_score"
+
+        If `preset` is None, you can specify the steps manually with the `steps` parameter.
+    resolve_graph : bool, default: False
+        If True, the function resolves the potential unit pairs to be merged into multiple-unit merges.
+    min_spikes : int, default: 100
+        Minimum number of spikes for each unit to consider a potential merge.
+        Enough spikes are needed to estimate the correlogram
+    min_snr : float, default 2
+        Minimum Signal to Noise ratio for templates to be considered while merging
+    max_distance_um : float, default: 150
+        Maximum distance between units for considering a merge
+    corr_diff_thresh : float, default: 0.16
+        The threshold on the "correlogram distance metric" for considering a merge.
+        It needs to be between 0 and 1
+    template_diff_thresh : float, default: 0.25
+        The threshold on the "template distance metric" for considering a merge.
+        It needs to be between 0 and 1
+    contamination_thresh : float, default: 0.2
+        Threshold for not taking in account a unit when it is too contaminated.
+    presence_distance_thresh : float, default: 100
+        Parameter to control how present two units should be simultaneously.
+    p_value : float, default: 0.2
+        The p-value threshold for the cross-contamination test.
+    cc_thresh : float, default: 0.1
+        The threshold on the cross-contamination for considering a merge.
+    censored_period_ms : float, default: 0.3
+        Used to compute the refractory period violations aka "contamination".
+    refractory_period_ms : float, default: 1
+        Used to compute the refractory period violations aka "contamination".
+    sigma_smooth_ms : float, default: 0.6
+        Parameters to smooth the correlogram estimation.
+    adaptative_window_thresh : float, default: 0.5
+        Parameter to detect the window size in correlogram estimation.
+    censor_correlograms_ms : float, default: 0.15
+        The period to censor on the auto and cross-correlograms.
+    firing_contamination_balance : float, default: 2.5
+        Parameter to control the balance between firing rate and contamination in computing unit "quality score".
+    k_nn : int, default 5
+        The number of neighbors to consider for every spike in the recording.
+    knn_kwargs : dict, default None
+        The dict of extra params to be passed to knn.
+    extra_outputs : bool, default: False
+        If True, an additional dictionary (`outs`) with processed data is returned.
+    steps : None or list of str, default: None
+        Which steps to run, if no preset is used.
+        Pontential steps : "num_spikes", "snr", "remove_contaminated", "unit_locations", "correlogram",
+        "template_similarity", "presence_distance", "cross_contamination", "knn", "quality_score"
+        Please check steps explanations above!
+    presence_distance_kwargs : None|dict, default: None
+        A dictionary of kwargs to be passed to compute_presence_distance().
+
+    Returns
+    -------
+    potential_merges:
+        A list of tuples of 2 elements (if `resolve_graph`if false) or 2+ elements (if `resolve_graph` is true).
+        List of pairs that could be merged.
+    outs:
+        Returned only when extra_outputs=True
+        A dictionary that contains data for debugging and plotting.
+
+    References
+    ----------
+    This function is inspired and built upon similar functions from Lussac [Llobet]_,
+    done by Aurelien Wyngaard and Victor Llobet.
+    https://github.com/BarbourLab/lussac/blob/v1.0.0/postprocessing/merge_units.py
+    """
+    presence_distance_kwargs = presence_distance_kwargs or dict()
+    knn_kwargs = knn_kwargs or dict()
+    return auto_merges(
+        sorting_analyzer,
+        preset,
+        resolve_graph,
+        num_spikes_kwargs={"min_spikes": min_spikes},
+        snr_kwargs={"min_snr": min_snr},
+        remove_contaminated_kwargs={
+            "contamination_thresh": contamination_thresh,
+            "refractory_period_ms": refractory_period_ms,
+            "censored_period_ms": censored_period_ms,
+        },
+        unit_locations_kwargs={"max_distance_um": max_distance_um},
+        correlogram_kwargs={
+            "corr_diff_thresh": corr_diff_thresh,
+            "censor_correlograms_ms": censor_correlograms_ms,
+            "sigma_smooth_ms": sigma_smooth_ms,
+            "adaptative_window_thresh": adaptative_window_thresh,
+        },
+        template_similarity_kwargs={"template_diff_thresh": template_diff_thresh},
+        presence_distance_kwargs={"presence_distance_thresh": presence_distance_thresh, **presence_distance_kwargs},
+        knn_kwargs={"k_nn": k_nn, **knn_kwargs},
+        cross_contamination_kwargs={
+            "cc_thresh": cc_thresh,
+            "p_value": p_value,
+            "refractory_period_ms": refractory_period_ms,
+            "censored_period_ms": censored_period_ms,
+        },
+        quality_score_kwargs={
+            "firing_contamination_balance": firing_contamination_balance,
+            "refractory_period_ms": refractory_period_ms,
+            "censored_period_ms": censored_period_ms,
+        },
+        compute_needed_extensions=False,
+        extra_outputs=extra_outputs,
+        steps=steps,
+    )
+
+
 def get_pairs_via_nntree(sorting_analyzer, k_nn=5, pair_mask=None, **knn_kwargs):
 
     sorting = sorting_analyzer.sorting

From 1505a213d58fde4ee232adc57c4767654a4f8e32 Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Wed, 25 Sep 2024 15:30:11 +0200
Subject: [PATCH 031/344] Adding tests

---
 .../postprocessing/template_similarity.py     |  1 +
 .../postprocessing/tests/test_correlograms.py |  1 -
 .../tests/test_template_similarity.py         | 42 ++++++++++++++++++-
 3 files changed, 42 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/postprocessing/template_similarity.py b/src/spikeinterface/postprocessing/template_similarity.py
index 9bfe899840..cfa9d89fea 100644
--- a/src/spikeinterface/postprocessing/template_similarity.py
+++ b/src/spikeinterface/postprocessing/template_similarity.py
@@ -263,6 +263,7 @@ def _compute_similarity_matrix_numba(templates_array, other_templates_array, num
 
                     norm_i = 0
                     norm_j = 0
+                    distances[count, i, j] = 0
 
                     for k in range(len(src)):
                         if metric == 0:
diff --git a/src/spikeinterface/postprocessing/tests/test_correlograms.py b/src/spikeinterface/postprocessing/tests/test_correlograms.py
index 66d84c9565..0431c8d675 100644
--- a/src/spikeinterface/postprocessing/tests/test_correlograms.py
+++ b/src/spikeinterface/postprocessing/tests/test_correlograms.py
@@ -93,7 +93,6 @@ def test_equal_results_correlograms(window_and_bin_ms):
     )
 
     assert np.array_equal(result_numpy, result_numba)
-    assert np.array_equal(result_numpy, result_numba)
 
 
 @pytest.mark.parametrize("method", ["numpy", param("numba", marks=SKIP_NUMBA)])
diff --git a/src/spikeinterface/postprocessing/tests/test_template_similarity.py b/src/spikeinterface/postprocessing/tests/test_template_similarity.py
index cc6797c262..364c54beea 100644
--- a/src/spikeinterface/postprocessing/tests/test_template_similarity.py
+++ b/src/spikeinterface/postprocessing/tests/test_template_similarity.py
@@ -7,7 +7,19 @@
 )
 
 from spikeinterface.postprocessing import check_equal_template_with_distribution_overlap, ComputeTemplateSimilarity
-from spikeinterface.postprocessing.template_similarity import compute_similarity_with_templates_array
+from spikeinterface.postprocessing.template_similarity import compute_similarity_with_templates_array, _compute_similarity_matrix_numba, _compute_similarity_matrix_numpy
+
+try:
+    import numba
+
+    HAVE_NUMBA = True
+except ModuleNotFoundError as err:
+    HAVE_NUMBA = False
+
+import pytest
+from pytest import param
+
+SKIP_NUMBA = pytest.mark.skipif(not HAVE_NUMBA, reason="Numba not available")
 
 
 class TestSimilarityExtension(AnalyzerExtensionCommonTestSuite):
@@ -71,6 +83,34 @@ def test_compute_similarity_with_templates_array(params):
     similarity = compute_similarity_with_templates_array(templates_array, other_templates_array, **params)
     print(similarity.shape)
 
+pytest.mark.skipif(not HAVE_NUMBA, reason="Numba not available")
+@pytest.mark.parametrize(
+    "params",
+    [
+        dict(method="cosine", num_shifts=8),
+        dict(method="l1", num_shifts=0),
+        dict(method="l2", num_shifts=0),
+        dict(method="cosine", num_shifts=0),
+    ],
+)
+def test_equal_results_numba(params):
+    """
+    Test that the 2 methods have same results with some varied time bins
+    that are not tested in other tests.
+    """
+
+    rng = np.random.default_rng(seed=2205)
+    templates_array = rng.random(size=(4, 20, 5), dtype=np.float32)
+    other_templates_array = rng.random(size=(2, 20, 5), dtype=np.float32)
+    mask = np.ones((4, 2, 5), dtype=bool)
+
+    result_numpy = _compute_similarity_matrix_numba(templates_array, other_templates_array, mask=mask, **params)
+    result_numba = _compute_similarity_matrix_numpy(templates_array, other_templates_array, mask=mask, **params)
+
+    assert np.allclose(result_numpy, result_numba, 1e-3)
+
+
+
 
 if __name__ == "__main__":
     from spikeinterface.postprocessing.tests.common_extension_tests import get_dataset

From 9caa8c9c12324d02afa80d94c617ee39f0b271c2 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Wed, 25 Sep 2024 13:43:55 +0000
Subject: [PATCH 032/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 .../postprocessing/tests/test_template_similarity.py  | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/src/spikeinterface/postprocessing/tests/test_template_similarity.py b/src/spikeinterface/postprocessing/tests/test_template_similarity.py
index 364c54beea..2b6cd566b3 100644
--- a/src/spikeinterface/postprocessing/tests/test_template_similarity.py
+++ b/src/spikeinterface/postprocessing/tests/test_template_similarity.py
@@ -7,7 +7,11 @@
 )
 
 from spikeinterface.postprocessing import check_equal_template_with_distribution_overlap, ComputeTemplateSimilarity
-from spikeinterface.postprocessing.template_similarity import compute_similarity_with_templates_array, _compute_similarity_matrix_numba, _compute_similarity_matrix_numpy
+from spikeinterface.postprocessing.template_similarity import (
+    compute_similarity_with_templates_array,
+    _compute_similarity_matrix_numba,
+    _compute_similarity_matrix_numpy,
+)
 
 try:
     import numba
@@ -83,7 +87,10 @@ def test_compute_similarity_with_templates_array(params):
     similarity = compute_similarity_with_templates_array(templates_array, other_templates_array, **params)
     print(similarity.shape)
 
+
 pytest.mark.skipif(not HAVE_NUMBA, reason="Numba not available")
+
+
 @pytest.mark.parametrize(
     "params",
     [
@@ -110,8 +117,6 @@ def test_equal_results_numba(params):
     assert np.allclose(result_numpy, result_numba, 1e-3)
 
 
-
-
 if __name__ == "__main__":
     from spikeinterface.postprocessing.tests.common_extension_tests import get_dataset
     from spikeinterface.core import estimate_sparsity

From 1f2e37a2fb5201627c5472c1840e32bbf3efcb0b Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Wed, 25 Sep 2024 15:48:34 +0200
Subject: [PATCH 033/344] Imports

---
 .../postprocessing/tests/test_template_similarity.py            | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/postprocessing/tests/test_template_similarity.py b/src/spikeinterface/postprocessing/tests/test_template_similarity.py
index 2b6cd566b3..20d8373981 100644
--- a/src/spikeinterface/postprocessing/tests/test_template_similarity.py
+++ b/src/spikeinterface/postprocessing/tests/test_template_similarity.py
@@ -9,7 +9,6 @@
 from spikeinterface.postprocessing import check_equal_template_with_distribution_overlap, ComputeTemplateSimilarity
 from spikeinterface.postprocessing.template_similarity import (
     compute_similarity_with_templates_array,
-    _compute_similarity_matrix_numba,
     _compute_similarity_matrix_numpy,
 )
 
@@ -17,6 +16,7 @@
     import numba
 
     HAVE_NUMBA = True
+    from spikeinterface.postprocessing.template_similarity import _compute_similarity_matrix_numba
 except ModuleNotFoundError as err:
     HAVE_NUMBA = False
 

From 4797e96f8d397716310a56c75f166cf42ecdad30 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Wed, 25 Sep 2024 15:54:38 +0200
Subject: [PATCH 034/344] Get default encoding for Popen

---
 src/spikeinterface/sorters/utils/shellscript.py | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/spikeinterface/sorters/utils/shellscript.py b/src/spikeinterface/sorters/utils/shellscript.py
index 286445dd2d..24f353bf00 100644
--- a/src/spikeinterface/sorters/utils/shellscript.py
+++ b/src/spikeinterface/sorters/utils/shellscript.py
@@ -86,15 +86,15 @@ def start(self) -> None:
         if self._verbose:
             print("RUNNING SHELL SCRIPT: " + cmd)
         self._start_time = time.time()
+        encoding = sys.getdefaultencoding()
         self._process = subprocess.Popen(
-            cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, bufsize=1, universal_newlines=True
+            cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, bufsize=1, universal_newlines=True, encoding=encoding
         )
         with open(script_log_path, "w+") as script_log_file:
             for line in self._process.stdout:
                 script_log_file.write(line)
-                if (
-                    self._verbose
-                ):  # Print onto console depending on the verbose property passed on from the sorter class
+                if self._verbose:
+                    # Print onto console depending on the verbose property passed on from the sorter class
                     print(line)
 
     def wait(self, timeout=None) -> Optional[int]:

From 30c397819da01fc762d29194d3cc1b52af3174d0 Mon Sep 17 00:00:00 2001
From: zm711 <92116279+zm711@users.noreply.github.com>
Date: Wed, 25 Sep 2024 10:14:08 -0400
Subject: [PATCH 035/344] back to dev mode

---
 pyproject.toml                 | 16 ++++++++--------
 src/spikeinterface/__init__.py |  4 ++--
 2 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index c1c02db8db..c1a150028b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -124,16 +124,16 @@ test_core = [
 
     # for github test : probeinterface and neo from master
     # for release we need pypi, so this need to be commented
-    # "probeinterface @ git+https://github.com/SpikeInterface/probeinterface.git",
-    # "neo @ git+https://github.com/NeuralEnsemble/python-neo.git",
+     "probeinterface @ git+https://github.com/SpikeInterface/probeinterface.git",
+     "neo @ git+https://github.com/NeuralEnsemble/python-neo.git",
 ]
 
 test_extractors = [
     # Functions to download data in neo test suite
     "pooch>=1.8.2",
     "datalad>=1.0.2",
-    # "probeinterface @ git+https://github.com/SpikeInterface/probeinterface.git",
-    # "neo @ git+https://github.com/NeuralEnsemble/python-neo.git",
+     "probeinterface @ git+https://github.com/SpikeInterface/probeinterface.git",
+     "neo @ git+https://github.com/NeuralEnsemble/python-neo.git",
 ]
 
 test_preprocessing = [
@@ -173,8 +173,8 @@ test = [
 
     # for github test : probeinterface and neo from master
     # for release we need pypi, so this need to be commented
-    # "probeinterface @ git+https://github.com/SpikeInterface/probeinterface.git",
-    # "neo @ git+https://github.com/NeuralEnsemble/python-neo.git",
+     "probeinterface @ git+https://github.com/SpikeInterface/probeinterface.git",
+     "neo @ git+https://github.com/NeuralEnsemble/python-neo.git",
 ]
 
 docs = [
@@ -197,8 +197,8 @@ docs = [
     "datalad>=1.0.2",
 
     # for release we need pypi, so this needs to be commented
-    # "probeinterface @ git+https://github.com/SpikeInterface/probeinterface.git",  # We always build from the latest version
-    # "neo @ git+https://github.com/NeuralEnsemble/python-neo.git",  # We always build from the latest version
+     "probeinterface @ git+https://github.com/SpikeInterface/probeinterface.git",  # We always build from the latest version
+     "neo @ git+https://github.com/NeuralEnsemble/python-neo.git",  # We always build from the latest version
 
 ]
 
diff --git a/src/spikeinterface/__init__.py b/src/spikeinterface/__init__.py
index 97fb95b623..306c12d516 100644
--- a/src/spikeinterface/__init__.py
+++ b/src/spikeinterface/__init__.py
@@ -30,5 +30,5 @@
 # This flag must be set to False for release
 # This avoids using versioning that contains ".dev0" (and this is a better choice)
 # This is mainly useful when using run_sorter in a container and spikeinterface install
-# DEV_MODE = True
-DEV_MODE = False
+DEV_MODE = True
+# DEV_MODE = False

From 3b5645f58abda184147331dece3e21dd59404573 Mon Sep 17 00:00:00 2001
From: zm711 <92116279+zm711@users.noreply.github.com>
Date: Wed, 25 Sep 2024 10:51:15 -0400
Subject: [PATCH 036/344] bump version number

---
 pyproject.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pyproject.toml b/pyproject.toml
index c1a150028b..d246520280 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "spikeinterface"
-version = "0.101.1"
+version = "0.101.2"
 authors = [
   { name="Alessio Buccino", email="alessiop.buccino@gmail.com" },
   { name="Samuel Garcia", email="sam.garcia.die@gmail.com" },

From c86cd5f996e93183265588bc999bec8a756e7e1e Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Wed, 25 Sep 2024 19:22:31 +0200
Subject: [PATCH 037/344] Allow to save recordingless analyzer as

---
 src/spikeinterface/core/sortinganalyzer.py | 48 +++++++++++++---------
 1 file changed, 28 insertions(+), 20 deletions(-)

diff --git a/src/spikeinterface/core/sortinganalyzer.py b/src/spikeinterface/core/sortinganalyzer.py
index 4961db8524..e4bed0dbb6 100644
--- a/src/spikeinterface/core/sortinganalyzer.py
+++ b/src/spikeinterface/core/sortinganalyzer.py
@@ -352,8 +352,6 @@ def create_memory(cls, sorting, recording, sparsity, return_scaled, rec_attribut
     def create_binary_folder(cls, folder, sorting, recording, sparsity, return_scaled, rec_attributes):
         # used by create and save_as
 
-        assert recording is not None, "To create a SortingAnalyzer you need to specify the recording"
-
         folder = Path(folder)
         if folder.is_dir():
             raise ValueError(f"Folder already exists {folder}")
@@ -372,11 +370,17 @@ def create_binary_folder(cls, folder, sorting, recording, sparsity, return_scale
         # NumpyFolderSorting.write_sorting(sorting, folder / "sorting")
         sorting.save(folder=folder / "sorting")
 
-        # save recording and sorting provenance
-        if recording.check_serializability("json"):
-            recording.dump(folder / "recording.json", relative_to=folder)
-        elif recording.check_serializability("pickle"):
-            recording.dump(folder / "recording.pickle", relative_to=folder)
+        if recording is not None:
+            # save recording and sorting provenance
+            if recording.check_serializability("json"):
+                recording.dump(folder / "recording.json", relative_to=folder)
+            elif recording.check_serializability("pickle"):
+                recording.dump(folder / "recording.pickle", relative_to=folder)
+        else:
+            assert rec_attributes is not None, "recording or rec_attributes must be provided"
+            # write an empty recording.json
+            with open(folder / "recording.json", mode="w") as f:
+                json.dump({}, f, indent=4)
 
         if sorting.check_serializability("json"):
             sorting.dump(folder / "sorting_provenance.json", relative_to=folder)
@@ -519,20 +523,24 @@ def create_zarr(cls, folder, sorting, recording, sparsity, return_scaled, rec_at
         zarr_root.attrs["settings"] = check_json(settings)
 
         # the recording
-        rec_dict = recording.to_dict(relative_to=folder, recursive=True)
-
-        if recording.check_serializability("json"):
-            # zarr_root.create_dataset("recording", data=rec_dict, object_codec=numcodecs.JSON())
-            zarr_rec = np.array([check_json(rec_dict)], dtype=object)
-            zarr_root.create_dataset("recording", data=zarr_rec, object_codec=numcodecs.JSON())
-        elif recording.check_serializability("pickle"):
-            # zarr_root.create_dataset("recording", data=rec_dict, object_codec=numcodecs.Pickle())
-            zarr_rec = np.array([rec_dict], dtype=object)
-            zarr_root.create_dataset("recording", data=zarr_rec, object_codec=numcodecs.Pickle())
+        if recording is not None:
+            rec_dict = recording.to_dict(relative_to=folder, recursive=True)
+            if recording.check_serializability("json"):
+                # zarr_root.create_dataset("recording", data=rec_dict, object_codec=numcodecs.JSON())
+                zarr_rec = np.array([check_json(rec_dict)], dtype=object)
+                zarr_root.create_dataset("recording", data=zarr_rec, object_codec=numcodecs.JSON())
+            elif recording.check_serializability("pickle"):
+                # zarr_root.create_dataset("recording", data=rec_dict, object_codec=numcodecs.Pickle())
+                zarr_rec = np.array([rec_dict], dtype=object)
+                zarr_root.create_dataset("recording", data=zarr_rec, object_codec=numcodecs.Pickle())
+            else:
+                warnings.warn(
+                    "SortingAnalyzer with zarr : the Recording is not json serializable, the recording link will be lost for future load"
+                )
         else:
-            warnings.warn(
-                "SortingAnalyzer with zarr : the Recording is not json serializable, the recording link will be lost for future load"
-            )
+            assert rec_attributes is not None, "recording or rec_attributes must be provided"
+            zarr_rec = np.array([{}], dtype=object)
+            zarr_root.create_dataset("recording", data=zarr_rec, object_codec=numcodecs.JSON())
 
         # sorting provenance
         sort_dict = sorting.to_dict(relative_to=folder, recursive=True)

From 7359f1644abad5dae45d6c6b329692379c3e52a9 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Wed, 25 Sep 2024 19:27:42 +0200
Subject: [PATCH 038/344] Fix missing run_info

---
 src/spikeinterface/core/sortinganalyzer.py | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/spikeinterface/core/sortinganalyzer.py b/src/spikeinterface/core/sortinganalyzer.py
index e4bed0dbb6..7a84a2b5fa 100644
--- a/src/spikeinterface/core/sortinganalyzer.py
+++ b/src/spikeinterface/core/sortinganalyzer.py
@@ -2023,7 +2023,10 @@ def copy(self, new_sorting_analyzer, unit_ids=None):
             new_extension.data = self.data
         else:
             new_extension.data = self._select_extension_data(unit_ids)
-        new_extension.run_info = self.run_info.copy()
+        if self.run_info is not None:
+            new_extension.run_info = self.run_info.copy()
+        else:
+            new_extension.run_info = None
         new_extension.save()
         return new_extension
 

From b037b2952d2423c8a351fd51c25d2ff5b9cd04b9 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Wed, 25 Sep 2024 19:29:43 +0200
Subject: [PATCH 039/344] Fix missing run_info 2

---
 src/spikeinterface/core/sortinganalyzer.py | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

diff --git a/src/spikeinterface/core/sortinganalyzer.py b/src/spikeinterface/core/sortinganalyzer.py
index 7a84a2b5fa..cd9096bf24 100644
--- a/src/spikeinterface/core/sortinganalyzer.py
+++ b/src/spikeinterface/core/sortinganalyzer.py
@@ -2262,15 +2262,16 @@ def _save_importing_provenance(self):
             extension_group.attrs["info"] = info
 
     def _save_run_info(self):
-        run_info = self.run_info.copy()
-
-        if self.format == "binary_folder":
-            extension_folder = self._get_binary_extension_folder()
-            run_info_file = extension_folder / "run_info.json"
-            run_info_file.write_text(json.dumps(run_info, indent=4), encoding="utf8")
-        elif self.format == "zarr":
-            extension_group = self._get_zarr_extension_group(mode="r+")
-            extension_group.attrs["run_info"] = run_info
+        if self.run_info is not None:
+            run_info = self.run_info.copy()
+
+            if self.format == "binary_folder":
+                extension_folder = self._get_binary_extension_folder()
+                run_info_file = extension_folder / "run_info.json"
+                run_info_file.write_text(json.dumps(run_info, indent=4), encoding="utf8")
+            elif self.format == "zarr":
+                extension_group = self._get_zarr_extension_group(mode="r+")
+                extension_group.attrs["run_info"] = run_info
 
     def get_pipeline_nodes(self):
         assert (

From b5b553fd1bc63cb02b4b383b87450bdf7e0015ec Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Wed, 25 Sep 2024 19:30:44 +0200
Subject: [PATCH 040/344] Fix missing run_info 3

---
 src/spikeinterface/core/sortinganalyzer.py | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/spikeinterface/core/sortinganalyzer.py b/src/spikeinterface/core/sortinganalyzer.py
index cd9096bf24..754d05948f 100644
--- a/src/spikeinterface/core/sortinganalyzer.py
+++ b/src/spikeinterface/core/sortinganalyzer.py
@@ -2044,7 +2044,10 @@ def merge(
         new_extension.data = self._merge_extension_data(
             merge_unit_groups, new_unit_ids, new_sorting_analyzer, keep_mask, verbose=verbose, **job_kwargs
         )
-        new_extension.run_info = self.run_info.copy()
+        if self.run_info is not None:
+            new_extension.run_info = self.run_info.copy()
+        else:
+            new_extension.run_info = None
         new_extension.save()
         return new_extension
 

From f7efefea5e7f159bb19b88fc6e585d988514e508 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Thu, 26 Sep 2024 09:49:28 +0200
Subject: [PATCH 041/344] Relax causal filter tests

---
 src/spikeinterface/preprocessing/tests/test_filter.py | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/spikeinterface/preprocessing/tests/test_filter.py b/src/spikeinterface/preprocessing/tests/test_filter.py
index 9df60af3db..2a056b50d5 100644
--- a/src/spikeinterface/preprocessing/tests/test_filter.py
+++ b/src/spikeinterface/preprocessing/tests/test_filter.py
@@ -46,7 +46,7 @@ def test_causal_filter_main_kwargs(self, recording_and_data):
 
         filt_data = causal_filter(recording, direction="forward", **options, margin_ms=0).get_traces()
 
-        assert np.allclose(test_data, filt_data, rtol=0, atol=1e-6)
+        assert np.allclose(test_data, filt_data, rtol=0, atol=1e-4)
 
         # Then, change all kwargs to ensure they are propagated
         # and check the backwards version.
@@ -66,7 +66,7 @@ def test_causal_filter_main_kwargs(self, recording_and_data):
 
         filt_data = causal_filter(recording, direction="backward", **options, margin_ms=0).get_traces()
 
-        assert np.allclose(test_data, filt_data, rtol=0, atol=1e-6)
+        assert np.allclose(test_data, filt_data, rtol=0, atol=1e-4)
 
     def test_causal_filter_custom_coeff(self, recording_and_data):
         """
@@ -89,7 +89,7 @@ def test_causal_filter_custom_coeff(self, recording_and_data):
 
         filt_data = causal_filter(recording, direction="forward", **options, margin_ms=0).get_traces()
 
-        assert np.allclose(test_data, filt_data, rtol=0, atol=1e-6, equal_nan=True)
+        assert np.allclose(test_data, filt_data, rtol=0, atol=1e-4, equal_nan=True)
 
         # Next, in "sos" mode
         options["filter_mode"] = "sos"
@@ -100,7 +100,7 @@ def test_causal_filter_custom_coeff(self, recording_and_data):
 
         filt_data = causal_filter(recording, direction="forward", **options, margin_ms=0).get_traces()
 
-        assert np.allclose(test_data, filt_data, rtol=0, atol=1e-6, equal_nan=True)
+        assert np.allclose(test_data, filt_data, rtol=0, atol=1e-4, equal_nan=True)
 
     def test_causal_kwarg_error_raised(self, recording_and_data):
         """

From a5372b0097573d1bfb9723e9dcea08fa18e82774 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Thu, 26 Sep 2024 15:04:40 +0200
Subject: [PATCH 042/344] relax test causal to fix failure

---
 src/spikeinterface/preprocessing/tests/test_filter.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/preprocessing/tests/test_filter.py b/src/spikeinterface/preprocessing/tests/test_filter.py
index 2a056b50d5..56e238fc54 100644
--- a/src/spikeinterface/preprocessing/tests/test_filter.py
+++ b/src/spikeinterface/preprocessing/tests/test_filter.py
@@ -100,7 +100,7 @@ def test_causal_filter_custom_coeff(self, recording_and_data):
 
         filt_data = causal_filter(recording, direction="forward", **options, margin_ms=0).get_traces()
 
-        assert np.allclose(test_data, filt_data, rtol=0, atol=1e-4, equal_nan=True)
+        assert np.allclose(test_data, filt_data, rtol=0, atol=1e-3, equal_nan=True)
 
     def test_causal_kwarg_error_raised(self, recording_and_data):
         """

From 211d68ead4d2ce76b7fd25c01df4b4d8c0ecef46 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Thu, 26 Sep 2024 20:19:40 +0200
Subject: [PATCH 043/344] Chris' suggestion

---
 src/spikeinterface/core/sortinganalyzer.py | 11 +++--------
 1 file changed, 3 insertions(+), 8 deletions(-)

diff --git a/src/spikeinterface/core/sortinganalyzer.py b/src/spikeinterface/core/sortinganalyzer.py
index 754d05948f..26313c9892 100644
--- a/src/spikeinterface/core/sortinganalyzer.py
+++ b/src/spikeinterface/core/sortinganalyzer.py
@@ -11,6 +11,7 @@
 import shutil
 import warnings
 import importlib
+from copy import copy
 from packaging.version import parse
 from time import perf_counter
 
@@ -2023,10 +2024,7 @@ def copy(self, new_sorting_analyzer, unit_ids=None):
             new_extension.data = self.data
         else:
             new_extension.data = self._select_extension_data(unit_ids)
-        if self.run_info is not None:
-            new_extension.run_info = self.run_info.copy()
-        else:
-            new_extension.run_info = None
+        new_extension.run_info = copy(self.run_info)
         new_extension.save()
         return new_extension
 
@@ -2044,10 +2042,7 @@ def merge(
         new_extension.data = self._merge_extension_data(
             merge_unit_groups, new_unit_ids, new_sorting_analyzer, keep_mask, verbose=verbose, **job_kwargs
         )
-        if self.run_info is not None:
-            new_extension.run_info = self.run_info.copy()
-        else:
-            new_extension.run_info = None
+        new_extension.run_info = copy(self.run_info)
         new_extension.save()
         return new_extension
 

From 7221004cfbfc0361879ec5fa59c5f929bf68709c Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Fri, 27 Sep 2024 09:36:49 +0200
Subject: [PATCH 044/344] Expose zarr_kwargs at the analyzer level to zarr
 dataset options

---
 src/spikeinterface/core/sortinganalyzer.py    | 55 +++++++++++------
 .../core/tests/test_sortinganalyzer.py        | 61 ++++++++++++++++---
 src/spikeinterface/core/zarrextractors.py     |  3 +-
 3 files changed, 90 insertions(+), 29 deletions(-)

diff --git a/src/spikeinterface/core/sortinganalyzer.py b/src/spikeinterface/core/sortinganalyzer.py
index 4961db8524..5ffdc85e50 100644
--- a/src/spikeinterface/core/sortinganalyzer.py
+++ b/src/spikeinterface/core/sortinganalyzer.py
@@ -219,6 +219,9 @@ def __init__(
         # this is used to store temporary recording
         self._temporary_recording = None
 
+        # for zarr format, we store the kwargs to create zarr datasets (e.g., compression)
+        self._zarr_kwargs = {}
+
         # extensions are not loaded at init
         self.extensions = dict()
 
@@ -500,7 +503,7 @@ def _get_zarr_root(self, mode="r+"):
         return zarr_root
 
     @classmethod
-    def create_zarr(cls, folder, sorting, recording, sparsity, return_scaled, rec_attributes):
+    def create_zarr(cls, folder, sorting, recording, sparsity, return_scaled, rec_attributes, **zarr_kwargs):
         # used by create and save_as
         import zarr
         import numcodecs
@@ -531,7 +534,8 @@ def create_zarr(cls, folder, sorting, recording, sparsity, return_scaled, rec_at
             zarr_root.create_dataset("recording", data=zarr_rec, object_codec=numcodecs.Pickle())
         else:
             warnings.warn(
-                "SortingAnalyzer with zarr : the Recording is not json serializable, the recording link will be lost for future load"
+                "SortingAnalyzer with zarr : the Recording is not json serializable, "
+                "the recording link will be lost for future load"
             )
 
         # sorting provenance
@@ -569,7 +573,6 @@ def create_zarr(cls, folder, sorting, recording, sparsity, return_scaled, rec_at
 
         # Alessio : we need to find a way to propagate compressor for all steps.
         # kwargs = dict(compressor=...)
-        zarr_kwargs = dict()
         add_sorting_to_zarr_group(sorting, zarr_root.create_group("sorting"), **zarr_kwargs)
 
         recording_info = zarr_root.create_group("extensions")
@@ -645,6 +648,18 @@ def load_from_zarr(cls, folder, recording=None, storage_options=None):
 
         return sorting_analyzer
 
+    def set_zarr_kwargs(self, **zarr_kwargs):
+        """
+        Set the zarr kwargs for the zarr datasets. This can be used to specify custom compressors or filters.
+        Note that currently the zarr kwargs will be used for all zarr datasets.
+
+        Parameters
+        ----------
+        zarr_kwargs : keyword arguments
+            The zarr kwargs to set.
+        """
+        self._zarr_kwargs = zarr_kwargs
+
     def set_temporary_recording(self, recording: BaseRecording, check_dtype: bool = True):
         """
         Sets a temporary recording object. This function can be useful to temporarily set
@@ -683,7 +698,7 @@ def _save_or_select_or_merge(
         sparsity_overlap=0.75,
         verbose=False,
         new_unit_ids=None,
-        **job_kwargs,
+        **kwargs,
     ) -> "SortingAnalyzer":
         """
         Internal method used by both `save_as()`, `copy()`, `select_units()`, and `merge_units()`.
@@ -712,8 +727,8 @@ def _save_or_select_or_merge(
             The new unit ids for merged units. Required if `merge_unit_groups` is not None.
         verbose : bool, default: False
             If True, output is verbose.
-        job_kwargs : dict
-            Keyword arguments for parallelization.
+        kwargs : keyword arguments
+            Keyword arguments including job_kwargs and zarr_kwargs.
 
         Returns
         -------
@@ -727,6 +742,8 @@ def _save_or_select_or_merge(
         else:
             recording = None
 
+        zarr_kwargs, job_kwargs = split_job_kwargs(kwargs)
+
         if self.sparsity is not None and unit_ids is None and merge_unit_groups is None:
             sparsity = self.sparsity
         elif self.sparsity is not None and unit_ids is not None and merge_unit_groups is None:
@@ -807,10 +824,11 @@ def _save_or_select_or_merge(
             assert folder is not None, "For format='zarr' folder must be provided"
             folder = clean_zarr_folder_name(folder)
             SortingAnalyzer.create_zarr(
-                folder, sorting_provenance, recording, sparsity, self.return_scaled, self.rec_attributes
+                folder, sorting_provenance, recording, sparsity, self.return_scaled, self.rec_attributes, **zarr_kwargs
             )
             new_sorting_analyzer = SortingAnalyzer.load_from_zarr(folder, recording=recording)
             new_sorting_analyzer.folder = folder
+            new_sorting_analyzer._zarr_kwargs = zarr_kwargs
         else:
             raise ValueError(f"SortingAnalyzer.save: unsupported format: {format}")
 
@@ -848,7 +866,7 @@ def _save_or_select_or_merge(
 
         return new_sorting_analyzer
 
-    def save_as(self, format="memory", folder=None) -> "SortingAnalyzer":
+    def save_as(self, format="memory", folder=None, **zarr_kwargs) -> "SortingAnalyzer":
         """
         Save SortingAnalyzer object into another format.
         Uselful for memory to zarr or memory to binary.
@@ -863,10 +881,11 @@ def save_as(self, format="memory", folder=None) -> "SortingAnalyzer":
             The output folder if `format` is "zarr" or "binary_folder"
         format : "memory" | "binary_folder" | "zarr", default: "memory"
             The new backend format to use
+        zarr_kwargs : keyword arguments for zarr format
         """
         if format == "zarr":
             folder = clean_zarr_folder_name(folder)
-        return self._save_or_select_or_merge(format=format, folder=folder)
+        return self._save_or_select_or_merge(format=format, folder=folder, **zarr_kwargs)
 
     def select_units(self, unit_ids, format="memory", folder=None) -> "SortingAnalyzer":
         """
@@ -2051,24 +2070,24 @@ def run(self, save=True, **kwargs):
 
         if save and not self.sorting_analyzer.is_read_only():
             self._save_run_info()
-            self._save_data(**kwargs)
+            self._save_data()
             if self.format == "zarr":
                 import zarr
 
                 zarr.consolidate_metadata(self.sorting_analyzer._get_zarr_root().store)
 
-    def save(self, **kwargs):
+    def save(self):
         self._save_params()
         self._save_importing_provenance()
         self._save_run_info()
-        self._save_data(**kwargs)
+        self._save_data()
 
         if self.format == "zarr":
             import zarr
 
             zarr.consolidate_metadata(self.sorting_analyzer._get_zarr_root().store)
 
-    def _save_data(self, **kwargs):
+    def _save_data(self):
         if self.format == "memory":
             return
 
@@ -2107,14 +2126,14 @@ def _save_data(self, **kwargs):
                     except:
                         raise Exception(f"Could not save {ext_data_name} as extension data")
         elif self.format == "zarr":
-            import zarr
             import numcodecs
 
+            zarr_kwargs = self.sorting_analyzer._zarr_kwargs
             extension_group = self._get_zarr_extension_group(mode="r+")
 
-            compressor = kwargs.get("compressor", None)
-            if compressor is None:
-                compressor = get_default_zarr_compressor()
+            # if compression is not externally given, we use the default
+            if "compressor" not in zarr_kwargs:
+                zarr_kwargs["compressor"] = get_default_zarr_compressor()
 
             for ext_data_name, ext_data in self.data.items():
                 if ext_data_name in extension_group:
@@ -2124,7 +2143,7 @@ def _save_data(self, **kwargs):
                         name=ext_data_name, data=np.array([ext_data], dtype=object), object_codec=numcodecs.JSON()
                     )
                 elif isinstance(ext_data, np.ndarray):
-                    extension_group.create_dataset(name=ext_data_name, data=ext_data, compressor=compressor)
+                    extension_group.create_dataset(name=ext_data_name, data=ext_data, **zarr_kwargs)
                 elif HAS_PANDAS and isinstance(ext_data, pd.DataFrame):
                     df_group = extension_group.create_group(ext_data_name)
                     # first we save the index
diff --git a/src/spikeinterface/core/tests/test_sortinganalyzer.py b/src/spikeinterface/core/tests/test_sortinganalyzer.py
index 5c7e267cc6..53e28fe083 100644
--- a/src/spikeinterface/core/tests/test_sortinganalyzer.py
+++ b/src/spikeinterface/core/tests/test_sortinganalyzer.py
@@ -10,6 +10,7 @@
     load_sorting_analyzer,
     get_available_analyzer_extensions,
     get_default_analyzer_extension_params,
+    get_default_zarr_compressor,
 )
 from spikeinterface.core.sortinganalyzer import (
     register_result_extension,
@@ -99,16 +100,25 @@ def test_SortingAnalyzer_zarr(tmp_path, dataset):
     recording, sorting = dataset
 
     folder = tmp_path / "test_SortingAnalyzer_zarr.zarr"
-    if folder.exists():
-        shutil.rmtree(folder)
 
+    default_compressor = get_default_zarr_compressor()
     sorting_analyzer = create_sorting_analyzer(
-        sorting, recording, format="zarr", folder=folder, sparse=False, sparsity=None
+        sorting, recording, format="zarr", folder=folder, sparse=False, sparsity=None, overwrite=True
     )
     sorting_analyzer.compute(["random_spikes", "templates"])
     sorting_analyzer = load_sorting_analyzer(folder, format="auto")
     _check_sorting_analyzers(sorting_analyzer, sorting, cache_folder=tmp_path)
 
+    # check that compression is applied
+    assert (
+        sorting_analyzer._get_zarr_root()["extensions"]["random_spikes"]["random_spikes_indices"].compressor.codec_id
+        == default_compressor.codec_id
+    )
+    assert (
+        sorting_analyzer._get_zarr_root()["extensions"]["templates"]["average"].compressor.codec_id
+        == default_compressor.codec_id
+    )
+
     # test select_units see https://github.com/SpikeInterface/spikeinterface/issues/3041
     # this bug requires that we have an info.json file so we calculate templates above
     select_units_sorting_analyer = sorting_analyzer.select_units(unit_ids=[1])
@@ -117,11 +127,44 @@ def test_SortingAnalyzer_zarr(tmp_path, dataset):
     assert len(remove_units_sorting_analyer.unit_ids) == len(sorting_analyzer.unit_ids) - 1
     assert 1 not in remove_units_sorting_analyer.unit_ids
 
-    folder = tmp_path / "test_SortingAnalyzer_zarr.zarr"
-    if folder.exists():
-        shutil.rmtree(folder)
-    sorting_analyzer = create_sorting_analyzer(
-        sorting, recording, format="zarr", folder=folder, sparse=False, sparsity=None, return_scaled=False
+    # test no compression
+    sorting_analyzer_no_compression = create_sorting_analyzer(
+        sorting,
+        recording,
+        format="zarr",
+        folder=folder,
+        sparse=False,
+        sparsity=None,
+        return_scaled=False,
+        overwrite=True,
+    )
+    sorting_analyzer_no_compression.set_zarr_kwargs(compressor=None)
+    sorting_analyzer_no_compression.compute(["random_spikes", "templates"])
+    assert (
+        sorting_analyzer_no_compression._get_zarr_root()["extensions"]["random_spikes"][
+            "random_spikes_indices"
+        ].compressor
+        is None
+    )
+    assert sorting_analyzer_no_compression._get_zarr_root()["extensions"]["templates"]["average"].compressor is None
+
+    # test a different compressor
+    from numcodecs import LZMA
+
+    lzma_compressor = LZMA()
+    folder = tmp_path / "test_SortingAnalyzer_zarr_lzma.zarr"
+    sorting_analyzer_lzma = sorting_analyzer_no_compression.save_as(
+        format="zarr", folder=folder, compressor=lzma_compressor
+    )
+    assert (
+        sorting_analyzer_lzma._get_zarr_root()["extensions"]["random_spikes"][
+            "random_spikes_indices"
+        ].compressor.codec_id
+        == LZMA.codec_id
+    )
+    assert (
+        sorting_analyzer_lzma._get_zarr_root()["extensions"]["templates"]["average"].compressor.codec_id
+        == LZMA.codec_id
     )
 
 
@@ -326,7 +369,7 @@ def _check_sorting_analyzers(sorting_analyzer, original_sorting, cache_folder):
         else:
             folder = None
         sorting_analyzer5 = sorting_analyzer.merge_units(
-            merge_unit_groups=[[0, 1]], new_unit_ids=[50], format=format, folder=folder, mode="hard"
+            merge_unit_groups=[[0, 1]], new_unit_ids=[50], format=format, folder=folder, merging_mode="hard"
         )
 
     # test compute with extension-specific params
diff --git a/src/spikeinterface/core/zarrextractors.py b/src/spikeinterface/core/zarrextractors.py
index 17f1ac08b3..355553428e 100644
--- a/src/spikeinterface/core/zarrextractors.py
+++ b/src/spikeinterface/core/zarrextractors.py
@@ -329,8 +329,7 @@ def add_sorting_to_zarr_group(sorting: BaseSorting, zarr_group: zarr.hierarchy.G
     zarr_group.attrs["num_segments"] = int(num_segments)
     zarr_group.create_dataset(name="unit_ids", data=sorting.unit_ids, compressor=None)
 
-    if "compressor" not in kwargs:
-        compressor = get_default_zarr_compressor()
+    compressor = kwargs.get("compressor", get_default_zarr_compressor())
 
     # save sub fields
     spikes_group = zarr_group.create_group(name="spikes")

From 23413b388c97730cb6208341d042864a1995dcf9 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Fri, 27 Sep 2024 09:55:32 +0200
Subject: [PATCH 045/344] Update src/spikeinterface/core/sortinganalyzer.py

---
 src/spikeinterface/core/sortinganalyzer.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/core/sortinganalyzer.py b/src/spikeinterface/core/sortinganalyzer.py
index 5ffdc85e50..f7a8485502 100644
--- a/src/spikeinterface/core/sortinganalyzer.py
+++ b/src/spikeinterface/core/sortinganalyzer.py
@@ -828,7 +828,7 @@ def _save_or_select_or_merge(
             )
             new_sorting_analyzer = SortingAnalyzer.load_from_zarr(folder, recording=recording)
             new_sorting_analyzer.folder = folder
-            new_sorting_analyzer._zarr_kwargs = zarr_kwargs
+            new_sorting_analyzer.set_zarr_kwargs(zarr_kwargs)
         else:
             raise ValueError(f"SortingAnalyzer.save: unsupported format: {format}")
 

From fa97fd45689b29d5050652718938ae856132ff91 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Fri, 27 Sep 2024 09:59:53 +0200
Subject: [PATCH 046/344] Fix tests

---
 src/spikeinterface/core/sortinganalyzer.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/core/sortinganalyzer.py b/src/spikeinterface/core/sortinganalyzer.py
index f7a8485502..16945008ae 100644
--- a/src/spikeinterface/core/sortinganalyzer.py
+++ b/src/spikeinterface/core/sortinganalyzer.py
@@ -828,7 +828,7 @@ def _save_or_select_or_merge(
             )
             new_sorting_analyzer = SortingAnalyzer.load_from_zarr(folder, recording=recording)
             new_sorting_analyzer.folder = folder
-            new_sorting_analyzer.set_zarr_kwargs(zarr_kwargs)
+            new_sorting_analyzer.set_zarr_kwargs(**zarr_kwargs)
         else:
             raise ValueError(f"SortingAnalyzer.save: unsupported format: {format}")
 

From a0b1cd10ac9b0d97327f17f94b07f2f2b3e3b668 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Fri, 27 Sep 2024 15:00:15 +0200
Subject: [PATCH 047/344] STart refactor template matcghing into noepieline

---
 src/spikeinterface/core/node_pipeline.py      |   2 +-
 .../sortingcomponents/matching/base.py        |  31 ++
 .../sortingcomponents/matching/main.py        | 255 ++++++++++------
 .../sortingcomponents/matching/method_list.py |  12 +-
 .../sortingcomponents/matching/naive.py       | 243 +++++++++------
 .../sortingcomponents/matching/tdc.py         | 287 ++++++++++++++----
 .../tests/test_template_matching.py           |  32 +-
 7 files changed, 599 insertions(+), 263 deletions(-)
 create mode 100644 src/spikeinterface/sortingcomponents/matching/base.py

diff --git a/src/spikeinterface/core/node_pipeline.py b/src/spikeinterface/core/node_pipeline.py
index ceff8577d3..2b361a29bd 100644
--- a/src/spikeinterface/core/node_pipeline.py
+++ b/src/spikeinterface/core/node_pipeline.py
@@ -96,7 +96,7 @@ def compute(self, traces, start_frame, end_frame, segment_index, max_margin, *ar
 
 
 class PeakSource(PipelineNode):
-    # base class for peak detector
+    # base class for peak detector or template matching
     def get_trace_margin(self):
         raise NotImplementedError
 
diff --git a/src/spikeinterface/sortingcomponents/matching/base.py b/src/spikeinterface/sortingcomponents/matching/base.py
new file mode 100644
index 0000000000..3ffc559c65
--- /dev/null
+++ b/src/spikeinterface/sortingcomponents/matching/base.py
@@ -0,0 +1,31 @@
+import numpy as np
+from spikeinterface.core import Templates
+from spikeinterface.core.node_pipeline import PeakSource
+
+_base_matching_dtype = [
+    ("sample_index", "int64"),
+    ("channel_index", "int64"),
+    ("cluster_index", "int64"),
+    ("amplitude", "float64"),
+    ("segment_index", "int64"),
+]
+
+class BaseTemplateMatching(PeakSource):
+    def __init__(self, recording, templates, return_output=True, parents=None):
+        # TODO make a sharedmem of template here
+        # TODO maybe check that channel_id are the same with recording
+
+        assert isinstance(d["templates"], Templates), (
+            f"The templates supplied is of type {type(d['templates'])} " f"and must be a Templates"
+        )
+        self.templates = templates
+        PeakSource.__init__(self, recording, return_output=return_output, parents=parents)
+
+    def get_dtype(self):
+        return np.dtype(_base_matching_dtype)
+
+    def get_trace_margin(self):
+        raise NotImplementedError  
+
+    def compute(self, traces, start_frame, end_frame, segment_index, max_margin, *args):
+        raise NotImplementedError    
\ No newline at end of file
diff --git a/src/spikeinterface/sortingcomponents/matching/main.py b/src/spikeinterface/sortingcomponents/matching/main.py
index 6e5267cb70..b1fdaaf15f 100644
--- a/src/spikeinterface/sortingcomponents/matching/main.py
+++ b/src/spikeinterface/sortingcomponents/matching/main.py
@@ -3,8 +3,12 @@
 from threadpoolctl import threadpool_limits
 import numpy as np
 
-from spikeinterface.core.job_tools import ChunkRecordingExecutor, fix_job_kwargs
-from spikeinterface.core import get_chunk_with_margin
+# from spikeinterface.core.job_tools import ChunkRecordingExecutor, fix_job_kwargs
+# from spikeinterface.core import get_chunk_with_margin
+
+from spikeinterface.core.job_tools import fix_job_kwargs
+from spikeinterface.core.node_pipeline import run_node_pipeline
+
 
 
 def find_spikes_from_templates(
@@ -42,117 +46,174 @@ def find_spikes_from_templates(
     job_kwargs = fix_job_kwargs(job_kwargs)
 
     method_class = matching_methods[method]
+    node0 = method_class(recording, **method_kwargs)
+    nodes = [node0]
 
-    # initialize
-    method_kwargs = method_class.initialize_and_check_kwargs(recording, method_kwargs)
-
-    # add
-    method_kwargs["margin"] = method_class.get_margin(recording, method_kwargs)
-
-    # serialiaze for worker
-    method_kwargs_seralized = method_class.serialize_method_kwargs(method_kwargs)
-
-    # and run
-    func = _find_spikes_chunk
-    init_func = _init_worker_find_spikes
-    init_args = (recording, method, method_kwargs_seralized)
-    processor = ChunkRecordingExecutor(
+    spikes = run_node_pipeline(
         recording,
-        func,
-        init_func,
-        init_args,
-        handle_returns=True,
+        nodes,
+        job_kwargs,
         job_name=f"find spikes ({method})",
-        verbose=verbose,
-        **job_kwargs,
+        gather_mode="memory",
+        squeeze_output=True,
     )
-    spikes = processor.run()
-
-    spikes = np.concatenate(spikes)
-
     if extra_outputs:
+        # TODO deprecated extra_outputs
+        method_kwargs = {}
         return spikes, method_kwargs
     else:
         return spikes
 
 
-def _init_worker_find_spikes(recording, method, method_kwargs):
-    """Initialize worker for finding spikes."""
 
-    from .method_list import matching_methods
+# def find_spikes_from_templates(
+#     recording, method="naive", method_kwargs={}, extra_outputs=False, verbose=False, **job_kwargs
+# ) -> np.ndarray | tuple[np.ndarray, dict]:
+#     """Find spike from a recording from given templates.
 
-    method_class = matching_methods[method]
-    method_kwargs = method_class.unserialize_in_worker(method_kwargs)
+#     Parameters
+#     ----------
+#     recording : RecordingExtractor
+#         The recording extractor object
+#     method : "naive" | "tridesclous" | "circus" | "circus-omp" | "wobble", default: "naive"
+#         Which method to use for template matching
+#     method_kwargs : dict, optional
+#         Keyword arguments for the chosen method
+#     extra_outputs : bool
+#         If True then method_kwargs is also returned
+#     **job_kwargs : dict
+#         Parameters for ChunkRecordingExecutor
+#     verbose : Bool, default: False
+#         If True, output is verbose
 
-    # create a local dict per worker
-    worker_ctx = {}
-    worker_ctx["recording"] = recording
-    worker_ctx["method"] = method
-    worker_ctx["method_kwargs"] = method_kwargs
-    worker_ctx["function"] = method_class.main_function
+#     Returns
+#     -------
+#     spikes : ndarray
+#         Spikes found from templates.
+#     method_kwargs:
+#         Optionaly returns for debug purpose.
 
-    return worker_ctx
+#     """
+#     from .method_list import matching_methods
 
+#     assert method in matching_methods, f"The 'method' {method} is not valid. Use a method from {matching_methods}"
 
-def _find_spikes_chunk(segment_index, start_frame, end_frame, worker_ctx):
-    """Find spikes from a chunk of data."""
+#     job_kwargs = fix_job_kwargs(job_kwargs)
 
-    # recover variables of the worker
-    recording = worker_ctx["recording"]
-    method = worker_ctx["method"]
-    method_kwargs = worker_ctx["method_kwargs"]
-    margin = method_kwargs["margin"]
+#     method_class = matching_methods[method]
 
-    # load trace in memory given some margin
-    recording_segment = recording._recording_segments[segment_index]
-    traces, left_margin, right_margin = get_chunk_with_margin(
-        recording_segment, start_frame, end_frame, None, margin, add_zeros=True
-    )
+#     # initialize
+#     method_kwargs = method_class.initialize_and_check_kwargs(recording, method_kwargs)
+
+#     # add
+#     method_kwargs["margin"] = method_class.get_margin(recording, method_kwargs)
+
+#     # serialiaze for worker
+#     method_kwargs_seralized = method_class.serialize_method_kwargs(method_kwargs)
+
+#     # and run
+#     func = _find_spikes_chunk
+#     init_func = _init_worker_find_spikes
+#     init_args = (recording, method, method_kwargs_seralized)
+#     processor = ChunkRecordingExecutor(
+#         recording,
+#         func,
+#         init_func,
+#         init_args,
+#         handle_returns=True,
+#         job_name=f"find spikes ({method})",
+#         verbose=verbose,
+#         **job_kwargs,
+#     )
+#     spikes = processor.run()
+
+#     spikes = np.concatenate(spikes)
+
+#     if extra_outputs:
+#         return spikes, method_kwargs
+#     else:
+#         return spikes
+    
+
+
+
+# def _init_worker_find_spikes(recording, method, method_kwargs):
+#     """Initialize worker for finding spikes."""
+
+#     from .method_list import matching_methods
+
+#     method_class = matching_methods[method]
+#     method_kwargs = method_class.unserialize_in_worker(method_kwargs)
+
+#     # create a local dict per worker
+#     worker_ctx = {}
+#     worker_ctx["recording"] = recording
+#     worker_ctx["method"] = method
+#     worker_ctx["method_kwargs"] = method_kwargs
+#     worker_ctx["function"] = method_class.main_function
+
+#     return worker_ctx
+
+
+# def _find_spikes_chunk(segment_index, start_frame, end_frame, worker_ctx):
+#     """Find spikes from a chunk of data."""
+
+#     # recover variables of the worker
+#     recording = worker_ctx["recording"]
+#     method = worker_ctx["method"]
+#     method_kwargs = worker_ctx["method_kwargs"]
+#     margin = method_kwargs["margin"]
+
+#     # load trace in memory given some margin
+#     recording_segment = recording._recording_segments[segment_index]
+#     traces, left_margin, right_margin = get_chunk_with_margin(
+#         recording_segment, start_frame, end_frame, None, margin, add_zeros=True
+#     )
+
+#     function = worker_ctx["function"]
+
+#     with threadpool_limits(limits=1):
+#         spikes = function(traces, method_kwargs)
+
+#     # remove spikes in margin
+#     if margin > 0:
+#         keep = (spikes["sample_index"] >= margin) & (spikes["sample_index"] < (traces.shape[0] - margin))
+#         spikes = spikes[keep]
+
+#     spikes["sample_index"] += start_frame - margin
+#     spikes["segment_index"] = segment_index
+#     return spikes
+
+
+# # generic class for template engine
+# class BaseTemplateMatchingEngine:
+#     default_params = {}
+
+#     @classmethod
+#     def initialize_and_check_kwargs(cls, recording, kwargs):
+#         """This function runs before loops"""
+#         # need to be implemented in subclass
+#         raise NotImplementedError
 
-    function = worker_ctx["function"]
-
-    with threadpool_limits(limits=1):
-        spikes = function(traces, method_kwargs)
-
-    # remove spikes in margin
-    if margin > 0:
-        keep = (spikes["sample_index"] >= margin) & (spikes["sample_index"] < (traces.shape[0] - margin))
-        spikes = spikes[keep]
-
-    spikes["sample_index"] += start_frame - margin
-    spikes["segment_index"] = segment_index
-    return spikes
-
-
-# generic class for template engine
-class BaseTemplateMatchingEngine:
-    default_params = {}
-
-    @classmethod
-    def initialize_and_check_kwargs(cls, recording, kwargs):
-        """This function runs before loops"""
-        # need to be implemented in subclass
-        raise NotImplementedError
-
-    @classmethod
-    def serialize_method_kwargs(cls, kwargs):
-        """This function serializes kwargs to distribute them to workers"""
-        # need to be implemented in subclass
-        raise NotImplementedError
-
-    @classmethod
-    def unserialize_in_worker(cls, recording, kwargs):
-        """This function unserializes kwargs in workers"""
-        # need to be implemented in subclass
-        raise NotImplementedError
-
-    @classmethod
-    def get_margin(cls, recording, kwargs):
-        # need to be implemented in subclass
-        raise NotImplementedError
-
-    @classmethod
-    def main_function(cls, traces, method_kwargs):
-        """This function returns the number of samples for the chunk margins"""
-        # need to be implemented in subclass
-        raise NotImplementedError
+#     @classmethod
+#     def serialize_method_kwargs(cls, kwargs):
+#         """This function serializes kwargs to distribute them to workers"""
+#         # need to be implemented in subclass
+#         raise NotImplementedError
+
+#     @classmethod
+#     def unserialize_in_worker(cls, recording, kwargs):
+#         """This function unserializes kwargs in workers"""
+#         # need to be implemented in subclass
+#         raise NotImplementedError
+
+#     @classmethod
+#     def get_margin(cls, recording, kwargs):
+#         # need to be implemented in subclass
+#         raise NotImplementedError
+
+#     @classmethod
+#     def main_function(cls, traces, method_kwargs):
+#         """This function returns the number of samples for the chunk margins"""
+#         # need to be implemented in subclass
+#         raise NotImplementedError
diff --git a/src/spikeinterface/sortingcomponents/matching/method_list.py b/src/spikeinterface/sortingcomponents/matching/method_list.py
index ca6c0db924..27a132c287 100644
--- a/src/spikeinterface/sortingcomponents/matching/method_list.py
+++ b/src/spikeinterface/sortingcomponents/matching/method_list.py
@@ -1,14 +1,14 @@
 from __future__ import annotations
 
 from .naive import NaiveMatching
-from .tdc import TridesclousPeeler
-from .circus import CircusPeeler, CircusOMPSVDPeeler
-from .wobble import WobbleMatch
+# from .tdc import TridesclousPeeler
+# from .circus import CircusPeeler, CircusOMPSVDPeeler
+# from .wobble import WobbleMatch
 
 matching_methods = {
     "naive": NaiveMatching,
     "tdc-peeler": TridesclousPeeler,
-    "circus": CircusPeeler,
-    "circus-omp-svd": CircusOMPSVDPeeler,
-    "wobble": WobbleMatch,
+    # "circus": CircusPeeler,
+    # "circus-omp-svd": CircusOMPSVDPeeler,
+    # "wobble": WobbleMatch,
 }
diff --git a/src/spikeinterface/sortingcomponents/matching/naive.py b/src/spikeinterface/sortingcomponents/matching/naive.py
index 0dc71d789b..6cd6cecab7 100644
--- a/src/spikeinterface/sortingcomponents/matching/naive.py
+++ b/src/spikeinterface/sortingcomponents/matching/naive.py
@@ -4,118 +4,181 @@
 
 
 import numpy as np
-from spikeinterface.core import get_noise_levels, get_channel_distances, get_random_data_chunks
+from spikeinterface.core import get_noise_levels, get_channel_distances
 from spikeinterface.sortingcomponents.peak_detection import DetectPeakLocallyExclusive
-from spikeinterface.core.template import Templates
-
-spike_dtype = [
-    ("sample_index", "int64"),
-    ("channel_index", "int64"),
-    ("cluster_index", "int64"),
-    ("amplitude", "float64"),
-    ("segment_index", "int64"),
-]
-
-
-from .main import BaseTemplateMatchingEngine
-
-
-class NaiveMatching(BaseTemplateMatchingEngine):
-    """
-    This is a naive template matching that does not resolve collision
-    and does not take in account sparsity.
-    It just minimizes the distance to templates for detected peaks.
-
-    It is implemented for benchmarking against this low quality template matching.
-    And also as an example how to deal with methods_kwargs, margin, intit, func, ...
-    """
-
-    default_params = {
-        "templates": None,
-        "peak_sign": "neg",
-        "exclude_sweep_ms": 0.1,
-        "detect_threshold": 5,
-        "noise_levels": None,
-        "radius_um": 100,
-        "random_chunk_kwargs": {},
-    }
-
-    @classmethod
-    def initialize_and_check_kwargs(cls, recording, kwargs):
-        d = cls.default_params.copy()
-        d.update(kwargs)
-
-        assert isinstance(d["templates"], Templates), (
-            f"The templates supplied is of type {type(d['templates'])} " f"and must be a Templates"
-        )
-
-        templates = d["templates"]
-
-        if d["noise_levels"] is None:
-            d["noise_levels"] = get_noise_levels(recording, **d["random_chunk_kwargs"], return_scaled=False)
-
-        d["abs_threholds"] = d["noise_levels"] * d["detect_threshold"]
-
+# from spikeinterface.core.template import Templates
+
+# spike_dtype = [
+#     ("sample_index", "int64"),
+#     ("channel_index", "int64"),
+#     ("cluster_index", "int64"),
+#     ("amplitude", "float64"),
+#     ("segment_index", "int64"),
+# ]
+
+
+from .base import BaseTemplateMatching, _base_matching_dtype
+
+class NaiveMatching(BaseTemplateMatching):
+    def __init__(self, recording, return_output=True, parents=None,
+        templates=None,
+        peak_sign="neg",
+        exclude_sweep_ms=0.1,
+        detect_threshold=5,
+        noise_levels=None,
+        radius_um=100.,
+        random_chunk_kwargs={},
+        ):
+
+        BaseTemplateMatching.__init__(self, recording, templates, return_output=True, parents=None)
+
+        # TODO put this in base ????
+        self.templates_array = self.templates.get_dense_templates()
+
+        if noise_levels is None:
+            noise_levels = get_noise_levels(recording, **random_chunk_kwargs, return_scaled=False)
+        self.abs_threholds = noise_levels * detect_threshold
+        self.peak_sign = peak_sign
         channel_distance = get_channel_distances(recording)
-        d["neighbours_mask"] = channel_distance < d["radius_um"]
-
-        d["nbefore"] = templates.nbefore
-        d["nafter"] = templates.nafter
-
-        d["exclude_sweep_size"] = int(d["exclude_sweep_ms"] * recording.get_sampling_frequency() / 1000.0)
-
-        return d
-
-    @classmethod
-    def get_margin(cls, recording, kwargs):
-        margin = max(kwargs["nbefore"], kwargs["nafter"])
-        return margin
-
-    @classmethod
-    def serialize_method_kwargs(cls, kwargs):
-        kwargs = dict(kwargs)
-        return kwargs
+        self.neighbours_mask = channel_distance < radius_um
+        self.exclude_sweep_size = int(exclude_sweep_ms * recording.get_sampling_frequency() / 1000.0)
+        self.nbefore = self.templates.nbefore
+        self.nafter = self.templates.nafter
+        self.margin = max(self.nbefore, self.nafter)
 
-    @classmethod
-    def unserialize_in_worker(cls, kwargs):
-        return kwargs
 
-    @classmethod
-    def main_function(cls, traces, method_kwargs):
-        peak_sign = method_kwargs["peak_sign"]
-        abs_threholds = method_kwargs["abs_threholds"]
-        exclude_sweep_size = method_kwargs["exclude_sweep_size"]
-        neighbours_mask = method_kwargs["neighbours_mask"]
-        templates_array = method_kwargs["templates"].get_dense_templates()
+    def get_trace_margin(self):
+        return self.margin
 
-        nbefore = method_kwargs["nbefore"]
-        nafter = method_kwargs["nafter"]
 
-        margin = method_kwargs["margin"]
+    def compute(self, traces, start_frame, end_frame, segment_index, max_margin, *args):
 
-        if margin > 0:
-            peak_traces = traces[margin:-margin, :]
+        if self.margin > 0:
+            peak_traces = traces[self.margin:-self.margin, :]
         else:
             peak_traces = traces
         peak_sample_ind, peak_chan_ind = DetectPeakLocallyExclusive.detect_peaks(
-            peak_traces, peak_sign, abs_threholds, exclude_sweep_size, neighbours_mask
+            peak_traces, self.peak_sign, self.abs_threholds, self.exclude_sweep_size, self.neighbours_mask
         )
-        peak_sample_ind += margin
+        peak_sample_ind += self.margin
 
-        spikes = np.zeros(peak_sample_ind.size, dtype=spike_dtype)
+        spikes = np.zeros(peak_sample_ind.size, dtype=_base_matching_dtype)
         spikes["sample_index"] = peak_sample_ind
         spikes["channel_index"] = peak_chan_ind  # TODO need to put the channel from template
 
         # naively take the closest template
         for i in range(peak_sample_ind.size):
-            i0 = peak_sample_ind[i] - nbefore
-            i1 = peak_sample_ind[i] + nafter
+            i0 = peak_sample_ind[i] - self.nbefore
+            i1 = peak_sample_ind[i] + self.nafter
 
             waveforms = traces[i0:i1, :]
-            dist = np.sum(np.sum((templates_array - waveforms[None, :, :]) ** 2, axis=1), axis=1)
+            dist = np.sum(np.sum((self.templates_array - waveforms[None, :, :]) ** 2, axis=1), axis=1)
             cluster_index = np.argmin(dist)
 
             spikes["cluster_index"][i] = cluster_index
             spikes["amplitude"][i] = 0.0
 
         return spikes
+    
+        
+# from .main import BaseTemplateMatchingEngine
+
+# class NaiveMatching(BaseTemplateMatchingEngine):
+#     """
+#     This is a naive template matching that does not resolve collision
+#     and does not take in account sparsity.
+#     It just minimizes the distance to templates for detected peaks.
+
+#     It is implemented for benchmarking against this low quality template matching.
+#     And also as an example how to deal with methods_kwargs, margin, intit, func, ...
+#     """
+
+#     default_params = {
+#         "templates": None,
+#         "peak_sign": "neg",
+#         "exclude_sweep_ms": 0.1,
+#         "detect_threshold": 5,
+#         "noise_levels": None,
+#         "radius_um": 100,
+#         "random_chunk_kwargs": {},
+#     }
+
+#     @classmethod
+#     def initialize_and_check_kwargs(cls, recording, kwargs):
+#         d = cls.default_params.copy()
+#         d.update(kwargs)
+
+#         assert isinstance(d["templates"], Templates), (
+#             f"The templates supplied is of type {type(d['templates'])} " f"and must be a Templates"
+#         )
+
+#         templates = d["templates"]
+
+#         if d["noise_levels"] is None:
+#             d["noise_levels"] = get_noise_levels(recording, **d["random_chunk_kwargs"], return_scaled=False)
+
+#         d["abs_threholds"] = d["noise_levels"] * d["detect_threshold"]
+
+#         channel_distance = get_channel_distances(recording)
+#         d["neighbours_mask"] = channel_distance < d["radius_um"]
+
+#         d["nbefore"] = templates.nbefore
+#         d["nafter"] = templates.nafter
+
+#         d["exclude_sweep_size"] = int(d["exclude_sweep_ms"] * recording.get_sampling_frequency() / 1000.0)
+
+#         return d
+
+#     @classmethod
+#     def get_margin(cls, recording, kwargs):
+#         margin = max(kwargs["nbefore"], kwargs["nafter"])
+#         return margin
+
+#     @classmethod
+#     def serialize_method_kwargs(cls, kwargs):
+#         kwargs = dict(kwargs)
+#         return kwargs
+
+#     @classmethod
+#     def unserialize_in_worker(cls, kwargs):
+#         return kwargs
+
+#     @classmethod
+#     def main_function(cls, traces, method_kwargs):
+#         peak_sign = method_kwargs["peak_sign"]
+#         abs_threholds = method_kwargs["abs_threholds"]
+#         exclude_sweep_size = method_kwargs["exclude_sweep_size"]
+#         neighbours_mask = method_kwargs["neighbours_mask"]
+#         templates_array = method_kwargs["templates"].get_dense_templates()
+
+#         nbefore = method_kwargs["nbefore"]
+#         nafter = method_kwargs["nafter"]
+
+#         margin = method_kwargs["margin"]
+
+#         if margin > 0:
+#             peak_traces = traces[margin:-margin, :]
+#         else:
+#             peak_traces = traces
+#         peak_sample_ind, peak_chan_ind = DetectPeakLocallyExclusive.detect_peaks(
+#             peak_traces, peak_sign, abs_threholds, exclude_sweep_size, neighbours_mask
+#         )
+#         peak_sample_ind += margin
+
+#         spikes = np.zeros(peak_sample_ind.size, dtype=spike_dtype)
+#         spikes["sample_index"] = peak_sample_ind
+#         spikes["channel_index"] = peak_chan_ind  # TODO need to put the channel from template
+
+#         # naively take the closest template
+#         for i in range(peak_sample_ind.size):
+#             i0 = peak_sample_ind[i] - nbefore
+#             i1 = peak_sample_ind[i] + nafter
+
+#             waveforms = traces[i0:i1, :]
+#             dist = np.sum(np.sum((templates_array - waveforms[None, :, :]) ** 2, axis=1), axis=1)
+#             cluster_index = np.argmin(dist)
+
+#             spikes["cluster_index"][i] = cluster_index
+#             spikes["amplitude"][i] = 0.0
+
+#         return spikes
diff --git a/src/spikeinterface/sortingcomponents/matching/tdc.py b/src/spikeinterface/sortingcomponents/matching/tdc.py
index e66929e2b1..2698d76828 100644
--- a/src/spikeinterface/sortingcomponents/matching/tdc.py
+++ b/src/spikeinterface/sortingcomponents/matching/tdc.py
@@ -11,15 +11,17 @@
 from spikeinterface.sortingcomponents.peak_detection import DetectPeakLocallyExclusive
 from spikeinterface.core.template import Templates
 
-spike_dtype = [
-    ("sample_index", "int64"),
-    ("channel_index", "int64"),
-    ("cluster_index", "int64"),
-    ("amplitude", "float64"),
-    ("segment_index", "int64"),
-]
+from .base import BaseTemplateMatching, _base_matching_dtype
 
-from .main import BaseTemplateMatchingEngine
+# spike_dtype = [
+#     ("sample_index", "int64"),
+#     ("channel_index", "int64"),
+#     ("cluster_index", "int64"),
+#     ("amplitude", "float64"),
+#     ("segment_index", "int64"),
+# ]
+
+# from .main import BaseTemplateMatchingEngine
 
 try:
     import numba
@@ -30,7 +32,7 @@
     HAVE_NUMBA = False
 
 
-class TridesclousPeeler(BaseTemplateMatchingEngine):
+class TridesclousPeeler(BaseTemplateMatching):
     """
     Template-matching ported from Tridesclous sorter.
 
@@ -44,66 +46,55 @@ class TridesclousPeeler(BaseTemplateMatchingEngine):
     This method is quite fast but don't give exelent results to resolve
     spike collision when templates have high similarity.
     """
+    def __init__(self, recording, return_output=True, parents=None,
+        templates=None,
+        peak_shift_ms=0.2,
+        detect_threshold=5,
+        noise_levels=None,
+        radius_um=100.,
+        num_closest=5,
+        sample_shift=3,
+        ms_before=0.8,
+        ms_after=1.2,
+        num_peeler_loop=2,
+        num_template_try=1,
+        ):
+
+        BaseTemplateMatching.__init__(self, recording, templates, return_output=True, parents=None)
+
+        # maybe in base? 
+        self.templates_array = templates.get_dense_templates()
 
-    default_params = {
-        "templates": None,
-        "peak_sign": "neg",
-        "peak_shift_ms": 0.2,
-        "detect_threshold": 5,
-        "noise_levels": None,
-        "radius_um": 100,
-        "num_closest": 5,
-        "sample_shift": 3,
-        "ms_before": 0.8,
-        "ms_after": 1.2,
-        "num_peeler_loop": 2,
-        "num_template_try": 1,
-    }
-
-    @classmethod
-    def initialize_and_check_kwargs(cls, recording, kwargs):
-        assert HAVE_NUMBA, "TridesclousPeeler needs numba to be installed"
-
-        d = cls.default_params.copy()
-        d.update(kwargs)
-
-        assert isinstance(d["templates"], Templates), (
-            f"The templates supplied is of type {type(d['templates'])} " f"and must be a Templates"
-        )
-
-        templates = d["templates"]
         unit_ids = templates.unit_ids
-        channel_ids = templates.channel_ids
+        channel_ids = recording.channel_ids
 
-        sr = templates.sampling_frequency
+        sr = recording.sampling_frequency
 
-        d["nbefore"] = templates.nbefore
-        d["nafter"] = templates.nafter
-        templates_array = templates.get_dense_templates()
+        self.nbefore = templates.nbefore
+        self.nafter = templates.nafter
+        
 
-        nbefore_short = int(d["ms_before"] * sr / 1000.0)
-        nafter_short = int(d["ms_before"] * sr / 1000.0)
+        nbefore_short = int(ms_before * sr / 1000.0)
+        nafter_short = int(ms_before * sr / 1000.0)
         assert nbefore_short <= templates.nbefore
         assert nafter_short <= templates.nafter
-        d["nbefore_short"] = nbefore_short
-        d["nafter_short"] = nafter_short
+        self.nbefore_short = nbefore_short
+        self.nafter_short = nafter_short
         s0 = templates.nbefore - nbefore_short
         s1 = -(templates.nafter - nafter_short)
         if s1 == 0:
             s1 = None
-        templates_short = templates_array[:, slice(s0, s1), :].copy()
-        d["templates_short"] = templates_short
+        # TODO check with out copy
+        self.templates_short = self.templates_array[:, slice(s0, s1), :].copy()
 
-        d["peak_shift"] = int(d["peak_shift_ms"] / 1000 * sr)
+        self.peak_shift = int(peak_shift_ms / 1000 * sr)
 
-        if d["noise_levels"] is None:
-            print("TridesclousPeeler : noise should be computed outside")
-            d["noise_levels"] = get_noise_levels(recording)
+        assert noise_levels is not None, "TridesclousPeeler : noise should be computed outside"
 
-        d["abs_thresholds"] = d["noise_levels"] * d["detect_threshold"]
+        self.abs_thresholds = noise_levels * detect_threshold
 
         channel_distance = get_channel_distances(recording)
-        d["neighbours_mask"] = channel_distance < d["radius_um"]
+        self.neighbours_mask = channel_distance < radius_um
 
         sparsity = compute_sparsity(
             templates, method="best_channels"
@@ -216,6 +207,193 @@ def main_function(cls, traces, d):
         return all_spikes
 
 
+
+# class TridesclousPeeler(BaseTemplateMatchingEngine):
+#     """
+#     Template-matching ported from Tridesclous sorter.
+
+#     The idea of this peeler is pretty simple.
+#     1. Find peaks
+#     2. order by best amplitues
+#     3. find nearest template
+#     4. remove it from traces.
+#     5. in the residual find peaks again
+
+#     This method is quite fast but don't give exelent results to resolve
+#     spike collision when templates have high similarity.
+#     """
+
+#     default_params = {
+#         "templates": None,
+#         "peak_sign": "neg",
+#         "peak_shift_ms": 0.2,
+#         "detect_threshold": 5,
+#         "noise_levels": None,
+#         "radius_um": 100,
+#         "num_closest": 5,
+#         "sample_shift": 3,
+#         "ms_before": 0.8,
+#         "ms_after": 1.2,
+#         "num_peeler_loop": 2,
+#         "num_template_try": 1,
+#     }
+
+#     @classmethod
+#     def initialize_and_check_kwargs(cls, recording, kwargs):
+#         assert HAVE_NUMBA, "TridesclousPeeler needs numba to be installed"
+
+#         d = cls.default_params.copy()
+#         d.update(kwargs)
+
+#         assert isinstance(d["templates"], Templates), (
+#             f"The templates supplied is of type {type(d['templates'])} " f"and must be a Templates"
+#         )
+
+#         templates = d["templates"]
+#         unit_ids = templates.unit_ids
+#         channel_ids = templates.channel_ids
+
+#         sr = templates.sampling_frequency
+
+#         d["nbefore"] = templates.nbefore
+#         d["nafter"] = templates.nafter
+#         templates_array = templates.get_dense_templates()
+
+#         nbefore_short = int(d["ms_before"] * sr / 1000.0)
+#         nafter_short = int(d["ms_before"] * sr / 1000.0)
+#         assert nbefore_short <= templates.nbefore
+#         assert nafter_short <= templates.nafter
+#         d["nbefore_short"] = nbefore_short
+#         d["nafter_short"] = nafter_short
+#         s0 = templates.nbefore - nbefore_short
+#         s1 = -(templates.nafter - nafter_short)
+#         if s1 == 0:
+#             s1 = None
+#         templates_short = templates_array[:, slice(s0, s1), :].copy()
+#         d["templates_short"] = templates_short
+
+#         d["peak_shift"] = int(d["peak_shift_ms"] / 1000 * sr)
+
+#         if d["noise_levels"] is None:
+#             print("TridesclousPeeler : noise should be computed outside")
+#             d["noise_levels"] = get_noise_levels(recording)
+
+#         d["abs_thresholds"] = d["noise_levels"] * d["detect_threshold"]
+
+#         channel_distance = get_channel_distances(recording)
+#         d["neighbours_mask"] = channel_distance < d["radius_um"]
+
+#         sparsity = compute_sparsity(
+#             templates, method="best_channels"
+#         )  # , peak_sign=d["peak_sign"], threshold=d["detect_threshold"])
+#         template_sparsity_inds = sparsity.unit_id_to_channel_indices
+#         template_sparsity = np.zeros((unit_ids.size, channel_ids.size), dtype="bool")
+#         for unit_index, unit_id in enumerate(unit_ids):
+#             chan_inds = template_sparsity_inds[unit_id]
+#             template_sparsity[unit_index, chan_inds] = True
+
+#         d["template_sparsity"] = template_sparsity
+
+#         extremum_channel = get_template_extremum_channel(templates, peak_sign=d["peak_sign"], outputs="index")
+#         # as numpy vector
+#         extremum_channel = np.array([extremum_channel[unit_id] for unit_id in unit_ids], dtype="int64")
+#         d["extremum_channel"] = extremum_channel
+
+#         channel_locations = templates.probe.contact_positions
+
+#         # TODO try it with real locaion
+#         unit_locations = channel_locations[extremum_channel]
+#         # ~ print(unit_locations)
+
+#         # distance between units
+#         import scipy
+
+#         unit_distances = scipy.spatial.distance.cdist(unit_locations, unit_locations, metric="euclidean")
+
+#         # seach for closet units and unitary discriminant vector
+#         closest_units = []
+#         for unit_ind, unit_id in enumerate(unit_ids):
+#             order = np.argsort(unit_distances[unit_ind, :])
+#             closest_u = np.arange(unit_ids.size)[order].tolist()
+#             closest_u.remove(unit_ind)
+#             closest_u = np.array(closest_u[: d["num_closest"]])
+
+#             # compute unitary discriminent vector
+#             (chans,) = np.nonzero(d["template_sparsity"][unit_ind, :])
+#             template_sparse = templates_array[unit_ind, :, :][:, chans]
+#             closest_vec = []
+#             # against N closets
+#             for u in closest_u:
+#                 vec = templates_array[u, :, :][:, chans] - template_sparse
+#                 vec /= np.sum(vec**2)
+#                 closest_vec.append((u, vec))
+#             # against noise
+#             closest_vec.append((None, -template_sparse / np.sum(template_sparse**2)))
+
+#             closest_units.append(closest_vec)
+
+#         d["closest_units"] = closest_units
+
+#         # distance channel from unit
+#         import scipy
+
+#         distances = scipy.spatial.distance.cdist(channel_locations, unit_locations, metric="euclidean")
+#         near_cluster_mask = distances < d["radius_um"]
+
+#         # nearby cluster for each channel
+#         possible_clusters_by_channel = []
+#         for channel_index in range(distances.shape[0]):
+#             (cluster_inds,) = np.nonzero(near_cluster_mask[channel_index, :])
+#             possible_clusters_by_channel.append(cluster_inds)
+
+#         d["possible_clusters_by_channel"] = possible_clusters_by_channel
+#         d["possible_shifts"] = np.arange(-d["sample_shift"], d["sample_shift"] + 1, dtype="int64")
+
+#         return d
+
+#     @classmethod
+#     def serialize_method_kwargs(cls, kwargs):
+#         kwargs = dict(kwargs)
+#         return kwargs
+
+#     @classmethod
+#     def unserialize_in_worker(cls, kwargs):
+#         return kwargs
+
+#     @classmethod
+#     def get_margin(cls, recording, kwargs):
+#         margin = 2 * (kwargs["nbefore"] + kwargs["nafter"])
+#         return margin
+
+#     @classmethod
+#     def main_function(cls, traces, d):
+#         traces = traces.copy()
+
+#         all_spikes = []
+#         level = 0
+#         while True:
+#             spikes = _tdc_find_spikes(traces, d, level=level)
+#             keep = spikes["cluster_index"] >= 0
+
+#             if not np.any(keep):
+#                 break
+#             all_spikes.append(spikes[keep])
+
+#             level += 1
+
+#             if level == d["num_peeler_loop"]:
+#                 break
+
+#         if len(all_spikes) > 0:
+#             all_spikes = np.concatenate(all_spikes)
+#             order = np.argsort(all_spikes["sample_index"])
+#             all_spikes = all_spikes[order]
+#         else:
+#             all_spikes = np.zeros(0, dtype=spike_dtype)
+
+#         return all_spikes
+
+
 def _tdc_find_spikes(traces, d, level=0):
     peak_sign = d["peak_sign"]
     templates = d["templates"]
@@ -388,3 +566,6 @@ def numba_best_shift(traces, template, sample_index, nbefore, possible_shifts, d
             distances_shift[i] = sum_dist
 
         return distances_shift
+
+
+
diff --git a/src/spikeinterface/sortingcomponents/tests/test_template_matching.py b/src/spikeinterface/sortingcomponents/tests/test_template_matching.py
index dab19809be..0cd3868a8f 100644
--- a/src/spikeinterface/sortingcomponents/tests/test_template_matching.py
+++ b/src/spikeinterface/sortingcomponents/tests/test_template_matching.py
@@ -54,33 +54,33 @@ def test_find_spikes_from_templates(method, sorting_analyzer):
     method_kwargs_.update(method_kwargs_all)
     spikes = find_spikes_from_templates(recording, method=method, method_kwargs=method_kwargs_, **job_kwargs)
 
-    # DEBUG = True
+    DEBUG = True
 
-    # if DEBUG:
-    #     import matplotlib.pyplot as plt
-    #     import spikeinterface.full as si
+    if DEBUG:
+        import matplotlib.pyplot as plt
+        import spikeinterface.full as si
 
-    #     sorting_analyzer.compute("waveforms")
-    #     sorting_analyzer.compute("templates")
+        sorting_analyzer.compute("waveforms")
+        sorting_analyzer.compute("templates")
 
-    #     gt_sorting = sorting_analyzer.sorting
+        gt_sorting = sorting_analyzer.sorting
 
-    #     sorting = NumpySorting.from_times_labels(spikes["sample_index"], spikes["cluster_index"], sampling_frequency)
+        sorting = NumpySorting.from_times_labels(spikes["sample_index"], spikes["cluster_index"], sampling_frequency)
 
-    #     metrics = si.compute_quality_metrics(sorting_analyzer, metric_names=["snr"])
+        ##metrics = si.compute_quality_metrics(sorting_analyzer, metric_names=["snr"])
 
-    #     fig, ax = plt.subplots()
-    #     comp = si.compare_sorter_to_ground_truth(gt_sorting, sorting)
-    #     si.plot_agreement_matrix(comp, ax=ax)
-    #     ax.set_title(method)
-    #     plt.show()
+        fig, ax = plt.subplots()
+        comp = si.compare_sorter_to_ground_truth(gt_sorting, sorting)
+        si.plot_agreement_matrix(comp, ax=ax)
+        ax.set_title(method)
+        plt.show()
 
 
 if __name__ == "__main__":
     sorting_analyzer = get_sorting_analyzer()
     # method = "naive"
-    # method = "tdc-peeler"
+    method = "tdc-peeler"
     # method =  "circus"
     # method = "circus-omp-svd"
-    method = "wobble"
+    # method = "wobble"
     test_find_spikes_from_templates(method, sorting_analyzer)

From 8ced3d522d3f49098d27e481bf831c13d67d5cee Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Fri, 27 Sep 2024 20:18:52 +0200
Subject: [PATCH 048/344] wip refactor template matching with nodepipeline

---
 .../sortingcomponents/matching/base.py        |    4 +-
 .../sortingcomponents/matching/circus.py      | 1341 ++++++++++++-----
 .../sortingcomponents/matching/method_list.py |    8 +-
 .../sortingcomponents/matching/tdc.py         |  450 +++---
 .../tests/test_template_matching.py           |   12 +-
 5 files changed, 1268 insertions(+), 547 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/matching/base.py b/src/spikeinterface/sortingcomponents/matching/base.py
index 3ffc559c65..97e6e5be9b 100644
--- a/src/spikeinterface/sortingcomponents/matching/base.py
+++ b/src/spikeinterface/sortingcomponents/matching/base.py
@@ -15,8 +15,8 @@ def __init__(self, recording, templates, return_output=True, parents=None):
         # TODO make a sharedmem of template here
         # TODO maybe check that channel_id are the same with recording
 
-        assert isinstance(d["templates"], Templates), (
-            f"The templates supplied is of type {type(d['templates'])} " f"and must be a Templates"
+        assert isinstance(templates, Templates), (
+            f"The templates supplied is of type {type(templates)} and must be a Templates"
         )
         self.templates = templates
         PeakSource.__init__(self, recording, return_output=return_output, parents=parents)
diff --git a/src/spikeinterface/sortingcomponents/matching/circus.py b/src/spikeinterface/sortingcomponents/matching/circus.py
index ad7391a297..79f12ba0ac 100644
--- a/src/spikeinterface/sortingcomponents/matching/circus.py
+++ b/src/spikeinterface/sortingcomponents/matching/circus.py
@@ -17,7 +17,8 @@
     ("segment_index", "int64"),
 ]
 
-from .main import BaseTemplateMatchingEngine
+# from .main import BaseTemplateMatchingEngine
+from .base import BaseTemplateMatching
 
 
 def compress_templates(
@@ -88,8 +89,7 @@ def compute_overlaps(templates, num_samples, num_channels, sparsities):
 
     return new_overlaps
 
-
-class CircusOMPSVDPeeler(BaseTemplateMatchingEngine):
+class CircusOMPSVDPeeler(BaseTemplateMatching):
     """
     Orthogonal Matching Pursuit inspired from Spyking Circus sorter
 
@@ -120,148 +120,136 @@ class CircusOMPSVDPeeler(BaseTemplateMatchingEngine):
         of template temporal width)
     -----
     """
+    def __init__(self, recording, return_output=True, parents=None,
+        templates=None,
+        amplitudes=[0.6, np.inf],
+        stop_criteria="max_failures",
+        max_failures=10,
+        omp_min_sps=0.1,
+        relative_error=5e-5,
+        rank=5,
+        ignore_inds=[],
+        vicinity=3,
+        ):
+
+        BaseTemplateMatching.__init__(self, recording, templates, return_output=True, parents=None)
+
+        self.num_channels = recording.get_num_channels()
+        self.num_samples = templates.num_samples
+        self.nbefore = templates.nbefore
+        self.nafter = templates.nafter
+        self.sampling_frequency = recording.get_sampling_frequency()
+        self.vicinity = vicinity * self.num_samples
+
+        self.amplitudes = amplitudes
+        self.stop_criteria = stop_criteria
+        self.max_failures = max_failures
+        self.omp_min_sps = omp_min_sps
+        self.relative_error = relative_error
+        self.rank = rank
+
+        self.num_templates = len(templates.unit_ids)
+
+        # if "overlaps" not in d:
+        #     d = cls._prepare_templates(d)
+        # else:
+        #     for key in [
+        #         "norms",
+        #         "temporal",
+        #         "spatial",
+        #         "singular",
+        #         "units_overlaps",
+        #         "unit_overlaps_indices",
+        #     ]:
+        #         assert d[key] is not None, "If templates are provided, %d should also be there" % key
+        self._prepare_templates()
+
+        
+        self.ignore_inds = np.array(ignore_inds)
+
+        self.unit_overlaps_tables = {}
+        for i in range(self.num_templates):
+            self.unit_overlaps_tables[i] = np.zeros(self.num_templates, dtype=int)
+            self.unit_overlaps_tables[i][self.unit_overlaps_indices[i]] = np.arange(len(self.unit_overlaps_indices[i]))
+
+        if self.vicinity > 0:
+            self.margin = self.vicinity
+        else:
+            self.margin = 2 * self.num_samples
 
-    _default_params = {
-        "amplitudes": [0.6, np.inf],
-        "stop_criteria": "max_failures",
-        "max_failures": 10,
-        "omp_min_sps": 0.1,
-        "relative_error": 5e-5,
-        "templates": None,
-        "rank": 5,
-        "ignore_inds": [],
-        "vicinity": 3,
-    }
 
-    @classmethod
-    def _prepare_templates(cls, d):
-        templates = d["templates"]
-        num_templates = len(d["templates"].unit_ids)
+    def _prepare_templates(self):
 
-        assert d["stop_criteria"] in ["max_failures", "omp_min_sps", "relative_error"]
+        assert self.stop_criteria in ["max_failures", "omp_min_sps", "relative_error"]
 
-        sparsity = templates.sparsity.mask
+        sparsity = self.templates.sparsity.mask
 
         units_overlaps = np.sum(np.logical_and(sparsity[:, np.newaxis, :], sparsity[np.newaxis, :, :]), axis=2)
-        d["units_overlaps"] = units_overlaps > 0
-        d["unit_overlaps_indices"] = {}
-        for i in range(num_templates):
-            (d["unit_overlaps_indices"][i],) = np.nonzero(d["units_overlaps"][i])
+        self.units_overlaps = units_overlaps > 0
+        self.unit_overlaps_indices = {}
+        for i in range(self.num_templates):
+            self.unit_overlaps_indices[i] = np.flatnonzero(self.units_overlaps[i])
 
-        templates_array = templates.get_dense_templates().copy()
+        templates_array = self.templates.get_dense_templates().copy()
         # Then we keep only the strongest components
-        d["temporal"], d["singular"], d["spatial"], templates_array = compress_templates(templates_array, d["rank"])
+        self.temporal, self.singular, self.spatial, templates_array = compress_templates(templates_array, self.rank)
 
-        d["normed_templates"] = np.zeros(templates_array.shape, dtype=np.float32)
-        d["norms"] = np.zeros(num_templates, dtype=np.float32)
+        self.normed_templates = np.zeros(templates_array.shape, dtype=np.float32)
+        self.norms = np.zeros(self.num_templates, dtype=np.float32)
 
         # And get the norms, saving compressed templates for CC matrix
-        for count in range(num_templates):
+        for count in range(self.num_templates):
             template = templates_array[count][:, sparsity[count]]
-            d["norms"][count] = np.linalg.norm(template)
-            d["normed_templates"][count][:, sparsity[count]] = template / d["norms"][count]
+            self.norms[count] = np.linalg.norm(template)
+            self.normed_templates[count][:, sparsity[count]] = template / self.norms[count]
 
-        d["temporal"] /= d["norms"][:, np.newaxis, np.newaxis]
-        d["temporal"] = np.flip(d["temporal"], axis=1)
+        self.temporal /= self.norms[:, np.newaxis, np.newaxis]
+        self.temporal = np.flip(self.temporal, axis=1)
 
-        d["overlaps"] = []
-        d["max_similarity"] = np.zeros((num_templates, num_templates), dtype=np.float32)
-        for i in range(num_templates):
-            num_overlaps = np.sum(d["units_overlaps"][i])
-            overlapping_units = np.where(d["units_overlaps"][i])[0]
+        self.overlaps = []
+        self.max_similarity = np.zeros((self.num_templates, self.num_templates), dtype=np.float32)
+        for i in range(self.num_templates):
+            num_overlaps = np.sum(self.units_overlaps[i])
+            overlapping_units = np.flatnonzero(self.units_overlaps[i])
 
             # Reconstruct unit template from SVD Matrices
-            data = d["temporal"][i] * d["singular"][i][np.newaxis, :]
-            template_i = np.matmul(data, d["spatial"][i, :, :])
+            data = self.temporal[i] * self.singular[i][np.newaxis, :]
+            template_i = np.matmul(data, self.spatial[i, :, :])
             template_i = np.flipud(template_i)
 
-            unit_overlaps = np.zeros([num_overlaps, 2 * d["num_samples"] - 1], dtype=np.float32)
+            unit_overlaps = np.zeros([num_overlaps, 2 * self.num_samples - 1], dtype=np.float32)
 
             for count, j in enumerate(overlapping_units):
                 overlapped_channels = sparsity[j]
                 visible_i = template_i[:, overlapped_channels]
 
-                spatial_filters = d["spatial"][j, :, overlapped_channels]
+                spatial_filters = self.spatial[j, :, overlapped_channels]
                 spatially_filtered_template = np.matmul(visible_i, spatial_filters)
-                visible_i = spatially_filtered_template * d["singular"][j]
+                visible_i = spatially_filtered_template * self.singular[j]
 
                 for rank in range(visible_i.shape[1]):
-                    unit_overlaps[count, :] += np.convolve(visible_i[:, rank], d["temporal"][j][:, rank], mode="full")
+                    unit_overlaps[count, :] += np.convolve(visible_i[:, rank], self.temporal[j][:, rank], mode="full")
 
-                d["max_similarity"][i, j] = np.max(unit_overlaps[count])
+                self.max_similarity[i, j] = np.max(unit_overlaps[count])
 
-            d["overlaps"].append(unit_overlaps)
+            self.overlaps.append(unit_overlaps)
 
-        if d["amplitudes"] is None:
-            distances = np.sort(d["max_similarity"], axis=1)[:, ::-1]
+        if self.amplitudes is None:
+            distances = np.sort(self.max_similarity, axis=1)[:, ::-1]
             distances = 1 - distances[:, 1] / 2
-            d["amplitudes"] = np.zeros((num_templates, 2))
-            d["amplitudes"][:, 0] = distances
-            d["amplitudes"][:, 1] = np.inf
-
-        d["spatial"] = np.moveaxis(d["spatial"], [0, 1, 2], [1, 0, 2])
-        d["temporal"] = np.moveaxis(d["temporal"], [0, 1, 2], [1, 2, 0])
-        d["singular"] = d["singular"].T[:, :, np.newaxis]
-        return d
-
-    @classmethod
-    def initialize_and_check_kwargs(cls, recording, kwargs):
-        d = cls._default_params.copy()
-        d.update(kwargs)
-
-        assert isinstance(d["templates"], Templates), (
-            f"The templates supplied is of type {type(d['templates'])} " f"and must be a Templates"
-        )
+            self.amplitudes = np.zeros((self.num_templates, 2))
+            self.amplitudes[:, 0] = distances
+            self.amplitudes[:, 1] = np.inf
 
-        d["num_channels"] = recording.get_num_channels()
-        d["num_samples"] = d["templates"].num_samples
-        d["nbefore"] = d["templates"].nbefore
-        d["nafter"] = d["templates"].nafter
-        d["sampling_frequency"] = recording.get_sampling_frequency()
-        d["vicinity"] *= d["num_samples"]
+        self.spatial = np.moveaxis(self.spatial, [0, 1, 2], [1, 0, 2])
+        self.temporal = np.moveaxis(self.temporal, [0, 1, 2], [1, 2, 0])
+        self.singular = self.singular.T[:, :, np.newaxis]
 
-        if "overlaps" not in d:
-            d = cls._prepare_templates(d)
-        else:
-            for key in [
-                "norms",
-                "temporal",
-                "spatial",
-                "singular",
-                "units_overlaps",
-                "unit_overlaps_indices",
-            ]:
-                assert d[key] is not None, "If templates are provided, %d should also be there" % key
-
-        d["num_templates"] = len(d["templates"].templates_array)
-        d["ignore_inds"] = np.array(d["ignore_inds"])
-
-        d["unit_overlaps_tables"] = {}
-        for i in range(d["num_templates"]):
-            d["unit_overlaps_tables"][i] = np.zeros(d["num_templates"], dtype=int)
-            d["unit_overlaps_tables"][i][d["unit_overlaps_indices"][i]] = np.arange(len(d["unit_overlaps_indices"][i]))
-
-        return d
-
-    @classmethod
-    def serialize_method_kwargs(cls, kwargs):
-        kwargs = dict(kwargs)
-        return kwargs
-
-    @classmethod
-    def unserialize_in_worker(cls, kwargs):
-        return kwargs
-
-    @classmethod
-    def get_margin(cls, recording, kwargs):
-        if kwargs["vicinity"] > 0:
-            margin = kwargs["vicinity"]
-        else:
-            margin = 2 * kwargs["num_samples"]
-        return margin
 
-    @classmethod
-    def main_function(cls, traces, d):
+    def get_trace_margin(self):
+        return self.margin    
+
+    def compute(self, traces, start_frame, end_frame, segment_index, max_margin, *args):
         import scipy.spatial
         import scipy
 
@@ -269,50 +257,45 @@ def main_function(cls, traces, d):
 
         (nrm2,) = scipy.linalg.get_blas_funcs(("nrm2",), dtype=np.float32)
 
-        num_templates = d["num_templates"]
-        num_samples = d["num_samples"]
-        num_channels = d["num_channels"]
-        overlaps_array = d["overlaps"]
-        norms = d["norms"]
+        overlaps_array = self.overlaps
+
         omp_tol = np.finfo(np.float32).eps
-        num_samples = d["nafter"] + d["nbefore"]
+        num_samples = self.nafter + self.nbefore
         neighbor_window = num_samples - 1
-        if isinstance(d["amplitudes"], list):
-            min_amplitude, max_amplitude = d["amplitudes"]
+        if isinstance(self.amplitudes, list):
+            min_amplitude, max_amplitude = self.amplitudes
         else:
-            min_amplitude, max_amplitude = d["amplitudes"][:, 0], d["amplitudes"][:, 1]
+            min_amplitude, max_amplitude = self.amplitudes[:, 0], self.amplitudes[:, 1]
             min_amplitude = min_amplitude[:, np.newaxis]
             max_amplitude = max_amplitude[:, np.newaxis]
-        ignore_inds = d["ignore_inds"]
-        vicinity = d["vicinity"]
 
         num_timesteps = len(traces)
 
         num_peaks = num_timesteps - num_samples + 1
-        conv_shape = (num_templates, num_peaks)
+        conv_shape = (self.num_templates, num_peaks)
         scalar_products = np.zeros(conv_shape, dtype=np.float32)
 
         # Filter using overlap-and-add convolution
-        if len(ignore_inds) > 0:
-            not_ignored = ~np.isin(np.arange(num_templates), ignore_inds)
-            spatially_filtered_data = np.matmul(d["spatial"][:, not_ignored, :], traces.T[np.newaxis, :, :])
-            scaled_filtered_data = spatially_filtered_data * d["singular"][:, not_ignored, :]
+        if len(self.ignore_inds) > 0:
+            not_ignored = ~np.isin(np.arange(self.num_templates), self.ignore_inds)
+            spatially_filtered_data = np.matmul(self.spatial[:, not_ignored, :], traces.T[np.newaxis, :, :])
+            scaled_filtered_data = spatially_filtered_data * self.singular[:, not_ignored, :]
             objective_by_rank = scipy.signal.oaconvolve(
-                scaled_filtered_data, d["temporal"][:, not_ignored, :], axes=2, mode="valid"
+                scaled_filtered_data, self.temporal[:, not_ignored, :], axes=2, mode="valid"
             )
             scalar_products[not_ignored] += np.sum(objective_by_rank, axis=0)
-            scalar_products[ignore_inds] = -np.inf
+            scalar_products[self.ignore_inds] = -np.inf
         else:
-            spatially_filtered_data = np.matmul(d["spatial"], traces.T[np.newaxis, :, :])
-            scaled_filtered_data = spatially_filtered_data * d["singular"]
-            objective_by_rank = scipy.signal.oaconvolve(scaled_filtered_data, d["temporal"], axes=2, mode="valid")
+            spatially_filtered_data = np.matmul(self.spatial, traces.T[np.newaxis, :, :])
+            scaled_filtered_data = spatially_filtered_data * self.singular
+            objective_by_rank = scipy.signal.oaconvolve(scaled_filtered_data, self.temporal, axes=2, mode="valid")
             scalar_products += np.sum(objective_by_rank, axis=0)
 
         num_spikes = 0
 
         spikes = np.empty(scalar_products.size, dtype=spike_dtype)
 
-        M = np.zeros((num_templates, num_templates), dtype=np.float32)
+        M = np.zeros((self.num_templates, self.num_templates), dtype=np.float32)
 
         all_selections = np.empty((2, scalar_products.size), dtype=np.int32)
         final_amplitudes = np.zeros(scalar_products.shape, dtype=np.float32)
@@ -325,13 +308,13 @@ def main_function(cls, traces, d):
         all_amplitudes = np.zeros(0, dtype=np.float32)
         is_in_vicinity = np.zeros(0, dtype=np.int32)
 
-        if d["stop_criteria"] == "omp_min_sps":
-            stop_criteria = d["omp_min_sps"] * np.maximum(d["norms"], np.sqrt(num_channels * num_samples))
-        elif d["stop_criteria"] == "max_failures":
+        if self.stop_criteria == "omp_min_sps":
+            stop_criteria = self.omp_min_sps * np.maximum(self.norms, np.sqrt(self.num_channels * num_samples))
+        elif self.stop_criteria == "max_failures":
             num_valids = 0
-            nb_failures = d["max_failures"]
-        elif d["stop_criteria"] == "relative_error":
-            if len(ignore_inds) > 0:
+            nb_failures = self.max_failures
+        elif self.stop_criteria == "relative_error":
+            if len(self.ignore_inds) > 0:
                 new_error = np.linalg.norm(scalar_products[not_ignored])
             else:
                 new_error = np.linalg.norm(scalar_products)
@@ -350,8 +333,8 @@ def main_function(cls, traces, d):
                 myindices = selection[0, idx]
 
                 local_overlaps = overlaps_array[best_cluster_ind]
-                overlapping_templates = d["unit_overlaps_indices"][best_cluster_ind]
-                table = d["unit_overlaps_tables"][best_cluster_ind]
+                overlapping_templates = self.unit_overlaps_indices[best_cluster_ind]
+                table = self.unit_overlaps_tables[best_cluster_ind]
 
                 if num_selection == M.shape[0]:
                     Z = np.zeros((2 * num_selection, 2 * num_selection), dtype=np.float32)
@@ -362,7 +345,7 @@ def main_function(cls, traces, d):
                 a, b = myindices[mask], myline[mask]
                 M[num_selection, idx[mask]] = local_overlaps[table[a], b]
 
-                if vicinity == 0:
+                if self.vicinity == 0:
                     scipy.linalg.solve_triangular(
                         M[:num_selection, :num_selection],
                         M[num_selection, :num_selection],
@@ -378,7 +361,7 @@ def main_function(cls, traces, d):
                         break
                     M[num_selection, num_selection] = np.sqrt(Lkk)
                 else:
-                    is_in_vicinity = np.where(np.abs(delta_t) < vicinity)[0]
+                    is_in_vicinity = np.where(np.abs(delta_t) < self.vicinity)[0]
 
                     if len(is_in_vicinity) > 0:
                         L = M[is_in_vicinity, :][:, is_in_vicinity]
@@ -403,15 +386,15 @@ def main_function(cls, traces, d):
             selection = all_selections[:, :num_selection]
             res_sps = full_sps[selection[0], selection[1]]
 
-            if vicinity == 0:
+            if self.vicinity == 0:
                 all_amplitudes, _ = potrs(M[:num_selection, :num_selection], res_sps, lower=True, overwrite_b=False)
-                all_amplitudes /= norms[selection[0]]
+                all_amplitudes /= self.norms[selection[0]]
             else:
                 is_in_vicinity = np.append(is_in_vicinity, num_selection - 1)
                 all_amplitudes = np.append(all_amplitudes, np.float32(1))
                 L = M[is_in_vicinity, :][:, is_in_vicinity]
                 all_amplitudes[is_in_vicinity], _ = potrs(L, res_sps[is_in_vicinity], lower=True, overwrite_b=False)
-                all_amplitudes[is_in_vicinity] /= norms[selection[0][is_in_vicinity]]
+                all_amplitudes[is_in_vicinity] /= self.norms[selection[0][is_in_vicinity]]
 
             diff_amplitudes = all_amplitudes - final_amplitudes[selection[0], selection[1]]
             modified = np.where(np.abs(diff_amplitudes) > omp_tol)[0]
@@ -419,10 +402,10 @@ def main_function(cls, traces, d):
 
             for i in modified:
                 tmp_best, tmp_peak = selection[:, i]
-                diff_amp = diff_amplitudes[i] * norms[tmp_best]
+                diff_amp = diff_amplitudes[i] * self.norms[tmp_best]
 
                 local_overlaps = overlaps_array[tmp_best]
-                overlapping_templates = d["units_overlaps"][tmp_best]
+                overlapping_templates = self.units_overlaps[tmp_best]
 
                 if not tmp_peak in neighbors.keys():
                     idx = [max(0, tmp_peak - neighbor_window), min(num_peaks, tmp_peak + num_samples)]
@@ -436,32 +419,32 @@ def main_function(cls, traces, d):
                 scalar_products[overlapping_templates, idx[0] : idx[1]] -= to_add
 
             # We stop when updates do not modify the chosen spikes anymore
-            if d["stop_criteria"] == "omp_min_sps":
+            if self.stop_criteria == "omp_min_sps":
                 is_valid = scalar_products > stop_criteria[:, np.newaxis]
                 do_loop = np.any(is_valid)
-            elif d["stop_criteria"] == "max_failures":
+            elif self.stop_criteria == "max_failures":
                 is_valid = (final_amplitudes > min_amplitude) * (final_amplitudes < max_amplitude)
                 new_num_valids = np.sum(is_valid)
                 if (new_num_valids - num_valids) > 0:
-                    nb_failures = d["max_failures"]
+                    nb_failures = self.max_failures
                 else:
                     nb_failures -= 1
                 num_valids = new_num_valids
                 do_loop = nb_failures > 0
-            elif d["stop_criteria"] == "relative_error":
+            elif self.stop_criteria == "relative_error":
                 previous_error = new_error
-                if len(ignore_inds) > 0:
+                if len(self.ignore_inds) > 0:
                     new_error = np.linalg.norm(scalar_products[not_ignored])
                 else:
                     new_error = np.linalg.norm(scalar_products)
                 delta_error = np.abs(new_error / previous_error - 1)
-                do_loop = delta_error > d["relative_error"]
+                do_loop = delta_error > self.relative_error
 
         is_valid = (final_amplitudes > min_amplitude) * (final_amplitudes < max_amplitude)
         valid_indices = np.where(is_valid)
 
         num_spikes = len(valid_indices[0])
-        spikes["sample_index"][:num_spikes] = valid_indices[1] + d["nbefore"]
+        spikes["sample_index"][:num_spikes] = valid_indices[1] + self.nbefore
         spikes["channel_index"][:num_spikes] = 0
         spikes["cluster_index"][:num_spikes] = valid_indices[0]
         spikes["amplitude"][:num_spikes] = final_amplitudes[valid_indices[0], valid_indices[1]]
@@ -473,7 +456,392 @@ def main_function(cls, traces, d):
         return spikes
 
 
-class CircusPeeler(BaseTemplateMatchingEngine):
+
+# class CircusOMPSVDPeeler(BaseTemplateMatchingEngine):
+#     """
+#     Orthogonal Matching Pursuit inspired from Spyking Circus sorter
+
+#     https://elifesciences.org/articles/34518
+
+#     This is an Orthogonal Template Matching algorithm. For speed and
+#     memory optimization, templates are automatically sparsified. Signal
+#     is convolved with the templates, and as long as some scalar products
+#     are higher than a given threshold, we use a Cholesky decomposition
+#     to compute the optimal amplitudes needed to reconstruct the signal.
+
+#     IMPORTANT NOTE: small chunks are more efficient for such Peeler,
+#     consider using 100ms chunk
+
+#     Parameters
+#     ----------
+#     amplitude: tuple
+#         (Minimal, Maximal) amplitudes allowed for every template
+#     max_failures: int
+#         Stopping criteria of the OMP algorithm, as number of retry while updating amplitudes
+#     sparse_kwargs: dict
+#         Parameters to extract a sparsity mask from the waveform_extractor, if not
+#         already sparse.
+#     rank: int, default: 5
+#         Number of components used internally by the SVD
+#     vicinity: int
+#         Size of the area surrounding a spike to perform modification (expressed in terms
+#         of template temporal width)
+#     -----
+#     """
+
+#     _default_params = {
+#         "amplitudes": [0.6, np.inf],
+#         "stop_criteria": "max_failures",
+#         "max_failures": 10,
+#         "omp_min_sps": 0.1,
+#         "relative_error": 5e-5,
+#         "templates": None,
+#         "rank": 5,
+#         "ignore_inds": [],
+#         "vicinity": 3,
+#     }
+
+#     @classmethod
+#     def _prepare_templates(cls, d):
+#         templates = d["templates"]
+#         num_templates = len(d["templates"].unit_ids)
+
+#         assert d["stop_criteria"] in ["max_failures", "omp_min_sps", "relative_error"]
+
+#         sparsity = templates.sparsity.mask
+
+#         units_overlaps = np.sum(np.logical_and(sparsity[:, np.newaxis, :], sparsity[np.newaxis, :, :]), axis=2)
+#         d["units_overlaps"] = units_overlaps > 0
+#         d["unit_overlaps_indices"] = {}
+#         for i in range(num_templates):
+#             (d["unit_overlaps_indices"][i],) = np.nonzero(d["units_overlaps"][i])
+
+#         templates_array = templates.get_dense_templates().copy()
+#         # Then we keep only the strongest components
+#         d["temporal"], d["singular"], d["spatial"], templates_array = compress_templates(templates_array, d["rank"])
+
+#         d["normed_templates"] = np.zeros(templates_array.shape, dtype=np.float32)
+#         d["norms"] = np.zeros(num_templates, dtype=np.float32)
+
+#         # And get the norms, saving compressed templates for CC matrix
+#         for count in range(num_templates):
+#             template = templates_array[count][:, sparsity[count]]
+#             d["norms"][count] = np.linalg.norm(template)
+#             d["normed_templates"][count][:, sparsity[count]] = template / d["norms"][count]
+
+#         d["temporal"] /= d["norms"][:, np.newaxis, np.newaxis]
+#         d["temporal"] = np.flip(d["temporal"], axis=1)
+
+#         d["overlaps"] = []
+#         d["max_similarity"] = np.zeros((num_templates, num_templates), dtype=np.float32)
+#         for i in range(num_templates):
+#             num_overlaps = np.sum(d["units_overlaps"][i])
+#             overlapping_units = np.where(d["units_overlaps"][i])[0]
+
+#             # Reconstruct unit template from SVD Matrices
+#             data = d["temporal"][i] * d["singular"][i][np.newaxis, :]
+#             template_i = np.matmul(data, d["spatial"][i, :, :])
+#             template_i = np.flipud(template_i)
+
+#             unit_overlaps = np.zeros([num_overlaps, 2 * d["num_samples"] - 1], dtype=np.float32)
+
+#             for count, j in enumerate(overlapping_units):
+#                 overlapped_channels = sparsity[j]
+#                 visible_i = template_i[:, overlapped_channels]
+
+#                 spatial_filters = d["spatial"][j, :, overlapped_channels]
+#                 spatially_filtered_template = np.matmul(visible_i, spatial_filters)
+#                 visible_i = spatially_filtered_template * d["singular"][j]
+
+#                 for rank in range(visible_i.shape[1]):
+#                     unit_overlaps[count, :] += np.convolve(visible_i[:, rank], d["temporal"][j][:, rank], mode="full")
+
+#                 d["max_similarity"][i, j] = np.max(unit_overlaps[count])
+
+#             d["overlaps"].append(unit_overlaps)
+
+#         if d["amplitudes"] is None:
+#             distances = np.sort(d["max_similarity"], axis=1)[:, ::-1]
+#             distances = 1 - distances[:, 1] / 2
+#             d["amplitudes"] = np.zeros((num_templates, 2))
+#             d["amplitudes"][:, 0] = distances
+#             d["amplitudes"][:, 1] = np.inf
+
+#         d["spatial"] = np.moveaxis(d["spatial"], [0, 1, 2], [1, 0, 2])
+#         d["temporal"] = np.moveaxis(d["temporal"], [0, 1, 2], [1, 2, 0])
+#         d["singular"] = d["singular"].T[:, :, np.newaxis]
+#         return d
+
+#     @classmethod
+#     def initialize_and_check_kwargs(cls, recording, kwargs):
+#         d = cls._default_params.copy()
+#         d.update(kwargs)
+
+#         assert isinstance(d["templates"], Templates), (
+#             f"The templates supplied is of type {type(d['templates'])} " f"and must be a Templates"
+#         )
+
+#         d["num_channels"] = recording.get_num_channels()
+#         d["num_samples"] = d["templates"].num_samples
+#         d["nbefore"] = d["templates"].nbefore
+#         d["nafter"] = d["templates"].nafter
+#         d["sampling_frequency"] = recording.get_sampling_frequency()
+#         d["vicinity"] *= d["num_samples"]
+
+#         if "overlaps" not in d:
+#             d = cls._prepare_templates(d)
+#         else:
+#             for key in [
+#                 "norms",
+#                 "temporal",
+#                 "spatial",
+#                 "singular",
+#                 "units_overlaps",
+#                 "unit_overlaps_indices",
+#             ]:
+#                 assert d[key] is not None, "If templates are provided, %d should also be there" % key
+
+#         d["num_templates"] = len(d["templates"].templates_array)
+#         d["ignore_inds"] = np.array(d["ignore_inds"])
+
+#         d["unit_overlaps_tables"] = {}
+#         for i in range(d["num_templates"]):
+#             d["unit_overlaps_tables"][i] = np.zeros(d["num_templates"], dtype=int)
+#             d["unit_overlaps_tables"][i][d["unit_overlaps_indices"][i]] = np.arange(len(d["unit_overlaps_indices"][i]))
+
+#         return d
+
+#     @classmethod
+#     def serialize_method_kwargs(cls, kwargs):
+#         kwargs = dict(kwargs)
+#         return kwargs
+
+#     @classmethod
+#     def unserialize_in_worker(cls, kwargs):
+#         return kwargs
+
+#     @classmethod
+#     def get_margin(cls, recording, kwargs):
+#         if kwargs["vicinity"] > 0:
+#             margin = kwargs["vicinity"]
+#         else:
+#             margin = 2 * kwargs["num_samples"]
+#         return margin
+
+#     @classmethod
+#     def main_function(cls, traces, d):
+#         import scipy.spatial
+#         import scipy
+
+#         (potrs,) = scipy.linalg.get_lapack_funcs(("potrs",), dtype=np.float32)
+
+#         (nrm2,) = scipy.linalg.get_blas_funcs(("nrm2",), dtype=np.float32)
+
+#         num_templates = d["num_templates"]
+#         num_samples = d["num_samples"]
+#         num_channels = d["num_channels"]
+#         overlaps_array = d["overlaps"]
+#         norms = d["norms"]
+#         omp_tol = np.finfo(np.float32).eps
+#         num_samples = d["nafter"] + d["nbefore"]
+#         neighbor_window = num_samples - 1
+#         if isinstance(d["amplitudes"], list):
+#             min_amplitude, max_amplitude = d["amplitudes"]
+#         else:
+#             min_amplitude, max_amplitude = d["amplitudes"][:, 0], d["amplitudes"][:, 1]
+#             min_amplitude = min_amplitude[:, np.newaxis]
+#             max_amplitude = max_amplitude[:, np.newaxis]
+#         ignore_inds = d["ignore_inds"]
+#         vicinity = d["vicinity"]
+
+#         num_timesteps = len(traces)
+
+#         num_peaks = num_timesteps - num_samples + 1
+#         conv_shape = (num_templates, num_peaks)
+#         scalar_products = np.zeros(conv_shape, dtype=np.float32)
+
+#         # Filter using overlap-and-add convolution
+#         if len(ignore_inds) > 0:
+#             not_ignored = ~np.isin(np.arange(num_templates), ignore_inds)
+#             spatially_filtered_data = np.matmul(d["spatial"][:, not_ignored, :], traces.T[np.newaxis, :, :])
+#             scaled_filtered_data = spatially_filtered_data * d["singular"][:, not_ignored, :]
+#             objective_by_rank = scipy.signal.oaconvolve(
+#                 scaled_filtered_data, d["temporal"][:, not_ignored, :], axes=2, mode="valid"
+#             )
+#             scalar_products[not_ignored] += np.sum(objective_by_rank, axis=0)
+#             scalar_products[ignore_inds] = -np.inf
+#         else:
+#             spatially_filtered_data = np.matmul(d["spatial"], traces.T[np.newaxis, :, :])
+#             scaled_filtered_data = spatially_filtered_data * d["singular"]
+#             objective_by_rank = scipy.signal.oaconvolve(scaled_filtered_data, d["temporal"], axes=2, mode="valid")
+#             scalar_products += np.sum(objective_by_rank, axis=0)
+
+#         num_spikes = 0
+
+#         spikes = np.empty(scalar_products.size, dtype=spike_dtype)
+
+#         M = np.zeros((num_templates, num_templates), dtype=np.float32)
+
+#         all_selections = np.empty((2, scalar_products.size), dtype=np.int32)
+#         final_amplitudes = np.zeros(scalar_products.shape, dtype=np.float32)
+#         num_selection = 0
+
+#         full_sps = scalar_products.copy()
+
+#         neighbors = {}
+
+#         all_amplitudes = np.zeros(0, dtype=np.float32)
+#         is_in_vicinity = np.zeros(0, dtype=np.int32)
+
+#         if d["stop_criteria"] == "omp_min_sps":
+#             stop_criteria = d["omp_min_sps"] * np.maximum(d["norms"], np.sqrt(num_channels * num_samples))
+#         elif d["stop_criteria"] == "max_failures":
+#             num_valids = 0
+#             nb_failures = d["max_failures"]
+#         elif d["stop_criteria"] == "relative_error":
+#             if len(ignore_inds) > 0:
+#                 new_error = np.linalg.norm(scalar_products[not_ignored])
+#             else:
+#                 new_error = np.linalg.norm(scalar_products)
+#             delta_error = np.inf
+
+#         do_loop = True
+
+#         while do_loop:
+#             best_amplitude_ind = scalar_products.argmax()
+#             best_cluster_ind, peak_index = np.unravel_index(best_amplitude_ind, scalar_products.shape)
+
+#             if num_selection > 0:
+#                 delta_t = selection[1] - peak_index
+#                 idx = np.where((delta_t < num_samples) & (delta_t > -num_samples))[0]
+#                 myline = neighbor_window + delta_t[idx]
+#                 myindices = selection[0, idx]
+
+#                 local_overlaps = overlaps_array[best_cluster_ind]
+#                 overlapping_templates = d["unit_overlaps_indices"][best_cluster_ind]
+#                 table = d["unit_overlaps_tables"][best_cluster_ind]
+
+#                 if num_selection == M.shape[0]:
+#                     Z = np.zeros((2 * num_selection, 2 * num_selection), dtype=np.float32)
+#                     Z[:num_selection, :num_selection] = M
+#                     M = Z
+
+#                 mask = np.isin(myindices, overlapping_templates)
+#                 a, b = myindices[mask], myline[mask]
+#                 M[num_selection, idx[mask]] = local_overlaps[table[a], b]
+
+#                 if vicinity == 0:
+#                     scipy.linalg.solve_triangular(
+#                         M[:num_selection, :num_selection],
+#                         M[num_selection, :num_selection],
+#                         trans=0,
+#                         lower=1,
+#                         overwrite_b=True,
+#                         check_finite=False,
+#                     )
+
+#                     v = nrm2(M[num_selection, :num_selection]) ** 2
+#                     Lkk = 1 - v
+#                     if Lkk <= omp_tol:  # selected atoms are dependent
+#                         break
+#                     M[num_selection, num_selection] = np.sqrt(Lkk)
+#                 else:
+#                     is_in_vicinity = np.where(np.abs(delta_t) < vicinity)[0]
+
+#                     if len(is_in_vicinity) > 0:
+#                         L = M[is_in_vicinity, :][:, is_in_vicinity]
+
+#                         M[num_selection, is_in_vicinity] = scipy.linalg.solve_triangular(
+#                             L, M[num_selection, is_in_vicinity], trans=0, lower=1, overwrite_b=True, check_finite=False
+#                         )
+
+#                         v = nrm2(M[num_selection, is_in_vicinity]) ** 2
+#                         Lkk = 1 - v
+#                         if Lkk <= omp_tol:  # selected atoms are dependent
+#                             break
+#                         M[num_selection, num_selection] = np.sqrt(Lkk)
+#                     else:
+#                         M[num_selection, num_selection] = 1.0
+#             else:
+#                 M[0, 0] = 1
+
+#             all_selections[:, num_selection] = [best_cluster_ind, peak_index]
+#             num_selection += 1
+
+#             selection = all_selections[:, :num_selection]
+#             res_sps = full_sps[selection[0], selection[1]]
+
+#             if vicinity == 0:
+#                 all_amplitudes, _ = potrs(M[:num_selection, :num_selection], res_sps, lower=True, overwrite_b=False)
+#                 all_amplitudes /= norms[selection[0]]
+#             else:
+#                 is_in_vicinity = np.append(is_in_vicinity, num_selection - 1)
+#                 all_amplitudes = np.append(all_amplitudes, np.float32(1))
+#                 L = M[is_in_vicinity, :][:, is_in_vicinity]
+#                 all_amplitudes[is_in_vicinity], _ = potrs(L, res_sps[is_in_vicinity], lower=True, overwrite_b=False)
+#                 all_amplitudes[is_in_vicinity] /= norms[selection[0][is_in_vicinity]]
+
+#             diff_amplitudes = all_amplitudes - final_amplitudes[selection[0], selection[1]]
+#             modified = np.where(np.abs(diff_amplitudes) > omp_tol)[0]
+#             final_amplitudes[selection[0], selection[1]] = all_amplitudes
+
+#             for i in modified:
+#                 tmp_best, tmp_peak = selection[:, i]
+#                 diff_amp = diff_amplitudes[i] * norms[tmp_best]
+
+#                 local_overlaps = overlaps_array[tmp_best]
+#                 overlapping_templates = d["units_overlaps"][tmp_best]
+
+#                 if not tmp_peak in neighbors.keys():
+#                     idx = [max(0, tmp_peak - neighbor_window), min(num_peaks, tmp_peak + num_samples)]
+#                     tdx = [neighbor_window + idx[0] - tmp_peak, num_samples + idx[1] - tmp_peak - 1]
+#                     neighbors[tmp_peak] = {"idx": idx, "tdx": tdx}
+
+#                 idx = neighbors[tmp_peak]["idx"]
+#                 tdx = neighbors[tmp_peak]["tdx"]
+
+#                 to_add = diff_amp * local_overlaps[:, tdx[0] : tdx[1]]
+#                 scalar_products[overlapping_templates, idx[0] : idx[1]] -= to_add
+
+#             # We stop when updates do not modify the chosen spikes anymore
+#             if d["stop_criteria"] == "omp_min_sps":
+#                 is_valid = scalar_products > stop_criteria[:, np.newaxis]
+#                 do_loop = np.any(is_valid)
+#             elif d["stop_criteria"] == "max_failures":
+#                 is_valid = (final_amplitudes > min_amplitude) * (final_amplitudes < max_amplitude)
+#                 new_num_valids = np.sum(is_valid)
+#                 if (new_num_valids - num_valids) > 0:
+#                     nb_failures = d["max_failures"]
+#                 else:
+#                     nb_failures -= 1
+#                 num_valids = new_num_valids
+#                 do_loop = nb_failures > 0
+#             elif d["stop_criteria"] == "relative_error":
+#                 previous_error = new_error
+#                 if len(ignore_inds) > 0:
+#                     new_error = np.linalg.norm(scalar_products[not_ignored])
+#                 else:
+#                     new_error = np.linalg.norm(scalar_products)
+#                 delta_error = np.abs(new_error / previous_error - 1)
+#                 do_loop = delta_error > d["relative_error"]
+
+#         is_valid = (final_amplitudes > min_amplitude) * (final_amplitudes < max_amplitude)
+#         valid_indices = np.where(is_valid)
+
+#         num_spikes = len(valid_indices[0])
+#         spikes["sample_index"][:num_spikes] = valid_indices[1] + d["nbefore"]
+#         spikes["channel_index"][:num_spikes] = 0
+#         spikes["cluster_index"][:num_spikes] = valid_indices[0]
+#         spikes["amplitude"][:num_spikes] = final_amplitudes[valid_indices[0], valid_indices[1]]
+
+#         spikes = spikes[:num_spikes]
+#         order = np.argsort(spikes["sample_index"])
+#         spikes = spikes[order]
+
+#         return spikes
+
+
+class CircusPeeler(BaseTemplateMatching):
     """
     Greedy Template-matching ported from the Spyking Circus sorter
 
@@ -518,226 +886,130 @@ class CircusPeeler(BaseTemplateMatchingEngine):
 
 
     """
+    def __init__(self, recording, return_output=True, parents=None,
+  
+            templates=None,
+            peak_sign="neg",
+            exclude_sweep_ms=0.1,
+            jitter_ms=0.1,
+            detect_threshold=5,
+            noise_levels=None,
+            random_chunk_kwargs={},
+            max_amplitude=1.5,
+            min_amplitude=0.5,
+            use_sparse_matrix_threshold=0.25,
+        ):
+
+        BaseTemplateMatching.__init__(self, recording, templates, return_output=True, parents=None)
 
-    _default_params = {
-        "peak_sign": "neg",
-        "exclude_sweep_ms": 0.1,
-        "jitter_ms": 0.1,
-        "detect_threshold": 5,
-        "noise_levels": None,
-        "random_chunk_kwargs": {},
-        "max_amplitude": 1.5,
-        "min_amplitude": 0.5,
-        "use_sparse_matrix_threshold": 0.25,
-        "templates": None,
-    }
-
-    @classmethod
-    def _prepare_templates(cls, d):
-        import scipy.spatial
-        import scipy
+        try:
+            from sklearn.feature_extraction.image import extract_patches_2d
 
-        templates = d["templates"]
-        num_samples = d["num_samples"]
-        num_channels = d["num_channels"]
-        num_templates = d["num_templates"]
-        use_sparse_matrix_threshold = d["use_sparse_matrix_threshold"]
+            HAVE_SKLEARN = True
+        except ImportError:
+            HAVE_SKLEARN = False
 
-        d["norms"] = np.zeros(num_templates, dtype=np.float32)
+        assert HAVE_SKLEARN, "CircusPeeler needs sklearn to work"
 
-        all_units = d["templates"].unit_ids
+        assert (use_sparse_matrix_threshold >= 0) and (use_sparse_matrix_threshold <= 1), f"use_sparse_matrix_threshold should be in [0, 1]"
 
-        sparsity = templates.sparsity.mask
+        self.num_channels = recording.get_num_channels()
+        self.num_samples = templates.num_samples
+        self.num_templates = len(templates.unit_ids)
 
-        templates_array = templates.get_dense_templates()
-        d["sparsities"] = {}
-        d["normed_templates"] = {}
+        if noise_levels is None:
+            print("CircusPeeler : noise should be computed outside")
+            noise_levels = get_noise_levels(recording, **d["random_chunk_kwargs"], return_scaled=False)
 
-        for count, unit_id in enumerate(all_units):
-            (d["sparsities"][count],) = np.nonzero(sparsity[count])
-            d["norms"][count] = np.linalg.norm(templates_array[count])
-            templates_array[count] /= d["norms"][count]
-            d["normed_templates"][count] = templates_array[count][:, sparsity[count]]
+        self.abs_threholds = noise_levels * detect_threshold
 
-        templates_array = templates_array.reshape(num_templates, -1)
 
-        nnz = np.sum(templates_array != 0) / (num_templates * num_samples * num_channels)
-        if nnz <= use_sparse_matrix_threshold:
-            templates_array = scipy.sparse.csr_matrix(templates_array)
-            print(f"Templates are automatically sparsified (sparsity level is {nnz})")
-            d["is_dense"] = False
-        else:
-            d["is_dense"] = True
-
-        d["circus_templates"] = templates_array
-
-        return d
-
-    # @classmethod
-    # def _mcc_error(cls, bounds, good, bad):
-    #     fn = np.sum((good < bounds[0]) | (good > bounds[1]))
-    #     fp = np.sum((bounds[0] <= bad) & (bad <= bounds[1]))
-    #     tp = np.sum((bounds[0] <= good) & (good <= bounds[1]))
-    #     tn = np.sum((bad < bounds[0]) | (bad > bounds[1]))
-    #     denom = (tp + fp) * (tp + fn) * (tn + fp) * (tn + fn)
-    #     if denom > 0:
-    #         mcc = 1 - (tp * tn - fp * fn) / np.sqrt(denom)
-    #     else:
-    #         mcc = 1
-    #     return mcc
-
-    # @classmethod
-    # def _cost_function_mcc(cls, bounds, good, bad, delta_amplitude, alpha):
-    #     # We want a minimal error, with the larger bounds that are possible
-    #     cost = alpha * cls._mcc_error(bounds, good, bad) + (1 - alpha) * np.abs(
-    #         (1 - (bounds[1] - bounds[0]) / delta_amplitude)
-    #     )
-    #     return cost
-
-    # @classmethod
-    # def _optimize_amplitudes(cls, noise_snippets, d):
-    #     parameters = d
-    #     waveform_extractor = parameters["waveform_extractor"]
-    #     templates = parameters["templates"]
-    #     num_templates = parameters["num_templates"]
-    #     max_amplitude = parameters["max_amplitude"]
-    #     min_amplitude = parameters["min_amplitude"]
-    #     alpha = 0.5
-    #     norms = parameters["norms"]
-    #     all_units = list(waveform_extractor.sorting.unit_ids)
-
-    #     parameters["amplitudes"] = np.zeros((num_templates, 2), dtype=np.float32)
-    #     noise = templates.dot(noise_snippets) / norms[:, np.newaxis]
-
-    #     all_amps = {}
-    #     for count, unit_id in enumerate(all_units):
-    #         waveform = waveform_extractor.get_waveforms(unit_id, force_dense=True)
-    #         snippets = waveform.reshape(waveform.shape[0], -1).T
-    #         amps = templates.dot(snippets) / norms[:, np.newaxis]
-    #         good = amps[count, :].flatten()
-
-    #         sub_amps = amps[np.concatenate((np.arange(count), np.arange(count + 1, num_templates))), :]
-    #         bad = sub_amps[sub_amps >= good]
-    #         bad = np.concatenate((bad, noise[count]))
-    #         cost_kwargs = [good, bad, max_amplitude - min_amplitude, alpha]
-    #         cost_bounds = [(min_amplitude, 1), (1, max_amplitude)]
-    #         res = scipy.optimize.differential_evolution(cls._cost_function_mcc, bounds=cost_bounds, args=cost_kwargs)
-    #         parameters["amplitudes"][count] = res.x
-
-    #     return d
-
-    @classmethod
-    def initialize_and_check_kwargs(cls, recording, kwargs):
-        try:
-            from sklearn.feature_extraction.image import extract_patches_2d
+        #if "overlaps" not in d:
+        #     d = self._prepare_templates()
+        #     d["overlaps"] = compute_overlaps(
+        #         d["normed_templates"],
+        #         d["num_samples"],
+        #         d["num_channels"],
+        #         d["sparsities"],
+        #     )
+        # else:
+        #     for key in ["circus_templates", "norms"]:
+        #         assert d[key] is not None, "If templates are provided, %d should also be there" % key
+        self.use_sparse_matrix_threshold = use_sparse_matrix_threshold
+        self._prepare_templates()
+        self.overlaps = compute_overlaps(
+            self.normed_templates,
+            self.num_samples,
+            self.num_channels,
+            self.sparsities,
+        )
 
-            HAVE_SKLEARN = True
-        except ImportError:
-            HAVE_SKLEARN = False
+        self.exclude_sweep_size = int(exclude_sweep_ms * recording.get_sampling_frequency() / 1000.0)
 
-        assert HAVE_SKLEARN, "CircusPeeler needs sklearn to work"
-        d = cls._default_params.copy()
-        d.update(kwargs)
+        self.nbefore = templates.nbefore
+        self.nafter = templates.nafter
+        self.patch_sizes = (templates.num_samples, self.num_channels)
+        self.sym_patch = self.nbefore == self.nafter
+        self.jitter = int(jitter_ms * recording.get_sampling_frequency() / 1000.0)
 
-        # assert isinstance(d['waveform_extractor'], WaveformExtractor)
-        for v in ["use_sparse_matrix_threshold"]:
-            assert (d[v] >= 0) and (d[v] <= 1), f"{v} should be in [0, 1]"
+        self.amplitudes = np.zeros((self.num_templates, 2), dtype=np.float32)
+        self.amplitudes[:, 0] = min_amplitude
+        self.amplitudes[:, 1] = max_amplitude
 
-        d["num_channels"] = recording.get_num_channels()
-        d["num_samples"] = d["templates"].num_samples
-        d["num_templates"] = len(d["templates"].unit_ids)
+        self.margin = max(self.nbefore, self.nafter) * 2
+        self.peak_sign = peak_sign
 
-        if d["noise_levels"] is None:
-            print("CircusPeeler : noise should be computed outside")
-            d["noise_levels"] = get_noise_levels(recording, **d["random_chunk_kwargs"], return_scaled=False)
 
-        d["abs_threholds"] = d["noise_levels"] * d["detect_threshold"]
 
-        if "overlaps" not in d:
-            d = cls._prepare_templates(d)
-            d["overlaps"] = compute_overlaps(
-                d["normed_templates"],
-                d["num_samples"],
-                d["num_channels"],
-                d["sparsities"],
-            )
+    def _prepare_templates(self):
+        import scipy.spatial
+        import scipy
+
+        self.norms = np.zeros(self.num_templates, dtype=np.float32)
+
+        all_units = self.templates.unit_ids
+
+        sparsity = self.templates.sparsity.mask
+
+        templates_array = self.templates.get_dense_templates()
+        self.sparsities = {}
+        self.normed_templates = {}
+
+        for count, unit_id in enumerate(all_units):
+            self.sparsities[count] = np.flatnonzero(sparsity[count])
+            self.norms[count] = np.linalg.norm(templates_array[count])
+            templates_array[count] /= self.norms[count]
+            self.normed_templates[count] = templates_array[count][:, sparsity[count]]
+
+        templates_array = templates_array.reshape(self.num_templates, -1)
+
+        nnz = np.sum(templates_array != 0) / (self.num_templates * self.num_samples * self.num_channels)
+        if nnz <= self.use_sparse_matrix_threshold:
+            templates_array = scipy.sparse.csr_matrix(templates_array)
+            print(f"Templates are automatically sparsified (sparsity level is {nnz})")
+            self.is_dense = False
         else:
-            for key in ["circus_templates", "norms"]:
-                assert d[key] is not None, "If templates are provided, %d should also be there" % key
+            self.is_dense = True
 
-        d["exclude_sweep_size"] = int(d["exclude_sweep_ms"] * recording.get_sampling_frequency() / 1000.0)
+        self.circus_templates = templates_array
 
-        d["nbefore"] = d["templates"].nbefore
-        d["nafter"] = d["templates"].nafter
-        d["patch_sizes"] = (
-            d["templates"].num_samples,
-            d["num_channels"],
-        )
-        d["sym_patch"] = d["nbefore"] == d["nafter"]
-        d["jitter"] = int(d["jitter_ms"] * recording.get_sampling_frequency() / 1000.0)
-
-        d["amplitudes"] = np.zeros((d["num_templates"], 2), dtype=np.float32)
-        d["amplitudes"][:, 0] = d["min_amplitude"]
-        d["amplitudes"][:, 1] = d["max_amplitude"]
-        # num_segments = recording.get_num_segments()
-        # if d["waveform_extractor"]._params["max_spikes_per_unit"] is None:
-        #     num_snippets = 1000
-        # else:
-        #     num_snippets = 2 * d["waveform_extractor"]._params["max_spikes_per_unit"]
-
-        # num_chunks = num_snippets // num_segments
-        # noise_snippets = get_random_data_chunks(
-        #     recording, num_chunks_per_segment=num_chunks, chunk_size=d["num_samples"], seed=42
-        # )
-        # noise_snippets = (
-        #     noise_snippets.reshape(num_chunks, d["num_samples"], d["num_channels"])
-        #     .reshape(num_chunks, -1)
-        #     .T
-        # )
-        # parameters = cls._optimize_amplitudes(noise_snippets, d)
-
-        return d
-
-    @classmethod
-    def serialize_method_kwargs(cls, kwargs):
-        kwargs = dict(kwargs)
-        return kwargs
-
-    @classmethod
-    def unserialize_in_worker(cls, kwargs):
-        return kwargs
-
-    @classmethod
-    def get_margin(cls, recording, kwargs):
-        margin = 2 * max(kwargs["nbefore"], kwargs["nafter"])
-        return margin
-
-    @classmethod
-    def main_function(cls, traces, d):
-        peak_sign = d["peak_sign"]
-        abs_threholds = d["abs_threholds"]
-        exclude_sweep_size = d["exclude_sweep_size"]
-        templates = d["circus_templates"]
-        num_templates = d["num_templates"]
-        overlaps = d["overlaps"]
-        margin = d["margin"]
-        norms = d["norms"]
-        jitter = d["jitter"]
-        patch_sizes = d["patch_sizes"]
-        num_samples = d["nafter"] + d["nbefore"]
-        neighbor_window = num_samples - 1
-        amplitudes = d["amplitudes"]
-        sym_patch = d["sym_patch"]
+    def get_trace_margin(self):
+        return self.margin
 
-        peak_traces = traces[margin // 2 : -margin // 2, :]
+
+    def compute(self, traces, start_frame, end_frame, segment_index, max_margin, *args):
+
+        neighbor_window = self.num_samples - 1
+
+        peak_traces = traces[self.margin // 2 : -self.margin // 2, :]
         peak_sample_index, peak_chan_ind = DetectPeakByChannel.detect_peaks(
-            peak_traces, peak_sign, abs_threholds, exclude_sweep_size
+            peak_traces, self.peak_sign, self.abs_threholds, self.exclude_sweep_size
         )
         from sklearn.feature_extraction.image import extract_patches_2d
 
-        if jitter > 0:
-            jittered_peaks = peak_sample_index[:, np.newaxis] + np.arange(-jitter, jitter)
-            jittered_channels = peak_chan_ind[:, np.newaxis] + np.zeros(2 * jitter)
+        if self.jitter > 0:
+            jittered_peaks = peak_sample_index[:, np.newaxis] + np.arange(-self.jitter, self.jitter)
+            jittered_channels = peak_chan_ind[:, np.newaxis] + np.zeros(2 * self.jitter)
             mask = (jittered_peaks > 0) & (jittered_peaks < len(peak_traces))
             jittered_peaks = jittered_peaks[mask]
             jittered_channels = jittered_channels[mask]
@@ -749,26 +1021,26 @@ def main_function(cls, traces, d):
 
         num_peaks = len(peak_sample_index)
 
-        if sym_patch:
-            snippets = extract_patches_2d(traces, patch_sizes)[peak_sample_index]
-            peak_sample_index += margin // 2
+        if self.sym_patch:
+            snippets = extract_patches_2d(traces, self.patch_sizes)[peak_sample_index]
+            peak_sample_index += self.margin // 2
         else:
-            peak_sample_index += margin // 2
-            snippet_window = np.arange(-d["nbefore"], d["nafter"])
+            peak_sample_index += self.margin // 2
+            snippet_window = np.arange(-self.nbefore, self.nafter)
             snippets = traces[peak_sample_index[:, np.newaxis] + snippet_window]
 
         if num_peaks > 0:
             snippets = snippets.reshape(num_peaks, -1)
-            scalar_products = templates.dot(snippets.T)
+            scalar_products = self.circus_templates.dot(snippets.T)
         else:
-            scalar_products = np.zeros((num_templates, 0), dtype=np.float32)
+            scalar_products = np.zeros((self.num_templates, 0), dtype=np.float32)
 
         num_spikes = 0
         spikes = np.empty(scalar_products.size, dtype=spike_dtype)
-        idx_lookup = np.arange(scalar_products.size).reshape(num_templates, -1)
+        idx_lookup = np.arange(scalar_products.size).reshape(self.num_templates, -1)
 
-        min_sps = (amplitudes[:, 0] * norms)[:, np.newaxis]
-        max_sps = (amplitudes[:, 1] * norms)[:, np.newaxis]
+        min_sps = (self.amplitudes[:, 0] * self.norms)[:, np.newaxis]
+        max_sps = (self.amplitudes[:, 1] * self.norms)[:, np.newaxis]
 
         is_valid = (scalar_products > min_sps) & (scalar_products < max_sps)
 
@@ -787,7 +1059,7 @@ def main_function(cls, traces, d):
             idx_neighbor = peak_data[is_valid_nn[0] : is_valid_nn[1]] + neighbor_window
 
             if not best_cluster_ind in cached_overlaps.keys():
-                cached_overlaps[best_cluster_ind] = overlaps[best_cluster_ind].toarray()
+                cached_overlaps[best_cluster_ind] = self.overlaps[best_cluster_ind].toarray()
 
             to_add = -best_amplitude * cached_overlaps[best_cluster_ind][:, idx_neighbor]
 
@@ -802,10 +1074,349 @@ def main_function(cls, traces, d):
 
             is_valid = (scalar_products > min_sps) & (scalar_products < max_sps)
 
-        spikes["amplitude"][:num_spikes] /= norms[spikes["cluster_index"][:num_spikes]]
+        spikes["amplitude"][:num_spikes] /= self.norms[spikes["cluster_index"][:num_spikes]]
 
         spikes = spikes[:num_spikes]
         order = np.argsort(spikes["sample_index"])
         spikes = spikes[order]
 
         return spikes
+
+
+
+# class CircusPeeler(BaseTemplateMatchingEngine):
+#     """
+#     Greedy Template-matching ported from the Spyking Circus sorter
+
+#     https://elifesciences.org/articles/34518
+
+#     This is a Greedy Template Matching algorithm. The idea is to detect
+#     all the peaks (negative, positive or both) above a certain threshold
+#     Then, at every peak (plus or minus some jitter) we look if the signal
+#     can be explained with a scaled template.
+#     The amplitudes allowed, for every templates, are automatically adjusted
+#     in an optimal manner, to enhance the Matthew Correlation Coefficient
+#     between all spikes/templates in the waveformextractor. For speed and
+#     memory optimization, templates are automatically sparsified if the
+#     density of the matrix falls below a given threshold
+
+#     Parameters
+#     ----------
+#     peak_sign: str
+#         Sign of the peak (neg, pos, or both)
+#     exclude_sweep_ms: float
+#         The number of samples before/after to classify a peak (should be low)
+#     jitter: int
+#         The number of samples considered before/after every peak to search for
+#         matches
+#     detect_threshold: int
+#         The detection threshold
+#     noise_levels: array
+#         The noise levels, for every channels
+#     random_chunk_kwargs: dict
+#         Parameters for computing noise levels, if not provided (sub optimal)
+#     max_amplitude: float
+#         Maximal amplitude allowed for every template
+#     min_amplitude: float
+#         Minimal amplitude allowed for every template
+#     use_sparse_matrix_threshold: float
+#         If density of the templates is below a given threshold, sparse matrix
+#         are used (memory efficient)
+#     sparse_kwargs: dict
+#         Parameters to extract a sparsity mask from the waveform_extractor, if not
+#         already sparse.
+#     -----
+
+
+#     """
+
+#     _default_params = {
+#         "peak_sign": "neg",
+#         "exclude_sweep_ms": 0.1,
+#         "jitter_ms": 0.1,
+#         "detect_threshold": 5,
+#         "noise_levels": None,
+#         "random_chunk_kwargs": {},
+#         "max_amplitude": 1.5,
+#         "min_amplitude": 0.5,
+#         "use_sparse_matrix_threshold": 0.25,
+#         "templates": None,
+#     }
+
+#     @classmethod
+#     def _prepare_templates(cls, d):
+#         import scipy.spatial
+#         import scipy
+
+#         templates = d["templates"]
+#         num_samples = d["num_samples"]
+#         num_channels = d["num_channels"]
+#         num_templates = d["num_templates"]
+#         use_sparse_matrix_threshold = d["use_sparse_matrix_threshold"]
+
+#         d["norms"] = np.zeros(num_templates, dtype=np.float32)
+
+#         all_units = d["templates"].unit_ids
+
+#         sparsity = templates.sparsity.mask
+
+#         templates_array = templates.get_dense_templates()
+#         d["sparsities"] = {}
+#         d["normed_templates"] = {}
+
+#         for count, unit_id in enumerate(all_units):
+#             (d["sparsities"][count],) = np.nonzero(sparsity[count])
+#             d["norms"][count] = np.linalg.norm(templates_array[count])
+#             templates_array[count] /= d["norms"][count]
+#             d["normed_templates"][count] = templates_array[count][:, sparsity[count]]
+
+#         templates_array = templates_array.reshape(num_templates, -1)
+
+#         nnz = np.sum(templates_array != 0) / (num_templates * num_samples * num_channels)
+#         if nnz <= use_sparse_matrix_threshold:
+#             templates_array = scipy.sparse.csr_matrix(templates_array)
+#             print(f"Templates are automatically sparsified (sparsity level is {nnz})")
+#             d["is_dense"] = False
+#         else:
+#             d["is_dense"] = True
+
+#         d["circus_templates"] = templates_array
+
+#         return d
+
+#     # @classmethod
+#     # def _mcc_error(cls, bounds, good, bad):
+#     #     fn = np.sum((good < bounds[0]) | (good > bounds[1]))
+#     #     fp = np.sum((bounds[0] <= bad) & (bad <= bounds[1]))
+#     #     tp = np.sum((bounds[0] <= good) & (good <= bounds[1]))
+#     #     tn = np.sum((bad < bounds[0]) | (bad > bounds[1]))
+#     #     denom = (tp + fp) * (tp + fn) * (tn + fp) * (tn + fn)
+#     #     if denom > 0:
+#     #         mcc = 1 - (tp * tn - fp * fn) / np.sqrt(denom)
+#     #     else:
+#     #         mcc = 1
+#     #     return mcc
+
+#     # @classmethod
+#     # def _cost_function_mcc(cls, bounds, good, bad, delta_amplitude, alpha):
+#     #     # We want a minimal error, with the larger bounds that are possible
+#     #     cost = alpha * cls._mcc_error(bounds, good, bad) + (1 - alpha) * np.abs(
+#     #         (1 - (bounds[1] - bounds[0]) / delta_amplitude)
+#     #     )
+#     #     return cost
+
+#     # @classmethod
+#     # def _optimize_amplitudes(cls, noise_snippets, d):
+#     #     parameters = d
+#     #     waveform_extractor = parameters["waveform_extractor"]
+#     #     templates = parameters["templates"]
+#     #     num_templates = parameters["num_templates"]
+#     #     max_amplitude = parameters["max_amplitude"]
+#     #     min_amplitude = parameters["min_amplitude"]
+#     #     alpha = 0.5
+#     #     norms = parameters["norms"]
+#     #     all_units = list(waveform_extractor.sorting.unit_ids)
+
+#     #     parameters["amplitudes"] = np.zeros((num_templates, 2), dtype=np.float32)
+#     #     noise = templates.dot(noise_snippets) / norms[:, np.newaxis]
+
+#     #     all_amps = {}
+#     #     for count, unit_id in enumerate(all_units):
+#     #         waveform = waveform_extractor.get_waveforms(unit_id, force_dense=True)
+#     #         snippets = waveform.reshape(waveform.shape[0], -1).T
+#     #         amps = templates.dot(snippets) / norms[:, np.newaxis]
+#     #         good = amps[count, :].flatten()
+
+#     #         sub_amps = amps[np.concatenate((np.arange(count), np.arange(count + 1, num_templates))), :]
+#     #         bad = sub_amps[sub_amps >= good]
+#     #         bad = np.concatenate((bad, noise[count]))
+#     #         cost_kwargs = [good, bad, max_amplitude - min_amplitude, alpha]
+#     #         cost_bounds = [(min_amplitude, 1), (1, max_amplitude)]
+#     #         res = scipy.optimize.differential_evolution(cls._cost_function_mcc, bounds=cost_bounds, args=cost_kwargs)
+#     #         parameters["amplitudes"][count] = res.x
+
+#     #     return d
+
+#     @classmethod
+#     def initialize_and_check_kwargs(cls, recording, kwargs):
+#         try:
+#             from sklearn.feature_extraction.image import extract_patches_2d
+
+#             HAVE_SKLEARN = True
+#         except ImportError:
+#             HAVE_SKLEARN = False
+
+#         assert HAVE_SKLEARN, "CircusPeeler needs sklearn to work"
+#         d = cls._default_params.copy()
+#         d.update(kwargs)
+
+#         # assert isinstance(d['waveform_extractor'], WaveformExtractor)
+#         for v in ["use_sparse_matrix_threshold"]:
+#             assert (d[v] >= 0) and (d[v] <= 1), f"{v} should be in [0, 1]"
+
+#         d["num_channels"] = recording.get_num_channels()
+#         d["num_samples"] = d["templates"].num_samples
+#         d["num_templates"] = len(d["templates"].unit_ids)
+
+#         if d["noise_levels"] is None:
+#             print("CircusPeeler : noise should be computed outside")
+#             d["noise_levels"] = get_noise_levels(recording, **d["random_chunk_kwargs"], return_scaled=False)
+
+#         d["abs_threholds"] = d["noise_levels"] * d["detect_threshold"]
+
+#         if "overlaps" not in d:
+#             d = cls._prepare_templates(d)
+#             d["overlaps"] = compute_overlaps(
+#                 d["normed_templates"],
+#                 d["num_samples"],
+#                 d["num_channels"],
+#                 d["sparsities"],
+#             )
+#         else:
+#             for key in ["circus_templates", "norms"]:
+#                 assert d[key] is not None, "If templates are provided, %d should also be there" % key
+
+#         d["exclude_sweep_size"] = int(d["exclude_sweep_ms"] * recording.get_sampling_frequency() / 1000.0)
+
+#         d["nbefore"] = d["templates"].nbefore
+#         d["nafter"] = d["templates"].nafter
+#         d["patch_sizes"] = (
+#             d["templates"].num_samples,
+#             d["num_channels"],
+#         )
+#         d["sym_patch"] = d["nbefore"] == d["nafter"]
+#         d["jitter"] = int(d["jitter_ms"] * recording.get_sampling_frequency() / 1000.0)
+
+#         d["amplitudes"] = np.zeros((d["num_templates"], 2), dtype=np.float32)
+#         d["amplitudes"][:, 0] = d["min_amplitude"]
+#         d["amplitudes"][:, 1] = d["max_amplitude"]
+#         # num_segments = recording.get_num_segments()
+#         # if d["waveform_extractor"]._params["max_spikes_per_unit"] is None:
+#         #     num_snippets = 1000
+#         # else:
+#         #     num_snippets = 2 * d["waveform_extractor"]._params["max_spikes_per_unit"]
+
+#         # num_chunks = num_snippets // num_segments
+#         # noise_snippets = get_random_data_chunks(
+#         #     recording, num_chunks_per_segment=num_chunks, chunk_size=d["num_samples"], seed=42
+#         # )
+#         # noise_snippets = (
+#         #     noise_snippets.reshape(num_chunks, d["num_samples"], d["num_channels"])
+#         #     .reshape(num_chunks, -1)
+#         #     .T
+#         # )
+#         # parameters = cls._optimize_amplitudes(noise_snippets, d)
+
+#         return d
+
+#     @classmethod
+#     def serialize_method_kwargs(cls, kwargs):
+#         kwargs = dict(kwargs)
+#         return kwargs
+
+#     @classmethod
+#     def unserialize_in_worker(cls, kwargs):
+#         return kwargs
+
+#     @classmethod
+#     def get_margin(cls, recording, kwargs):
+#         margin = 2 * max(kwargs["nbefore"], kwargs["nafter"])
+#         return margin
+
+#     @classmethod
+#     def main_function(cls, traces, d):
+#         peak_sign = d["peak_sign"]
+#         abs_threholds = d["abs_threholds"]
+#         exclude_sweep_size = d["exclude_sweep_size"]
+#         templates = d["circus_templates"]
+#         num_templates = d["num_templates"]
+#         overlaps = d["overlaps"]
+#         margin = d["margin"]
+#         norms = d["norms"]
+#         jitter = d["jitter"]
+#         patch_sizes = d["patch_sizes"]
+#         num_samples = d["nafter"] + d["nbefore"]
+#         neighbor_window = num_samples - 1
+#         amplitudes = d["amplitudes"]
+#         sym_patch = d["sym_patch"]
+
+#         peak_traces = traces[margin // 2 : -margin // 2, :]
+#         peak_sample_index, peak_chan_ind = DetectPeakByChannel.detect_peaks(
+#             peak_traces, peak_sign, abs_threholds, exclude_sweep_size
+#         )
+#         from sklearn.feature_extraction.image import extract_patches_2d
+
+#         if jitter > 0:
+#             jittered_peaks = peak_sample_index[:, np.newaxis] + np.arange(-jitter, jitter)
+#             jittered_channels = peak_chan_ind[:, np.newaxis] + np.zeros(2 * jitter)
+#             mask = (jittered_peaks > 0) & (jittered_peaks < len(peak_traces))
+#             jittered_peaks = jittered_peaks[mask]
+#             jittered_channels = jittered_channels[mask]
+#             peak_sample_index, unique_idx = np.unique(jittered_peaks, return_index=True)
+#             peak_chan_ind = jittered_channels[unique_idx]
+#         else:
+#             peak_sample_index, unique_idx = np.unique(peak_sample_index, return_index=True)
+#             peak_chan_ind = peak_chan_ind[unique_idx]
+
+#         num_peaks = len(peak_sample_index)
+
+#         if sym_patch:
+#             snippets = extract_patches_2d(traces, patch_sizes)[peak_sample_index]
+#             peak_sample_index += margin // 2
+#         else:
+#             peak_sample_index += margin // 2
+#             snippet_window = np.arange(-d["nbefore"], d["nafter"])
+#             snippets = traces[peak_sample_index[:, np.newaxis] + snippet_window]
+
+#         if num_peaks > 0:
+#             snippets = snippets.reshape(num_peaks, -1)
+#             scalar_products = templates.dot(snippets.T)
+#         else:
+#             scalar_products = np.zeros((num_templates, 0), dtype=np.float32)
+
+#         num_spikes = 0
+#         spikes = np.empty(scalar_products.size, dtype=spike_dtype)
+#         idx_lookup = np.arange(scalar_products.size).reshape(num_templates, -1)
+
+#         min_sps = (amplitudes[:, 0] * norms)[:, np.newaxis]
+#         max_sps = (amplitudes[:, 1] * norms)[:, np.newaxis]
+
+#         is_valid = (scalar_products > min_sps) & (scalar_products < max_sps)
+
+#         cached_overlaps = {}
+
+#         while np.any(is_valid):
+#             best_amplitude_ind = scalar_products[is_valid].argmax()
+#             best_cluster_ind, peak_index = np.unravel_index(idx_lookup[is_valid][best_amplitude_ind], idx_lookup.shape)
+
+#             best_amplitude = scalar_products[best_cluster_ind, peak_index]
+#             best_peak_sample_index = peak_sample_index[peak_index]
+#             best_peak_chan_ind = peak_chan_ind[peak_index]
+
+#             peak_data = peak_sample_index - peak_sample_index[peak_index]
+#             is_valid_nn = np.searchsorted(peak_data, [-neighbor_window, neighbor_window + 1])
+#             idx_neighbor = peak_data[is_valid_nn[0] : is_valid_nn[1]] + neighbor_window
+
+#             if not best_cluster_ind in cached_overlaps.keys():
+#                 cached_overlaps[best_cluster_ind] = overlaps[best_cluster_ind].toarray()
+
+#             to_add = -best_amplitude * cached_overlaps[best_cluster_ind][:, idx_neighbor]
+
+#             scalar_products[:, is_valid_nn[0] : is_valid_nn[1]] += to_add
+#             scalar_products[best_cluster_ind, is_valid_nn[0] : is_valid_nn[1]] = -np.inf
+
+#             spikes["sample_index"][num_spikes] = best_peak_sample_index
+#             spikes["channel_index"][num_spikes] = best_peak_chan_ind
+#             spikes["cluster_index"][num_spikes] = best_cluster_ind
+#             spikes["amplitude"][num_spikes] = best_amplitude
+#             num_spikes += 1
+
+#             is_valid = (scalar_products > min_sps) & (scalar_products < max_sps)
+
+#         spikes["amplitude"][:num_spikes] /= norms[spikes["cluster_index"][:num_spikes]]
+
+#         spikes = spikes[:num_spikes]
+#         order = np.argsort(spikes["sample_index"])
+#         spikes = spikes[order]
+
+#         return spikes
diff --git a/src/spikeinterface/sortingcomponents/matching/method_list.py b/src/spikeinterface/sortingcomponents/matching/method_list.py
index 27a132c287..8cb44b09b7 100644
--- a/src/spikeinterface/sortingcomponents/matching/method_list.py
+++ b/src/spikeinterface/sortingcomponents/matching/method_list.py
@@ -1,14 +1,14 @@
 from __future__ import annotations
 
 from .naive import NaiveMatching
-# from .tdc import TridesclousPeeler
-# from .circus import CircusPeeler, CircusOMPSVDPeeler
+from .tdc import TridesclousPeeler
+from .circus import CircusPeeler, CircusOMPSVDPeeler
 # from .wobble import WobbleMatch
 
 matching_methods = {
     "naive": NaiveMatching,
     "tdc-peeler": TridesclousPeeler,
-    # "circus": CircusPeeler,
-    # "circus-omp-svd": CircusOMPSVDPeeler,
+    "circus": CircusPeeler,
+    "circus-omp-svd": CircusOMPSVDPeeler,
     # "wobble": WobbleMatch,
 }
diff --git a/src/spikeinterface/sortingcomponents/matching/tdc.py b/src/spikeinterface/sortingcomponents/matching/tdc.py
index 2698d76828..c43808c2a7 100644
--- a/src/spikeinterface/sortingcomponents/matching/tdc.py
+++ b/src/spikeinterface/sortingcomponents/matching/tdc.py
@@ -48,6 +48,7 @@ class TridesclousPeeler(BaseTemplateMatching):
     """
     def __init__(self, recording, return_output=True, parents=None,
         templates=None,
+        peak_sign="neg",
         peak_shift_ms=0.2,
         detect_threshold=5,
         noise_levels=None,
@@ -73,9 +74,10 @@ def __init__(self, recording, return_output=True, parents=None,
         self.nbefore = templates.nbefore
         self.nafter = templates.nafter
         
+        self.peak_sign = peak_sign
 
         nbefore_short = int(ms_before * sr / 1000.0)
-        nafter_short = int(ms_before * sr / 1000.0)
+        nafter_short = int(ms_after * sr / 1000.0)
         assert nbefore_short <= templates.nbefore
         assert nafter_short <= templates.nafter
         self.nbefore_short = nbefore_short
@@ -96,31 +98,20 @@ def __init__(self, recording, return_output=True, parents=None,
         channel_distance = get_channel_distances(recording)
         self.neighbours_mask = channel_distance < radius_um
 
-        sparsity = compute_sparsity(
-            templates, method="best_channels"
-        )  # , peak_sign=d["peak_sign"], threshold=d["detect_threshold"])
-        template_sparsity_inds = sparsity.unit_id_to_channel_indices
-        template_sparsity = np.zeros((unit_ids.size, channel_ids.size), dtype="bool")
-        for unit_index, unit_id in enumerate(unit_ids):
-            chan_inds = template_sparsity_inds[unit_id]
-            template_sparsity[unit_index, chan_inds] = True
-
-        d["template_sparsity"] = template_sparsity
+        if templates.sparsity is not None:
+            self.template_sparsity = templates.sparsity.mask
+        else:
+            self.template_sparsity = np.ones((unit_ids.size, channel_ids.size), dtype=bool)
 
-        extremum_channel = get_template_extremum_channel(templates, peak_sign=d["peak_sign"], outputs="index")
+        extremum_chan = get_template_extremum_channel(templates, peak_sign=peak_sign, outputs="index")
         # as numpy vector
-        extremum_channel = np.array([extremum_channel[unit_id] for unit_id in unit_ids], dtype="int64")
-        d["extremum_channel"] = extremum_channel
+        self.extremum_channel = np.array([extremum_chan[unit_id] for unit_id in unit_ids], dtype="int64")
 
         channel_locations = templates.probe.contact_positions
-
-        # TODO try it with real locaion
-        unit_locations = channel_locations[extremum_channel]
-        # ~ print(unit_locations)
+        unit_locations = channel_locations[self.extremum_channel]
 
         # distance between units
         import scipy
-
         unit_distances = scipy.spatial.distance.cdist(unit_locations, unit_locations, metric="euclidean")
 
         # seach for closet units and unitary discriminant vector
@@ -129,15 +120,15 @@ def __init__(self, recording, return_output=True, parents=None,
             order = np.argsort(unit_distances[unit_ind, :])
             closest_u = np.arange(unit_ids.size)[order].tolist()
             closest_u.remove(unit_ind)
-            closest_u = np.array(closest_u[: d["num_closest"]])
+            closest_u = np.array(closest_u[: num_closest])
 
             # compute unitary discriminent vector
-            (chans,) = np.nonzero(d["template_sparsity"][unit_ind, :])
-            template_sparse = templates_array[unit_ind, :, :][:, chans]
+            (chans,) = np.nonzero(self.template_sparsity[unit_ind, :])
+            template_sparse = self.templates_array[unit_ind, :, :][:, chans]
             closest_vec = []
             # against N closets
             for u in closest_u:
-                vec = templates_array[u, :, :][:, chans] - template_sparse
+                vec = self.templates_array[u, :, :][:, chans] - template_sparse
                 vec /= np.sum(vec**2)
                 closest_vec.append((u, vec))
             # against noise
@@ -145,47 +136,38 @@ def __init__(self, recording, return_output=True, parents=None,
 
             closest_units.append(closest_vec)
 
-        d["closest_units"] = closest_units
+        self.closest_units = closest_units
 
         # distance channel from unit
         import scipy
 
         distances = scipy.spatial.distance.cdist(channel_locations, unit_locations, metric="euclidean")
-        near_cluster_mask = distances < d["radius_um"]
+        near_cluster_mask = distances < radius_um
 
         # nearby cluster for each channel
-        possible_clusters_by_channel = []
+        self.possible_clusters_by_channel = []
         for channel_index in range(distances.shape[0]):
             (cluster_inds,) = np.nonzero(near_cluster_mask[channel_index, :])
-            possible_clusters_by_channel.append(cluster_inds)
+            self.possible_clusters_by_channel.append(cluster_inds)
 
-        d["possible_clusters_by_channel"] = possible_clusters_by_channel
-        d["possible_shifts"] = np.arange(-d["sample_shift"], d["sample_shift"] + 1, dtype="int64")
+        self.possible_shifts = np.arange(-sample_shift, sample_shift + 1, dtype="int64")
 
-        return d
+        self.num_peeler_loop = num_peeler_loop
+        self.num_template_try = num_template_try
 
-    @classmethod
-    def serialize_method_kwargs(cls, kwargs):
-        kwargs = dict(kwargs)
-        return kwargs
+        self.margin = max(self.nbefore, self.nafter) * 2
 
-    @classmethod
-    def unserialize_in_worker(cls, kwargs):
-        return kwargs
+    def get_trace_margin(self):
+        return self.margin
 
-    @classmethod
-    def get_margin(cls, recording, kwargs):
-        margin = 2 * (kwargs["nbefore"] + kwargs["nafter"])
-        return margin
-
-    @classmethod
-    def main_function(cls, traces, d):
+    def compute(self, traces, start_frame, end_frame, segment_index, max_margin, *args):
         traces = traces.copy()
 
         all_spikes = []
         level = 0
         while True:
-            spikes = _tdc_find_spikes(traces, d, level=level)
+            # spikes = _tdc_find_spikes(traces, d, level=level)
+            spikes = self._find_spikes_one_level(traces, level=level)
             keep = spikes["cluster_index"] >= 0
 
             if not np.any(keep):
@@ -194,7 +176,7 @@ def main_function(cls, traces, d):
 
             level += 1
 
-            if level == d["num_peeler_loop"]:
+            if level == self.num_peeler_loop:
                 break
 
         if len(all_spikes) > 0:
@@ -202,10 +184,134 @@ def main_function(cls, traces, d):
             order = np.argsort(all_spikes["sample_index"])
             all_spikes = all_spikes[order]
         else:
-            all_spikes = np.zeros(0, dtype=spike_dtype)
+            all_spikes = np.zeros(0, dtype=_base_matching_dtype)
 
         return all_spikes
 
+    def _find_spikes_one_level(self, traces, level=0):
+
+        peak_traces = traces[self.margin // 2 : -self.margin // 2, :]
+        peak_sample_ind, peak_chan_ind = DetectPeakLocallyExclusive.detect_peaks(
+            peak_traces, self.peak_sign, self.abs_thresholds, self.peak_shift, self.neighbours_mask
+        )
+        peak_sample_ind += self.margin // 2
+
+        peak_amplitude = traces[peak_sample_ind, peak_chan_ind]
+        order = np.argsort(np.abs(peak_amplitude))[::-1]
+        peak_sample_ind = peak_sample_ind[order]
+        peak_chan_ind = peak_chan_ind[order]
+
+        spikes = np.zeros(peak_sample_ind.size, dtype=_base_matching_dtype)
+        spikes["sample_index"] = peak_sample_ind
+        spikes["channel_index"] = peak_chan_ind  # TODO need to put the channel from template
+
+        possible_shifts = self.possible_shifts
+        distances_shift = np.zeros(possible_shifts.size)
+
+        for i in range(peak_sample_ind.size):
+            sample_index = peak_sample_ind[i]
+
+            chan_ind = peak_chan_ind[i]
+            possible_clusters = self.possible_clusters_by_channel[chan_ind]
+
+            if possible_clusters.size > 0:
+                # ~ s0 = sample_index - d['nbefore']
+                # ~ s1 = sample_index + d['nafter']
+
+                # ~ wf = traces[s0:s1, :]
+
+                s0 = sample_index - self.nbefore_short
+                s1 = sample_index + self.nafter_short
+                wf_short = traces[s0:s1, :]
+
+                ## pure numpy with cluster spasity
+                # distances = np.sum(np.sum((templates[possible_clusters, :, :] - wf[None, : , :])**2, axis=1), axis=1)
+
+                ## pure numpy with cluster+channel spasity
+                # union_channels, = np.nonzero(np.any(d['template_sparsity'][possible_clusters, :], axis=0))
+                # distances = np.sum(np.sum((templates[possible_clusters][:, :, union_channels] - wf[: , union_channels][None, : :])**2, axis=1), axis=1)
+
+                ## numba with cluster+channel spasity
+                union_channels = np.any(self.template_sparsity[possible_clusters, :], axis=0)
+                # distances = numba_sparse_dist(wf, templates, union_channels, possible_clusters)
+                distances = numba_sparse_dist(wf_short, self.templates_short, union_channels, possible_clusters)
+
+                # DEBUG
+                # ~ ind = np.argmin(distances)
+                # ~ cluster_index = possible_clusters[ind]
+
+                for ind in np.argsort(distances)[: self.num_template_try]:
+                    cluster_index = possible_clusters[ind]
+
+                    chan_sparsity = self.template_sparsity[cluster_index, :]
+                    template_sparse = self.templates_array[cluster_index, :, :][:, chan_sparsity]
+
+                    # find best shift
+
+                    ## pure numpy version
+                    # for s, shift in enumerate(possible_shifts):
+                    #     wf_shift = traces[s0 + shift: s1 + shift, chan_sparsity]
+                    #     distances_shift[s] = np.sum((template_sparse - wf_shift)**2)
+                    # ind_shift = np.argmin(distances_shift)
+                    # shift = possible_shifts[ind_shift]
+
+                    ## numba version
+                    numba_best_shift(
+                        traces,
+                        self.templates_array[cluster_index, :, :],
+                        sample_index,
+                        self.nbefore,
+                        possible_shifts,
+                        distances_shift,
+                        chan_sparsity,
+                    )
+                    ind_shift = np.argmin(distances_shift)
+                    shift = possible_shifts[ind_shift]
+
+                    sample_index = sample_index + shift
+                    s0 = sample_index - self.nbefore
+                    s1 = sample_index + self.nafter
+                    wf_sparse = traces[s0:s1, chan_sparsity]
+
+                    # accept or not
+
+                    centered = wf_sparse - template_sparse
+                    accepted = True
+                    for other_ind, other_vector in self.closest_units[cluster_index]:
+                        v = np.sum(centered * other_vector)
+                        if np.abs(v) > 0.5:
+                            accepted = False
+                            break
+
+                    if accepted:
+                        # ~ if ind != np.argsort(distances)[0]:
+                        # ~ print('not first one', np.argsort(distances), ind)
+                        break
+
+                if accepted:
+                    amplitude = 1.0
+
+                    # remove template
+                    template = self.templates_array[cluster_index, :, :]
+                    s0 = sample_index - self.nbefore
+                    s1 = sample_index + self.nafter
+                    traces[s0:s1, :] -= template * amplitude
+
+                else:
+                    cluster_index = -1
+                    amplitude = 0.0
+
+            else:
+                cluster_index = -1
+                amplitude = 0.0
+
+            spikes["cluster_index"][i] = cluster_index
+            spikes["amplitude"][i] = amplitude
+
+        return spikes
+
+
+
 
 
 # class TridesclousPeeler(BaseTemplateMatchingEngine):
@@ -394,134 +500,134 @@ def main_function(cls, traces, d):
 #         return all_spikes
 
 
-def _tdc_find_spikes(traces, d, level=0):
-    peak_sign = d["peak_sign"]
-    templates = d["templates"]
-    templates_short = d["templates_short"]
-    templates_array = templates.get_dense_templates()
-
-    margin = d["margin"]
-    possible_clusters_by_channel = d["possible_clusters_by_channel"]
-
-    peak_traces = traces[margin // 2 : -margin // 2, :]
-    peak_sample_ind, peak_chan_ind = DetectPeakLocallyExclusive.detect_peaks(
-        peak_traces, peak_sign, d["abs_thresholds"], d["peak_shift"], d["neighbours_mask"]
-    )
-    peak_sample_ind += margin // 2
-
-    peak_amplitude = traces[peak_sample_ind, peak_chan_ind]
-    order = np.argsort(np.abs(peak_amplitude))[::-1]
-    peak_sample_ind = peak_sample_ind[order]
-    peak_chan_ind = peak_chan_ind[order]
-
-    spikes = np.zeros(peak_sample_ind.size, dtype=spike_dtype)
-    spikes["sample_index"] = peak_sample_ind
-    spikes["channel_index"] = peak_chan_ind  # TODO need to put the channel from template
-
-    possible_shifts = d["possible_shifts"]
-    distances_shift = np.zeros(possible_shifts.size)
-
-    for i in range(peak_sample_ind.size):
-        sample_index = peak_sample_ind[i]
-
-        chan_ind = peak_chan_ind[i]
-        possible_clusters = possible_clusters_by_channel[chan_ind]
-
-        if possible_clusters.size > 0:
-            # ~ s0 = sample_index - d['nbefore']
-            # ~ s1 = sample_index + d['nafter']
-
-            # ~ wf = traces[s0:s1, :]
-
-            s0 = sample_index - d["nbefore_short"]
-            s1 = sample_index + d["nafter_short"]
-            wf_short = traces[s0:s1, :]
-
-            ## pure numpy with cluster spasity
-            # distances = np.sum(np.sum((templates[possible_clusters, :, :] - wf[None, : , :])**2, axis=1), axis=1)
-
-            ## pure numpy with cluster+channel spasity
-            # union_channels, = np.nonzero(np.any(d['template_sparsity'][possible_clusters, :], axis=0))
-            # distances = np.sum(np.sum((templates[possible_clusters][:, :, union_channels] - wf[: , union_channels][None, : :])**2, axis=1), axis=1)
-
-            ## numba with cluster+channel spasity
-            union_channels = np.any(d["template_sparsity"][possible_clusters, :], axis=0)
-            # distances = numba_sparse_dist(wf, templates, union_channels, possible_clusters)
-            distances = numba_sparse_dist(wf_short, templates_short, union_channels, possible_clusters)
-
-            # DEBUG
-            # ~ ind = np.argmin(distances)
-            # ~ cluster_index = possible_clusters[ind]
-
-            for ind in np.argsort(distances)[: d["num_template_try"]]:
-                cluster_index = possible_clusters[ind]
-
-                chan_sparsity = d["template_sparsity"][cluster_index, :]
-                template_sparse = templates_array[cluster_index, :, :][:, chan_sparsity]
-
-                # find best shift
-
-                ## pure numpy version
-                # for s, shift in enumerate(possible_shifts):
-                #     wf_shift = traces[s0 + shift: s1 + shift, chan_sparsity]
-                #     distances_shift[s] = np.sum((template_sparse - wf_shift)**2)
-                # ind_shift = np.argmin(distances_shift)
-                # shift = possible_shifts[ind_shift]
-
-                ## numba version
-                numba_best_shift(
-                    traces,
-                    templates_array[cluster_index, :, :],
-                    sample_index,
-                    d["nbefore"],
-                    possible_shifts,
-                    distances_shift,
-                    chan_sparsity,
-                )
-                ind_shift = np.argmin(distances_shift)
-                shift = possible_shifts[ind_shift]
-
-                sample_index = sample_index + shift
-                s0 = sample_index - d["nbefore"]
-                s1 = sample_index + d["nafter"]
-                wf_sparse = traces[s0:s1, chan_sparsity]
-
-                # accept or not
-
-                centered = wf_sparse - template_sparse
-                accepted = True
-                for other_ind, other_vector in d["closest_units"][cluster_index]:
-                    v = np.sum(centered * other_vector)
-                    if np.abs(v) > 0.5:
-                        accepted = False
-                        break
-
-                if accepted:
-                    # ~ if ind != np.argsort(distances)[0]:
-                    # ~ print('not first one', np.argsort(distances), ind)
-                    break
-
-            if accepted:
-                amplitude = 1.0
+# def _tdc_find_spikes(traces, d, level=0):
+#     peak_sign = d["peak_sign"]
+#     templates = d["templates"]
+#     templates_short = d["templates_short"]
+#     templates_array = templates.get_dense_templates()
+
+#     margin = d["margin"]
+#     possible_clusters_by_channel = d["possible_clusters_by_channel"]
+
+#     peak_traces = traces[margin // 2 : -margin // 2, :]
+#     peak_sample_ind, peak_chan_ind = DetectPeakLocallyExclusive.detect_peaks(
+#         peak_traces, peak_sign, d["abs_thresholds"], d["peak_shift"], d["neighbours_mask"]
+#     )
+#     peak_sample_ind += margin // 2
+
+#     peak_amplitude = traces[peak_sample_ind, peak_chan_ind]
+#     order = np.argsort(np.abs(peak_amplitude))[::-1]
+#     peak_sample_ind = peak_sample_ind[order]
+#     peak_chan_ind = peak_chan_ind[order]
+
+#     spikes = np.zeros(peak_sample_ind.size, dtype=spike_dtype)
+#     spikes["sample_index"] = peak_sample_ind
+#     spikes["channel_index"] = peak_chan_ind  # TODO need to put the channel from template
+
+#     possible_shifts = d["possible_shifts"]
+#     distances_shift = np.zeros(possible_shifts.size)
+
+#     for i in range(peak_sample_ind.size):
+#         sample_index = peak_sample_ind[i]
+
+#         chan_ind = peak_chan_ind[i]
+#         possible_clusters = possible_clusters_by_channel[chan_ind]
+
+#         if possible_clusters.size > 0:
+#             # ~ s0 = sample_index - d['nbefore']
+#             # ~ s1 = sample_index + d['nafter']
+
+#             # ~ wf = traces[s0:s1, :]
+
+#             s0 = sample_index - d["nbefore_short"]
+#             s1 = sample_index + d["nafter_short"]
+#             wf_short = traces[s0:s1, :]
+
+#             ## pure numpy with cluster spasity
+#             # distances = np.sum(np.sum((templates[possible_clusters, :, :] - wf[None, : , :])**2, axis=1), axis=1)
+
+#             ## pure numpy with cluster+channel spasity
+#             # union_channels, = np.nonzero(np.any(d['template_sparsity'][possible_clusters, :], axis=0))
+#             # distances = np.sum(np.sum((templates[possible_clusters][:, :, union_channels] - wf[: , union_channels][None, : :])**2, axis=1), axis=1)
+
+#             ## numba with cluster+channel spasity
+#             union_channels = np.any(d["template_sparsity"][possible_clusters, :], axis=0)
+#             # distances = numba_sparse_dist(wf, templates, union_channels, possible_clusters)
+#             distances = numba_sparse_dist(wf_short, templates_short, union_channels, possible_clusters)
+
+#             # DEBUG
+#             # ~ ind = np.argmin(distances)
+#             # ~ cluster_index = possible_clusters[ind]
+
+#             for ind in np.argsort(distances)[: d["num_template_try"]]:
+#                 cluster_index = possible_clusters[ind]
+
+#                 chan_sparsity = d["template_sparsity"][cluster_index, :]
+#                 template_sparse = templates_array[cluster_index, :, :][:, chan_sparsity]
+
+#                 # find best shift
+
+#                 ## pure numpy version
+#                 # for s, shift in enumerate(possible_shifts):
+#                 #     wf_shift = traces[s0 + shift: s1 + shift, chan_sparsity]
+#                 #     distances_shift[s] = np.sum((template_sparse - wf_shift)**2)
+#                 # ind_shift = np.argmin(distances_shift)
+#                 # shift = possible_shifts[ind_shift]
+
+#                 ## numba version
+#                 numba_best_shift(
+#                     traces,
+#                     templates_array[cluster_index, :, :],
+#                     sample_index,
+#                     d["nbefore"],
+#                     possible_shifts,
+#                     distances_shift,
+#                     chan_sparsity,
+#                 )
+#                 ind_shift = np.argmin(distances_shift)
+#                 shift = possible_shifts[ind_shift]
+
+#                 sample_index = sample_index + shift
+#                 s0 = sample_index - d["nbefore"]
+#                 s1 = sample_index + d["nafter"]
+#                 wf_sparse = traces[s0:s1, chan_sparsity]
+
+#                 # accept or not
+
+#                 centered = wf_sparse - template_sparse
+#                 accepted = True
+#                 for other_ind, other_vector in d["closest_units"][cluster_index]:
+#                     v = np.sum(centered * other_vector)
+#                     if np.abs(v) > 0.5:
+#                         accepted = False
+#                         break
+
+#                 if accepted:
+#                     # ~ if ind != np.argsort(distances)[0]:
+#                     # ~ print('not first one', np.argsort(distances), ind)
+#                     break
+
+#             if accepted:
+#                 amplitude = 1.0
+
+#                 # remove template
+#                 template = templates_array[cluster_index, :, :]
+#                 s0 = sample_index - d["nbefore"]
+#                 s1 = sample_index + d["nafter"]
+#                 traces[s0:s1, :] -= template * amplitude
+
+#             else:
+#                 cluster_index = -1
+#                 amplitude = 0.0
 
-                # remove template
-                template = templates_array[cluster_index, :, :]
-                s0 = sample_index - d["nbefore"]
-                s1 = sample_index + d["nafter"]
-                traces[s0:s1, :] -= template * amplitude
-
-            else:
-                cluster_index = -1
-                amplitude = 0.0
-
-        else:
-            cluster_index = -1
-            amplitude = 0.0
+#         else:
+#             cluster_index = -1
+#             amplitude = 0.0
 
-        spikes["cluster_index"][i] = cluster_index
-        spikes["amplitude"][i] = amplitude
+#         spikes["cluster_index"][i] = cluster_index
+#         spikes["amplitude"][i] = amplitude
 
-    return spikes
+#     return spikes
 
 
 if HAVE_NUMBA:
diff --git a/src/spikeinterface/sortingcomponents/tests/test_template_matching.py b/src/spikeinterface/sortingcomponents/tests/test_template_matching.py
index 0cd3868a8f..0b3c979417 100644
--- a/src/spikeinterface/sortingcomponents/tests/test_template_matching.py
+++ b/src/spikeinterface/sortingcomponents/tests/test_template_matching.py
@@ -9,7 +9,8 @@
 from spikeinterface.sortingcomponents.tests.common import make_dataset
 
 
-job_kwargs = dict(n_jobs=-1, chunk_duration="500ms", progress_bar=True)
+# job_kwargs = dict(n_jobs=-1, chunk_duration="500ms", progress_bar=True)
+job_kwargs = dict(n_jobs=1, chunk_duration="500ms", progress_bar=True)
 
 
 def get_sorting_analyzer():
@@ -40,8 +41,11 @@ def test_find_spikes_from_templates(method, sorting_analyzer):
     noise_levels = sorting_analyzer.get_extension("noise_levels").get_data()
 
     # sorting_analyzer
-    method_kwargs_all = {"templates": templates, "noise_levels": noise_levels}
+    method_kwargs_all = {"templates": templates, }
     method_kwargs = {}
+    if method in ("naive", "tdc-peeler", "circus"):
+        method_kwargs["noise_levels"] = noise_levels
+    
     # method_kwargs["wobble"] = {
     #     "templates": waveform_extractor.get_all_templates(),
     #     "nbefore": waveform_extractor.nbefore,
@@ -79,8 +83,8 @@ def test_find_spikes_from_templates(method, sorting_analyzer):
 if __name__ == "__main__":
     sorting_analyzer = get_sorting_analyzer()
     # method = "naive"
-    method = "tdc-peeler"
+    # method = "tdc-peeler"
     # method =  "circus"
-    # method = "circus-omp-svd"
+    method = "circus-omp-svd"
     # method = "wobble"
     test_find_spikes_from_templates(method, sorting_analyzer)

From 482ffa12d80f8859fa204a641a0f252411cdb374 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Fri, 27 Sep 2024 21:02:44 +0200
Subject: [PATCH 049/344] fix tests

---
 .../sortingcomponents/matching/method_list.py |   4 +-
 .../sortingcomponents/matching/wobble.py      | 659 +++++++++++++++---
 .../tests/test_template_matching.py           |  43 +-
 3 files changed, 568 insertions(+), 138 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/matching/method_list.py b/src/spikeinterface/sortingcomponents/matching/method_list.py
index 8cb44b09b7..ca6c0db924 100644
--- a/src/spikeinterface/sortingcomponents/matching/method_list.py
+++ b/src/spikeinterface/sortingcomponents/matching/method_list.py
@@ -3,12 +3,12 @@
 from .naive import NaiveMatching
 from .tdc import TridesclousPeeler
 from .circus import CircusPeeler, CircusOMPSVDPeeler
-# from .wobble import WobbleMatch
+from .wobble import WobbleMatch
 
 matching_methods = {
     "naive": NaiveMatching,
     "tdc-peeler": TridesclousPeeler,
     "circus": CircusPeeler,
     "circus-omp-svd": CircusOMPSVDPeeler,
-    # "wobble": WobbleMatch,
+    "wobble": WobbleMatch,
 }
diff --git a/src/spikeinterface/sortingcomponents/matching/wobble.py b/src/spikeinterface/sortingcomponents/matching/wobble.py
index 99de6fcd4e..1a23992485 100644
--- a/src/spikeinterface/sortingcomponents/matching/wobble.py
+++ b/src/spikeinterface/sortingcomponents/matching/wobble.py
@@ -4,7 +4,8 @@
 from dataclasses import dataclass
 from typing import List, Tuple, Optional
 
-from .main import BaseTemplateMatchingEngine
+# from .main import BaseTemplateMatchingEngine
+from .base import BaseTemplateMatching, _base_matching_dtype
 from spikeinterface.core.template import Templates
 
 
@@ -197,8 +198,9 @@ def from_parameters_and_templates(cls, params, templates):
         return template_meta
 
 
+# important : this is differents from the spikeinterface.core.Sparsity
 @dataclass
-class Sparsity:
+class _Sparsity:
     """Variables that describe channel sparsity.
 
     Parameters
@@ -226,7 +228,7 @@ def from_parameters_and_templates(cls, params, templates):
 
         Returns
         -------
-        sparsity : Sparsity
+        sparsity : _Sparsity
             Dataclass object for aggregating channel sparsity variables together.
         """
         visible_channels = np.ptp(templates, axis=1) > params.visibility_threshold
@@ -250,7 +252,7 @@ def from_templates(cls, params, templates):
 
         Returns
         -------
-        sparsity : Sparsity
+        sparsity : _Sparsity
             Dataclass object for aggregating channel sparsity variables together.
         """
         visible_channels = templates.sparsity.mask
@@ -297,7 +299,7 @@ def __post_init__(self):
         self.temporal, self.singular, self.spatial, self.temporal_jittered = self.compressed_templates
 
 
-class WobbleMatch(BaseTemplateMatchingEngine):
+class WobbleMatch(BaseTemplateMatching):
     """Template matching method from the Paninski lab.
 
     Templates are jittered or "wobbled" in time and amplitude to capture variability in spike amplitude and
@@ -331,53 +333,26 @@ class WobbleMatch(BaseTemplateMatchingEngine):
     - "peaks" are considered spikes if their amplitude clears the threshold parameter
     """
 
-    default_params = {
-        "templates": None,
-    }
-    spike_dtype = [
-        ("sample_index", "int64"),
-        ("channel_index", "int64"),
-        ("cluster_index", "int64"),
-        ("amplitude", "float64"),
-        ("segment_index", "int64"),
-    ]
+    # default_params = {
+    #     "templates": None,
+    # }
 
-    @classmethod
-    def initialize_and_check_kwargs(cls, recording, kwargs):
-        """Initialize the objective and precompute various useful objects.
-
-        Parameters
-        ----------
-        recording : RecordingExtractor
-            The recording extractor object.
-        kwargs : dict
-            Keyword arguments for matching method.
-
-        Returns
-        -------
-        d : dict
-            Updated Keyword arguments.
-        """
-        d = cls.default_params.copy()
+    def __init__(self, recording, return_output=True, parents=None,
+        templates=None,
+        parameters={},
+        ):
 
-        required_kwargs_keys = ["templates"]
-        for required_key in required_kwargs_keys:
-            assert required_key in kwargs, f"`{required_key}` is a required key in the kwargs"
+        BaseTemplateMatching.__init__(self, recording, templates, return_output=True, parents=None)
 
-        parameters = kwargs.get("parameters", {})
-        templates = kwargs["templates"]
-        assert isinstance(templates, Templates), (
-            f"The templates supplied is of type {type(d['templates'])} " f"and must be a Templates"
-        )
         templates_array = templates.get_dense_templates().astype(np.float32, casting="safe")
 
         # Aggregate useful parameters/variables for handy access in downstream functions
         params = WobbleParameters(**parameters)
         template_meta = TemplateMetadata.from_parameters_and_templates(params, templates_array)
         if not templates.are_templates_sparse():
-            sparsity = Sparsity.from_parameters_and_templates(params, templates_array)
+            sparsity = _Sparsity.from_parameters_and_templates(params, templates_array)
         else:
-            sparsity = Sparsity.from_templates(params, templates)
+            sparsity = _Sparsity.from_templates(params, templates)
 
         # Perform initial computations on templates necessary for computing the objective
         sparse_templates = np.where(sparsity.visible_channels[:, np.newaxis, :], templates_array, 0)
@@ -394,84 +369,42 @@ def initialize_and_check_kwargs(cls, recording, kwargs):
             norm_squared=norm_squared,
         )
 
-        # Pack initial data into kwargs
-        kwargs["params"] = params
-        kwargs["template_meta"] = template_meta
-        kwargs["sparsity"] = sparsity
-        kwargs["template_data"] = template_data
-        kwargs["nbefore"] = templates.nbefore
-        kwargs["nafter"] = templates.nafter
-        d.update(kwargs)
-        return d
+        self.params = params
+        self.template_meta = template_meta
+        self.sparsity = sparsity
+        self.template_data = template_data
+        self.nbefore = templates.nbefore
+        self.nafter = templates.nafter
 
-    @classmethod
-    def serialize_method_kwargs(cls, kwargs):
-        # This function does nothing without a waveform extractor -- candidate for refactor
-        kwargs = dict(kwargs)
-        return kwargs
+        # buffer_ms = 10
+        # self.margin = int(buffer_ms*1e-3 * recording.sampling_frequency)
+        self.margin = 300  # To ensure equivalence with spike-psvae version of the algorithm
 
-    @classmethod
-    def unserialize_in_worker(cls, kwargs):
-        # This function does nothing without a waveform extractor -- candidate for refactor
-        return kwargs
+    def get_trace_margin(self):
+        return self.margin
 
-    @classmethod
-    def get_margin(cls, recording, kwargs):
-        """Get margin for chunking recording.
-
-        Parameters
-        ----------
-        recording : RecordingExtractor
-            The recording extractor object.
-        kwargs : dict
-            Keyword arguments for matching method.
+    def compute(self, traces, start_frame, end_frame, segment_index, max_margin, *args):
 
-        Returns
-        -------
-        margin : int
-            Buffer in samples on each side of a chunk.
-        """
-        buffer_ms = 10
-        # margin = int(buffer_ms*1e-3 * recording.sampling_frequency)
-        margin = 300  # To ensure equivalence with spike-psvae version of the algorithm
-        return margin
-
-    @classmethod
-    def main_function(cls, traces, method_kwargs):
-        """Detect spikes in traces using the template matching algorithm.
-
-        Parameters
-        ----------
-        traces : ndarray (chunk_len + 2*margin, num_channels)
-            Voltage traces for a chunk of the recording.
-        method_kwargs : dict
-            Keyword arguments for matching method.
-
-        Returns
-        -------
-        spikes : ndarray (num_spikes,)
-            Resulting spike train.
-        """
         # Unpack method_kwargs
-        nbefore, nafter = method_kwargs["nbefore"], method_kwargs["nafter"]
-        template_meta = method_kwargs["template_meta"]
-        params = method_kwargs["params"]
-        sparsity = method_kwargs["sparsity"]
-        template_data = method_kwargs["template_data"]
+        # nbefore, nafter = method_kwargs["nbefore"], method_kwargs["nafter"]
+        # template_meta = method_kwargs["template_meta"]
+        # params = method_kwargs["params"]
+        # sparsity = method_kwargs["sparsity"]
+        # template_data = method_kwargs["template_data"]
 
         # Check traces
         assert traces.dtype == np.float32, "traces must be specified as np.float32"
 
         # Compute objective
-        objective = compute_objective(traces, template_data, params.approx_rank)
-        objective_normalized = 2 * objective - template_data.norm_squared[:, np.newaxis]
+        objective = compute_objective(traces, self.template_data, self.params.approx_rank)
+        objective_normalized = 2 * objective - self.template_data.norm_squared[:, np.newaxis]
 
         # Compute spike train
         spike_trains, scalings, distance_metrics = [], [], []
-        for i in range(params.max_iter):
+        for i in range(self.params.max_iter):
             # find peaks
-            spike_train, scaling, distance_metric = cls.find_peaks(
-                objective, objective_normalized, np.array(spike_trains), params, template_data, template_meta
+            spike_train, scaling, distance_metric = self.find_peaks(
+                objective, objective_normalized, np.array(spike_trains), self.params, self.template_data, self.template_meta
             )
             if len(spike_train) == 0:
                 break
@@ -482,15 +415,15 @@ def main_function(cls, traces, method_kwargs):
             distance_metrics.extend(list(distance_metric))
 
             # subtract newly detected spike train from traces (via the objective)
-            objective, objective_normalized = cls.subtract_spike_train(
-                spike_train, scaling, template_data, objective, objective_normalized, params, template_meta, sparsity
+            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 len(spike_train) == 0:  # no spikes found
-            return np.zeros(0, dtype=cls.spike_dtype)
+            return np.zeros(0, dtype=_base_matching_dtype)
 
         # order spike times
         index = np.argsort(spike_train[:, 0])
@@ -499,8 +432,8 @@ def main_function(cls, traces, method_kwargs):
         distance_metric = distance_metric[index]
 
         # adjust spike_train
-        spike_train[:, 0] += nbefore  # beginning of template --> center of template
-        spike_train[:, 1] //= params.jitter_factor  # jittered_index --> template_index
+        spike_train[:, 0] += self.nbefore  # beginning of template --> center of template
+        spike_train[:, 1] //= self.params.jitter_factor  # jittered_index --> template_index
 
         # TODO : Benchmark spike amplitudes
         # Find spike amplitudes / channels
@@ -512,7 +445,7 @@ def main_function(cls, traces, method_kwargs):
             channel_inds.append(best_ch)
 
         # assign result to spikes array
-        spikes = np.zeros(spike_train.shape[0], dtype=cls.spike_dtype)
+        spikes = np.zeros(spike_train.shape[0], dtype=_base_matching_dtype)
         spikes["sample_index"] = spike_train[:, 0]
         spikes["cluster_index"] = spike_train[:, 1]
         spikes["channel_index"] = channel_inds
@@ -622,7 +555,7 @@ def subtract_spike_train(
             Dataclass object for aggregating the parameters together.
         template_meta : TemplateMetadata
             Dataclass object for aggregating template metadata together.
-        sparsity : Sparsity
+        sparsity : _Sparsity
             Dataclass object for aggregating channel sparsity variables together.
 
         Returns
@@ -796,6 +729,505 @@ def enforce_refractory(
             objective[spike_unit_indices[:, np.newaxis], waveform_samples[:, 1:-1]] = -1 * np.inf
         return objective, objective_normalized
 
+# class WobbleMatch(BaseTemplateMatchingEngine):
+#     """Template matching method from the Paninski lab.
+
+#     Templates are jittered or "wobbled" in time and amplitude to capture variability in spike amplitude and
+#     super-resolution jitter in spike timing.
+
+#     Algorithm
+#     ---------
+#     At initialization:
+#         1. Compute channel sparsity to determine which units are "visible" to each other
+#         2. Compress Templates using Singular Value Decomposition into rank approx_rank
+#         3. Upsample the temporal component of compressed templates and re-index to obtain many super-resolution-jittered
+#             temporal components for each template
+#         3. Convolve each pair of jittered compressed templates together (subject to channel sparsity)
+#     For each chunk of traces:
+#         1. Compute the "objective function" to be minimized by convolving each true template with the traces
+#         2. Normalize the objective relative to the magnitude of each true template
+#         3. Detect spikes by indexing peaks in the objective corresponding to "matches" between the spike and a template
+#         4. Determine which super-resolution-jittered template best matches each spike and scale the amplitude to match
+#         5. Subtract scaled pairwise convolved jittered templates from the objective(s) to account for the effect of
+#             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
+
+#     Notes
+#     -----
+#     For consistency, throughout this module
+#     - a "unit" refers to a putative neuron which may have one or more "templates" of its spike waveform
+#     - Each "template" may have many upsampled "jittered_templates" depending on the "jitter_factor"
+#     - "peaks" refer to relative maxima in the convolution of the templates with the voltage trace
+#     - "spikes" refer to putative extracellular action potentials (EAPs)
+#     - "peaks" are considered spikes if their amplitude clears the threshold parameter
+#     """
+
+#     default_params = {
+#         "templates": None,
+#     }
+#     spike_dtype = [
+#         ("sample_index", "int64"),
+#         ("channel_index", "int64"),
+#         ("cluster_index", "int64"),
+#         ("amplitude", "float64"),
+#         ("segment_index", "int64"),
+#     ]
+
+#     @classmethod
+#     def initialize_and_check_kwargs(cls, recording, kwargs):
+#         """Initialize the objective and precompute various useful objects.
+
+#         Parameters
+#         ----------
+#         recording : RecordingExtractor
+#             The recording extractor object.
+#         kwargs : dict
+#             Keyword arguments for matching method.
+
+#         Returns
+#         -------
+#         d : dict
+#             Updated Keyword arguments.
+#         """
+#         d = cls.default_params.copy()
+
+#         required_kwargs_keys = ["templates"]
+#         for required_key in required_kwargs_keys:
+#             assert required_key in kwargs, f"`{required_key}` is a required key in the kwargs"
+
+#         parameters = kwargs.get("parameters", {})
+#         templates = kwargs["templates"]
+#         assert isinstance(templates, Templates), (
+#             f"The templates supplied is of type {type(d['templates'])} " f"and must be a Templates"
+#         )
+#         templates_array = templates.get_dense_templates().astype(np.float32, casting="safe")
+
+#         # Aggregate useful parameters/variables for handy access in downstream functions
+#         params = WobbleParameters(**parameters)
+#         template_meta = TemplateMetadata.from_parameters_and_templates(params, templates_array)
+#         if not templates.are_templates_sparse():
+#             sparsity = Sparsity.from_parameters_and_templates(params, templates_array)
+#         else:
+#             sparsity = Sparsity.from_templates(params, templates)
+
+#         # Perform initial computations on templates necessary for computing the objective
+#         sparse_templates = np.where(sparsity.visible_channels[:, np.newaxis, :], templates_array, 0)
+#         temporal, singular, spatial = compress_templates(sparse_templates, params.approx_rank)
+#         temporal_jittered = upsample_and_jitter(temporal, params.jitter_factor, template_meta.num_samples)
+#         compressed_templates = (temporal, singular, spatial, temporal_jittered)
+#         pairwise_convolution = convolve_templates(
+#             compressed_templates, params.jitter_factor, params.approx_rank, template_meta.jittered_indices, sparsity
+#         )
+#         norm_squared = compute_template_norm(sparsity.visible_channels, templates_array)
+#         template_data = TemplateData(
+#             compressed_templates=compressed_templates,
+#             pairwise_convolution=pairwise_convolution,
+#             norm_squared=norm_squared,
+#         )
+
+#         # Pack initial data into kwargs
+#         kwargs["params"] = params
+#         kwargs["template_meta"] = template_meta
+#         kwargs["sparsity"] = sparsity
+#         kwargs["template_data"] = template_data
+#         kwargs["nbefore"] = templates.nbefore
+#         kwargs["nafter"] = templates.nafter
+#         d.update(kwargs)
+#         return d
+
+#     @classmethod
+#     def serialize_method_kwargs(cls, kwargs):
+#         # This function does nothing without a waveform extractor -- candidate for refactor
+#         kwargs = dict(kwargs)
+#         return kwargs
+
+#     @classmethod
+#     def unserialize_in_worker(cls, kwargs):
+#         # This function does nothing without a waveform extractor -- candidate for refactor
+#         return kwargs
+
+#     @classmethod
+#     def get_margin(cls, recording, kwargs):
+#         """Get margin for chunking recording.
+
+#         Parameters
+#         ----------
+#         recording : RecordingExtractor
+#             The recording extractor object.
+#         kwargs : dict
+#             Keyword arguments for matching method.
+
+#         Returns
+#         -------
+#         margin : int
+#             Buffer in samples on each side of a chunk.
+#         """
+#         buffer_ms = 10
+#         # margin = int(buffer_ms*1e-3 * recording.sampling_frequency)
+#         margin = 300  # To ensure equivalence with spike-psvae version of the algorithm
+#         return margin
+
+#     @classmethod
+#     def main_function(cls, traces, method_kwargs):
+#         """Detect spikes in traces using the template matching algorithm.
+
+#         Parameters
+#         ----------
+#         traces : ndarray (chunk_len + 2*margin, num_channels)
+#             Voltage traces for a chunk of the recording.
+#         method_kwargs : dict
+#             Keyword arguments for matching method.
+
+#         Returns
+#         -------
+#         spikes : ndarray (num_spikes,)
+#             Resulting spike train.
+#         """
+#         # Unpack method_kwargs
+#         nbefore, nafter = method_kwargs["nbefore"], method_kwargs["nafter"]
+#         template_meta = method_kwargs["template_meta"]
+#         params = method_kwargs["params"]
+#         sparsity = method_kwargs["sparsity"]
+#         template_data = method_kwargs["template_data"]
+
+#         # Check traces
+#         assert traces.dtype == np.float32, "traces must be specified as np.float32"
+
+#         # Compute objective
+#         objective = compute_objective(traces, template_data, params.approx_rank)
+#         objective_normalized = 2 * objective - template_data.norm_squared[:, np.newaxis]
+
+#         # Compute spike train
+#         spike_trains, scalings, distance_metrics = [], [], []
+#         for i in range(params.max_iter):
+#             # find peaks
+#             spike_train, scaling, distance_metric = cls.find_peaks(
+#                 objective, objective_normalized, np.array(spike_trains), params, template_data, template_meta
+#             )
+#             if len(spike_train) == 0:
+#                 break
+
+#             # 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 = cls.subtract_spike_train(
+#                 spike_train, scaling, template_data, objective, objective_normalized, params, template_meta, sparsity
+#             )
+
+#         spike_train = np.array(spike_trains)
+#         scalings = np.array(scalings)
+#         distance_metric = np.array(distance_metrics)
+#         if len(spike_train) == 0:  # no spikes found
+#             return np.zeros(0, dtype=cls.spike_dtype)
+
+#         # order spike times
+#         index = np.argsort(spike_train[:, 0])
+#         spike_train = spike_train[index]
+#         scalings = scalings[index]
+#         distance_metric = distance_metric[index]
+
+#         # adjust spike_train
+#         spike_train[:, 0] += nbefore  # beginning of template --> center of template
+#         spike_train[:, 1] //= params.jitter_factor  # jittered_index --> template_index
+
+#         # TODO : Benchmark spike amplitudes
+#         # Find spike amplitudes / channels
+#         amplitudes, channel_inds = [], []
+#         for i, spike_index in enumerate(spike_train[:, 0]):
+#             best_ch = np.argmax(np.abs(traces[spike_index, :]))
+#             amp = np.abs(traces[spike_index, best_ch])
+#             amplitudes.append(amp)
+#             channel_inds.append(best_ch)
+
+#         # assign result to spikes array
+#         spikes = np.zeros(spike_train.shape[0], dtype=cls.spike_dtype)
+#         spikes["sample_index"] = spike_train[:, 0]
+#         spikes["cluster_index"] = spike_train[:, 1]
+#         spikes["channel_index"] = channel_inds
+#         spikes["amplitude"] = amplitudes
+
+#         return spikes
+
+#     # TODO: Replace this method with equivalent from spikeinterface
+#     @classmethod
+#     def find_peaks(
+#         cls, objective, objective_normalized, spike_trains, params, template_data, template_meta
+#     ) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+#         """Find new peaks in the objective and update spike train accordingly.
+
+#         Parameters
+#         ----------
+#         objective : ndarray (num_templates, traces.shape[0]+template_meta.num_samples-1)
+#             Template matching objective for each template.
+#         objective_normalized : ndarray (num_templates, traces.shape[0]+template_meta.num_samples-1)
+#             Template matching objective normalized by the magnitude of each template.
+#         spike_trains : ndarray (n_spikes, 2)
+#             Spike train from template matching.
+#         params : WobbleParameters
+#             Dataclass object for aggregating the parameters together.
+#         template_meta : TemplateMetadata
+#             Dataclass object for aggregating template metadata together.
+
+#         Returns
+#         -------
+#         new_spike_train : ndarray (num_spikes, 2)
+#             Spike train from template matching with newly detected spikes added.
+#         scalings : ndarray (num_spikes,)
+#             Amplitude scaling used for each spike.
+#         distance_metric : ndarray (num_spikes)
+#             A metric that describes how good of a "fit" each spike is to its corresponding template
+
+#         Notes
+#         -----
+#         This function first identifies spike times (indices) using peaks in the objective that correspond to matches
+#         between a template and a spike. Then, it finds the best upsampled/jittered template corresponding to each spike.
+#         Finally, it generates a new spike train from the spike times, and returns it along with additional metrics about
+#         each spike.
+#         """
+#         from scipy import signal
+
+#         # Get spike times (indices) using peaks in the objective
+#         objective_template_max = np.max(objective_normalized, axis=0)
+#         spike_window = (template_meta.num_samples - 1, objective_normalized.shape[1] - template_meta.num_samples)
+#         objective_windowed = objective_template_max[spike_window[0] : spike_window[1]]
+#         spike_time_indices = signal.argrelmax(objective_windowed, order=template_meta.num_samples - 1)[0]
+#         spike_time_indices += template_meta.num_samples - 1
+#         objective_spikes = objective_template_max[spike_time_indices]
+#         spike_time_indices = spike_time_indices[objective_spikes > params.threshold]
+
+#         if len(spike_time_indices) == 0:  # No new spikes found
+#             return np.zeros((0, 2), dtype=np.int32), np.zeros(0), np.zeros(0)
+
+#         # Extract metrics using spike times (indices)
+#         distance_metric = objective_template_max[spike_time_indices]
+#         scalings = np.ones(len(spike_time_indices), dtype=objective_normalized.dtype)
+
+#         # Find the best upsampled template
+#         spike_template_indices = np.argmax(objective_normalized[:, spike_time_indices], axis=0)
+#         high_res_shifts = cls.calculate_high_res_shift(
+#             spike_time_indices,
+#             spike_template_indices,
+#             objective,
+#             objective_normalized,
+#             template_data,
+#             params,
+#             template_meta,
+#         )
+#         template_shift, time_shift, non_refractory_indices, scaling = high_res_shifts
+
+#         # Update unit_indices, spike_times, and scalings
+#         spike_jittered_indices = spike_template_indices * params.jitter_factor
+#         at_least_one_spike = bool(len(non_refractory_indices))
+#         if at_least_one_spike:
+#             spike_jittered_indices[non_refractory_indices] += template_shift
+#             spike_time_indices[non_refractory_indices] += time_shift
+#             scalings[non_refractory_indices] = scaling
+
+#         # Generate new spike train from spike times (indices)
+#         convolution_correction = -1 * (template_meta.num_samples - 1)  # convolution indices --> raw_indices
+#         spike_time_indices += convolution_correction
+#         new_spike_train = np.array([spike_time_indices, spike_jittered_indices]).T
+
+#         return new_spike_train, scalings, distance_metric
+
+#     @classmethod
+#     def subtract_spike_train(
+#         cls, spike_train, scalings, template_data, objective, objective_normalized, params, template_meta, sparsity
+#     ) -> tuple[np.ndarray, np.ndarray]:
+#         """Subtract spike train of templates from the objective directly.
+
+#         Parameters
+#         ----------
+#         spike_train : ndarray (num_spikes, 2)
+#             Spike train from template matching.
+#         scalings : ndarray (num_spikes,)
+#             Amplitude scaling used for each spike.
+#         objective : ndarray (num_templates, traces.shape[0]+num_samples-1)
+#             Template matching objective for each template.
+#         objective_normalized : ndarray (num_templates, traces.shape[0]+num_samples-1)
+#             Template matching objective normalized by the magnitude of each template.
+#         params : WobbleParameters
+#             Dataclass object for aggregating the parameters together.
+#         template_meta : TemplateMetadata
+#             Dataclass object for aggregating template metadata together.
+#         sparsity : Sparsity
+#             Dataclass object for aggregating channel sparsity variables together.
+
+#         Returns
+#         -------
+#         objective : ndarray (template_meta.num_templates, traces.shape[0]+template_meta.num_samples-1)
+#             Template matching objective for each template.
+#         objective_normalized : ndarray (num_templates, traces.shape[0]+template_meta.num_samples-1)
+#             Template matching objective normalized by the magnitude of each template.
+#         """
+#         present_jittered_indices = np.unique(spike_train[:, 1])
+#         convolution_resolution_len = get_convolution_len(template_meta.num_samples, template_meta.num_samples)
+#         for jittered_index in present_jittered_indices:
+#             id_mask = spike_train[:, 1] == jittered_index
+#             id_spiketrain = spike_train[id_mask, 0]
+#             id_scaling = scalings[id_mask]
+#             overlapping_templates = sparsity.unit_overlap[jittered_index]
+#             # Note: pairwise_conv only has overlapping template convolutions already
+#             pconv = template_data.pairwise_convolution[jittered_index]
+#             # 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[overlapping_templates, spike_start_index:spike_stop_index] -= pconv_scaled
+
+#             objective, objective_normalized = cls.enforce_refractory(
+#                 spike_train, objective, objective_normalized, params, template_meta
+#             )
+#         return objective, objective_normalized
+
+#     @classmethod
+#     def calculate_high_res_shift(
+#         cls,
+#         spike_time_indices,
+#         spike_unit_indices,
+#         objective,
+#         objective_normalized,
+#         template_data,
+#         params,
+#         template_meta,
+#     ) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+#         """Determines optimal shifts when super-resolution, scaled templates are used.
+
+#         Parameters
+#         ----------
+#         spike_time_indices : ndarray (num_spikes,)
+#             Indices in the voltage traces corresponding to the time of each spike.
+#         spike_unit_indices : ndarray (num_spikes)
+#             Units corresponding to each spike.
+#         objective : ndarray (num_templates, traces.shape[0]+num_samples-1)
+#             Template matching objective for each template.
+#         objective_normalized : ndarray (num_templates, traces.shape[0]+num_samples-1)
+#             Template matching objective normalized by the magnitude of each template.
+#         template_data : TemplateData
+#             Dataclass object for aggregating template data together.
+#         params : WobbleParameters
+#             Dataclass object for aggregating the parameters together.
+#         template_meta : TemplateMetadata
+#             Dataclass object for aggregating template metadata together.
+
+#         Returns
+#         -------
+#         template_shift : ndarray (num_spikes,)
+#             Indices to shift each spike template_index to the correct jittered_index.
+#         time_shift : ndarray (num_spikes,)
+#             Indices to shift each spike time index to the adjusted time index.
+#         non_refractory_indices : ndarray
+#             Indices of the spike train that correspond to non-refractory spikes.
+#         scalings : ndarray (num_spikes,)
+#             Amplitude scaling used for each spike.
+#         """
+#         # Return identities if no high-resolution templates are necessary
+#         not_high_res = params.jitter_factor == 1 and not params.scale_amplitudes
+#         at_least_one_spike = bool(len(spike_time_indices))
+#         if not_high_res or not at_least_one_spike:
+#             template_shift = np.zeros_like(spike_time_indices)
+#             time_shift = np.zeros_like(spike_time_indices)
+#             non_refractory_indices = range(len(spike_time_indices))
+#             scalings = np.ones_like(spike_time_indices)
+#             return template_shift, time_shift, non_refractory_indices, scalings
+
+#         peak_indices = spike_time_indices + template_meta.peak_window[:, np.newaxis]
+#         objective_peaks = objective_normalized[spike_unit_indices, peak_indices]
+
+#         # Omit refractory spikes
+#         peak_is_refractory = np.logical_or(np.isinf(objective_peaks[0, :]), np.isinf(objective_peaks[-1, :]))
+#         refractory_before_spike = np.arange(-template_meta.overlapping_spike_buffer, 1)[:, np.newaxis]
+#         refractory_indices = spike_time_indices[peak_is_refractory] + refractory_before_spike
+#         objective_normalized[spike_unit_indices[peak_is_refractory], refractory_indices] = -1 * np.inf
+#         non_refractory_indices = np.flatnonzero(np.logical_not(peak_is_refractory))
+#         objective_peaks = objective_peaks[:, non_refractory_indices]
+#         if objective_peaks.shape[1] == 0:  # no non-refractory peaks --> exit function
+#             return np.array([]), np.array([]), np.array([]), np.array([])
+
+#         # Upsample and compute optimal template shift
+#         window_len_upsampled = template_meta.peak_window_len * params.jitter_factor
+#         from scipy import signal
+
+#         if not params.scale_amplitudes:
+#             # Perform simple upsampling using scipy.signal.resample
+#             high_resolution_peaks = signal.resample(objective_peaks, window_len_upsampled, axis=0)
+#             jitter = np.argmax(high_resolution_peaks[template_meta.jitter_window, :], axis=0)
+#             scalings = np.ones(len(non_refractory_indices))
+#         else:
+#             # upsampled the convolution for the detected peaks only
+#             objective_peaks_high_res = objective[spike_unit_indices, peak_indices]
+#             objective_peaks_high_res = objective_peaks_high_res[:, non_refractory_indices]
+#             high_resolution_conv = signal.resample(objective_peaks_high_res, window_len_upsampled, axis=0)
+
+#             # Find template norms for detected peaks only
+#             norm_peaks = template_data.norm_squared[spike_unit_indices[non_refractory_indices]]
+
+#             high_res_objective, scalings = compute_scale_amplitudes(
+#                 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))]
+
+#         # Extract outputs from jitter
+#         template_shift = template_meta.jitter2template_shift[jitter]
+#         time_shift = template_meta.jitter2spike_time_shift[jitter]
+#         return template_shift, time_shift, non_refractory_indices, scalings
+
+#     @classmethod
+#     def enforce_refractory(
+#         cls, spike_train, objective, objective_normalized, params, template_meta
+#     ) -> tuple[np.ndarray, np.ndarray]:
+#         """Enforcing the refractory period for each unit by setting the objective to -infinity.
+
+#         Parameters
+#         ----------
+#         spike_train : ndarray (num_spikes, 2)
+#             Spike train from template matching.
+#         objective : ndarray (num_templates, traces.shape[0]+num_samples-1)
+#             Template matching objective for each template.
+#         objective_normalized : ndarray (num_templates, traces.shape[0]+num_samples-1)
+#             Template matching objective normalized by the magnitude of each template.
+#         params : WobbleParameters
+#             Dataclass object for aggregating the parameters together.
+#         template_meta : TemplateMetadata
+#             Dataclass object for aggregating template metadata together.
+
+#         Returns
+#         -------
+#         objective : ndarray (template_meta.num_templates, traces.shape[0]+template_meta.num_samples-1)
+#             Template matching objective for each template.
+#         objective_normalized : ndarray (num_templates, traces.shape[0]+template_meta.num_samples-1)
+#             Template matching objective normalized by the magnitude of each template.
+#         """
+#         window = np.arange(-params.refractory_period_frames, params.refractory_period_frames + 1)
+
+#         # Adjust cluster IDs so that they match original templates
+#         spike_times = spike_train[:, 0]
+#         spike_template_indices = spike_train[:, 1] // params.jitter_factor
+
+#         # We want to enforce refractory conditions on unit_indices rather than template_indices for units with many templates
+#         spike_unit_indices = spike_template_indices.copy()
+#         for template_index in set(spike_template_indices):
+#             unit_index = template_meta.template_indices2unit_indices[
+#                 template_index
+#             ]  # unit_index corresponding to this template
+#             spike_unit_indices[spike_template_indices == template_index] = unit_index
+
+#         # Get the samples (time indices) that correspond to the waveform for each spike
+#         waveform_samples = get_convolution_len(spike_times[:, np.newaxis], template_meta.num_samples) + window
+
+#         # Enforce refractory by setting objective to negative infinity in invalid regions
+#         objective_normalized[spike_unit_indices[:, np.newaxis], waveform_samples[:, 1:-1]] = -1 * np.inf
+#         if params.scale_amplitudes:  # template_convolution is only used with amplitude scaling
+#             objective[spike_unit_indices[:, np.newaxis], waveform_samples[:, 1:-1]] = -1 * np.inf
+#         return objective, objective_normalized
+
 
 def compute_template_norm(visible_channels, templates):
     """Computes squared norm of each template.
@@ -1017,3 +1449,4 @@ def compute_scale_amplitudes(
     scalings = np.clip(b / a, scale_min, scale_max)
     high_res_objective = (2 * scalings * b) - (np.square(scalings) * a) - (1 / amplitude_variance)
     return high_res_objective, scalings
+
diff --git a/src/spikeinterface/sortingcomponents/tests/test_template_matching.py b/src/spikeinterface/sortingcomponents/tests/test_template_matching.py
index 0b3c979417..257a2dbecf 100644
--- a/src/spikeinterface/sortingcomponents/tests/test_template_matching.py
+++ b/src/spikeinterface/sortingcomponents/tests/test_template_matching.py
@@ -9,8 +9,8 @@
 from spikeinterface.sortingcomponents.tests.common import make_dataset
 
 
-# job_kwargs = dict(n_jobs=-1, chunk_duration="500ms", progress_bar=True)
-job_kwargs = dict(n_jobs=1, chunk_duration="500ms", progress_bar=True)
+job_kwargs = dict(n_jobs=-1, chunk_duration="500ms", progress_bar=True)
+# job_kwargs = dict(n_jobs=1, chunk_duration="500ms", progress_bar=True)
 
 
 def get_sorting_analyzer():
@@ -52,39 +52,36 @@ def test_find_spikes_from_templates(method, sorting_analyzer):
     #     "nafter": waveform_extractor.nafter,
     # }
 
-    sampling_frequency = recording.get_sampling_frequency()
+    method_kwargs.update(method_kwargs_all)
+    spikes = find_spikes_from_templates(recording, method=method, method_kwargs=method_kwargs, **job_kwargs)
 
-    method_kwargs_ = method_kwargs.get(method, {})
-    method_kwargs_.update(method_kwargs_all)
-    spikes = find_spikes_from_templates(recording, method=method, method_kwargs=method_kwargs_, **job_kwargs)
+    # DEBUG = True
 
-    DEBUG = True
+    # if DEBUG:
+    #     import matplotlib.pyplot as plt
+    #     import spikeinterface.full as si
 
-    if DEBUG:
-        import matplotlib.pyplot as plt
-        import spikeinterface.full as si
+    #     sorting_analyzer.compute("waveforms")
+    #     sorting_analyzer.compute("templates")
 
-        sorting_analyzer.compute("waveforms")
-        sorting_analyzer.compute("templates")
+    #     gt_sorting = sorting_analyzer.sorting
 
-        gt_sorting = sorting_analyzer.sorting
+    #     sorting = NumpySorting.from_times_labels(spikes["sample_index"], spikes["cluster_index"], sampling_frequency)
 
-        sorting = NumpySorting.from_times_labels(spikes["sample_index"], spikes["cluster_index"], sampling_frequency)
+    #     ##metrics = si.compute_quality_metrics(sorting_analyzer, metric_names=["snr"])
 
-        ##metrics = si.compute_quality_metrics(sorting_analyzer, metric_names=["snr"])
-
-        fig, ax = plt.subplots()
-        comp = si.compare_sorter_to_ground_truth(gt_sorting, sorting)
-        si.plot_agreement_matrix(comp, ax=ax)
-        ax.set_title(method)
-        plt.show()
+    #     fig, ax = plt.subplots()
+    #     comp = si.compare_sorter_to_ground_truth(gt_sorting, sorting)
+    #     si.plot_agreement_matrix(comp, ax=ax)
+    #     ax.set_title(method)
+    #     plt.show()
 
 
 if __name__ == "__main__":
     sorting_analyzer = get_sorting_analyzer()
     # method = "naive"
     # method = "tdc-peeler"
-    # method =  "circus"
-    method = "circus-omp-svd"
+    method =  "circus"
+    # method = "circus-omp-svd"
     # method = "wobble"
     test_find_spikes_from_templates(method, sorting_analyzer)

From a5d8c1db11182b31a3a98d2fe7cc41fe2ee9ca03 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Sat, 28 Sep 2024 16:54:39 +0200
Subject: [PATCH 050/344] Improve IBL recording extractor with PID

---
 .../extractors/iblextractors.py               | 31 ++++++++++++-------
 1 file changed, 19 insertions(+), 12 deletions(-)

diff --git a/src/spikeinterface/extractors/iblextractors.py b/src/spikeinterface/extractors/iblextractors.py
index 5dd549347d..317ea21cce 100644
--- a/src/spikeinterface/extractors/iblextractors.py
+++ b/src/spikeinterface/extractors/iblextractors.py
@@ -105,6 +105,8 @@ def get_stream_names(eid: str, cache_folder: Optional[Union[Path, str]] = None,
             An instance of the ONE API to use for data loading.
             If not provided, a default instance is created using the default parameters.
             If you need to use a specific instance, you can create it using the ONE API and pass it here.
+        stream_type : "ap" | "lf" | None, default: None
+            The stream type to load, required when pid is provided and stream_name is not.
 
         Returns
         -------
@@ -140,6 +142,7 @@ def __init__(
         remove_cached: bool = True,
         stream: bool = True,
         one: "one.api.OneAlyx" = None,
+        stream_type: str | None = None,
     ):
         try:
             from brainbox.io.one import SpikeSortingLoader
@@ -154,20 +157,24 @@ def __init__(
             one = IblRecordingExtractor._get_default_one(cache_folder=cache_folder)
 
         if pid is not None:
+            assert stream_type is not None, "When providing a PID, you must also provide a stream type."
             eid, _ = one.pid2eid(pid)
-
-        stream_names = IblRecordingExtractor.get_stream_names(eid=eid, cache_folder=cache_folder, one=one)
-        if len(stream_names) > 1:
-            assert (
-                stream_name is not None
-            ), f"Multiple streams found for session. Please specify a stream name from {stream_names}."
-            assert stream_name in stream_names, (
-                f"The `stream_name` '{stream_name}' is not available for this experiment {eid}! "
-                f"Please choose one of {stream_names}."
-            )
+            pids, probes = one.eid2pid(eid)
+            pname = probes[pids.index(pid)]
+            stream_name = f"{pname}.{stream_type}"
         else:
-            stream_name = stream_names[0]
-        pname, stream_type = stream_name.split(".")
+            stream_names = IblRecordingExtractor.get_stream_names(eid=eid, cache_folder=cache_folder, one=one)
+            if len(stream_names) > 1:
+                assert (
+                    stream_name is not None
+                ), f"Multiple streams found for session. Please specify a stream name from {stream_names}."
+                assert stream_name in stream_names, (
+                    f"The `stream_name` '{stream_name}' is not available for this experiment {eid}! "
+                    f"Please choose one of {stream_names}."
+                )
+            else:
+                stream_name = stream_names[0]
+            pname, stream_type = stream_name.split(".")
 
         self.ssl = SpikeSortingLoader(one=one, eid=eid, pid=pid, pname=pname)
         if pid is None:

From d9b169d1337cfd8ead75d3e8bf842045707c3a13 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Sat, 28 Sep 2024 16:58:30 +0200
Subject: [PATCH 051/344] Improve IBL recording extractors by PID

---
 .../extractors/iblextractors.py               | 31 ++++++++++++-------
 1 file changed, 19 insertions(+), 12 deletions(-)

diff --git a/src/spikeinterface/extractors/iblextractors.py b/src/spikeinterface/extractors/iblextractors.py
index 5dd549347d..317ea21cce 100644
--- a/src/spikeinterface/extractors/iblextractors.py
+++ b/src/spikeinterface/extractors/iblextractors.py
@@ -105,6 +105,8 @@ def get_stream_names(eid: str, cache_folder: Optional[Union[Path, str]] = None,
             An instance of the ONE API to use for data loading.
             If not provided, a default instance is created using the default parameters.
             If you need to use a specific instance, you can create it using the ONE API and pass it here.
+        stream_type : "ap" | "lf" | None, default: None
+            The stream type to load, required when pid is provided and stream_name is not.
 
         Returns
         -------
@@ -140,6 +142,7 @@ def __init__(
         remove_cached: bool = True,
         stream: bool = True,
         one: "one.api.OneAlyx" = None,
+        stream_type: str | None = None,
     ):
         try:
             from brainbox.io.one import SpikeSortingLoader
@@ -154,20 +157,24 @@ def __init__(
             one = IblRecordingExtractor._get_default_one(cache_folder=cache_folder)
 
         if pid is not None:
+            assert stream_type is not None, "When providing a PID, you must also provide a stream type."
             eid, _ = one.pid2eid(pid)
-
-        stream_names = IblRecordingExtractor.get_stream_names(eid=eid, cache_folder=cache_folder, one=one)
-        if len(stream_names) > 1:
-            assert (
-                stream_name is not None
-            ), f"Multiple streams found for session. Please specify a stream name from {stream_names}."
-            assert stream_name in stream_names, (
-                f"The `stream_name` '{stream_name}' is not available for this experiment {eid}! "
-                f"Please choose one of {stream_names}."
-            )
+            pids, probes = one.eid2pid(eid)
+            pname = probes[pids.index(pid)]
+            stream_name = f"{pname}.{stream_type}"
         else:
-            stream_name = stream_names[0]
-        pname, stream_type = stream_name.split(".")
+            stream_names = IblRecordingExtractor.get_stream_names(eid=eid, cache_folder=cache_folder, one=one)
+            if len(stream_names) > 1:
+                assert (
+                    stream_name is not None
+                ), f"Multiple streams found for session. Please specify a stream name from {stream_names}."
+                assert stream_name in stream_names, (
+                    f"The `stream_name` '{stream_name}' is not available for this experiment {eid}! "
+                    f"Please choose one of {stream_names}."
+                )
+            else:
+                stream_name = stream_names[0]
+            pname, stream_type = stream_name.split(".")
 
         self.ssl = SpikeSortingLoader(one=one, eid=eid, pid=pid, pname=pname)
         if pid is None:

From 2300efeb89f601e382731b78e28738d6a93292f3 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Sat, 28 Sep 2024 16:59:38 +0200
Subject: [PATCH 052/344] oups

---
 src/spikeinterface/core/node_pipeline.py              | 3 ++-
 src/spikeinterface/sortingcomponents/matching/base.py | 6 +++---
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/src/spikeinterface/core/node_pipeline.py b/src/spikeinterface/core/node_pipeline.py
index 2b361a29bd..057bd9d683 100644
--- a/src/spikeinterface/core/node_pipeline.py
+++ b/src/spikeinterface/core/node_pipeline.py
@@ -96,7 +96,7 @@ def compute(self, traces, start_frame, end_frame, segment_index, max_margin, *ar
 
 
 class PeakSource(PipelineNode):
-    # base class for peak detector or template matching
+    
     def get_trace_margin(self):
         raise NotImplementedError
 
@@ -106,6 +106,7 @@ def get_dtype(self):
 
 # this is used in sorting components
 class PeakDetector(PeakSource):
+    # base class for peak detector or template matching
     pass
 
 
diff --git a/src/spikeinterface/sortingcomponents/matching/base.py b/src/spikeinterface/sortingcomponents/matching/base.py
index 97e6e5be9b..8dccd7251f 100644
--- a/src/spikeinterface/sortingcomponents/matching/base.py
+++ b/src/spikeinterface/sortingcomponents/matching/base.py
@@ -1,6 +1,6 @@
 import numpy as np
 from spikeinterface.core import Templates
-from spikeinterface.core.node_pipeline import PeakSource
+from spikeinterface.core.node_pipeline import PeakDetector
 
 _base_matching_dtype = [
     ("sample_index", "int64"),
@@ -10,7 +10,7 @@
     ("segment_index", "int64"),
 ]
 
-class BaseTemplateMatching(PeakSource):
+class BaseTemplateMatching(PeakDetector):
     def __init__(self, recording, templates, return_output=True, parents=None):
         # TODO make a sharedmem of template here
         # TODO maybe check that channel_id are the same with recording
@@ -19,7 +19,7 @@ def __init__(self, recording, templates, return_output=True, parents=None):
             f"The templates supplied is of type {type(templates)} and must be a Templates"
         )
         self.templates = templates
-        PeakSource.__init__(self, recording, return_output=return_output, parents=parents)
+        PeakDetector.__init__(self, recording, return_output=return_output, parents=parents)
 
     def get_dtype(self):
         return np.dtype(_base_matching_dtype)

From f220263d4035c3a1679104c8e1c3d53e40dea74d Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Mon, 30 Sep 2024 13:29:41 +0200
Subject: [PATCH 053/344] put back extra_outputs in
 find_spikes_from_templates()

---
 .../clustering/clustering_tools.py            | 16 +++--------
 .../sortingcomponents/matching/base.py        |  6 ++++-
 .../sortingcomponents/matching/circus.py      | 27 ++++++++++++++++++-
 .../sortingcomponents/matching/main.py        | 10 +++----
 .../tests/test_template_matching.py           | 11 +++++---
 5 files changed, 45 insertions(+), 25 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/clustering/clustering_tools.py b/src/spikeinterface/sortingcomponents/clustering/clustering_tools.py
index 234be686d0..d93a4c257d 100644
--- a/src/spikeinterface/sortingcomponents/clustering/clustering_tools.py
+++ b/src/spikeinterface/sortingcomponents/clustering/clustering_tools.py
@@ -602,21 +602,11 @@ def detect_mixtures(templates, method_kwargs={}, job_kwargs={}, tmp_folder=None,
 
             sub_recording = recording.frame_slice(t_start, t_stop)
             local_params.update({"ignore_inds": ignore_inds + [i]})
-            spikes, computed = find_spikes_from_templates(
+            
+            spikes, more_outputs = find_spikes_from_templates(
                 sub_recording, method="circus-omp-svd", method_kwargs=local_params, extra_outputs=True, **job_kwargs
             )
-            local_params.update(
-                {
-                    "overlaps": computed["overlaps"],
-                    "normed_templates": computed["normed_templates"],
-                    "norms": computed["norms"],
-                    "temporal": computed["temporal"],
-                    "spatial": computed["spatial"],
-                    "singular": computed["singular"],
-                    "units_overlaps": computed["units_overlaps"],
-                    "unit_overlaps_indices": computed["unit_overlaps_indices"],
-                }
-            )
+            local_params["precomputed"] = more_outputs
             valid = (spikes["sample_index"] >= 0) * (spikes["sample_index"] < duration + 2 * margin)
 
             if np.sum(valid) > 0:
diff --git a/src/spikeinterface/sortingcomponents/matching/base.py b/src/spikeinterface/sortingcomponents/matching/base.py
index 8dccd7251f..8921db8c24 100644
--- a/src/spikeinterface/sortingcomponents/matching/base.py
+++ b/src/spikeinterface/sortingcomponents/matching/base.py
@@ -28,4 +28,8 @@ def get_trace_margin(self):
         raise NotImplementedError  
 
     def compute(self, traces, start_frame, end_frame, segment_index, max_margin, *args):
-        raise NotImplementedError    
\ No newline at end of file
+        raise NotImplementedError
+    
+    def get_extra_outputs(self):
+        # can be overwritten if need to ouput some variables with a dict
+        return None
\ No newline at end of file
diff --git a/src/spikeinterface/sortingcomponents/matching/circus.py b/src/spikeinterface/sortingcomponents/matching/circus.py
index 79f12ba0ac..48d85b8c1c 100644
--- a/src/spikeinterface/sortingcomponents/matching/circus.py
+++ b/src/spikeinterface/sortingcomponents/matching/circus.py
@@ -120,6 +120,17 @@ class CircusOMPSVDPeeler(BaseTemplateMatching):
         of template temporal width)
     -----
     """
+
+    _more_output_keys = [
+                "norms",
+                "temporal",
+                "spatial",
+                "singular",
+                "units_overlaps",
+                "unit_overlaps_indices",
+                "normed_templates",
+            ]
+
     def __init__(self, recording, return_output=True, parents=None,
         templates=None,
         amplitudes=[0.6, np.inf],
@@ -130,6 +141,7 @@ def __init__(self, recording, return_output=True, parents=None,
         rank=5,
         ignore_inds=[],
         vicinity=3,
+        precomputed=None,
         ):
 
         BaseTemplateMatching.__init__(self, recording, templates, return_output=True, parents=None)
@@ -162,7 +174,12 @@ def __init__(self, recording, return_output=True, parents=None,
         #         "unit_overlaps_indices",
         #     ]:
         #         assert d[key] is not None, "If templates are provided, %d should also be there" % key
-        self._prepare_templates()
+        if precomputed is None:
+            self._prepare_templates()
+        else:
+            for key in self._more_output_keys:
+                assert precomputed[key] is not None, "If templates are provided, %d should also be there" % key
+                setattr(self, key, precomputed[key])
 
         
         self.ignore_inds = np.array(ignore_inds)
@@ -245,6 +262,14 @@ def _prepare_templates(self):
         self.temporal = np.moveaxis(self.temporal, [0, 1, 2], [1, 2, 0])
         self.singular = self.singular.T[:, :, np.newaxis]
 
+    def get_extra_outputs(self):
+        output = {}
+        for key in self._more_output_keys:
+            output[key] = getattr(self, key)
+        return output
+
+
+
 
     def get_trace_margin(self):
         return self.margin    
diff --git a/src/spikeinterface/sortingcomponents/matching/main.py b/src/spikeinterface/sortingcomponents/matching/main.py
index b1fdaaf15f..2af170a75e 100644
--- a/src/spikeinterface/sortingcomponents/matching/main.py
+++ b/src/spikeinterface/sortingcomponents/matching/main.py
@@ -25,7 +25,7 @@ def find_spikes_from_templates(
     method_kwargs : dict, optional
         Keyword arguments for the chosen method
     extra_outputs : bool
-        If True then method_kwargs is also returned
+        If True then a dict is also returned is also returned
     **job_kwargs : dict
         Parameters for ChunkRecordingExecutor
     verbose : Bool, default: False
@@ -35,9 +35,8 @@ def find_spikes_from_templates(
     -------
     spikes : ndarray
         Spikes found from templates.
-    method_kwargs:
+    outputs:
         Optionaly returns for debug purpose.
-
     """
     from .method_list import matching_methods
 
@@ -58,9 +57,8 @@ def find_spikes_from_templates(
         squeeze_output=True,
     )
     if extra_outputs:
-        # TODO deprecated extra_outputs
-        method_kwargs = {}
-        return spikes, method_kwargs
+        outputs = node0.get_extra_outputs()
+        return spikes, outputs
     else:
         return spikes
 
diff --git a/src/spikeinterface/sortingcomponents/tests/test_template_matching.py b/src/spikeinterface/sortingcomponents/tests/test_template_matching.py
index 257a2dbecf..b970e45514 100644
--- a/src/spikeinterface/sortingcomponents/tests/test_template_matching.py
+++ b/src/spikeinterface/sortingcomponents/tests/test_template_matching.py
@@ -53,7 +53,10 @@ def test_find_spikes_from_templates(method, sorting_analyzer):
     # }
 
     method_kwargs.update(method_kwargs_all)
-    spikes = find_spikes_from_templates(recording, method=method, method_kwargs=method_kwargs, **job_kwargs)
+    spikes, info = find_spikes_from_templates(recording, method=method, 
+                                              method_kwargs=method_kwargs, extra_outputs=True, **job_kwargs)
+
+    # print(info)
 
     # DEBUG = True
 
@@ -66,7 +69,7 @@ def test_find_spikes_from_templates(method, sorting_analyzer):
 
     #     gt_sorting = sorting_analyzer.sorting
 
-    #     sorting = NumpySorting.from_times_labels(spikes["sample_index"], spikes["cluster_index"], sampling_frequency)
+    #     sorting = NumpySorting.from_times_labels(spikes["sample_index"], spikes["cluster_index"], recording.sampling_frequency)
 
     #     ##metrics = si.compute_quality_metrics(sorting_analyzer, metric_names=["snr"])
 
@@ -81,7 +84,7 @@ def test_find_spikes_from_templates(method, sorting_analyzer):
     sorting_analyzer = get_sorting_analyzer()
     # method = "naive"
     # method = "tdc-peeler"
-    method =  "circus"
-    # method = "circus-omp-svd"
+    # method =  "circus"
+    method = "circus-omp-svd"
     # method = "wobble"
     test_find_spikes_from_templates(method, sorting_analyzer)

From ed7e636ff75e9f01cc8104ec1e2e3830f81086cb Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Mon, 30 Sep 2024 14:38:06 +0200
Subject: [PATCH 054/344] matching handle segment_index

---
 src/spikeinterface/sortingcomponents/matching/circus.py | 4 ++++
 src/spikeinterface/sortingcomponents/matching/naive.py  | 2 ++
 src/spikeinterface/sortingcomponents/matching/tdc.py    | 4 +++-
 src/spikeinterface/sortingcomponents/matching/wobble.py | 3 ++-
 4 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/matching/circus.py b/src/spikeinterface/sortingcomponents/matching/circus.py
index 48d85b8c1c..e8179fdb11 100644
--- a/src/spikeinterface/sortingcomponents/matching/circus.py
+++ b/src/spikeinterface/sortingcomponents/matching/circus.py
@@ -477,6 +477,8 @@ def compute(self, traces, start_frame, end_frame, segment_index, max_margin, *ar
         spikes = spikes[:num_spikes]
         order = np.argsort(spikes["sample_index"])
         spikes = spikes[order]
+        
+        spikes["segment_index"] = segment_index
 
         return spikes
 
@@ -1105,6 +1107,8 @@ def compute(self, traces, start_frame, end_frame, segment_index, max_margin, *ar
         order = np.argsort(spikes["sample_index"])
         spikes = spikes[order]
 
+        spikes["segment_index"] = segment_index
+        
         return spikes
 
 
diff --git a/src/spikeinterface/sortingcomponents/matching/naive.py b/src/spikeinterface/sortingcomponents/matching/naive.py
index 6cd6cecab7..0cff30bd22 100644
--- a/src/spikeinterface/sortingcomponents/matching/naive.py
+++ b/src/spikeinterface/sortingcomponents/matching/naive.py
@@ -78,6 +78,8 @@ def compute(self, traces, start_frame, end_frame, segment_index, max_margin, *ar
             spikes["cluster_index"][i] = cluster_index
             spikes["amplitude"][i] = 0.0
 
+        spikes["segment_index"] = segment_index
+        
         return spikes
     
         
diff --git a/src/spikeinterface/sortingcomponents/matching/tdc.py b/src/spikeinterface/sortingcomponents/matching/tdc.py
index c43808c2a7..0a74ecf056 100644
--- a/src/spikeinterface/sortingcomponents/matching/tdc.py
+++ b/src/spikeinterface/sortingcomponents/matching/tdc.py
@@ -186,6 +186,8 @@ def compute(self, traces, start_frame, end_frame, segment_index, max_margin, *ar
         else:
             all_spikes = np.zeros(0, dtype=_base_matching_dtype)
 
+        all_spikes["segment_index"] = segment_index
+
         return all_spikes
 
     def _find_spikes_one_level(self, traces, level=0):
@@ -307,7 +309,7 @@ def _find_spikes_one_level(self, traces, level=0):
 
             spikes["cluster_index"][i] = cluster_index
             spikes["amplitude"][i] = amplitude
-
+        
         return spikes
 
 
diff --git a/src/spikeinterface/sortingcomponents/matching/wobble.py b/src/spikeinterface/sortingcomponents/matching/wobble.py
index 1a23992485..e8e1d57f8e 100644
--- a/src/spikeinterface/sortingcomponents/matching/wobble.py
+++ b/src/spikeinterface/sortingcomponents/matching/wobble.py
@@ -450,7 +450,8 @@ def compute(self, traces, start_frame, end_frame, segment_index, max_margin, *ar
         spikes["cluster_index"] = spike_train[:, 1]
         spikes["channel_index"] = channel_inds
         spikes["amplitude"] = amplitudes
-
+        spikes["segment_index"] = segment_index
+        
         return spikes
 
     # TODO: Replace this method with equivalent from spikeinterface

From e782cbbe0f39916fa4b3ccfd8edb7874776b35ec Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Mon, 30 Sep 2024 15:07:17 +0200
Subject: [PATCH 055/344] oups : spikes in margin

---
 .../sortingcomponents/matching/base.py              | 13 ++++++++++++-
 .../sortingcomponents/matching/circus.py            |  8 ++------
 .../sortingcomponents/matching/naive.py             |  4 +---
 .../sortingcomponents/matching/tdc.py               |  4 +---
 .../sortingcomponents/matching/wobble.py            |  5 ++---
 .../tests/test_template_matching.py                 |  2 +-
 6 files changed, 19 insertions(+), 17 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/matching/base.py b/src/spikeinterface/sortingcomponents/matching/base.py
index 8921db8c24..d25e751ff8 100644
--- a/src/spikeinterface/sortingcomponents/matching/base.py
+++ b/src/spikeinterface/sortingcomponents/matching/base.py
@@ -27,7 +27,18 @@ def get_dtype(self):
     def get_trace_margin(self):
         raise NotImplementedError  
 
-    def compute(self, traces, start_frame, end_frame, segment_index, max_margin, *args):
+    def compute(self, traces, start_frame, end_frame, segment_index, max_margin):
+        spikes = self.compute_matching(traces, start_frame, end_frame, segment_index)
+        spikes["segment_index"] = segment_index
+
+        margin = self.get_trace_margin()
+        if margin > 0:
+            keep = (spikes["sample_index"] >= margin) & (spikes["sample_index"] < (traces.shape[0] - margin))
+            spikes = spikes[keep]
+
+        return spikes
+
+    def compute_matching(self, traces, start_frame, end_frame, segment_index):
         raise NotImplementedError
     
     def get_extra_outputs(self):
diff --git a/src/spikeinterface/sortingcomponents/matching/circus.py b/src/spikeinterface/sortingcomponents/matching/circus.py
index e8179fdb11..51f5cceacd 100644
--- a/src/spikeinterface/sortingcomponents/matching/circus.py
+++ b/src/spikeinterface/sortingcomponents/matching/circus.py
@@ -274,7 +274,7 @@ def get_extra_outputs(self):
     def get_trace_margin(self):
         return self.margin    
 
-    def compute(self, traces, start_frame, end_frame, segment_index, max_margin, *args):
+    def compute_matching(self, traces, start_frame, end_frame, segment_index):
         import scipy.spatial
         import scipy
 
@@ -478,8 +478,6 @@ def compute(self, traces, start_frame, end_frame, segment_index, max_margin, *ar
         order = np.argsort(spikes["sample_index"])
         spikes = spikes[order]
         
-        spikes["segment_index"] = segment_index
-
         return spikes
 
 
@@ -1024,7 +1022,7 @@ def get_trace_margin(self):
         return self.margin
 
 
-    def compute(self, traces, start_frame, end_frame, segment_index, max_margin, *args):
+    def compute_matching(self, traces, start_frame, end_frame, segment_index):
 
         neighbor_window = self.num_samples - 1
 
@@ -1107,8 +1105,6 @@ def compute(self, traces, start_frame, end_frame, segment_index, max_margin, *ar
         order = np.argsort(spikes["sample_index"])
         spikes = spikes[order]
 
-        spikes["segment_index"] = segment_index
-        
         return spikes
 
 
diff --git a/src/spikeinterface/sortingcomponents/matching/naive.py b/src/spikeinterface/sortingcomponents/matching/naive.py
index 0cff30bd22..2f548b9175 100644
--- a/src/spikeinterface/sortingcomponents/matching/naive.py
+++ b/src/spikeinterface/sortingcomponents/matching/naive.py
@@ -51,7 +51,7 @@ def get_trace_margin(self):
         return self.margin
 
 
-    def compute(self, traces, start_frame, end_frame, segment_index, max_margin, *args):
+    def compute_matching(self, traces, start_frame, end_frame, segment_index):
 
         if self.margin > 0:
             peak_traces = traces[self.margin:-self.margin, :]
@@ -78,8 +78,6 @@ def compute(self, traces, start_frame, end_frame, segment_index, max_margin, *ar
             spikes["cluster_index"][i] = cluster_index
             spikes["amplitude"][i] = 0.0
 
-        spikes["segment_index"] = segment_index
-        
         return spikes
     
         
diff --git a/src/spikeinterface/sortingcomponents/matching/tdc.py b/src/spikeinterface/sortingcomponents/matching/tdc.py
index 0a74ecf056..226b314b6d 100644
--- a/src/spikeinterface/sortingcomponents/matching/tdc.py
+++ b/src/spikeinterface/sortingcomponents/matching/tdc.py
@@ -160,7 +160,7 @@ def __init__(self, recording, return_output=True, parents=None,
     def get_trace_margin(self):
         return self.margin
 
-    def compute(self, traces, start_frame, end_frame, segment_index, max_margin, *args):
+    def compute_matching(self, traces, start_frame, end_frame, segment_index):
         traces = traces.copy()
 
         all_spikes = []
@@ -186,8 +186,6 @@ def compute(self, traces, start_frame, end_frame, segment_index, max_margin, *ar
         else:
             all_spikes = np.zeros(0, dtype=_base_matching_dtype)
 
-        all_spikes["segment_index"] = segment_index
-
         return all_spikes
 
     def _find_spikes_one_level(self, traces, level=0):
diff --git a/src/spikeinterface/sortingcomponents/matching/wobble.py b/src/spikeinterface/sortingcomponents/matching/wobble.py
index e8e1d57f8e..242c35cc84 100644
--- a/src/spikeinterface/sortingcomponents/matching/wobble.py
+++ b/src/spikeinterface/sortingcomponents/matching/wobble.py
@@ -383,7 +383,7 @@ def __init__(self, recording, return_output=True, parents=None,
     def get_trace_margin(self):
         return self.margin
 
-    def compute(self, traces, start_frame, end_frame, segment_index, max_margin, *args):
+    def compute_matching(self, traces, start_frame, end_frame, segment_index):
 
         # Unpack method_kwargs
         # nbefore, nafter = method_kwargs["nbefore"], method_kwargs["nafter"]
@@ -450,8 +450,7 @@ def compute(self, traces, start_frame, end_frame, segment_index, max_margin, *ar
         spikes["cluster_index"] = spike_train[:, 1]
         spikes["channel_index"] = channel_inds
         spikes["amplitude"] = amplitudes
-        spikes["segment_index"] = segment_index
-        
+
         return spikes
 
     # TODO: Replace this method with equivalent from spikeinterface
diff --git a/src/spikeinterface/sortingcomponents/tests/test_template_matching.py b/src/spikeinterface/sortingcomponents/tests/test_template_matching.py
index b970e45514..f23ef007ea 100644
--- a/src/spikeinterface/sortingcomponents/tests/test_template_matching.py
+++ b/src/spikeinterface/sortingcomponents/tests/test_template_matching.py
@@ -77,7 +77,7 @@ def test_find_spikes_from_templates(method, sorting_analyzer):
     #     comp = si.compare_sorter_to_ground_truth(gt_sorting, sorting)
     #     si.plot_agreement_matrix(comp, ax=ax)
     #     ax.set_title(method)
-    #     plt.show()
+        plt.show()
 
 
 if __name__ == "__main__":

From 20af55c80caadec6d75dc80044d6ea357eecc399 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Mon, 30 Sep 2024 17:44:46 +0200
Subject: [PATCH 056/344] Fix reset_global_job_kwargs

---
 src/spikeinterface/core/globals.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/spikeinterface/core/globals.py b/src/spikeinterface/core/globals.py
index 23d60a5ac5..ace71128b9 100644
--- a/src/spikeinterface/core/globals.py
+++ b/src/spikeinterface/core/globals.py
@@ -135,7 +135,9 @@ def reset_global_job_kwargs():
     Reset the global job kwargs.
     """
     global global_job_kwargs
-    global_job_kwargs = dict(n_jobs=1, chunk_duration="1s", progress_bar=True)
+    global_job_kwargs = dict(
+        n_jobs=1, chunk_duration="1s", progress_bar=True, mp_context=None, max_threads_per_process=1
+    )
 
 
 def is_set_global_job_kwargs_set() -> bool:

From e044e19d2b24a0ea6336ab32498149643a4e13d1 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Mon, 30 Sep 2024 17:56:29 +0200
Subject: [PATCH 057/344] Skip saving empty recording files/fields and improve
 warnings and assertions

---
 src/spikeinterface/core/sortinganalyzer.py | 38 ++++++++++++----------
 1 file changed, 21 insertions(+), 17 deletions(-)

diff --git a/src/spikeinterface/core/sortinganalyzer.py b/src/spikeinterface/core/sortinganalyzer.py
index 26313c9892..bf24048c2b 100644
--- a/src/spikeinterface/core/sortinganalyzer.py
+++ b/src/spikeinterface/core/sortinganalyzer.py
@@ -255,6 +255,7 @@ def create(
         sparsity=None,
         return_scaled=True,
     ):
+        assert recording is not None, "To create a SortingAnalyzer you need to specify the recording"
         # some checks
         if sorting.sampling_frequency != recording.sampling_frequency:
             if math.isclose(sorting.sampling_frequency, recording.sampling_frequency, abs_tol=1e-2, rel_tol=1e-5):
@@ -368,7 +369,6 @@ def create_binary_folder(cls, folder, sorting, recording, sparsity, return_scale
             json.dump(check_json(info), f, indent=4)
 
         # save a copy of the sorting
-        # NumpyFolderSorting.write_sorting(sorting, folder / "sorting")
         sorting.save(folder=folder / "sorting")
 
         if recording is not None:
@@ -377,16 +377,20 @@ def create_binary_folder(cls, folder, sorting, recording, sparsity, return_scale
                 recording.dump(folder / "recording.json", relative_to=folder)
             elif recording.check_serializability("pickle"):
                 recording.dump(folder / "recording.pickle", relative_to=folder)
+            else:
+                warnings.warn("The Recording is not serializable! The recording link will be lost for future load")
         else:
             assert rec_attributes is not None, "recording or rec_attributes must be provided"
-            # write an empty recording.json
-            with open(folder / "recording.json", mode="w") as f:
-                json.dump({}, f, indent=4)
+            warnings.warn("Recording not provided, instntiating SortingAnalyzer in recordingless mode.")
 
         if sorting.check_serializability("json"):
             sorting.dump(folder / "sorting_provenance.json", relative_to=folder)
         elif sorting.check_serializability("pickle"):
             sorting.dump(folder / "sorting_provenance.pickle", relative_to=folder)
+        else:
+            warnings.warn(
+                "The sorting provenance is not serializable! The sorting provenance link will be lost for future load"
+            )
 
         # dump recording attributes
         probegroup = None
@@ -535,13 +539,10 @@ def create_zarr(cls, folder, sorting, recording, sparsity, return_scaled, rec_at
                 zarr_rec = np.array([rec_dict], dtype=object)
                 zarr_root.create_dataset("recording", data=zarr_rec, object_codec=numcodecs.Pickle())
             else:
-                warnings.warn(
-                    "SortingAnalyzer with zarr : the Recording is not json serializable, the recording link will be lost for future load"
-                )
+                warnings.warn("The Recording is not serializable! The recording link will be lost for future load")
         else:
             assert rec_attributes is not None, "recording or rec_attributes must be provided"
-            zarr_rec = np.array([{}], dtype=object)
-            zarr_root.create_dataset("recording", data=zarr_rec, object_codec=numcodecs.JSON())
+            warnings.warn("Recording not provided, instntiating SortingAnalyzer in recordingless mode.")
 
         # sorting provenance
         sort_dict = sorting.to_dict(relative_to=folder, recursive=True)
@@ -551,9 +552,10 @@ def create_zarr(cls, folder, sorting, recording, sparsity, return_scaled, rec_at
         elif sorting.check_serializability("pickle"):
             zarr_sort = np.array([sort_dict], dtype=object)
             zarr_root.create_dataset("sorting_provenance", data=zarr_sort, object_codec=numcodecs.Pickle())
-
-        # else:
-        #     warnings.warn("SortingAnalyzer with zarr : the sorting provenance is not json serializable, the sorting provenance link will be lost for futur load")
+        else:
+            warnings.warn(
+                "The sorting provenance is not serializable! The sorting provenance link will be lost for future load"
+            )
 
         recording_info = zarr_root.create_group("recording_info")
 
@@ -614,11 +616,13 @@ def load_from_zarr(cls, folder, recording=None, storage_options=None):
 
         # load recording if possible
         if recording is None:
-            rec_dict = zarr_root["recording"][0]
-            try:
-                recording = load_extractor(rec_dict, base_folder=folder)
-            except:
-                recording = None
+            rec_field = zarr_root.get("recording")
+            if rec_field is not None:
+                rec_dict = rec_field[0]
+                try:
+                    recording = load_extractor(rec_dict, base_folder=folder)
+                except:
+                    recording = None
         else:
             # TODO maybe maybe not??? : do we need to check  attributes match internal rec_attributes
             # Note this will make the loading too slow

From 2838c486fdb60e6f004156250035423dcbd40325 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Mon, 30 Sep 2024 17:58:08 +0200
Subject: [PATCH 058/344] Remove redundant assertions

---
 src/spikeinterface/core/sortinganalyzer.py | 2 --
 1 file changed, 2 deletions(-)

diff --git a/src/spikeinterface/core/sortinganalyzer.py b/src/spikeinterface/core/sortinganalyzer.py
index bf24048c2b..5057b5001e 100644
--- a/src/spikeinterface/core/sortinganalyzer.py
+++ b/src/spikeinterface/core/sortinganalyzer.py
@@ -397,7 +397,6 @@ def create_binary_folder(cls, folder, sorting, recording, sparsity, return_scale
         rec_attributes_file = folder / "recording_info" / "recording_attributes.json"
         rec_attributes_file.parent.mkdir()
         if rec_attributes is None:
-            assert recording is not None
             rec_attributes = get_rec_attributes(recording)
             rec_attributes_file.write_text(json.dumps(check_json(rec_attributes), indent=4), encoding="utf8")
             probegroup = recording.get_probegroup()
@@ -560,7 +559,6 @@ def create_zarr(cls, folder, sorting, recording, sparsity, return_scaled, rec_at
         recording_info = zarr_root.create_group("recording_info")
 
         if rec_attributes is None:
-            assert recording is not None
             rec_attributes = get_rec_attributes(recording)
             probegroup = recording.get_probegroup()
         else:

From 04ebe5ed6360aacca491a39e01002840c4af70fb Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Mon, 30 Sep 2024 18:29:52 +0200
Subject: [PATCH 059/344] Use more general backend_kwargs

---
 src/spikeinterface/core/sortinganalyzer.py    | 68 +++++++++++++------
 .../core/tests/test_sortinganalyzer.py        |  4 +-
 2 files changed, 49 insertions(+), 23 deletions(-)

diff --git a/src/spikeinterface/core/sortinganalyzer.py b/src/spikeinterface/core/sortinganalyzer.py
index 16945008ae..4ffdc8d95a 100644
--- a/src/spikeinterface/core/sortinganalyzer.py
+++ b/src/spikeinterface/core/sortinganalyzer.py
@@ -219,8 +219,9 @@ def __init__(
         # this is used to store temporary recording
         self._temporary_recording = None
 
-        # for zarr format, we store the kwargs to create zarr datasets (e.g., compression)
-        self._zarr_kwargs = {}
+        # backend-specific kwargs for different formats, which can be used to
+        # set some parameters for saving (e.g., compression)
+        self._backend_kwargs = {"binary_folder": {}, "zarr": {}}
 
         # extensions are not loaded at init
         self.extensions = dict()
@@ -352,7 +353,9 @@ def create_memory(cls, sorting, recording, sparsity, return_scaled, rec_attribut
         return sorting_analyzer
 
     @classmethod
-    def create_binary_folder(cls, folder, sorting, recording, sparsity, return_scaled, rec_attributes):
+    def create_binary_folder(
+        cls, folder, sorting, recording, sparsity, return_scaled, rec_attributes, **binary_format_kwargs
+    ):
         # used by create and save_as
 
         assert recording is not None, "To create a SortingAnalyzer you need to specify the recording"
@@ -571,8 +574,6 @@ def create_zarr(cls, folder, sorting, recording, sparsity, return_scaled, rec_at
         # write sorting copy
         from .zarrextractors import add_sorting_to_zarr_group
 
-        # Alessio : we need to find a way to propagate compressor for all steps.
-        # kwargs = dict(compressor=...)
         add_sorting_to_zarr_group(sorting, zarr_root.create_group("sorting"), **zarr_kwargs)
 
         recording_info = zarr_root.create_group("extensions")
@@ -648,17 +649,27 @@ def load_from_zarr(cls, folder, recording=None, storage_options=None):
 
         return sorting_analyzer
 
-    def set_zarr_kwargs(self, **zarr_kwargs):
+    @property
+    def backend_kwargs(self):
+        """
+        Returns the backend kwargs for the analyzer.
+        """
+        return self._backend_kwargs.copy()
+
+    @backend_kwargs.setter
+    def backend_kwargs(self, backend_kwargs):
         """
-        Set the zarr kwargs for the zarr datasets. This can be used to specify custom compressors or filters.
-        Note that currently the zarr kwargs will be used for all zarr datasets.
+        Sets the backend kwargs for the analyzer. If the backend kwargs are not set, the default backend kwargs are used.
 
         Parameters
         ----------
-        zarr_kwargs : keyword arguments
+        backend_kwargs : keyword arguments
             The zarr kwargs to set.
         """
-        self._zarr_kwargs = zarr_kwargs
+        for key in backend_kwargs:
+            if key not in ("zarr", "binary_folder"):
+                raise ValueError(f"Unknown backend key: {key}. Available keys are 'zarr' and 'binary_folder'.")
+            self._backend_kwargs[key] = backend_kwargs[key]
 
     def set_temporary_recording(self, recording: BaseRecording, check_dtype: bool = True):
         """
@@ -698,7 +709,8 @@ def _save_or_select_or_merge(
         sparsity_overlap=0.75,
         verbose=False,
         new_unit_ids=None,
-        **kwargs,
+        backend_kwargs=None,
+        **job_kwargs,
     ) -> "SortingAnalyzer":
         """
         Internal method used by both `save_as()`, `copy()`, `select_units()`, and `merge_units()`.
@@ -727,8 +739,10 @@ def _save_or_select_or_merge(
             The new unit ids for merged units. Required if `merge_unit_groups` is not None.
         verbose : bool, default: False
             If True, output is verbose.
-        kwargs : keyword arguments
-            Keyword arguments including job_kwargs and zarr_kwargs.
+        backend_kwargs : dict | None, default: None
+            Keyword arguments for the backend specified by format.
+        job_kwargs : keyword arguments
+            Keyword arguments for the job parallelization.
 
         Returns
         -------
@@ -742,8 +756,6 @@ def _save_or_select_or_merge(
         else:
             recording = None
 
-        zarr_kwargs, job_kwargs = split_job_kwargs(kwargs)
-
         if self.sparsity is not None and unit_ids is None and merge_unit_groups is None:
             sparsity = self.sparsity
         elif self.sparsity is not None and unit_ids is not None and merge_unit_groups is None:
@@ -804,6 +816,8 @@ def _save_or_select_or_merge(
             # TODO: sam/pierre would create a curation field / curation.json with the applied merges.
             # What do you think?
 
+        backend_kwargs = {} if backend_kwargs is None else backend_kwargs
+
         if format == "memory":
             # This make a copy of actual SortingAnalyzer
             new_sorting_analyzer = SortingAnalyzer.create_memory(
@@ -814,8 +828,15 @@ def _save_or_select_or_merge(
             # create  a new folder
             assert folder is not None, "For format='binary_folder' folder must be provided"
             folder = Path(folder)
+            binary_format_kwargs = backend_kwargs
             SortingAnalyzer.create_binary_folder(
-                folder, sorting_provenance, recording, sparsity, self.return_scaled, self.rec_attributes
+                folder,
+                sorting_provenance,
+                recording,
+                sparsity,
+                self.return_scaled,
+                self.rec_attributes,
+                **binary_format_kwargs,
             )
             new_sorting_analyzer = SortingAnalyzer.load_from_binary_folder(folder, recording=recording)
             new_sorting_analyzer.folder = folder
@@ -823,15 +844,18 @@ def _save_or_select_or_merge(
         elif format == "zarr":
             assert folder is not None, "For format='zarr' folder must be provided"
             folder = clean_zarr_folder_name(folder)
+            zarr_kwargs = backend_kwargs
             SortingAnalyzer.create_zarr(
                 folder, sorting_provenance, recording, sparsity, self.return_scaled, self.rec_attributes, **zarr_kwargs
             )
             new_sorting_analyzer = SortingAnalyzer.load_from_zarr(folder, recording=recording)
             new_sorting_analyzer.folder = folder
-            new_sorting_analyzer.set_zarr_kwargs(**zarr_kwargs)
         else:
             raise ValueError(f"SortingAnalyzer.save: unsupported format: {format}")
 
+        if format != "memory":
+            new_sorting_analyzer.backend_kwargs = {format: backend_kwargs}
+
         # make a copy of extensions
         # note that the copy of extension handle itself the slicing of units when necessary and also the saveing
         sorted_extensions = _sort_extensions_by_dependency(self.extensions)
@@ -866,7 +890,7 @@ def _save_or_select_or_merge(
 
         return new_sorting_analyzer
 
-    def save_as(self, format="memory", folder=None, **zarr_kwargs) -> "SortingAnalyzer":
+    def save_as(self, format="memory", folder=None, backend_kwargs=None) -> "SortingAnalyzer":
         """
         Save SortingAnalyzer object into another format.
         Uselful for memory to zarr or memory to binary.
@@ -881,11 +905,13 @@ def save_as(self, format="memory", folder=None, **zarr_kwargs) -> "SortingAnalyz
             The output folder if `format` is "zarr" or "binary_folder"
         format : "memory" | "binary_folder" | "zarr", default: "memory"
             The new backend format to use
-        zarr_kwargs : keyword arguments for zarr format
+        backend_kwargs : dict | None, default: None
+            Backend-specific kwargs for the specified format, which can be used to set some parameters for saving.
+            For example, if `format` is "zarr", one can set the compressor for the zarr datasets with `backend_kwargs={"compressor": some_compressor}`.
         """
         if format == "zarr":
             folder = clean_zarr_folder_name(folder)
-        return self._save_or_select_or_merge(format=format, folder=folder, **zarr_kwargs)
+        return self._save_or_select_or_merge(format=format, folder=folder, backend_kwargs=backend_kwargs)
 
     def select_units(self, unit_ids, format="memory", folder=None) -> "SortingAnalyzer":
         """
@@ -2128,7 +2154,7 @@ def _save_data(self):
         elif self.format == "zarr":
             import numcodecs
 
-            zarr_kwargs = self.sorting_analyzer._zarr_kwargs
+            zarr_kwargs = self.sorting_analyzer.backend_kwargs.get("zarr", {})
             extension_group = self._get_zarr_extension_group(mode="r+")
 
             # if compression is not externally given, we use the default
diff --git a/src/spikeinterface/core/tests/test_sortinganalyzer.py b/src/spikeinterface/core/tests/test_sortinganalyzer.py
index 53e28fe083..f2aa7f459d 100644
--- a/src/spikeinterface/core/tests/test_sortinganalyzer.py
+++ b/src/spikeinterface/core/tests/test_sortinganalyzer.py
@@ -138,7 +138,7 @@ def test_SortingAnalyzer_zarr(tmp_path, dataset):
         return_scaled=False,
         overwrite=True,
     )
-    sorting_analyzer_no_compression.set_zarr_kwargs(compressor=None)
+    sorting_analyzer_no_compression.backend_kwargs = {"zarr": dict(compressor=None)}
     sorting_analyzer_no_compression.compute(["random_spikes", "templates"])
     assert (
         sorting_analyzer_no_compression._get_zarr_root()["extensions"]["random_spikes"][
@@ -154,7 +154,7 @@ def test_SortingAnalyzer_zarr(tmp_path, dataset):
     lzma_compressor = LZMA()
     folder = tmp_path / "test_SortingAnalyzer_zarr_lzma.zarr"
     sorting_analyzer_lzma = sorting_analyzer_no_compression.save_as(
-        format="zarr", folder=folder, compressor=lzma_compressor
+        format="zarr", folder=folder, backend_kwargs=dict(compressor=lzma_compressor)
     )
     assert (
         sorting_analyzer_lzma._get_zarr_root()["extensions"]["random_spikes"][

From c3386588be23d388360d279a012cd29d462d1c35 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Mon, 30 Sep 2024 18:59:49 +0200
Subject: [PATCH 060/344] further relaxation of causal_filter equality
 tests....

---
 src/spikeinterface/preprocessing/tests/test_filter.py | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/spikeinterface/preprocessing/tests/test_filter.py b/src/spikeinterface/preprocessing/tests/test_filter.py
index 56e238fc54..bf723c84b9 100644
--- a/src/spikeinterface/preprocessing/tests/test_filter.py
+++ b/src/spikeinterface/preprocessing/tests/test_filter.py
@@ -46,7 +46,7 @@ def test_causal_filter_main_kwargs(self, recording_and_data):
 
         filt_data = causal_filter(recording, direction="forward", **options, margin_ms=0).get_traces()
 
-        assert np.allclose(test_data, filt_data, rtol=0, atol=1e-4)
+        assert np.allclose(test_data, filt_data, rtol=0, atol=1e-2)
 
         # Then, change all kwargs to ensure they are propagated
         # and check the backwards version.
@@ -66,7 +66,7 @@ def test_causal_filter_main_kwargs(self, recording_and_data):
 
         filt_data = causal_filter(recording, direction="backward", **options, margin_ms=0).get_traces()
 
-        assert np.allclose(test_data, filt_data, rtol=0, atol=1e-4)
+        assert np.allclose(test_data, filt_data, rtol=0, atol=1e-2)
 
     def test_causal_filter_custom_coeff(self, recording_and_data):
         """
@@ -89,7 +89,7 @@ def test_causal_filter_custom_coeff(self, recording_and_data):
 
         filt_data = causal_filter(recording, direction="forward", **options, margin_ms=0).get_traces()
 
-        assert np.allclose(test_data, filt_data, rtol=0, atol=1e-4, equal_nan=True)
+        assert np.allclose(test_data, filt_data, rtol=0, atol=1e-2, equal_nan=True)
 
         # Next, in "sos" mode
         options["filter_mode"] = "sos"
@@ -100,7 +100,7 @@ def test_causal_filter_custom_coeff(self, recording_and_data):
 
         filt_data = causal_filter(recording, direction="forward", **options, margin_ms=0).get_traces()
 
-        assert np.allclose(test_data, filt_data, rtol=0, atol=1e-3, equal_nan=True)
+        assert np.allclose(test_data, filt_data, rtol=0, atol=1e-2, equal_nan=True)
 
     def test_causal_kwarg_error_raised(self, recording_and_data):
         """

From 66a3ea456be5572f6c2e96ad1d59e2fadad409ac Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Tue, 1 Oct 2024 10:17:28 +0200
Subject: [PATCH 061/344] Add _default_job_kwargs

---
 src/spikeinterface/core/globals.py | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/spikeinterface/core/globals.py b/src/spikeinterface/core/globals.py
index ace71128b9..38f39c5481 100644
--- a/src/spikeinterface/core/globals.py
+++ b/src/spikeinterface/core/globals.py
@@ -97,8 +97,10 @@ def is_set_global_dataset_folder() -> bool:
 
 
 ########################################
+_default_job_kwargs = dict(n_jobs=1, chunk_duration="1s", progress_bar=True, mp_context=None, max_threads_per_process=1)
+
 global global_job_kwargs
-global_job_kwargs = dict(n_jobs=1, chunk_duration="1s", progress_bar=True, mp_context=None, max_threads_per_process=1)
+global_job_kwargs = _default_job_kwargs.copy()
 global global_job_kwargs_set
 global_job_kwargs_set = False
 
@@ -135,9 +137,7 @@ def reset_global_job_kwargs():
     Reset the global job kwargs.
     """
     global global_job_kwargs
-    global_job_kwargs = dict(
-        n_jobs=1, chunk_duration="1s", progress_bar=True, mp_context=None, max_threads_per_process=1
-    )
+    global_job_kwargs = _default_job_kwargs.copy()
 
 
 def is_set_global_job_kwargs_set() -> bool:

From 022f924f1b4a7527e6c5a4b8d0ef4a68bf0e6a6c Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Tue, 1 Oct 2024 11:05:01 +0200
Subject: [PATCH 062/344] Use backend_options for storage/saving_options

---
 src/spikeinterface/core/sortinganalyzer.py    | 185 ++++++++++--------
 .../core/tests/test_sortinganalyzer.py        |   5 +-
 2 files changed, 107 insertions(+), 83 deletions(-)

diff --git a/src/spikeinterface/core/sortinganalyzer.py b/src/spikeinterface/core/sortinganalyzer.py
index 4ffdc8d95a..10c5d8d475 100644
--- a/src/spikeinterface/core/sortinganalyzer.py
+++ b/src/spikeinterface/core/sortinganalyzer.py
@@ -11,6 +11,7 @@
 import shutil
 import warnings
 import importlib
+from copy import copy
 from packaging.version import parse
 from time import perf_counter
 
@@ -45,6 +46,7 @@ def create_sorting_analyzer(
     sparsity=None,
     return_scaled=True,
     overwrite=False,
+    backend_options=None,
     **sparsity_kwargs,
 ) -> "SortingAnalyzer":
     """
@@ -80,7 +82,12 @@ def create_sorting_analyzer(
         This prevent return_scaled being differents from different extensions and having wrong snr for instance.
     overwrite: bool, default: False
         If True, overwrite the folder if it already exists.
-
+    backend_options : dict | None, default: None
+        Keyword arguments for the backend specified by format. It can contain the:
+        - storage_options: dict | None (fsspec storage options)
+        - saving_options: dict | None (additional saving options for creating and saving datasets,
+                                       e.g. compression/filters for zarr)
+    sparsity_kwargs : keyword arguments
 
     Returns
     -------
@@ -144,13 +151,19 @@ def create_sorting_analyzer(
         return_scaled = False
 
     sorting_analyzer = SortingAnalyzer.create(
-        sorting, recording, format=format, folder=folder, sparsity=sparsity, return_scaled=return_scaled
+        sorting,
+        recording,
+        format=format,
+        folder=folder,
+        sparsity=sparsity,
+        return_scaled=return_scaled,
+        backend_options=backend_options,
     )
 
     return sorting_analyzer
 
 
-def load_sorting_analyzer(folder, load_extensions=True, format="auto", storage_options=None) -> "SortingAnalyzer":
+def load_sorting_analyzer(folder, load_extensions=True, format="auto", backend_options=None) -> "SortingAnalyzer":
     """
     Load a SortingAnalyzer object from disk.
 
@@ -172,7 +185,7 @@ def load_sorting_analyzer(folder, load_extensions=True, format="auto", storage_o
         The loaded SortingAnalyzer
 
     """
-    return SortingAnalyzer.load(folder, load_extensions=load_extensions, format=format, storage_options=storage_options)
+    return SortingAnalyzer.load(folder, load_extensions=load_extensions, format=format, backend_options=backend_options)
 
 
 class SortingAnalyzer:
@@ -205,7 +218,7 @@ def __init__(
         format=None,
         sparsity=None,
         return_scaled=True,
-        storage_options=None,
+        backend_options=None,
     ):
         # very fast init because checks are done in load and create
         self.sorting = sorting
@@ -215,13 +228,17 @@ def __init__(
         self.format = format
         self.sparsity = sparsity
         self.return_scaled = return_scaled
-        self.storage_options = storage_options
+
         # this is used to store temporary recording
         self._temporary_recording = None
 
         # backend-specific kwargs for different formats, which can be used to
         # set some parameters for saving (e.g., compression)
-        self._backend_kwargs = {"binary_folder": {}, "zarr": {}}
+        #
+        # - storage_options: dict | None (fsspec storage options)
+        # - saving_options: dict | None
+        # (additional saving options for creating and saving datasets, e.g. compression/filters for zarr)
+        self._backend_options = {} if backend_options is None else backend_options
 
         # extensions are not loaded at init
         self.extensions = dict()
@@ -257,6 +274,7 @@ def create(
         folder=None,
         sparsity=None,
         return_scaled=True,
+        backend_options=None,
     ):
         # some checks
         if sorting.sampling_frequency != recording.sampling_frequency:
@@ -281,22 +299,34 @@ def create(
         if format == "memory":
             sorting_analyzer = cls.create_memory(sorting, recording, sparsity, return_scaled, rec_attributes=None)
         elif format == "binary_folder":
-            cls.create_binary_folder(folder, sorting, recording, sparsity, return_scaled, rec_attributes=None)
-            sorting_analyzer = cls.load_from_binary_folder(folder, recording=recording)
-            sorting_analyzer.folder = Path(folder)
+            sorting_analyzer = cls.create_binary_folder(
+                folder,
+                sorting,
+                recording,
+                sparsity,
+                return_scaled,
+                rec_attributes=None,
+                backend_options=backend_options,
+            )
         elif format == "zarr":
             assert folder is not None, "For format='zarr' folder must be provided"
             folder = clean_zarr_folder_name(folder)
-            cls.create_zarr(folder, sorting, recording, sparsity, return_scaled, rec_attributes=None)
-            sorting_analyzer = cls.load_from_zarr(folder, recording=recording)
-            sorting_analyzer.folder = Path(folder)
+            sorting_analyzer = cls.create_zarr(
+                folder,
+                sorting,
+                recording,
+                sparsity,
+                return_scaled,
+                rec_attributes=None,
+                backend_options=backend_options,
+            )
         else:
             raise ValueError("SortingAnalyzer.create: wrong format")
 
         return sorting_analyzer
 
     @classmethod
-    def load(cls, folder, recording=None, load_extensions=True, format="auto", storage_options=None):
+    def load(cls, folder, recording=None, load_extensions=True, format="auto", backend_options=None):
         """
         Load folder or zarr.
         The recording can be given if the recording location has changed.
@@ -310,10 +340,12 @@ def load(cls, folder, recording=None, load_extensions=True, format="auto", stora
                 format = "binary_folder"
 
         if format == "binary_folder":
-            sorting_analyzer = SortingAnalyzer.load_from_binary_folder(folder, recording=recording)
+            sorting_analyzer = SortingAnalyzer.load_from_binary_folder(
+                folder, recording=recording, backend_options=backend_options
+            )
         elif format == "zarr":
             sorting_analyzer = SortingAnalyzer.load_from_zarr(
-                folder, recording=recording, storage_options=storage_options
+                folder, recording=recording, backend_options=backend_options
             )
 
         if is_path_remote(str(folder)):
@@ -353,9 +385,7 @@ def create_memory(cls, sorting, recording, sparsity, return_scaled, rec_attribut
         return sorting_analyzer
 
     @classmethod
-    def create_binary_folder(
-        cls, folder, sorting, recording, sparsity, return_scaled, rec_attributes, **binary_format_kwargs
-    ):
+    def create_binary_folder(cls, folder, sorting, recording, sparsity, return_scaled, rec_attributes, backend_options):
         # used by create and save_as
 
         assert recording is not None, "To create a SortingAnalyzer you need to specify the recording"
@@ -417,8 +447,10 @@ def create_binary_folder(
         with open(settings_file, mode="w") as f:
             json.dump(check_json(settings), f, indent=4)
 
+        return cls.load_from_binary_folder(folder, recording=recording, backend_options=backend_options)
+
     @classmethod
-    def load_from_binary_folder(cls, folder, recording=None):
+    def load_from_binary_folder(cls, folder, recording=None, backend_options=None):
         folder = Path(folder)
         assert folder.is_dir(), f"This folder does not exists {folder}"
 
@@ -489,34 +521,42 @@ def load_from_binary_folder(cls, folder, recording=None):
             format="binary_folder",
             sparsity=sparsity,
             return_scaled=return_scaled,
+            backend_options=backend_options,
         )
+        sorting_analyzer.folder = folder
 
         return sorting_analyzer
 
     def _get_zarr_root(self, mode="r+"):
         import zarr
 
-        if is_path_remote(str(self.folder)):
-            mode = "r"
+        # if is_path_remote(str(self.folder)):
+        #     mode = "r"
+        storage_options = self._backend_options.get("storage_options", {})
         # we open_consolidated only if we are in read mode
         if mode in ("r+", "a"):
-            zarr_root = zarr.open(str(self.folder), mode=mode, storage_options=self.storage_options)
+            zarr_root = zarr.open(str(self.folder), mode=mode, storage_options=storage_options)
         else:
-            zarr_root = zarr.open_consolidated(self.folder, mode=mode, storage_options=self.storage_options)
+            zarr_root = zarr.open_consolidated(self.folder, mode=mode, storage_options=storage_options)
         return zarr_root
 
     @classmethod
-    def create_zarr(cls, folder, sorting, recording, sparsity, return_scaled, rec_attributes, **zarr_kwargs):
+    def create_zarr(cls, folder, sorting, recording, sparsity, return_scaled, rec_attributes, backend_options):
         # used by create and save_as
         import zarr
         import numcodecs
+        from .zarrextractors import add_sorting_to_zarr_group
 
         folder = clean_zarr_folder_name(folder)
 
         if folder.is_dir():
             raise ValueError(f"Folder already exists {folder}")
 
-        zarr_root = zarr.open(folder, mode="w")
+        backend_options = {} if backend_options is None else backend_options
+        storage_options = backend_options.get("storage_options", {})
+        saving_options = backend_options.get("saving_options", {})
+
+        zarr_root = zarr.open(folder, mode="w", storage_options=storage_options)
 
         info = dict(version=spikeinterface.__version__, dev_mode=spikeinterface.DEV_MODE, object="SortingAnalyzer")
         zarr_root.attrs["spikeinterface_info"] = check_json(info)
@@ -569,21 +609,23 @@ def create_zarr(cls, folder, sorting, recording, sparsity, return_scaled, rec_at
             recording_info.attrs["probegroup"] = check_json(probegroup.to_dict())
 
         if sparsity is not None:
-            zarr_root.create_dataset("sparsity_mask", data=sparsity.mask)
-
-        # write sorting copy
-        from .zarrextractors import add_sorting_to_zarr_group
+            zarr_root.create_dataset("sparsity_mask", data=sparsity.mask, **saving_options)
 
-        add_sorting_to_zarr_group(sorting, zarr_root.create_group("sorting"), **zarr_kwargs)
+        add_sorting_to_zarr_group(sorting, zarr_root.create_group("sorting"), **saving_options)
 
         recording_info = zarr_root.create_group("extensions")
 
         zarr.consolidate_metadata(zarr_root.store)
 
+        return cls.load_from_zarr(folder, recording=recording, backend_options=backend_options)
+
     @classmethod
-    def load_from_zarr(cls, folder, recording=None, storage_options=None):
+    def load_from_zarr(cls, folder, recording=None, backend_options=None):
         import zarr
 
+        backend_options = {} if backend_options is None else backend_options
+        storage_options = backend_options.get("storage_options", {})
+
         zarr_root = zarr.open_consolidated(str(folder), mode="r", storage_options=storage_options)
 
         si_info = zarr_root.attrs["spikeinterface_info"]
@@ -644,33 +686,12 @@ def load_from_zarr(cls, folder, recording=None, storage_options=None):
             format="zarr",
             sparsity=sparsity,
             return_scaled=return_scaled,
-            storage_options=storage_options,
+            backend_options=backend_options,
         )
+        sorting_analyzer.folder = folder
 
         return sorting_analyzer
 
-    @property
-    def backend_kwargs(self):
-        """
-        Returns the backend kwargs for the analyzer.
-        """
-        return self._backend_kwargs.copy()
-
-    @backend_kwargs.setter
-    def backend_kwargs(self, backend_kwargs):
-        """
-        Sets the backend kwargs for the analyzer. If the backend kwargs are not set, the default backend kwargs are used.
-
-        Parameters
-        ----------
-        backend_kwargs : keyword arguments
-            The zarr kwargs to set.
-        """
-        for key in backend_kwargs:
-            if key not in ("zarr", "binary_folder"):
-                raise ValueError(f"Unknown backend key: {key}. Available keys are 'zarr' and 'binary_folder'.")
-            self._backend_kwargs[key] = backend_kwargs[key]
-
     def set_temporary_recording(self, recording: BaseRecording, check_dtype: bool = True):
         """
         Sets a temporary recording object. This function can be useful to temporarily set
@@ -709,7 +730,7 @@ def _save_or_select_or_merge(
         sparsity_overlap=0.75,
         verbose=False,
         new_unit_ids=None,
-        backend_kwargs=None,
+        backend_options=None,
         **job_kwargs,
     ) -> "SortingAnalyzer":
         """
@@ -739,8 +760,11 @@ def _save_or_select_or_merge(
             The new unit ids for merged units. Required if `merge_unit_groups` is not None.
         verbose : bool, default: False
             If True, output is verbose.
-        backend_kwargs : dict | None, default: None
-            Keyword arguments for the backend specified by format.
+        backend_options : dict | None, default: None
+            Keyword arguments for the backend specified by format. It can contain the:
+            - storage_options: dict | None (fsspec storage options)
+            - saving_options: dict | None (additional saving options for creating and saving datasets,
+                                           e.g. compression/filters for zarr)
         job_kwargs : keyword arguments
             Keyword arguments for the job parallelization.
 
@@ -816,7 +840,7 @@ def _save_or_select_or_merge(
             # TODO: sam/pierre would create a curation field / curation.json with the applied merges.
             # What do you think?
 
-        backend_kwargs = {} if backend_kwargs is None else backend_kwargs
+        backend_options = {} if backend_options is None else backend_options
 
         if format == "memory":
             # This make a copy of actual SortingAnalyzer
@@ -828,34 +852,31 @@ def _save_or_select_or_merge(
             # create  a new folder
             assert folder is not None, "For format='binary_folder' folder must be provided"
             folder = Path(folder)
-            binary_format_kwargs = backend_kwargs
-            SortingAnalyzer.create_binary_folder(
+            new_sorting_analyzer = SortingAnalyzer.create_binary_folder(
                 folder,
                 sorting_provenance,
                 recording,
                 sparsity,
                 self.return_scaled,
                 self.rec_attributes,
-                **binary_format_kwargs,
+                backend_options=backend_options,
             )
-            new_sorting_analyzer = SortingAnalyzer.load_from_binary_folder(folder, recording=recording)
-            new_sorting_analyzer.folder = folder
 
         elif format == "zarr":
             assert folder is not None, "For format='zarr' folder must be provided"
             folder = clean_zarr_folder_name(folder)
-            zarr_kwargs = backend_kwargs
-            SortingAnalyzer.create_zarr(
-                folder, sorting_provenance, recording, sparsity, self.return_scaled, self.rec_attributes, **zarr_kwargs
+            new_sorting_analyzer = SortingAnalyzer.create_zarr(
+                folder,
+                sorting_provenance,
+                recording,
+                sparsity,
+                self.return_scaled,
+                self.rec_attributes,
+                backend_options=backend_options,
             )
-            new_sorting_analyzer = SortingAnalyzer.load_from_zarr(folder, recording=recording)
-            new_sorting_analyzer.folder = folder
         else:
             raise ValueError(f"SortingAnalyzer.save: unsupported format: {format}")
 
-        if format != "memory":
-            new_sorting_analyzer.backend_kwargs = {format: backend_kwargs}
-
         # make a copy of extensions
         # note that the copy of extension handle itself the slicing of units when necessary and also the saveing
         sorted_extensions = _sort_extensions_by_dependency(self.extensions)
@@ -890,7 +911,7 @@ def _save_or_select_or_merge(
 
         return new_sorting_analyzer
 
-    def save_as(self, format="memory", folder=None, backend_kwargs=None) -> "SortingAnalyzer":
+    def save_as(self, format="memory", folder=None, backend_options=None) -> "SortingAnalyzer":
         """
         Save SortingAnalyzer object into another format.
         Uselful for memory to zarr or memory to binary.
@@ -905,13 +926,15 @@ def save_as(self, format="memory", folder=None, backend_kwargs=None) -> "Sorting
             The output folder if `format` is "zarr" or "binary_folder"
         format : "memory" | "binary_folder" | "zarr", default: "memory"
             The new backend format to use
-        backend_kwargs : dict | None, default: None
-            Backend-specific kwargs for the specified format, which can be used to set some parameters for saving.
-            For example, if `format` is "zarr", one can set the compressor for the zarr datasets with `backend_kwargs={"compressor": some_compressor}`.
+        backend_options : dict | None, default: None
+            Keyword arguments for the backend specified by format. It can contain the:
+            - storage_options: dict | None (fsspec storage options)
+            - saving_options: dict | None (additional saving options for creating and saving datasets,
+                                           e.g. compression/filters for zarr)
         """
         if format == "zarr":
             folder = clean_zarr_folder_name(folder)
-        return self._save_or_select_or_merge(format=format, folder=folder, backend_kwargs=backend_kwargs)
+        return self._save_or_select_or_merge(format=format, folder=folder, backend_options=backend_options)
 
     def select_units(self, unit_ids, format="memory", folder=None) -> "SortingAnalyzer":
         """
@@ -2154,12 +2177,12 @@ def _save_data(self):
         elif self.format == "zarr":
             import numcodecs
 
-            zarr_kwargs = self.sorting_analyzer.backend_kwargs.get("zarr", {})
+            saving_options = self.sorting_analyzer._backend_options.get("saving_options", {})
             extension_group = self._get_zarr_extension_group(mode="r+")
 
             # if compression is not externally given, we use the default
-            if "compressor" not in zarr_kwargs:
-                zarr_kwargs["compressor"] = get_default_zarr_compressor()
+            if "compressor" not in saving_options:
+                saving_options["compressor"] = get_default_zarr_compressor()
 
             for ext_data_name, ext_data in self.data.items():
                 if ext_data_name in extension_group:
@@ -2169,7 +2192,7 @@ def _save_data(self):
                         name=ext_data_name, data=np.array([ext_data], dtype=object), object_codec=numcodecs.JSON()
                     )
                 elif isinstance(ext_data, np.ndarray):
-                    extension_group.create_dataset(name=ext_data_name, data=ext_data, **zarr_kwargs)
+                    extension_group.create_dataset(name=ext_data_name, data=ext_data, **saving_options)
                 elif HAS_PANDAS and isinstance(ext_data, pd.DataFrame):
                     df_group = extension_group.create_group(ext_data_name)
                     # first we save the index
diff --git a/src/spikeinterface/core/tests/test_sortinganalyzer.py b/src/spikeinterface/core/tests/test_sortinganalyzer.py
index f2aa7f459d..35ab18b5f2 100644
--- a/src/spikeinterface/core/tests/test_sortinganalyzer.py
+++ b/src/spikeinterface/core/tests/test_sortinganalyzer.py
@@ -137,8 +137,9 @@ def test_SortingAnalyzer_zarr(tmp_path, dataset):
         sparsity=None,
         return_scaled=False,
         overwrite=True,
+        backend_options={"saving_options": {"compressor": None}},
     )
-    sorting_analyzer_no_compression.backend_kwargs = {"zarr": dict(compressor=None)}
+    print(sorting_analyzer_no_compression._backend_options)
     sorting_analyzer_no_compression.compute(["random_spikes", "templates"])
     assert (
         sorting_analyzer_no_compression._get_zarr_root()["extensions"]["random_spikes"][
@@ -154,7 +155,7 @@ def test_SortingAnalyzer_zarr(tmp_path, dataset):
     lzma_compressor = LZMA()
     folder = tmp_path / "test_SortingAnalyzer_zarr_lzma.zarr"
     sorting_analyzer_lzma = sorting_analyzer_no_compression.save_as(
-        format="zarr", folder=folder, backend_kwargs=dict(compressor=lzma_compressor)
+        format="zarr", folder=folder, backend_options={"saving_options": {"compressor": lzma_compressor}}
     )
     assert (
         sorting_analyzer_lzma._get_zarr_root()["extensions"]["random_spikes"][

From 605b7b40e8d2d51e144222ef710dcc5aa5cc8852 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Tue, 1 Oct 2024 12:44:40 +0200
Subject: [PATCH 063/344] Fix saving analyzer directly to remote storage

---
 src/spikeinterface/core/sortinganalyzer.py | 64 ++++++++++++++--------
 1 file changed, 41 insertions(+), 23 deletions(-)

diff --git a/src/spikeinterface/core/sortinganalyzer.py b/src/spikeinterface/core/sortinganalyzer.py
index 0ff028bd42..a50c391798 100644
--- a/src/spikeinterface/core/sortinganalyzer.py
+++ b/src/spikeinterface/core/sortinganalyzer.py
@@ -124,12 +124,14 @@ def create_sorting_analyzer(
     """
     if format != "memory":
         if format == "zarr":
-            folder = clean_zarr_folder_name(folder)
-        if Path(folder).is_dir():
-            if not overwrite:
-                raise ValueError(f"Folder already exists {folder}! Use overwrite=True to overwrite it.")
-            else:
-                shutil.rmtree(folder)
+            if not is_path_remote(folder):
+                folder = clean_zarr_folder_name(folder)
+        if not is_path_remote(folder):
+            if Path(folder).is_dir():
+                if not overwrite:
+                    raise ValueError(f"Folder already exists {folder}! Use overwrite=True to overwrite it.")
+                else:
+                    shutil.rmtree(folder)
 
     # handle sparsity
     if sparsity is not None:
@@ -249,6 +251,9 @@ def __repr__(self) -> str:
         nchan = self.get_num_channels()
         nunits = self.get_num_units()
         txt = f"{clsname}: {nchan} channels - {nunits} units - {nseg} segments - {self.format}"
+        if self.format != "memory":
+            if is_path_remote(str(self.folder)):
+                txt += f" (remote)"
         if self.is_sparse():
             txt += " - sparse"
         if self.has_recording():
@@ -311,7 +316,8 @@ def create(
             )
         elif format == "zarr":
             assert folder is not None, "For format='zarr' folder must be provided"
-            folder = clean_zarr_folder_name(folder)
+            if not is_path_remote(folder):
+                folder = clean_zarr_folder_name(folder)
             sorting_analyzer = cls.create_zarr(
                 folder,
                 sorting,
@@ -349,12 +355,7 @@ def load(cls, folder, recording=None, load_extensions=True, format="auto", backe
                 folder, recording=recording, backend_options=backend_options
             )
 
-        if is_path_remote(str(folder)):
-            sorting_analyzer.folder = folder
-            # in this case we only load extensions when needed
-        else:
-            sorting_analyzer.folder = Path(folder)
-
+        if not is_path_remote(str(folder)):
             if load_extensions:
                 sorting_analyzer.load_all_saved_extension()
 
@@ -537,12 +538,16 @@ def load_from_binary_folder(cls, folder, recording=None, backend_options=None):
     def _get_zarr_root(self, mode="r+"):
         import zarr
 
-        # if is_path_remote(str(self.folder)):
-        #     mode = "r"
+        assert mode in ("r+", "a", "r"), "mode must be 'r+', 'a' or 'r'"
+
         storage_options = self._backend_options.get("storage_options", {})
         # we open_consolidated only if we are in read mode
         if mode in ("r+", "a"):
-            zarr_root = zarr.open(str(self.folder), mode=mode, storage_options=storage_options)
+            try:
+                zarr_root = zarr.open(str(self.folder), mode=mode, storage_options=storage_options)
+            except Exception as e:
+                # this could happen in remote mode, and it's a way to check if the folder is still there
+                zarr_root = zarr.open_consolidated(self.folder, mode=mode, storage_options=storage_options)
         else:
             zarr_root = zarr.open_consolidated(self.folder, mode=mode, storage_options=storage_options)
         return zarr_root
@@ -554,10 +559,14 @@ def create_zarr(cls, folder, sorting, recording, sparsity, return_scaled, rec_at
         import numcodecs
         from .zarrextractors import add_sorting_to_zarr_group
 
-        folder = clean_zarr_folder_name(folder)
-
-        if folder.is_dir():
-            raise ValueError(f"Folder already exists {folder}")
+        if is_path_remote(folder):
+            remote = True
+        else:
+            remote = False
+        if not remote:
+            folder = clean_zarr_folder_name(folder)
+            if folder.is_dir():
+                raise ValueError(f"Folder already exists {folder}")
 
         backend_options = {} if backend_options is None else backend_options
         storage_options = backend_options.get("storage_options", {})
@@ -572,8 +581,9 @@ def create_zarr(cls, folder, sorting, recording, sparsity, return_scaled, rec_at
         zarr_root.attrs["settings"] = check_json(settings)
 
         # the recording
+        relative_to = folder if not remote else None
         if recording is not None:
-            rec_dict = recording.to_dict(relative_to=folder, recursive=True)
+            rec_dict = recording.to_dict(relative_to=relative_to, recursive=True)
             if recording.check_serializability("json"):
                 # zarr_root.create_dataset("recording", data=rec_dict, object_codec=numcodecs.JSON())
                 zarr_rec = np.array([check_json(rec_dict)], dtype=object)
@@ -589,7 +599,7 @@ def create_zarr(cls, folder, sorting, recording, sparsity, return_scaled, rec_at
             warnings.warn("Recording not provided, instntiating SortingAnalyzer in recordingless mode.")
 
         # sorting provenance
-        sort_dict = sorting.to_dict(relative_to=folder, recursive=True)
+        sort_dict = sorting.to_dict(relative_to=relative_to, recursive=True)
         if sorting.check_serializability("json"):
             zarr_sort = np.array([check_json(sort_dict)], dtype=object)
             zarr_root.create_dataset("sorting_provenance", data=zarr_sort, object_codec=numcodecs.JSON())
@@ -1106,7 +1116,15 @@ def copy(self):
     def is_read_only(self) -> bool:
         if self.format == "memory":
             return False
-        return not os.access(self.folder, os.W_OK)
+        elif self.format == "binary_folder":
+            return not os.access(self.folder, os.W_OK)
+        else:
+            if not is_path_remote(str(self.folder)):
+                return not os.access(self.folder, os.W_OK)
+            else:
+                # in this case we don't know if the file is read only so an error
+                # will be raised if we try to save/append
+                return False
 
     ## map attribute and property zone
 

From cffb2c9415501028740ea7ee75f9308e4f824198 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Tue, 1 Oct 2024 15:02:31 +0200
Subject: [PATCH 064/344] Only reset extension when save is False

---
 src/spikeinterface/core/sortinganalyzer.py | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/core/sortinganalyzer.py b/src/spikeinterface/core/sortinganalyzer.py
index a50c391798..bb3e8d5564 100644
--- a/src/spikeinterface/core/sortinganalyzer.py
+++ b/src/spikeinterface/core/sortinganalyzer.py
@@ -260,7 +260,9 @@ def __repr__(self) -> str:
             txt += " - has recording"
         if self.has_temporary_recording():
             txt += " - has temporary recording"
-        ext_txt = f"Loaded {len(self.extensions)} extensions: " + ", ".join(self.extensions.keys())
+        ext_txt = f"Loaded {len(self.extensions)} extensions"
+        if len(self.extensions) > 0:
+            ext_txt += f": {', '.join(self.extensions.keys())}"
         txt += "\n" + ext_txt
         return txt
 
@@ -2297,7 +2299,8 @@ def set_params(self, save=True, **params):
         """
         # this ensure data is also deleted and corresponds to params
         # this also ensure the group is created
-        self._reset_extension_folder()
+        if save:
+            self._reset_extension_folder()
 
         params = self._set_params(**params)
         self.params = params

From b3a397c5c6fad281e3026ecd2fd9333f4d3a533c Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Tue, 1 Oct 2024 15:06:59 +0200
Subject: [PATCH 065/344] Avoid warnings in sortin analyzer

---
 src/spikeinterface/core/sortinganalyzer.py                  | 6 ++++--
 .../qualitymetrics/quality_metric_calculator.py             | 3 ++-
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/src/spikeinterface/core/sortinganalyzer.py b/src/spikeinterface/core/sortinganalyzer.py
index 5057b5001e..fdace37dd0 100644
--- a/src/spikeinterface/core/sortinganalyzer.py
+++ b/src/spikeinterface/core/sortinganalyzer.py
@@ -1976,7 +1976,8 @@ def load_data(self):
                     continue
                 ext_data_name = ext_data_file.stem
                 if ext_data_file.suffix == ".json":
-                    ext_data = json.load(ext_data_file.open("r"))
+                    with ext_data_file.open("r") as f:
+                        ext_data = json.load(f)
                 elif ext_data_file.suffix == ".npy":
                     # The lazy loading of an extension is complicated because if we compute again
                     # and have a link to the old buffer on windows then it fails
@@ -1988,7 +1989,8 @@ def load_data(self):
 
                     ext_data = pd.read_csv(ext_data_file, index_col=0)
                 elif ext_data_file.suffix == ".pkl":
-                    ext_data = pickle.load(ext_data_file.open("rb"))
+                    with ext_data_file.open("rb") as f:
+                        ext_data = pickle.load(f)
                 else:
                     continue
                 self.data[ext_data_name] = ext_data
diff --git a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
index 3b6c6d3e50..b6a50d60f5 100644
--- a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
+++ b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
@@ -234,7 +234,8 @@ def _run(self, verbose=False, **job_kwargs):
         )
 
         existing_metrics = []
-        qm_extension = self.sorting_analyzer.get_extension("quality_metrics")
+        # here we get in the loaded via the dict only (to avoid full loading from disk after params reset)
+        qm_extension = self.sorting_analyzer.extensions.get("quality_metrics", None)
         if (
             delete_existing_metrics is False
             and qm_extension is not None

From 303211251210dc4093919eef2222f8e110e71950 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Tue, 1 Oct 2024 15:20:29 +0200
Subject: [PATCH 066/344] fix random_spikes_selection()

---
 src/spikeinterface/core/sorting_tools.py           | 14 +++++++++-----
 .../core/tests/test_sorting_tools.py               |  6 +++---
 2 files changed, 12 insertions(+), 8 deletions(-)

diff --git a/src/spikeinterface/core/sorting_tools.py b/src/spikeinterface/core/sorting_tools.py
index 5f33350820..575c7f67e9 100644
--- a/src/spikeinterface/core/sorting_tools.py
+++ b/src/spikeinterface/core/sorting_tools.py
@@ -197,17 +197,21 @@ def random_spikes_selection(
         cum_sizes = np.cumsum([0] + [s.size for s in spikes])
 
         # this fast when numba
-        spike_indices = spike_vector_to_indices(spikes, sorting.unit_ids)
+        spike_indices = spike_vector_to_indices(spikes, sorting.unit_ids, absolute_index=False)
 
         random_spikes_indices = []
         for unit_index, unit_id in enumerate(sorting.unit_ids):
             all_unit_indices = []
             for segment_index in range(sorting.get_num_segments()):
-                inds_in_seg = spike_indices[segment_index][unit_id] + cum_sizes[segment_index]
+                # this is local index
+                inds_in_seg = spike_indices[segment_index][unit_id]
                 if margin_size is not None:
-                    inds_in_seg = inds_in_seg[inds_in_seg >= margin_size]
-                    inds_in_seg = inds_in_seg[inds_in_seg < (num_samples[segment_index] - margin_size)]
-                all_unit_indices.append(inds_in_seg)
+                    local_spikes = spikes[segment_index][inds_in_seg]
+                    mask = (local_spikes["sample_index"] >= margin_size) & (local_spikes["sample_index"] < (num_samples[segment_index] - margin_size))
+                    inds_in_seg = inds_in_seg[mask]
+                # go back to absolut index
+                inds_in_seg_abs = inds_in_seg + cum_sizes[segment_index]
+                all_unit_indices.append(inds_in_seg_abs)
             all_unit_indices = np.concatenate(all_unit_indices)
             selected_unit_indices = rng.choice(
                 all_unit_indices, size=min(max_spikes_per_unit, all_unit_indices.size), replace=False, shuffle=False
diff --git a/src/spikeinterface/core/tests/test_sorting_tools.py b/src/spikeinterface/core/tests/test_sorting_tools.py
index 34bb3a221d..7d26773ac3 100644
--- a/src/spikeinterface/core/tests/test_sorting_tools.py
+++ b/src/spikeinterface/core/tests/test_sorting_tools.py
@@ -162,8 +162,8 @@ def test_generate_unit_ids_for_merge_group():
 if __name__ == "__main__":
     # test_spike_vector_to_spike_trains()
     # test_spike_vector_to_indices()
-    # test_random_spikes_selection()
+    test_random_spikes_selection()
 
-    test_apply_merges_to_sorting()
-    test_get_ids_after_merging()
+    # test_apply_merges_to_sorting()
+    # test_get_ids_after_merging()
     # test_generate_unit_ids_for_merge_group()

From 036691bb04ed079d5736a53808d4a7e8edb375da Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Tue, 1 Oct 2024 13:24:14 +0000
Subject: [PATCH 067/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/core/sorting_tools.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/spikeinterface/core/sorting_tools.py b/src/spikeinterface/core/sorting_tools.py
index 575c7f67e9..213968a80b 100644
--- a/src/spikeinterface/core/sorting_tools.py
+++ b/src/spikeinterface/core/sorting_tools.py
@@ -207,7 +207,9 @@ def random_spikes_selection(
                 inds_in_seg = spike_indices[segment_index][unit_id]
                 if margin_size is not None:
                     local_spikes = spikes[segment_index][inds_in_seg]
-                    mask = (local_spikes["sample_index"] >= margin_size) & (local_spikes["sample_index"] < (num_samples[segment_index] - margin_size))
+                    mask = (local_spikes["sample_index"] >= margin_size) & (
+                        local_spikes["sample_index"] < (num_samples[segment_index] - margin_size)
+                    )
                     inds_in_seg = inds_in_seg[mask]
                 # go back to absolut index
                 inds_in_seg_abs = inds_in_seg + cum_sizes[segment_index]

From 8d6402b29d5c65015f529dbfa62dea974c98afa7 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Wed, 2 Oct 2024 13:10:01 +0200
Subject: [PATCH 068/344] Prepare release 0.101.2

---
 doc/releases/0.101.2.rst       | 63 ++++++++++++++++++++++++++++++++++
 doc/whatisnew.rst              |  6 ++++
 pyproject.toml                 | 12 +++----
 src/spikeinterface/__init__.py |  4 +--
 4 files changed, 77 insertions(+), 8 deletions(-)
 create mode 100644 doc/releases/0.101.2.rst

diff --git a/doc/releases/0.101.2.rst b/doc/releases/0.101.2.rst
new file mode 100644
index 0000000000..7b45fee796
--- /dev/null
+++ b/doc/releases/0.101.2.rst
@@ -0,0 +1,63 @@
+.. _release0.101.2:
+
+SpikeInterface 0.101.2 release notes
+------------------------------------
+
+3rd October 2024
+
+Minor release with bug fixes
+
+core:
+
+* Avoid warnings in `SortingAnalyzer` (#3455)
+* Fix `reset_global_job_kwargs` (#3452)
+* Allow to save recordingless analyzer as (#3443)
+* Fix compute analyzer pipeline with tmp recording (#3433)
+* Fix bug in saving zarr recordings (#3432)
+* Set `run_info` to `None` for `load_waveforms` (#3430)
+* Fix integer overflow in parallel computing (#3426)
+* Refactor `pandas` save load and `convert_dtypes` (#3412)
+* Add spike-train based lazy `SortingGenerator` (#2227)
+
+extractors:
+
+* Improve IBL recording extractors by PID (#3449)
+
+sorters:
+
+* Get default encoding for `Popen` (#3439)
+
+postprocessing:
+
+* Add `max_threads_per_process` and `mp_context` to pca by channel computation and PCA metrics (#3434)
+
+widgets:
+
+* Fix metrics widgets for convert_dtypes (#3417)
+* Fix plot motion for multi-segment (#3414)
+
+motion correction:
+
+* Auto-cast recording to float prior to interpolation (#3415)
+
+documentation:
+
+* Add docstring for `generate_unit_locations`  (#3418)
+* Add `get_channel_locations` to the base recording API (#3403)
+
+continuous integration:
+
+* Enable testing arm64 Mac architecture in the CI (#3422)
+* Add kachery_zone secret (#3416)
+
+testing:
+
+* Relax causal filter tests (#3445)
+
+Contributors:
+
+* @alejoe91
+* @h-mayorquin
+* @jiumao2
+* @samuelgarcia
+* @zm711
diff --git a/doc/whatisnew.rst b/doc/whatisnew.rst
index c8038387f9..2851f8ab4a 100644
--- a/doc/whatisnew.rst
+++ b/doc/whatisnew.rst
@@ -8,6 +8,7 @@ Release notes
 .. toctree::
   :maxdepth: 1
 
+  releases/0.101.2.rst
   releases/0.101.1.rst
   releases/0.101.0.rst
   releases/0.100.8.rst
@@ -44,6 +45,11 @@ Release notes
   releases/0.9.1.rst
 
 
+Version 0.101.2
+===============
+
+* Minor release with bug fixes
+
 Version 0.101.1
 ===============
 
diff --git a/pyproject.toml b/pyproject.toml
index d246520280..b4a71bdb47 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -124,16 +124,16 @@ test_core = [
 
     # for github test : probeinterface and neo from master
     # for release we need pypi, so this need to be commented
-     "probeinterface @ git+https://github.com/SpikeInterface/probeinterface.git",
-     "neo @ git+https://github.com/NeuralEnsemble/python-neo.git",
+    # "probeinterface @ git+https://github.com/SpikeInterface/probeinterface.git",
+    # "neo @ git+https://github.com/NeuralEnsemble/python-neo.git",
 ]
 
 test_extractors = [
     # Functions to download data in neo test suite
     "pooch>=1.8.2",
     "datalad>=1.0.2",
-     "probeinterface @ git+https://github.com/SpikeInterface/probeinterface.git",
-     "neo @ git+https://github.com/NeuralEnsemble/python-neo.git",
+    # "probeinterface @ git+https://github.com/SpikeInterface/probeinterface.git",
+    # "neo @ git+https://github.com/NeuralEnsemble/python-neo.git",
 ]
 
 test_preprocessing = [
@@ -173,8 +173,8 @@ test = [
 
     # for github test : probeinterface and neo from master
     # for release we need pypi, so this need to be commented
-     "probeinterface @ git+https://github.com/SpikeInterface/probeinterface.git",
-     "neo @ git+https://github.com/NeuralEnsemble/python-neo.git",
+    # "probeinterface @ git+https://github.com/SpikeInterface/probeinterface.git",
+    # "neo @ git+https://github.com/NeuralEnsemble/python-neo.git",
 ]
 
 docs = [
diff --git a/src/spikeinterface/__init__.py b/src/spikeinterface/__init__.py
index 306c12d516..97fb95b623 100644
--- a/src/spikeinterface/__init__.py
+++ b/src/spikeinterface/__init__.py
@@ -30,5 +30,5 @@
 # This flag must be set to False for release
 # This avoids using versioning that contains ".dev0" (and this is a better choice)
 # This is mainly useful when using run_sorter in a container and spikeinterface install
-DEV_MODE = True
-# DEV_MODE = False
+# DEV_MODE = True
+DEV_MODE = False

From e3b3f02ed236d3b518fe5037805b312b70029cca Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Wed, 2 Oct 2024 13:12:10 +0200
Subject: [PATCH 069/344] Add open PR

---
 doc/releases/0.101.2.rst | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/doc/releases/0.101.2.rst b/doc/releases/0.101.2.rst
index 7b45fee796..22e0113cb7 100644
--- a/doc/releases/0.101.2.rst
+++ b/doc/releases/0.101.2.rst
@@ -9,6 +9,8 @@ Minor release with bug fixes
 
 core:
 
+* Fix `random_spikes_selection()` (#3456)
+* Expose `backend_options` at the analyzer level to set `storage_options` and `saving_options` (#3446)
 * Avoid warnings in `SortingAnalyzer` (#3455)
 * Fix `reset_global_job_kwargs` (#3452)
 * Allow to save recordingless analyzer as (#3443)
@@ -19,6 +21,7 @@ core:
 * Refactor `pandas` save load and `convert_dtypes` (#3412)
 * Add spike-train based lazy `SortingGenerator` (#2227)
 
+
 extractors:
 
 * Improve IBL recording extractors by PID (#3449)

From e564f8b8229572d049c8107ad9d9d358c6c96724 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Wed, 2 Oct 2024 17:05:42 +0200
Subject: [PATCH 070/344] Fall back to anon=True for zarr extractors and
 analyzers in case backend/storage options is not provided

---
 src/spikeinterface/core/sortinganalyzer.py | 40 ++++++++++++++++------
 src/spikeinterface/core/zarrextractors.py  | 32 ++++++++++++++---
 2 files changed, 57 insertions(+), 15 deletions(-)

diff --git a/src/spikeinterface/core/sortinganalyzer.py b/src/spikeinterface/core/sortinganalyzer.py
index 1f404c755d..14b4f73eaf 100644
--- a/src/spikeinterface/core/sortinganalyzer.py
+++ b/src/spikeinterface/core/sortinganalyzer.py
@@ -65,18 +65,18 @@ def create_sorting_analyzer(
     recording : Recording
         The recording object
     folder : str or Path or None, default: None
-        The folder where waveforms are cached
+        The folder where analyzer is cached
     format : "memory | "binary_folder" | "zarr", default: "memory"
-        The mode to store waveforms. If "folder", waveforms are stored on disk in the specified folder.
+        The mode to store analyzer. If "folder", the analyzer is stored on disk in the specified folder.
         The "folder" argument must be specified in case of mode "folder".
-        If "memory" is used, the waveforms are stored in RAM. Use this option carefully!
+        If "memory" is used, the analyzer is stored in RAM. Use this option carefully!
     sparse : bool, default: True
         If True, then a sparsity mask is computed using the `estimate_sparsity()` function using
         a few spikes to get an estimate of dense templates to create a ChannelSparsity object.
         Then, the sparsity will be propagated to all ResultExtention that handle sparsity (like wavforms, pca, ...)
         You can control `estimate_sparsity()` : all extra arguments are propagated to it (included job_kwargs)
     sparsity : ChannelSparsity or None, default: None
-        The sparsity used to compute waveforms. If this is given, `sparse` is ignored.
+        The sparsity used to compute exensions. If this is given, `sparse` is ignored.
     return_scaled : bool, default: True
         All extensions that play with traces will use this global return_scaled : "waveforms", "noise_levels", "templates".
         This prevent return_scaled being differents from different extensions and having wrong snr for instance.
@@ -98,7 +98,7 @@ def create_sorting_analyzer(
     --------
     >>> import spikeinterface as si
 
-    >>> # Extract dense waveforms and save to disk with binary_folder format.
+    >>> # Create dense analyzer and save to disk with binary_folder format.
     >>> sorting_analyzer = si.create_sorting_analyzer(sorting, recording, format="binary_folder", folder="/path/to_my/result")
 
     >>> # Can be reload
@@ -172,14 +172,19 @@ def load_sorting_analyzer(folder, load_extensions=True, format="auto", backend_o
     Parameters
     ----------
     folder : str or Path
-        The folder / zarr folder where the waveform extractor is stored
+        The folder / zarr folder where the analyzer is stored. If the folder is a remote path stored in the cloud,
+        the backend_options can be used to specify credentials. If the remote path is not accessible,
+        and backend_options is not provided, the function will try to load the object in anonymous mode (anon=True),
+        which enables to load data from open buckets.
     load_extensions : bool, default: True
         Load all extensions or not.
     format : "auto" | "binary_folder" | "zarr"
         The format of the folder.
-    storage_options : dict | None, default: None
-        The storage options to specify credentials to remote zarr bucket.
-        For open buckets, it doesn't need to be specified.
+    backend_options : dict | None, default: None
+        The backend options for the backend.
+        The dictionary can contain the following keys:
+        - storage_options: dict | None (fsspec storage options)
+        - saving_options: dict | None (additional saving options for creating and saving datasets)
 
     Returns
     -------
@@ -187,7 +192,20 @@ def load_sorting_analyzer(folder, load_extensions=True, format="auto", backend_o
         The loaded SortingAnalyzer
 
     """
-    return SortingAnalyzer.load(folder, load_extensions=load_extensions, format=format, backend_options=backend_options)
+    if is_path_remote(folder) and backend_options is None:
+        try:
+            return SortingAnalyzer.load(
+                folder, load_extensions=load_extensions, format=format, backend_options=backend_options
+            )
+        except Exception as e:
+            backend_options = dict(storage_options=dict(anon=True))
+            return SortingAnalyzer.load(
+                folder, load_extensions=load_extensions, format=format, backend_options=backend_options
+            )
+    else:
+        return SortingAnalyzer.load(
+            folder, load_extensions=load_extensions, format=format, backend_options=backend_options
+        )
 
 
 class SortingAnalyzer:
@@ -2286,7 +2304,7 @@ def delete(self):
 
     def reset(self):
         """
-        Reset the waveform extension.
+        Reset the extension.
         Delete the sub folder and create a new empty one.
         """
         self._reset_extension_folder()
diff --git a/src/spikeinterface/core/zarrextractors.py b/src/spikeinterface/core/zarrextractors.py
index 355553428e..26cb3cc6fc 100644
--- a/src/spikeinterface/core/zarrextractors.py
+++ b/src/spikeinterface/core/zarrextractors.py
@@ -12,6 +12,7 @@
 from .core_tools import define_function_from_class, check_json
 from .job_tools import split_job_kwargs
 from .recording_tools import determine_cast_unsigned
+from .core_tools import is_path_remote
 
 
 class ZarrRecordingExtractor(BaseRecording):
@@ -21,7 +22,11 @@ class ZarrRecordingExtractor(BaseRecording):
     Parameters
     ----------
     folder_path : str or Path
-        Path to the zarr root folder
+        Path to the zarr root folder. This can be a local path or a remote path (s3:// or gcs://).
+        If the path is a remote path, the storage_options can be provided to specify credentials.
+        If the remote path is not accessible and backend_options is not provided,
+        the function will try to load the object in anonymous mode (anon=True),
+        which enables to load data from open buckets.
     storage_options : dict or None
         Storage options for zarr `store`. E.g., if "s3://" or "gcs://" they can provide authentication methods, etc.
 
@@ -35,7 +40,14 @@ def __init__(self, folder_path: Path | str, storage_options: dict | None = None)
 
         folder_path, folder_path_kwarg = resolve_zarr_path(folder_path)
 
-        self._root = zarr.open(str(folder_path), mode="r", storage_options=storage_options)
+        if is_path_remote(str(folder_path)) and storage_options is None:
+            try:
+                self._root = zarr.open(str(folder_path), mode="r", storage_options=storage_options)
+            except Exception as e:
+                storage_options = {"anon": True}
+                self._root = zarr.open(str(folder_path), mode="r", storage_options=storage_options)
+        else:
+            self._root = zarr.open(str(folder_path), mode="r", storage_options=storage_options)
 
         sampling_frequency = self._root.attrs.get("sampling_frequency", None)
         num_segments = self._root.attrs.get("num_segments", None)
@@ -150,7 +162,11 @@ class ZarrSortingExtractor(BaseSorting):
     Parameters
     ----------
     folder_path : str or Path
-        Path to the zarr root file
+        Path to the zarr root file. This can be a local path or a remote path (s3:// or gcs://).
+        If the path is a remote path, the storage_options can be provided to specify credentials.
+        If the remote path is not accessible and backend_options is not provided,
+        the function will try to load the object in anonymous mode (anon=True),
+        which enables to load data from open buckets.
     storage_options : dict or None
         Storage options for zarr `store`. E.g., if "s3://" or "gcs://" they can provide authentication methods, etc.
     zarr_group : str or None, default: None
@@ -165,7 +181,15 @@ def __init__(self, folder_path: Path | str, storage_options: dict | None = None,
 
         folder_path, folder_path_kwarg = resolve_zarr_path(folder_path)
 
-        zarr_root = self._root = zarr.open(str(folder_path), mode="r", storage_options=storage_options)
+        if is_path_remote(str(folder_path)) and storage_options is None:
+            try:
+                zarr_root = zarr.open(str(folder_path), mode="r", storage_options=storage_options)
+            except Exception as e:
+                storage_options = {"anon": True}
+                zarr_root = zarr.open(str(folder_path), mode="r", storage_options=storage_options)
+        else:
+            zarr_root = zarr.open(str(folder_path), mode="r", storage_options=storage_options)
+
         if zarr_group is None:
             self._root = zarr_root
         else:

From 580703f5e8382aeca58cc5d9ec4e300cbfc6f3e3 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Wed, 2 Oct 2024 17:50:23 +0200
Subject: [PATCH 071/344] Protect against uninitialized chunks and add
 anonymous zarr open

---
 src/spikeinterface/core/zarrextractors.py | 42 +++++++++++++----------
 1 file changed, 23 insertions(+), 19 deletions(-)

diff --git a/src/spikeinterface/core/zarrextractors.py b/src/spikeinterface/core/zarrextractors.py
index 26cb3cc6fc..ff552dfb54 100644
--- a/src/spikeinterface/core/zarrextractors.py
+++ b/src/spikeinterface/core/zarrextractors.py
@@ -15,6 +15,18 @@
 from .core_tools import is_path_remote
 
 
+def anononymous_zarr_open(folder_path: str | Path, mode: str = "r", storage_options: dict | None = None):
+    if is_path_remote(str(folder_path)) and storage_options is None:
+        try:
+            root = zarr.open(str(folder_path), mode="r", storage_options=storage_options)
+        except Exception as e:
+            storage_options = {"anon": True}
+            root = zarr.open(str(folder_path), mode="r", storage_options=storage_options)
+    else:
+        root = zarr.open(str(folder_path), mode="r", storage_options=storage_options)
+    return root
+
+
 class ZarrRecordingExtractor(BaseRecording):
     """
     RecordingExtractor for a zarr format
@@ -40,14 +52,7 @@ def __init__(self, folder_path: Path | str, storage_options: dict | None = None)
 
         folder_path, folder_path_kwarg = resolve_zarr_path(folder_path)
 
-        if is_path_remote(str(folder_path)) and storage_options is None:
-            try:
-                self._root = zarr.open(str(folder_path), mode="r", storage_options=storage_options)
-            except Exception as e:
-                storage_options = {"anon": True}
-                self._root = zarr.open(str(folder_path), mode="r", storage_options=storage_options)
-        else:
-            self._root = zarr.open(str(folder_path), mode="r", storage_options=storage_options)
+        self._root = anononymous_zarr_open(folder_path, mode="r", storage_options=storage_options)
 
         sampling_frequency = self._root.attrs.get("sampling_frequency", None)
         num_segments = self._root.attrs.get("num_segments", None)
@@ -93,7 +98,10 @@ def __init__(self, folder_path: Path | str, storage_options: dict | None = None)
 
             nbytes_segment = self._root[trace_name].nbytes
             nbytes_stored_segment = self._root[trace_name].nbytes_stored
-            cr_by_segment[segment_index] = nbytes_segment / nbytes_stored_segment
+            if nbytes_stored_segment > 0:
+                cr_by_segment[segment_index] = nbytes_segment / nbytes_stored_segment
+            else:
+                cr_by_segment[segment_index] = np.nan
 
             total_nbytes += nbytes_segment
             total_nbytes_stored += nbytes_stored_segment
@@ -117,7 +125,10 @@ def __init__(self, folder_path: Path | str, storage_options: dict | None = None)
         if annotations is not None:
             self.annotate(**annotations)
         # annotate compression ratios
-        cr = total_nbytes / total_nbytes_stored
+        if total_nbytes_stored > 0:
+            cr = total_nbytes / total_nbytes_stored
+        else:
+            cr = np.nan
         self.annotate(compression_ratio=cr, compression_ratio_segments=cr_by_segment)
 
         self._kwargs = {"folder_path": folder_path_kwarg, "storage_options": storage_options}
@@ -181,14 +192,7 @@ def __init__(self, folder_path: Path | str, storage_options: dict | None = None,
 
         folder_path, folder_path_kwarg = resolve_zarr_path(folder_path)
 
-        if is_path_remote(str(folder_path)) and storage_options is None:
-            try:
-                zarr_root = zarr.open(str(folder_path), mode="r", storage_options=storage_options)
-            except Exception as e:
-                storage_options = {"anon": True}
-                zarr_root = zarr.open(str(folder_path), mode="r", storage_options=storage_options)
-        else:
-            zarr_root = zarr.open(str(folder_path), mode="r", storage_options=storage_options)
+        zarr_root = anononymous_zarr_open(folder_path, mode="r", storage_options=storage_options)
 
         if zarr_group is None:
             self._root = zarr_root
@@ -267,7 +271,7 @@ def read_zarr(
     """
     # TODO @alessio : we should have something more explicit in our zarr format to tell which object it is.
     # for the futur SortingAnalyzer we will have this 2 fields!!!
-    root = zarr.open(str(folder_path), mode="r", storage_options=storage_options)
+    root = anononymous_zarr_open(folder_path, mode="r", storage_options=storage_options)
     if "channel_ids" in root.keys():
         return read_zarr_recording(folder_path, storage_options=storage_options)
     elif "unit_ids" in root.keys():

From 76fa01ec78b381d510895a6cb10608ce6697e435 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Thu, 3 Oct 2024 15:55:16 +0200
Subject: [PATCH 072/344] Fix docs

---
 doc/how_to/combine_recordings.rst          |  2 +-
 doc/how_to/load_matlab_data.rst            |  2 +-
 doc/how_to/load_your_data_into_sorting.rst |  4 ++--
 doc/how_to/process_by_channel_group.rst    |  2 +-
 doc/how_to/viewers.rst                     |  2 +-
 src/spikeinterface/core/sortinganalyzer.py | 10 ++++++++--
 6 files changed, 14 insertions(+), 8 deletions(-)

diff --git a/doc/how_to/combine_recordings.rst b/doc/how_to/combine_recordings.rst
index db37e28382..4a088f01b1 100644
--- a/doc/how_to/combine_recordings.rst
+++ b/doc/how_to/combine_recordings.rst
@@ -1,4 +1,4 @@
-Combine Recordings in SpikeInterface
+Combine recordings in SpikeInterface
 ====================================
 
 In this tutorial we will walk through combining multiple recording objects. Sometimes this occurs due to hardware
diff --git a/doc/how_to/load_matlab_data.rst b/doc/how_to/load_matlab_data.rst
index 1f24fb66d3..eab1e0a300 100644
--- a/doc/how_to/load_matlab_data.rst
+++ b/doc/how_to/load_matlab_data.rst
@@ -1,4 +1,4 @@
-Export MATLAB Data to Binary & Load in SpikeInterface
+Export MATLAB data to binary & load in SpikeInterface
 ========================================================
 
 In this tutorial, we will walk through the process of exporting data from MATLAB in a binary format and subsequently loading it using SpikeInterface in Python.
diff --git a/doc/how_to/load_your_data_into_sorting.rst b/doc/how_to/load_your_data_into_sorting.rst
index 4e434ecb7a..e250cfa6e9 100644
--- a/doc/how_to/load_your_data_into_sorting.rst
+++ b/doc/how_to/load_your_data_into_sorting.rst
@@ -1,5 +1,5 @@
-Load Your Own Data into a Sorting
-=================================
+Load your own data into a Sorting object
+========================================
 
 Why make a :code:`Sorting`?
 
diff --git a/doc/how_to/process_by_channel_group.rst b/doc/how_to/process_by_channel_group.rst
index bac0de4d0c..08a87ab738 100644
--- a/doc/how_to/process_by_channel_group.rst
+++ b/doc/how_to/process_by_channel_group.rst
@@ -1,4 +1,4 @@
-Process a Recording by Channel Group
+Process a recording by channel group
 ====================================
 
 In this tutorial, we will walk through how to preprocess and sort a recording
diff --git a/doc/how_to/viewers.rst b/doc/how_to/viewers.rst
index c7574961bd..7bb41cadb6 100644
--- a/doc/how_to/viewers.rst
+++ b/doc/how_to/viewers.rst
@@ -1,4 +1,4 @@
-Visualize Data
+Visualize data
 ==============
 
 There are several ways to plot signals (raw, preprocessed) and spikes.
diff --git a/src/spikeinterface/core/sortinganalyzer.py b/src/spikeinterface/core/sortinganalyzer.py
index 14b4f73eaf..55cbe6070a 100644
--- a/src/spikeinterface/core/sortinganalyzer.py
+++ b/src/spikeinterface/core/sortinganalyzer.py
@@ -2245,9 +2245,15 @@ def _save_data(self):
                 elif HAS_PANDAS and isinstance(ext_data, pd.DataFrame):
                     df_group = extension_group.create_group(ext_data_name)
                     # first we save the index
-                    df_group.create_dataset(name="index", data=ext_data.index.to_numpy())
+                    indices = ext_data.index.to_numpy()
+                    if indices.dtype.kind == "O":
+                        indices = indices.astype(str)
+                    df_group.create_dataset(name="index", data=indices)
                     for col in ext_data.columns:
-                        df_group.create_dataset(name=col, data=ext_data[col].to_numpy())
+                        col_data = ext_data[col].to_numpy()
+                        if col_data.dtype.kind == "O":
+                            col_data = col_data.astype(str)
+                        df_group.create_dataset(name=col, data=col_data)
                     df_group.attrs["dataframe"] = True
                 else:
                     # any object

From dc46a2e47bacda1fa2dd8f1cc93e26bc4b4e2259 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Thu, 3 Oct 2024 17:36:23 +0200
Subject: [PATCH 073/344] Add stylistic convention for docs titles

---
 doc/development/development.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/doc/development/development.rst b/doc/development/development.rst
index 246a2bcb9a..a91818a271 100644
--- a/doc/development/development.rst
+++ b/doc/development/development.rst
@@ -192,6 +192,7 @@ Miscelleaneous Stylistic Conventions
 #. Avoid using abbreviations in variable names (e.g. use :code:`recording` instead of :code:`rec`). It is especially important to avoid single letter variables.
 #. Use index as singular and indices for plural following the NumPy convention. Avoid idx or indexes. Plus, id and ids are reserved for identifiers (i.e. channel_ids)
 #. We use file_path and folder_path (instead of file_name and folder_name) for clarity.
+#. For the titles of documentation pages, only capitalize the first letter of the first word and classes or software packages. For example, "How to use a SortingAnalyzer in SpikeInterface".
 #. For creating headers to divide sections of code we use the following convention (see issue `#3019 <https://github.com/SpikeInterface/spikeinterface/issues/3019>`_):
 
 

From c1504f641fef0b7888c6c7d6afe63b7b4ab402c0 Mon Sep 17 00:00:00 2001
From: Jake Swann <jswann@axoft.us>
Date: Thu, 3 Oct 2024 13:39:10 -0400
Subject: [PATCH 074/344] Added vspacing_factor as a param for TracesWidget

---
 src/spikeinterface/widgets/traces.py | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/spikeinterface/widgets/traces.py b/src/spikeinterface/widgets/traces.py
index 86f2350a85..f5dadc780f 100644
--- a/src/spikeinterface/widgets/traces.py
+++ b/src/spikeinterface/widgets/traces.py
@@ -52,6 +52,8 @@ class TracesWidget(BaseWidget):
         If dict, keys should be the same as recording keys
     scale : float, default: 1
         Scale factor for the traces
+    vspacing_factor : float, default: 1.5
+        Vertical spacing between channels as a multiple of maximum channel amplitude
     with_colorbar : bool, default: True
         When mode is "map", a colorbar is added
     tile_size : int, default: 1500
@@ -82,6 +84,7 @@ def __init__(
         tile_size=1500,
         seconds_per_row=0.2,
         scale=1,
+        vspacing_factor=1.5,
         with_colorbar=True,
         add_legend=True,
         backend=None,
@@ -168,7 +171,7 @@ def __init__(
         traces0 = list_traces[0]
         mean_channel_std = np.mean(np.std(traces0, axis=0))
         max_channel_amp = np.max(np.max(np.abs(traces0), axis=0))
-        vspacing = max_channel_amp * 1.5
+        vspacing = max_channel_amp * vspacing_factor
 
         if rec0.get_channel_groups() is None:
             color_groups = False

From b1ba8efba7cecc09e3b06634572818f4003f5983 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Fri, 4 Oct 2024 10:50:29 +0200
Subject: [PATCH 075/344] Update doc/releases/0.101.2.rst

---
 doc/releases/0.101.2.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/releases/0.101.2.rst b/doc/releases/0.101.2.rst
index 22e0113cb7..e54546ddfb 100644
--- a/doc/releases/0.101.2.rst
+++ b/doc/releases/0.101.2.rst
@@ -3,7 +3,7 @@
 SpikeInterface 0.101.2 release notes
 ------------------------------------
 
-3rd October 2024
+4th October 2024
 
 Minor release with bug fixes
 

From db6cc1970b965b43546d84afef8f7d1fb607dc65 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Fri, 4 Oct 2024 11:01:29 +0200
Subject: [PATCH 076/344] Comment out last install from git

---
 pyproject.toml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index b4a71bdb47..4cbcb23b3d 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -197,8 +197,8 @@ docs = [
     "datalad>=1.0.2",
 
     # for release we need pypi, so this needs to be commented
-     "probeinterface @ git+https://github.com/SpikeInterface/probeinterface.git",  # We always build from the latest version
-     "neo @ git+https://github.com/NeuralEnsemble/python-neo.git",  # We always build from the latest version
+    # "probeinterface @ git+https://github.com/SpikeInterface/probeinterface.git",  # We always build from the latest version
+    # "neo @ git+https://github.com/NeuralEnsemble/python-neo.git",  # We always build from the latest version
 
 ]
 

From 822ac26e460d63ca1e4214bc11448b835c99ac27 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Mon, 7 Oct 2024 12:42:38 +0200
Subject: [PATCH 077/344] Add some doc for this new module.

---
 doc/images/overview.png                       | Bin 334122 -> 101776 bytes
 doc/modules/benchmark.rst                     | 141 +++++++++++++++
 doc/modules/comparison.rst                    | 161 +-----------------
 .../benchmark/benchmark_sorter.py             |   2 +-
 src/spikeinterface/comparison/collision.py    | 141 +++++++--------
 src/spikeinterface/comparison/correlogram.py  | 111 ++++++------
 6 files changed, 275 insertions(+), 281 deletions(-)
 create mode 100644 doc/modules/benchmark.rst

diff --git a/doc/images/overview.png b/doc/images/overview.png
index ea5ba49d089085a180a5aff490fd1242dfb1efcf..e367c4b6e4866a5b6ec291c590f375b9e956d92d 100644
GIT binary patch
literal 101776
zcmeEuWmHw|`zGDpAt0cLfC!S(T_TO7AV`T)(nxogpoG%W<q<(Rl!Ve!O30xUX(Xj_
z?(@DA|CzOZ-)6pzUu2!w``OQP=XG88iP6zgB_(1a!oa{FRaaBe!@$5E#lXPgB*21K
z9;nrYU|<Aes4K}E_*iVb_V%agKK;z8jQM7g!XP#{cBzEh8aw^wq>em}vfLYLjiT5*
zwdY)U9C-%Ui3qq`=m{|iTMnrRC<u~q6rS@uZA&`MaJ%)=e2c#k*|P2XH)X=k&dbF+
z$2aGAU}M8MI*dYrfIXaI@u9*1&Od)CsHrGU-9^8q5d9^8gA4vAVDDPi@uL3sgYMi&
zLiC#iJGawN|GXJ~bg9qz-|za9*^2%1Cc8`&BKzM<=l=i8{omTVqwI&D6Ai1)8y!Xp
z^7HeJs?7!8-FR`+^5S{-c$xlSbNsLA_m5d5JU;xrIJNX!ebe&nFl#FF<<ZfR+mBD4
z>))y@TKrffz0OY7YnF#zKc?ddr%07YpX}M)1SS!M)T1rr?|~=81oGE0M4tSz6{hCW
z)LF(}a<a3h_}<_m_8jZ;*9s%}E9ggpSUIs#hB8=!4MluyI7QIjb|*P+%0!+#w$S&E
zTm%vpy5{eU+!Pg(4B)e9{&26#^muPM>XXPGma4IFMw1QpJ8t&yWRg(I7Zi&w(+w^)
zO0#v3#^CNjeOo;}J$xpJo-bd^^gj=1vE9uQPT~Bn>h*j2{hj+RAy~L7Nvtitd%p}T
z?hWQhBh4C|?H+;sG2(#nb<LT#_<61j=O-|W<p@5E%zPOxYb!=TPVO>Y_oyxKod154
z&967)%zay}0jGV}Luh&LWlVt?`(vZOoOop7bxH<r4iD?xeuLa<>L1_)=MX~M{NJ}O
zbFGOik}`)g?#gj=gIOZ$EZ#FA2}TyaOBFS(w=_f@hVyc|yW{9@ntvFsv26Ry`fTHc
znX~+Hljr)@)Vt5zZMOY%*Il+hvjs6+jqoe$*?RwYqCB9pqhlynwq`jL_V&k&MjCgD
zn2W{jW453(!S2I1!j9uBZF_1Q?^UJX$arx-C9x$1P1IOgzOx&Aw$+H=rq|@L$`*LE
z@Vo8ry$Jh(jC``A`7rXn2%Fwi<*P)Ts)=X6@l(YEPCRNXT5<wUR*}D3PlqIb`|ppa
zey?{z2K^0u_o`FSZBgkq89&8eezW>YjdY$#UdvYh$@^6LIQIM{`|a4|8NN&(3a;LH
zQRgyuvGmeX<?do_!>r%qoyG1QUhzGe3WJ@~-)&-#zg3zyK2^Tamv((`_Sx?@J}qSH
z1M6U#mBxaCCT}#-KP9p}J6JP(cZoe52OU0=gF+THcfQi)8I<X%SVceW4b6$1*Rqhh
z0;YZECI8oc#d;>&aNR<c)oz*ty;PKH;-!$vwEZVj2u2rVnC25y(*dd2OdeVFQQP0s
zwu}sh76G*#>p8#m8-*EpbaukdGd?}Z>{IXTwOcJAO5QbCa7HyTHeL^XJRZ2f2A-26
z8x;7?T#X>md4FX@#j3}xx9VOM)02`Hk9qSl67J)O*@~$s^(MWHheMNMXa6|!c|qJ~
z`@s~#c5sw#NQ^(PO7KXq-$bsAO*U|bTbqDgo)qlpC!5`uoGKda#7nnl{rB!hcT8A3
ztMXVKz3u+XgB?js&tK^^eqAT89TsMIyx+eCuSgw?>+^e!=Z^ayEkwEDv`FzU>@M~D
z`Tn-?&R2-gGx+nMGm=zqQgW)reOZgd=nAiPjuf0E|9+iDNV!F`&sz(NUT1Dk`#~1#
z%>rl1{oiwKW>iTsC#5tW&i{NjED#8~@b~n;igY`BY2jC<lE75cyxTV@HdmSWcOi<c
zyrUxo8(;5|D8Uc{`Dm<|haOKMLT<2vrpJ58ms;T#^*?7-YEYKyz~Z3sgLDkeXR67w
zB4=^freV1FZuaElWEehq>&3}Bk6U{%X1SEoUdWYSgV`m0;uZEEO}r{@n{I>MaNXRR
ztb6o4HAmWSUuPA*aqk&p+$GogwY1B{Z#1(IX56NAE1|f=L$4(dJIQ5ByWo#I3;HEm
zWt<b$_syQZv;R^}h5NAnD1zQ1IW;-Qu|SNAt5_|CBlV(-T6<+FeS?nGZzaE{M@@D2
z&K3&UKy#0NB@1Ft*^kbZ(q$CVyMo4bv5U~t9s7si55jT#9A6cda&Q$0SMa8bhsXY_
z+wL-d&-P+zdDkLd-n6X76TrqNGg!3@I7pZ1acMg*-jpX`|M>4Ir@iQVal_2tzd3U=
zoFDn@&qmqkkHtmjrd2L=?aeWv<Q_*$Frc)$>8rxR<9wU0<5gxxPjmg&u5%JQ8X_QW
z&~n~!n+rHpXY{r?Y&o2Lwld6~{)Wb>%JhAm^hNieD$hifSxI7>-+`kvaUpK{o10k^
zw%##RS3N3d`HXc&Wsl~u)pr!UN<M8bbQ<~wj5Nw*`R(>z6XY84(g^XM^;IP@D%FwK
zZu8n?;#WnK8`V_XQ!1$GpfmC@e$U-EnX&XYWvsiRh3tniB81a6s`cK)rW`EB-PE|3
zBjp><_fdaJ+G$!?<oW%^r%N>StTUby_x19g9d4<-Fzt0+e(lX<LX>24SZ-LcUwO;6
zPwnKpOIuY5v2&mEt9lw<oxI?b_fFqMd$HOsPAW7eY#U7HI7;>PzTNges?D-hWzpcT
zHqG|`8}<B}_S$Fll<WG%rE}elW&58Jm@D>e`(HeIR@818be=Bh?R>p*j+S!#29~fg
zXB>q>C_PjhJ+cG2vUA1=l1$^b*4+!8Q6=I|Wj5X~`R~W`y~zmK%T~F>+PCF@yo-9;
ze*<y8@$O5pPkW(iQaN_hWwZJxzjD-lt{`t(G?&^-pYM;Q=CDrPuQC<!^rt6b7S-G=
z=yxtP-hA+A{ugJuf|8O_7#=CabHVYPliLye$Xx$jb@hR4v6>5umo!r?&%Adz-)Ke#
z38zsgU=g4rfF<Op*VnXJ^^c54Au0>1SkWWQg0!}}VyIQBI~At__6Ef&=6Ljr<Jo<2
z17s#~VS{fSYI4jYPT#z=(EIEiav?))*}pYbqFq7zw=BQk`F&#dfmH<Lt1Gg4eKdT=
z!!yreBk0f@5p?Cs75_t&_s!O$f}O4_84{l57NZdx)rJ)>Y*4P9q}R)B;FQh}=W6I4
z1Vc8;Qm*n2F2#cUDKa~hzcNvi+h|XP`4UCTV~}hO=`G23mg!`yy7dL>q^U6V>YYHa
zsi$Njj^jG3O&j-!5vXILFL37L^0PsI&wm;nvz-*a2&bUhK$jAF^YDn^+5Dz;rK2iK
z{VykoKP00l+*1upb=W!YY#Vs}g@tIOM;6u5Fn~?3E0`fK&m)*e^<!zT>vav>!OiV+
z4!EM<_|*3Nh#|O)@4nYdUL&nH=;Z&VM9ssaj;FHb6_gH|B(Tp{3>Sa=_}X6;N6TAm
z|Aq^R_Sl~Wu|i{HUu+vXO<Srg2wvYXtB1_Rump*jztOfYt<h^UD<zw&^*QQ>X<hQn
z_^*oyh@@I9b3V`29ghsWAhMdU_|JTB^ScK@$M6L|QucI1DE$Jmro*$M_**M~FAime
zk|-2zasCq)Gj6*V?^WC(W05FgErOi9ykALU>kSJ{ZPUqQ7IPl|b3}gArlHesMZe|C
z&qT>Bao71^i&ltgYZ*{Q2+dyGtPMwA9J6B2^=?6hR>tzWO}H#NCT2ucyy+FKt1>=0
z>$tu@4{~`Rvykkf_gb#n;#|;QRHM6nI%}%A*YBA|{lAXd2WwxyO15d|%1C=}%|KWx
z@4)z5-jN%4Qnn+=8D)5lp5I)6ije(^54xy7Q|wK>nqQlLSy55Z*5ro4eW<F^1a94%
z;+X=g&EYXDm%C~N-e5oUs=PV>?Pc{iu6&toR%=3s^lBNgA8P7elBq#a2uRx}W_Pt9
zR(z2@ES)(!-fM#>cED#5bnbb)H~^+*;A^5#s8bjRbwODdI^3oontH9rW$f_o9)E#q
z6}+_x^1ENJ*XDFt>TnGh%*(yc5mLuLpWlA^v(&P!)nc{;aeB1#1Cr%SYX*74a)UC+
zP~@^_wI|9S8CX{|OnV?(I5nWSzC%e;VZngSZfu#(XIwiECCSZ~XKNKTP>Zyv%^<yN
zT8W|X5c%iSf;aAA^)PbF{z!Kn`eME&{Ajex2U$N_%<nMU+{lw#u+jQ-sqftvnTkHe
zH)VWL2i=STujb<+${%hy*-3^hgz)@+zv1OD7a>^s^6ba<hbHg2fC;{$1?{O#HFZT|
z*!M>Z9TB$QlTqTNuWWV~|627pM;)9WLxe=}mB>Q`?$t#5%SFCbXQX3Q6~~<yd`o@l
z%(8*aCZ^9(@bEfIdrSRr2=Ak#3Ep|^PHl}3+atffe|#<GQ{gLovP<m*@|)Itl8JF~
zVGLjG$09hCV-0F7q(w#Vr3>33^_6lrSw){@Xo%gbExq%2=EK{ZYPn;r*Ak3hvn9Q^
zs_!GSlvxr9skx-U;Xjpffz^MJ{o8C6%_{9zs;{v_txz^npiDf~e^B6fiQ2xjO`mF6
zz<bNw#<0>@H!&|rME|YNj<qnhFy4FU24<so^kTJ<tg!4KNwW7WCG}`-T3qVn@s^oW
zgmj684vDfuuWn=CM_P9isVxVb{%Q2V(Xsp<ur_{uV`=Ex(m7t&48(m-PEI%Lq4j2L
z+#$!!>Gx2g#>K=4?xni_*_bLV<u<kgmkg<z<Ta|EzjUwKJTp1@!LK*CUh?N`GX9eT
zYJ@aqZGqB(1W56kJuZk57;xh*W<CF+ThiuZ0(;QbCeNcg(?wFot4PoH=M51#)-TXK
z?mvMvTFfST<DTAWdAB7UqUy?rMsjFosa~OvshRy8VJ6&Ax(RnS|JL4C&{o!r?tYli
zt-<Ut^gX`ayXXc+N{nKV)QL1DV0H8j)OD}4trxpup7UL9{V$)##L!?$W$IwcV%9sI
z0XK$?anj`_w29d*MmOB4gn95E4o2o0-5}}5*BKc;a0wjZtLS9qbG&Oyb1HfK(hvPC
z55m#U;$l<IoO;p`L2UmeC*l{_gQVAn@slSTBZaEz8y9<DWN$A(Lw{vV4vcO`%(0xg
z;{<B*ot+(u89_loh%QndE6J%SSVjnc$v+FYjb6YJbB}ZMDn!j3>1Tg__CEid$PzZ4
z2>)VZp<l~QMd|z;UV?!8U)FrYoPvTlBkul7Q$e94g;Vtp)S<Ad`$(_N*%mXXP<P#z
zhwe9d#GuguHLl=)mVX&(Yjs$rU$VHk2tl;Y`}gc?$oO#dr++pzymH0e7B{BeC8L7Q
z59r}I;i>;QK^G;jT-hKQLBXBLw-3P`CR?6~;T%HXt9M3~+jztMGllH=Et=KPXvP)l
ze;=L$3ANo9s5ijMg(W2Xz?vv#vPGSyn|<G<qF_r(v~ycs7tr?lKdfht0rBkb#X0!Q
z48pb_Of<haeFHYR@SmM}^zTmH_xk+lQ|!iUv#-#<UqvUUt~v4kE$Fx9yj&)0G5fOr
zdFJAOk4!HO1-C8u=Nd8Sh<wES4~R0s4$+As=pW4Fr^LUX{ReR|k3yT_8M^QcPhO{h
z4@bBC1J68VQTXRv(ce?3Rz!dJA`*S89#3>7(lv+v9zi47|Ers*CHHPUW(uNK2&L{>
z`PW)R+1VGMBGuK^g+mORw{Xd~Ieh!@GZi&;{!so1G@_2I5flo-9uW`9@f9}YhkKmw
zI~HQAGz3IU#`iPXv9dEkS_sXM@mw3<`SF<?Yyxbk3i|xXS}O<&0A%PRPJ2=~hnK)+
z8(kMVJV#4c<im@eSJ2VSb>-lMY|y>Gk?7IA_F~xHa$N4Ee-2KftjLhb%5}R(R0JD#
zl)_XFTSrGe1dmOu5CDyc{M)#GEjQHgVw3XO27|h$^(uI`zBluf042A7SyFLq@;NbG
z0e&8Z&HTxPWl+q8s39(UNaq$hC=58oP0P3(Ou-_hU*nv(yuW)ka6PW;ik4|<(A9~V
zs3T&OMAIWIXZlyz!iV6L?3K3V&)_+RXHrs9c<)u}AfC;&21Jpw$poH>r+Gino-7g1
z?v;7L5z3&@kcJLWfl4(&@n7;u^C*-;6@_$ssgYKXr*4SF%nLCz#?D9Tv(M&}UmP#z
zK6We(%sOI35&gcFf9+e5Csvd*uKifXoAc;b+JNvt1Awk#AZssGL9T?j4T(Oyt=#y%
z<JZ}M!}~PE8&fAtwv<cqf8NsQuF#DL_EY{X_}<}~3+Y0^*AjaB7XjHsVaak2yr*su
z-^ptf4D2=*m65rC9fRI{b@FZD))NuNQ>>73{}>OER9F7IO{KGNXC_+~Tgr&WY|GNj
zE6DtEcH~^(sZ-CE*qr|!DRHS&kDHCv59oiMYmG}O*~wQv$mpGlsgsUwQ{PQD_^d4Q
zC=Y`@y(WHfLuUC)?#tUQ+%Ec76jTIHZXj)a3H|Z1%(gVZ{aD3aFZ1wd+)ii3H00PJ
z=lRJ#&|<$+9l;|vhC_rB?vs$CC8&Hf-WXF~ZTh}k(}y^n*C>)A>QdCv&<w&XQ~h>|
z55?;q83s|kQY>K|48fVtjpTadHu_%F*%UYkW*PUB{nhaBaDY^lR8@b^wmbvl?kf|0
zGFc1t$Y8dZ%lk={vu+4LI-9$r4QQJ(eec*EOPfO1C()yTNuy}x9<(SlPf+T5gu505
z=PxkW2TL%X>=GXJDO$?=$OnND5EXRRkPW(kHn^6OmGuIUhxq~M1Ecnojt7=eeVPQ;
z9|iy`>R<DsprmBCE7vbc4F8~Mg8fIeA%(~z^sf1;pIux8A~86q!DX(x(tY=5FFNQp
z`|PZJttjree1&52zL#ZvYgr0pmb0TB=x^oRI|uj0P77*MUnV-$O)8yXm7CUuHV0TA
z?=I<RC2PdpNb^jNz~bi0l^0A>@DJms%v(T5TIifziL*0QhIArv9HewI9YiT+_HNMK
zFb&sNj_c^{{D|$D+NxrRRjoU4<p4v6(7M>~U@bpZ2k)wK5Oq+&cY?xuB)B7doP24#
zALTGT-mKHDh8ZxJ*bbgzOj<wO)pqU;KZGs%(40MqdD`b}GI@hn)27_4wG2~x%${l9
z&aa`XbeZkSPxa<8dtQ2D?)B&=3W8amTuLcZsN9olDG<aro>(&lOmaD@T-VAIZXn3g
zT%Fbs?rEnL3C<q@$c&#=`0+PBL28=@Zo+bjzt0zcVofjqrW>m6%1@Ei4M@h3V5BU2
z+k_Z`@CCJ#=f#<CpR+af20!wqX)YozDJdx?1`5+J0Cg-?*Rk#@dEIG#E*a1@(X&hC
zq2^dm)!}>rRWYB(de4)kPes|aT@!gZVkZ4}io~e$^SDwsA2O|qf3=|<!Y5rNCw?OL
zxLjAhc>l5B^A$Wb2}YLQTg*Pg`>SK!nxss^$){9L52g0LhP~FUF8WRoGL&I1=YBuE
zj>+-)`%BSBn1q)d1Le0A9&E&t28f^_&Ok|bTypTn3|5Q}zOqC-3fT=}%+bd%eDBR^
zT(Rew>`Ml>Xv1gkyzmBaGXQ@_y3~GLbRdL`kV~%U6#BG$hF_-K>+Qze!PdeFa};BF
z+6qxuOy!-G7&r@pvsH%lo3t|z?`MZ+P0^Oj);pQW4Gov{Ed9W8doxU$?5sm#&E+!;
zwMMrl8eit;iP{<b%Wae@Upd(Wn2?M^-23|PQbaqXh<dY=%euH6$Q}9@df#Fa5@@Fe
zr(mB$6}>)pcgv$&9P0eRWYjG-Jo0evIl%J_48~;^pXq!-djD402xAIXi>+hDa^Ffu
zTWMs6a6*urbSI_GvRP%x<?*~8V;hd*kXnMYN85!^zjv1{;><U1Z*8j2|J<qZ5$;nm
z$vDNoZOvuQX-!{*ZNSozrRmcdHvYuh!GU{`xr>b_d}r`Wbb`)aY0!sMnT0AO)k)sn
zZx8()dL62N=|;QA85VZvZl2JD@gcQ!z1-`wC&Mo%qwA>=d*o7L>QkN=Z-T^;k&!4U
zZ~Tw8DbWkBC9r0TN8En2^aUDh8>eanSsEKr9s|*s@P)kQJAh@!rPkQ8<TM{j>6K-3
zadCZ;inVMnTP#_q$Jbv>#wD`pdl44b@s-_?-HSbx9RY2E25Vph{$Pfn;=p*_BmI@9
zF)sM4N*BtFsm(HX(!}uI-T^OT$56;pEM$X7sZ;I25?cPEfv|9waxkxX={jW|FHTzc
zhD^|fl&#oX!ul5|L_KsbyCg53@+c|B`;COKK+VL@&kxBR2MlEyFtdC!D&MG&<QoV;
zS#1Ajn9KSk8~rHpN{bV9mRy>*V{yojuFs#dRd?vczaL#$Ox3x5`JE`UIej%vdeUSB
z0p3!T^U_C6a3VS(5trFZS<E9hMMdeX1m1m%l$LiY99nuvS=;fg$}GKp>^>oaywj+(
zy}fDl0I!^hHqlXasS{@<%%+<&nC<#HR60m2?<pv~ul6|aYp=XYiwy42*NSk6&LB8c
zjF$3Tqan(@+KPV=Z;XeOYfx5Jj&Vr-%zMD>PY?|j&aF9igpU#~{R=f)kEUZ$#4Xaw
zNLJ!<ESAaDv68{UqZA>gk{kOp?>y`<Uq<>wltxVA8s4Z;p*6&ZM4?vaFoLy1+DFd8
z2~{<<Q8X!f@e3Ns&J2aI_0N6TQ0X?as&;f(>lzcZrH)<vN&;Pit6?^;8=5cFOrjnm
zV^Foo4bfQ}gy;G_-#?bOX$#n`If(Me!ye!N;JUzp_RUG$1(MeZ(RhrMRrNaG<moy%
zV)F&={$NXcq_cO+m{xlE3DYFmIbB^ha4my{IHAN$b{56h6VX1ntHG03%eC;-bVvlA
z`z>oi31vGUd*rn>)3}~*w}I_wCX>uJO}1-F=Np%h#;dHV+TToG`H0%6iB-;!6K!FM
zt8@Fw4Ng4km+9$#663@K5RgqJL`Syb>uS$_Z?QNvCp)`)Mzpgt`sR*nRa^9LdFeuJ
zh4C<lWD~>8Z43MS$}qmkEzQvhqJcsRwmeNv3(n#cF{jnykoe$DC2sRp|0xIrf&$cw
z>Hfq6!=wVwQ&CRe>(j;ZdSCuoQM$l+e}jdh?zPOq4N<-7@Q+pTaX%ZS_qe;n^2#ZZ
zHuF5xv%4O<e#Evctqs|e2@g_H+q}MyUT+x`uqsV{qy;|g_v5a^Qu1g83OPDR-*=+w
zJ}Q{to9NJvGLL}A{jIMc9_wi_Vyx^KK`#(n=sbPD=fetK=DkUW034;>Ex;$_N9E0W
z+S9duYU_M2b>|jc5%n}9SLEzW&+EzWAJM*F*DB}C8gYboAR^r*s3g>A`Sa2WHykU$
zt*HcO^)skU21?f0zerK+V3yjiCXbuHZXUHM#8tGw&@HB{O3r!|PnqINv-mL0dH6?m
zGbyQ^o{RDC;ruX7-pj4>#bYsNy&~&QrVQIX4V(~2t`M`38jY&fdR%QwSv(7M&wI$G
zw1H<Uwu9H_{9R#+h33Nx)LKg47n##|grts+*LTJ~XR0D_5tqD;`WtB|`H;s`RTh`g
zm0RDIocxrNJvUN48G4E45XAR-9WQ*`YTLtsOrdT~$a@7FWHf0gFX$_9uBV~8n7NTo
z#J1i#^QK-EH3nX*qY?k{7HIrfP`|+$#f`+qwQYC}ZHPS4|GrB7Voge+fa9f?X{eA;
z#P=Z`ujiK|5ZON1whd1C8)QW0{ad}yuf=8h{n=2TV&UdSZbElOs0Ujs29HJ8x0Toa
ze&ga`!m?Wv7|-JWxK!;|;<^LlCE9HN`FX<$sk=1KPYw$I<3*C#WGx2v;b!_?_(Xlq
zlF+Gz()2kmlBS{RVHdbvZy-M>FkiD<n`@J`_0EI67D_{1QG>^xm78)h<3@&IO(0H}
zbA#xFNErlz|MR}t4KN6fwTEC||6lv2fng&ikqvbh3A99yC#nIz)Y+mm?&#=fJz9*D
z55q&h_4<|Xs60Wzz{$aS6bU1^BmL?4yT8XrKa!w@m9p+4h@ZMut8a6FN5_^aqP)R~
z@DH!yT<|o^6ut6rvtMB4@fqVvbkKIihD!TuV8<W@Vr@Y!`ezH34PXl$5e49bGi^b#
z9F&W?z)7_o|H=lqH!C6(Cw?R7c!}Oz85%q~K!0dyJ%MU@H|&XB%_4$^jyy=9N{)&d
zyS@Bz?L9W5^EaBe?mfGdt#RQKR<_g0@raw9c|qISd7KwrK?vqnRK8*qRM}A3XZec$
zsA;<}{orb4Y&;2j0!_TO(Dzw@<%ON5J%0A2Kw%@gSN&{w&f~4z+{0gu_!Se8MRS$c
zsg&6JRc#(zv9X<|sDY<rpzx<ziO$`5zA@YAeyv&f)~(TjT0wwxK034lK@Nf2F6Txg
z6sapCg=nJtXxmCC$zkBNB)#-qKy)(~sP5Ga?hI9yQO3iCi)5(~w>INd|JX8+h%+*;
zME~81+IW!>*Jh_8Pz&%O*WIj3;;!ujwT#h`fOu_A)XV`rJSer;1&3pG&%22+<SR3c
zkK?y-g0<u&&MQ=Yx($^BdF?Exw@9YL<B2@3Ts|`Q%DwH5$N3I|VJ73pPJmQR>!0{S
zh7;=4if5H(8cD8boxw+;BRZ=2ecu`>oz$(zu{NP_z2;K0dv+8l#Q}_Xn~GVVIO@BX
z5zH16zPmO;B9jaf9;L5qI5;>8U}djDw$m&Fk8S7ML+r|_D`)3B?!GHl`9)wN(=pa$
zYl}zEztJz?AZE@GH_15H2gI6p!=o`S>gEF|Ot^%F_o0umizF2XjuB|-52HiG4~A=N
z1txf-ja%fSB<=1dXi|fjse1PJkx1yhtEuXk2b?$Q(rxQvi=ZMqK5KV>UNo@U@?`3k
zkcjv(Kr{_crmTynF-Uw>6PRp^Pl5pvI@yY_3_9D1%KS-B$8UZF<Yh(~Q((pHfQFCH
z5wL|D%c{S}gdaOj3fWYdH||2SW9Jy`+UC5epGkmP4N~=dkSX}^6Tp*!3mv#ZoQ3Km
zt@T7<W5su$t-g6V-UfXJuq{bXESo$YL375_KXFMmP>P4APxI~&92dZ|zCh0jadN7S
z7<c_T((zI(u=0PBJInD}GxOF`!(5<{J~rtmBow+5o@;5D3)s+6qtIl#<{-gPjx;kB
z)naaifE=!<^Njd={;Axr*(PY>Xz$nHxxdTwdlUW6dUjry*=DrTLLWOk+w*ZnAD>b6
z4A3cq<9XJwPN?yA6$2!`PdHmqu<QV?S91~ZD@Ww<izlioDs<QNlx&ZgNcezne^|_Q
z4R}%Y=Ug&=V+HTtMxXCM93>}bgEP-$s;jhUX$ty#Vdt3lQLV|S#=@@LrSx7^R+1wI
zJ0U_+P;g{mn;099M9rxhmHYM1EjoI;yQJSED*>tezE-B>z4q;1I$^q~RR@kxdQqsA
zB{D)@(QBO#lmmdo*p+`-nR>UZ$`)W#d_wR2DrJ%g!YyorGl1K6<>caEeU25?UtUWt
zpW#uFkhWwzlk`7w1$=N|TrMne^KdRmOds_Sb_E(}|Lu?XmOcv+!0p{xd}$eY+htbD
z&<-pe;)p7XwejC!Me>$E(~nV2p48WpVq+c0OGkjX1!6V5KsoNu`h>PurcA&Ivr99Y
zWo-d=`qP*JJaB|-(4Q%LHlO(rII0a4a>8nG(H~w(MuB(+JU@zR?(N&R5KQ?D%g4cB
zW-CpE&TZAf>@8~_$OAUT8hB(ylS~^0%kEg3*VK5)fBx0T@_wtoNxFA}f9;^=do|!=
z<~w$%fs*6kZ-#(!^7`=2otKLWc0;dB>Yq$4cE`nu%S9COptTY`oJk;6m^9XlVXC-~
z6dl+Z5c<;2@ApteVt@!auXD5Q3~@!_Z2%|(N_j8ULNgCYli|`wxJCtFIUufJpfAZE
zbsGXyWz+qObQD|Y+drG%OAs&kOm>0(C@4pZfxz}l_W@<)z+LSzjFNyh5TDIIuilM|
z;bSXE1h@fBzx`uKByc~9EwEi4bSNRWY7sf>l>7r(OpMHkVe9p;6;Z_U*joVdSZo4F
z(e;&`*hm7@5bsYIcgi8$L4Hx<ls^xTh{&H_a1%p$P|r{>JF4@FW{EnT1pPe>a@bTe
za+-&OWVG7(`CJ>8r)MrABf}ao@<#_9epfBGe`ukKOKt(Gd;wad#c;|jJhDqi0JyC-
zI?(DpgQ&rF%O<+j%O8j{hk;Uw9t1S;tR^K|uS0o(y(BOMZ2E&+Ay2%QaiIz+j@*Y?
zz?cfXIe_X!wFXFLNiR-H{%+=s0UN3?te|tG4a9G;tvt*SveyE6%J!H`>+vrz9Rmq0
zO5yb}ZCO&w$cJljq`!t<o8>FuZs-Bg41~1dn<Qp2vXXEQ96is{l@*6@toJNTOtHi4
zZP9)Lc(fnr%qh?AV3BF8H9oSQ6qB~vhIFrjAF>@9DGebqJrKeR&}6>>7%(-#=i%Yt
zP&khp!nG}8Y|nBmo=Zlp_!YfyJ%gaLJeW-%`Dy9Lwc+UmF(Ye&kVHJ@6^~-g%uu{w
zBBkspKqWx8K_P49rleIz8gP?=zFw{uki9#G-L+Po4`h7A0<{LB991#DQh%*7qmK!?
zIKGyZd~xy;)J2quNfhT$7q62(1?@|8!&4bQ=?|Y+?61^!L?M_5r;#;764<n(AnpLi
zSA4Zlvum+$L6D_3kRvT=TDvwmj6B;P({?y9LD=-BaN?W3E8;Z$7y=t;cZH+Y&trnb
zx&;Cd1euUn4R<G#SU|(p>c2aORV(}s&A{3@0Uq-*OBVC$Q_XR51#BA%zeI3V?x`Cs
z*A;F%QdwDpUTcL*nQ76V2-Gn^Xs9Xf<4oSSeid9zgChK=3d);n+8dHQ{5?mWS!yHJ
zQ9W~0u^(hL7)>ug0P>1wAD<{r6MyB&)`uTtX{t{Y{FTI2nvthl$b3smX*cWIrxo|A
z#(y{ARbiF)XujWW^7Eu{&8HeRd?**{7&6cVJ~1M5mA;9ZHZg}#B&q+l+agXKR+E)E
z=Y{gpgIaH3JiEHP)qQc!q4||};<V_bd_cLsqT#uqvm*N7)<)diQ{&%k$$<ptq<@s<
zf<SMTUXmB~C0AB<2$L?Pg<=N))9WSzbe{-Uz6k7hY?TK2df|V?Wm6IyC($H7;G77(
z7h(zI2M5u7tpFR2^r%}7_s!2;UJyKnldS1qF<g<{ry%2R)YD~1&o6LYIEq2*)z(?N
zBTV!;u@&j$f=H_3rxgd~+~wrdByezesIl)e5Ma};JT!Q}-$ya#ic=&fT^Kk#??$WP
z^-#@!V^WYt(r=$TO9^mI-CT-q!@dm5J(RA54)+<B+g-&&dzg9%isqMx@oF*C|IC^A
zMM!$Cd)gMT6tL&NaP44dmVfY(KCNEmnOt1=2du{AyV_DaIBCyqti)4*Zt2;F=-DZv
z^B1ZO>3|dAg4k4)KopJ2Sj)jTv(v-hNk71@nD4SsX{<i;xU^!j&0DJ2_$Bx<p{xP}
zO<P#!S|EOj%9;GTD7Jj3P6-4DWeMq6ySkvB@^h6Q1wla$jm0N#iLK|0)Sqv)99jrJ
zi+aN{vf<{Z7WI&0*otqV_7bD*&*j<#t`N-NI_kQs8@C>`WAt_#&YND|aJ_$|8?U(^
z{DUkqpoJ`q;o5^ba`jjZm7C@e?9Z=^j3*G{j?)g^tN#qzJ39>bhjWZVc9;1si>q;p
z*@%sfq}=9{&a-K#jM^A4qfV>iS*^u0V2HHB{?(t(OFwk2<7AO*k(P<jkK!zDy=Ccz
z**FGaA=$W8Ig=k#AwgQ&>J?$~tH^~OvO8Di3zP!q#kqgiM$V}jjLAU)^51y-`GKV{
z#+k%M+`_9)$K<1QlXrGjMG2fgrcwSc2L8LdBH=~G_c?^K#DbW(cp(v&x!Eyv3D->Q
zB!~4VuQCfeTwWU4V!u1DFucA}F&tWB(yn-UUWfG>UXA_|3Ns3Lft*Yx2iM!PgZJ5E
ztp=(tBFYu(QX7TG8F;qA`x)le4Q=>tg*3J7d}2<&<YD}-Jo?^A*jGrB;*~3HxWsgF
zDeJ!(mFc;KREFX-FDseWIpkk>8n=iKsn(B>DyFPA5)u-^8V&JPCEbEFBT|Qj?aCu2
zzE)r}x`7;I-TmRPRVnvv#r?{ag#AWeZX;oX0Lp9Avix&a_l;6Gl=m}l2-|VvmAW3&
z-@TtJtC9^uQoA(WXH>=POga|1et^S9nOR{Mkg}G1Dg1%MB;t6*1hgX_<}V#2Jt~Gd
zcv$)@`1_Jk0(CNf!};;U#DqnozGhp$DmJ1q)dKeQK=hZ)KY5M;p|cmQb#eoXr1a8@
z!iCr_P8@Sd70DG37Inn;<4l2vDTJT?LhyWhLQjOZsIo=UuE{W8#)rv6@zChN<%BKX
ztHimbLUSCC15c@3Lw-KsXNv02;yz%pbe|=s^3V^Guwt70s&$^Tk}AA}FIm3u=4}rS
zDf3hOA3^D%Zg3}!J$Wz1u?q8XfuD#RtTtY#L2Oz&i7XvDPfR{0a&V6nQQkS2@-v8=
z5mBZKt<_N7pz>CXSKilO75|{w$&6s`G&;w-9Qk4Rn;umGDW+0x^XEwtD$C{p7Lrpx
zdOSA`1`@S*^z%nLO?pDrwqhhvqBYv1g-<E^@&Z`O`kkZ3IH=DgvYtOxjDP56eETXv
zFccDZB$^LKRN1=QH8-PmxIU!|=@yDadEN(V<2h#V+a4twZy%oz8g5r!qI5=excuZg
zDRd>UNXQNp*+&LF&$h%l-_pvYp@7VDdx!dfM@FvvX6}Nn$!qfjG<&5%g5r^BDV9n_
z`a)x_2cUW6T!i|R>9cMKgWIJPqs<&H@m;7$9E$On44yg?KQRxUmb)w$e5#HekWDg0
zsWS^=Pc_Vaq7y0>`za@>=1}oBb~!ZSikU-C9$Nh*8bUCmGThuL99g9k%=yB9%zq3!
zFb~eaMFt&wHClN-V`;TmD-k@-8n;vJN9s6Hje?S#^DSsK^}Y{xK}9kAj!E>%5s+pp
z#g9-;B6aUOQ_<8}#g2+-&;D}GGp%~|LXhLuAchC?xDuZ24|69;|H<fFi?_0szB7`q
zi0>hFa@%8VobX1M)#^q`j$gTTcPwbhQhk{)t;q@)?PWYxbk2`u6}>vu4PRh1LfXcA
zGG1fJrsedrfYPslX96A03l&}jOYrFy;NZQb=yK%4L}4_(XwLf)ce6Ek1Z|m(y^ILv
zsB`F>JlC6{%mpIJ%^2~WAte;@F<vYw-7D#5^{3PQxLe~@-s$Kvx|Elb(n|H7Up%we
z7KkYYp6b#fPOxO7RO0Z$b{VGDoUMDD!wHsY+Z`H8Ri+|0zC~#=5Xj4~t>a*n-*0~U
zt<og9(eDKoib5&hxlCK;Sm_Gq6(+npF3mfiK$?^H<#7Qi4UfSJPzZl_KC|Wb8Z@yZ
z1=I9Q$ao#ldVo&@*JZ-P@)50m!y*uMiNm7*K(rI4Vy}!MW&Wjh$Ez@30e{_uY<)z1
z)pF(~3WK&<ssLy<$7Z6bgkMFmK-CggmtS;SFgy{jM8=gmqC$1Z7<AdB{l-&bH@>Md
zCH_PpE!zTXD|0I3@Qomld(f>=jtAWLcKys4Q?;GH@u_z9oKcm&(&Qap)jiWjvMeTZ
z<#XO{8y&LaH_mp~DZCU@u^H{t+%T(gjcma9a42v7Vi%ZhU5I2}129?}o26}r1{-v&
za-Sc@=fAdXV4s%o-r8s;D}h>5&m}rws6a!&Mr@G)Pc5?hP5eNvyjRIl-8~;49{>W_
z9~04VKhV7Wp*_O3rNSZ%O5$TsD|u_30g21<Vk0vA>$~Cdk*h1km@C;V>fR*#9jT>F
z+&#`IwOBU%KSNK9f)}7ZmWlF|G}~_w`ryh<_~X*JS<`TYW{wnNfFp>zcE;B5_5lWV
z({;cWmpM_+92d0l2BDUX8D`2`|Kq1mnxO<8s_6@%daC7t4=r9oJdsH(tX+P?+87tv
zQyvCg7aH7A5$v%x3FQE5;=29HMyzQWIAexyDOaVFQNwh9H#2b@S<4sSPgwN7yqO!A
z-7h&$bK>zV*2gF_S!C$lfm#|q?fe1s)}l{6uVXKfcH@0C0tFX1L0QDR$bV3~*Jc-x
zwgE!8_B}d~!zu#AdgA1G&?m)Mx*7kl7?~TAdu|o)Xsl6{4O(}qNGpPO&?U-#TF?kn
zXkq8Oe7SRq@=_5K=@e;Aic>^ZT7=Kn+z%82w~XR$jCIx4cw13CWM2*@zthV{f~UL^
z7C*6eeJX*+lhyL0cTtXXDr!Y__tzjZ{9|KF5^TH0Yh5{e<-v6ahl87+2B@U%1~S~x
zLRY%*-k(E`v54=by!X8d6~?gw>>oHB*#TC_zE62LbBX;K<%-$^=(8`t3tP;-+hg2_
zzE?4~L@B^v_?((-UA+~Q#TrTJ1sgd+_GCmpf|#81rmo6RAA?XRj=ln|$ifpT);3(@
zGyec;?K2$`P?R-Xe7m8f`99-gO6rD+Fj^aapw4wh;m0+CnVfUNf%6*ru=Xy*Pu<{*
zv0TBY#(QjQ%X-gIMA5R`3PK{Z=EmQUYa+qc0?t^MZ4}RYG_dWbP!&cs<69MSR*Do1
zbE?6kdSCdM5T~H90R`&l^1!8U8Rd>&%gHKagH;*ag*qT0c`QGbhlc53q$XH2_|64X
z{VX}auc)7FdPaHLGX~^%BfkIlC?(YP_d@a{(13V`XvkJ-nG|*TexM_Q+3sr#?G23^
zAH~$}dhrggp%v0U-kNHM==c0=B5tnG<bG0TtXQMC()0Wp=pp3hZ*AGiN3Xl7hbVcn
zl|gykw4(Gx{;FJ58BLUkmJT&(<Oa}~J|M4;*RBH~R4XU*J9KxZp0T;BpVZ#l4Q2s~
z75$vTY-o}22IgC>S&qfl4d<`r=`&Kga%2i_O*fIG=xiw1B#^`L;pq|)zr1vR$c3`y
z-Ji8vn6Vow>5JhB${H}9L3blju&t?WS&bjLU^zrhD!@CPL}@XThWg;zwMLV$UhBMF
zZZCStxn~Q+%XyE5oU_HlVo&D&UX<|niCExBP#ODkBSD<B(*4Xy;N(k|NQK{x$j-Hn
z-{8DBH$8LjoRF+M3GV>HNxX7<fBJDv8OF<kjYuImn;sVao9*u>w-qZpqsYDgI+2%N
zeUF7H5^t)v$E#yE{GM$6n1q0Z+a>C2FUoJd%JE}6bjjz?RhR3m@FCf`&^maa=wsh(
zyHjA+rmSFiyoqk?<L8bisJKV2ShLP6I7}k2Xmn@+x~7;py>}jvDVwTbu!TpwVDHn{
zRb2D=4g{-V4Vj}{uVwTVgN|rQ&YyFDJwS-K8)Irem9T)Xxvf9SsS`ahY>WtGy5<gg
zk{2M=z40aD>oBU^L|V}c+hGo5;iYEypbLt;(B}=v|BW8bxY{8goNi)h%y{0^)EM%S
zXGqmqHE&Plhi<3Q{?5}lYU$+B&=sTM&R(LYhqhuT*Y;ie6a^VNSM#Y4w7if4j~#vJ
z5gs}&Px}di*y+BKzJgVw0Qwk36(~jo>-1|0T<R9-dmS=va|nYuM3i}Wbq;vLTYbZm
zMq97MVT?qaD^N=WBLl-~*e5K!WFBW6nWWcQ*cWb*rmr9rb~!Tjo)gt|2ioX6yT9+;
zYze=Y??~PjI!%q4z?u)LU5zxwssjCFr&4~O%;`HeVvdH&?_#L06{N$EkLra8D1Dnu
zqH^y&90&bbN7A?rh1L<IL8H%6O{tz(!|SzayTswRN5}!|jxE`<?J&IuI@`O##KKz;
z1g}t9MBYhO{<PKajN|Tb@6C1H=LF*7q=&W*R+dQ}^Dwe>MIwKPGxA~b%}qK?wlGWs
z<Ucf7gx@_5+V?cpHv-avC|~Z|1^X!?X{TDyn9SA(#k+Xx2xh$Q+Ck$~BCFU$66DJ7
zYi{~pVdw#YpjALmKg2d5iY!FZg>A(yWOjQv3F4__cj%37EG;x5HioS{UpqW;mbts7
zoW~i`9fkOgJe<x`E=XYd-I10#frU%-V4p<!7If(9F!UsYGYD0Qai#HFy*C={pVa*z
zVp=J?rUfm=TyuQ|0^nl6dF*1wKfa&*8TVL%qIgJbR}cGTQd7G6z3@{&%dnVAVZ5hQ
z0>{?Z6qiXiS3==4M%j(;$vrTzq5&e%k^8s#bU_E{W~c``Y78DaOfr%9t?e*!8Hcgr
z1in;vV|NCIb^7aiIE@t1D<lSNgw&k~f<%p+0yBlr_W;{1Re4o%aibctSgAEuQzzg<
z)ZG+S&}7jbCM^AH@+!Ecj=B#@^>94Sx>qPmqGl;kF;q4V1A4g<z`C@|VL35-hQ{h4
zkV-LBE4aFy0_Ko#t;AcB<X<y?Y2yr4Wc;Bz(#gJ97~Cu%-wu$k0>9Qq2tI53&2n8j
zygH~5jdj-#Y>sZfDtaXpDd!*n9h8!U79L*uly@Ee8Shd)p{rkk?qyt8!l#;-W{yLM
z>NpN4*qf3$=oVKgE-~c#h#7cUeH-8Aw^_|A<Lt;Avbt%&H%`8WNy-rLPD*&ScA6&~
zYnrF}Eg-T2v3^YCSWKZ`juS71)2!hjOY>JV1Rv^Dh~FB=7KQ$Ert#fVF-$#jg-iCK
zc-t^0q0k{wBezW>uAEh4;@WnL{T{+@FxK^Ftu>8Gy3RnUAmK(S2P&~t`a@f}w6Lrv
z7swhEoF1y$STT@$>mwNM($nIO^#ri@IOEVch|ol)Dk3A~(hMcA#`6UYlUDGTNVO^3
z!mz&0Q4zeycLN?hSLN9!ld?Ap3@p+xyLLoqP8Mnb1)i-J#wxk=K7|x6a^ApA=9X~B
zqxNsReoFg((aapug2IMlmq0%^^p<|2Ad(dFV0cskNgz!i&JE%*UXfg`$N*`guu^pq
z%y>bmEU{_@YXVa)mEiI!>$K1wJi!Eh>|!N?j!2>ny*CaGqa?}1&#ZdZY9(%lbJp4T
z8lw?gKW|w`G7L;1WbccpK+W~2(o|k(EH}kzI4^|61?MQmkDhM&S~Y=eR7G-a<(!}6
z6ymCaG?mpopK};Wd!RYmS?TI1@<N3-;+n=;*BlWoPfyEh7+cI=qX_ReyT1&u^un*n
z$v8PxtT=L8F{Z~qJ|##8D2jSa0x<accZhW*i7j2qzQi@$v_Tj=s<#_tYN-h|V))|7
zP4V8%pPT&B;IWY&wvp8r7x{(qY~e>#%*>DNig0F_Te4(cM)I0MwFFhw*ZVHZryZYm
zB|WY^?WB}-s`S#4yZ=$|Dfd~pTR#H_cH<|T)Xwss2kR5-#M2bs6cX&+@rKSHW@%(o
zNeX}T)K;D*88p>bs(!5qv-<<2L%%S&gjS|R=mXDI*H^)Ad!`|Yj7tZHw9y-0#`?dW
zzWMYN_mWh%WCqZL@wFE98P<dIILUE+-gN#H{5^W^2}DOMqY0Uws;O=VsyuEoj@|)g
zm=&wU&t1uM7R1#Q6tJqvTHe#w1bI3AYvAo7KdYD&{Qaf)aYB0=8#^R9QZ05%3uSvt
zun*!pPGT>=x)v$1Z7H3&Ko$R<8q1$THfn2X5Vw#&ShD^4tL)ei)$|w!em51H2F|kX
zf~(?R&LvYFwS#=4v1qv^C34v>=>#gH-!mN!U`Qe<w!@8&8<nbn@llD>%T%1Hr-<OK
zfn$YQ<WZ~N<R`1+2%@2r`VMjNYJ!Wzuz98tg*?lpA=fPN?-PXr(G0eg1nG}oqGV52
zIIkjcKaf0CUMloU2#$0OF~99@Q<f=WKsh6CD&tYLVCnE|7=z~<d$SxJv;I7Rq@RFN
z-H0uJ;*;iWRSEj#=;hk2N2SNVY0MJc?XLxdI9o<}<`8sHe#=%o@Syjh|F_n}W3Z{X
zos)-Wl<yokMH<hcXFjbq!+y8FxXmwpLrYe}%U&bz;&<aRt0yPJ>i`Fb(!J+~Tgk=H
zQI3W4&0%^Ew>?|Ly2+#8>zrF)<6VqnT@91Pj!jG_NSK)$BHt}miT!goh=JynZ3A0|
zOn@JRx!0c+GBIkfSqLw;rlSSZ3|F7+NFl4*kALv!y;4MA>s$j4Wf&BAVs4)it2GvV
z&WD-8kMvsokI~boSt5^tsKO!A3>yA+cSi8BqfKJ+lH@#rEB<oKPnw;ATi207;h-A_
zJ>4O+LN&UDc#(*j)|2w=8V>cr)>ZN_1vwjU7{5$Vj>!z$hXP9us6&=-h1Y-}{Igh<
zD~f5KxaS@C_(K(XP7_G81p52b6CYfrJnr2T_Rb=<Lj4@hS6sUhn3=w}{N+ow82K)5
z_i5v!#a7sqNyQhxgNfTIU%eFj&_32TQ}2|${*uO)07Pb9?kL~wry!RBwO<m8<hS$r
zAJeU?Bw-yOj7J3xixxUeA>L%iy$+4u$Cseu_UDI1rTztQzKP9u6MKl!o|OjEl%x3V
z_Uod^k{7lIc(^%PA|jz;HpgVbfxivtd4;%LKev*EiLw`Bu@DkmB%>TS9M~8#eLWfk
z=jWfe4T<kPSQVh4hG}6K)p+9Hoy_24Z}Kl0eVwWZ$mqO}g;Rw)$Zs}fAN%TVvrfIV
z5}3DnkjIJnkqu#%aogR_!C?iYc$+~;eEaCVt|>ee%PW}s+h3okxtlH8|Kf(bMXu`T
zBe<rtdI@Ysw8D!dIZjo5)iBj}+RNXmj59^MB!QU5BVxmqShPR822V&Wsu)S~XuOmX
z&k>l}&!8*(`aKStYzSvL>|ICW0*PDB$J3$?;ERFWMM0|#jDEH8+m3q&8$q{b5S12^
z$qROODJ7%$*w|^~A`^Zks3aCU`!9_@uI}usV`sFrjFkU7pDU+&7Gr7K5d8L*N-v02
z&!EAAZE&2zenmKhZy(|A9yH@(Pen!5(b)+|^4}@@+^LeB^Q0uc{xwoQ8DPVK5k4j`
zznmq^B%0N*v$jaG&{VF;ocb1c`+boM5|1uf962v!FVy?hFn_hPsO;-@4&85IK|wvx
z?f^TGGK-d~#CZHHAkirBFZLHJA(fW~HS`h$YKAyA7`FgT0&syaMX;v=8YCM~%n)_!
zWEAg^_X(H!(ih(bT>Z%*us{~A{+a#4=Sf`+Fy6engPw4Rb`j7ACZbCdQcO%zlB##y
z(H|(~M`F$h9hp6WtB!yfKo~DR1G|M0(<vCcUC;pJ72>Ou_tvFKb)#M8{~;$+dbhH&
z0-hj&FY!md%lUs7`=AiEcLc|PRr)WAlK(@Avlb|A&GH{rD@aIQ)?8<I{-XxRdAhDF
z;}MwBe-`q9BqBPKV&^}LfgteG32jck4f~JE7*ws5q9An|&i}E_<bsV^ge|e6MZ3DL
zmt=M%LbA4q3#lvyV4CFs&TCazHFU<eg!QVGrdTLo{$ePEED|(RPjJy{BzvcZXNS(q
zzLz7V{uXBA9pq*`dLYubg;CJIMSV@{((R`<ppS)vrkJ`9GggAsRFre@459o;82AOz
zFB@Fb)nh8b0dK11@dQ7ihd?rd?DVp=7+R#nFuet^qa$lH`_0-9kC^(l+86ndKwI4$
z^AykrQ|Z!FD+0aI5aJoA%17~6t3CEtbo-qDKJ0N8X~P(Muu)!#-T9WBqdpWwQDF{}
zg^JVA3D6Ns|IEjT75sTjDt5O}MJWx1Dc|edBN8pzc!vxXOo1;H0GyLGR|a{3`69Dz
zL#{4>!#VI<5HKdcFAt9r9O7a1`M?xY-ljpY?Q#g&qL~T)|JslduTpmpHS5=C-3rX<
zAwf`{Rr;`JkNJ9*9sCkO<fHxBXw#2>)%?dw*7KMJ<f!fh09$We4D$HWOoKjWSx$u6
zf&5xxmniX)#-)#VI0o;tER*Fyq0Yc`eZ7{P!>jY*RKmSh@EY`tBCzrR02(}|PzN$!
zmmP351|hov&~S`oXL&9^b9g<T=eZHjQu!k<MDH^f9+d!r$$LlIp&|eig`acq@l}Ev
z6_&~Z2c@KhgNJR`eN23!>p0n$q?WfW=k?HE_Cb4aBq=k<n4ST%NZ=2{DchS$)*-r{
zF!T*+N#{1)xB}WcnDs%6Prenp=zKc{_Pkg-m+a-I;oNV!?Gg}PqCAVWUc-h=$eG}`
zVz0M*JFvWNKS}KDmGfW=Yi~;025jmF&ShS!VxTi&@HZ?VSqqAnCv}16Cy+bHnS=>=
znqj3513+5esu;Bw_f{0Y%A{t6FUx`X`NmX>{TJ5#2$(M>JTuAZ;&}8Fe#@fKeHk5y
zp!tSOB)TsAL+2axmSotkvM)*bP<;Jbe3!Y+B&zj?Of8xJXYy}uSG?JndhVY6l8FT(
zv}+VbEcs092u?<&*i)&PMV~MTS}PT*Bt(+41)>F7T0%5liWc*r=<>QuiWbklK_3YC
zI@HuszPm+Jj%ub4JS5$J4Ga$tqlx46N8emdDAs}JNAt&ZiS+Ff5TaaQ#PD~e;@l3C
zvHhobMwwj}eAG46(RcujY7#3<e?5cwv588PhdG#TVE}1pX9!^0Wr6+zMi~ZA?uzXf
zdMvWZa{T!S!&OO1Abac##>BRM_;B!rf)pk#x`S?bJVC~6cjFmx<sO81(o5pW-_);_
z${7^iguANCmbQZc&bHF?l1FZQC;e7obbS1i(IP?>%W?PBpAeq|V0;7epSk%flm1n?
zGXho(S&eHl2b|Wtdg&+-eu1I@CbF`oB%&M8Kac{yuL34wcmEk#<yf<?`@YIA7YY}2
zC4*;*-zo&Zr?Dp%-C&akw_{^Vev3!tIsj8-Pv%-tXM&42Kn11XfF6=FnXq6F6ozrQ
zJ^Sbe%~#@YVcLjsUA4=(hz|++r%{*~+}?J5r<=Tw<{Th67749=lpuHwY9qlUtx^1P
zno;)iZ~4EELZhRj_fHeUwtfiR>I$HN<2!*deKIzgCl@5@Y%r8q#5R=~4^N}0_mA@Y
z(MUlzOau=8lDicOMxex7^LziJ1h|-aokNPRc`7BJW$UGa+tTQ3CwiQqFZ^(HRVEfF
zdwKW0UMV)rrMt2SA;u-uuAB_SDHuEq0bY{ys+^)w`vg*wc$kLp-SHr<90QYthsspF
z!uT1UW_anD{cA{~Bi{afFu2gN2UhU;rq8Af5lJ=pU8k>e?k(7kla$x$ZETd^t^2mX
z&^}JWxRrnzX0J}`$yx<yRG89pxrpib<SL6i{Yl67(yr?dOl!vhnmr~Fh;hG_zV%1m
z=@Ieo8C7w=eFykmj}JND$>DBMfj0K@sxaLr`ZyOyw%6tmyhK4!5e5pKrgLqCL4jZD
zm^Ax_XgyD{!1D~Fa_ocKL+vUsS#k^G&+>;moU@E-ApgN<^E@E8*q0|eNnuk@VxyFN
zuIUAb^>n;cw|FPUg#mIgOt&4Jc!SvfA<X$Zf#^39_JEW{V!Td%Egm5NGcwqfLQf_I
z#_;&_PmidzQL12$8<TH2=V({N0zoC2baEO0yr-=_DUyWIdO8^A_TOIgtiKri+zaIS
z;-wfDasMNMPYCD0MzjdGE>SkbQ)i(rQF^CGf{dx>w~yoHsDsTz2n$fMOiR)2FtQ%V
zll3R*<OKc{Yu@Ix4!U@b0%0wqluzv=uf;o&pcn?D9lTU_>)|Joc)!8(n49tu$VMek
zIF)@CS?u+^>AQD|uuz}>e)uheh2ssAk%J(F76NgW*eR@)o5E*Jwd(@PJ{Uo60G4X(
zSJzAUxtCo~$$TA1;o(+UKVme-*RnF@xVj>F@i}15Z8!ic<aCR3fAjmxn?-xF0{W0j
z?mjHSI`8@W@3nZ*K0rlB_et3^kc*$c8bTy+?Ap#W&*5hp0->O+OUw;HM+k2aCycT7
zhIqo2RV$wt{}x}7!R!dY4uOy;0^2MjGmBP_JO6<*(+zfg$IKz$)rNQmwG-5f!lYXM
z+K|0DIXF_Mx?;fJOs`!AYr#)<ndZC=$Yil67FOjun_j9hR;~X=*nbCd{kQMKI6^6#
z%<Pe5WE3IUBO^02yOK~zFGZB>y=R$aMn*ErDA^5>$Vj1(BoT?ak5}){_jBLB`~Kti
z{^z=`_tkiLJ)e*BJkH}d&f|g49HO`=0JBOd<fBi2+9h*84J-uhN#(%?PS;q*I`=w*
zFZ%$upzALS0ybx_0Ff0wJSpw*t_Ito6W#*`e0+R#N=qsLyiAOYf?u#3EdoNn<4pIO
z4u~zG*J<K5r|%X~b$mn-lrxo~Afh`IWUo8v$erjj{Sr@2I;8s}gjz)93pu%EXVzNA
zm3d_#bj@^hsnm>w+r-^DY#N?+n_n1f_)$`ntyc5sYwhT5XXnCpt~CbK-k>L+{*<5w
zWj-;)(diH?x`-XHXn&GB_`24O<1$l^zzM09=})i1x-j=FKMR%hzEPf<>rbqE-Lt7%
z{Im62=u5=j>??Q#Nvvzsd-kl_mzcnD+G%$01Wk({Y@!<HL^(b@6HDlCJ-Du%)Q4}o
z3B414&cX651yrXVY_&in1e<U9*mo74E2e<epQGn{xr+DZTx0x;_1nSW-g6`VEg>11
z``}GJ+Pt~kJFO)}6hpL!_}D4Rf_mh>ChS>ht}#@(aT&JP)9;>A9UuQZ?(<%A{buPQ
z8Cm)sqtocwr?uuM&8l{7EPx{!>g&DRs)B9fgI^OEfgzS=xrCuhu?krjZsUr#GQ0yu
zbXaKHTOAjUk*|h4(@SG<hA@RUU%NVZ71l1dp|X7+Io)hh8C7M*E_QN#QqCp`<l8PQ
zbB)@XBftmm&~N|*{YVyZx704zvAIwk`tKDBp7=T84L<wTtX1R(e#WqcZ0S>xcOBm2
zE65j*<vFS>rAvVI()CF&6$+<u&aaSx7nuk53kz%g!RP;i^N#XY{Bo<+!ua&kWE&c7
z!Z(MIu&^_|sb66e)7*f4z`VP!4MQ=u470~XgheKsFY8dMeHmu=DVtgvQ)yhVgTx8o
zLzWyY9dQzU%oppR#;36_i?QTbP5uzxcZP@FU&F6Fbb7Y)ZZsScnB~1Jy>m=HVUf0F
zb9on`E!LL=Aqn450Wr*J2WzK<lYx@rRK9lQf`4<r!L~pw_Jzk@WJ(y9e7usFK&!5@
z{hl2W3=V63AR6qTR}EAA?NKTiW@a&4jebGVFngDlTWN>Q9p}iXs3b9wXE4sRS{}%l
zZ-EImeA#V-rAd#o^}Oz}{L9(1UAe2+n4<cjdyZjAeSMWdK&#BY#ZHKlJbj;-Sf6YJ
zQ}zaff=^Y#th*WUeF+#akjqnJOmdMErOEtIloJpc6JxFj3V!?7zZkSa<BByZUHkdX
zzM&~;P|j9!jy@1e?hZz`K@+4-<p5ALGh;S!kX&b7xM#nsdg+q<IvVDiR`<XV_w%E*
zG~3gfY>pA0mRvkcv6ERPwf=y9+`W$TA6Wk$@zx^Qrka=WlUKF3rP^j_;nt8LMX|@{
z_%Pw9cA_$g#|;AL4j&6>-Q><3ko@YKzaj5B6AunBU>ccbB(v&MHU5uTV`00OnB?!l
z;9yzc(j4dfAra$v&i_7PvM;R%_5B1p1>W<qhbuPYQTuz3(3~;?{heV-60&pmlQ?2F
zizq)<2}l(5<E)M1ho$)VNJqh&8X+gnMSXYc_x>oDU&lo$_zYiMKnp?$RkB8~_R9N+
z)JOYm>no2@=dV6otdApR7{s{?R{zd8lRZ+#r&bCm(4}U-?P93%Y$&JajeQtWGtEZ+
zik#Q+NH_oUJXL%YV`>ane?ynl%qQ{INzwk-QLwmnw8%66;kQ`yYJIitgSz9T457JV
zfr5Cr^d$bSwft>!sd)S|^DdTupR+~qJqA3Szp*}wGWhl5W=!1XEDRP;-fRJbiBcRa
zi@o9Y2&O5s&$O3xSj_6ZNRt!%rVh;PuXw~CF<I5g{d8Ej+tcha+?$nH7}&mQLl!`$
z{US}0$LoUu%H8v%y>WZUIlYSbm6Y~8Q%mgozT7JrwcI?Q7AsI!>QZnoaU8!jQJu7=
z81WajT!KJe?CVMqzXLRG-n@PaYmyJgTYmq<yPfBF(Bqxiag9;UkB9}il`hzX>=cIW
zE!e!EKewfuFWmGYKyKp76p(6M2eH?Z7lM7gL((xOLQKfQTZi~3);YHAXBJ0@GiB~_
z66dpa0o428p(>e0%gzrCfz%^0U(p1gb#$C4HX<E8`gikz)M(6=5D#(%oj~+KXFp_e
z@He%c$?-qr(iM*><QOrd2E)@4xXQaIHbVxlAXq2?5e84tUWoS5mhi85DEYl%PT?>~
zxvJa8>eTyuvkM-&<=NPMC*lLi$HKrp*`qoxbwrJqNj!yGDvZMq=9q*XyR%&l)aM_J
z&&H{V?Z!VL%Db`{7DTE!vt9s5_g_L5kyyL6cJTE#ZT&Wm_Ew?yUF2SDwr%HOE(qaa
zOrUYha_#nXmvbMc|5^m|*Dz5zW)jy8`_WdSX8fkucw3A{i^9>V!VIN{34Kikwe)%&
zhuD@>jvy`S%WyXM?Ar5i2ZCdHYClPa8K~n1O9<lQLdbZoEs+Mpb7fAGW>(GVTuZ-K
zl|MZD56Z%a(xnRIpzxkTb(6mbL*y>u*4+_efz8@S5M9UJkvQ^L_Ea6dQ-M3|aBqHn
z-@@}^0xL3G`mcj-QS!GvK_3J4Sy*DK?ILGglwI%8b~FC&9BIP%YeK(=&VW8N#bV<-
zm4V;CI7A^zk5m0+yP&qFAWCdeqhqj9y4734HnRXU^D8b~iB+!@2*L(m<dx*&`I;_G
zck#KYH%`E?tSogluTp2H_vSD#ADx;N-0oH5*uzQ~uNx=aG7*K*-z3bS=5!_U@;F&o
zgwNR(VaEV{fnLu>hx8W<FF|`#<4Us8z6Z6hzL<3UsdwfL`+SIT<Rn%QX*uTe`rx<d
zdGIGrX*oR8?ioSn^*hf&)YiiV$MSsD%SwzA#@)&*?}mkiRaiX`2JJK~0TVAu{TZPn
z=kB@qxVQ)&%B>Xg$9B(p9mbLf-D*zl*4nN$q$0ZC3p>a6aXSr%OIhL4(Z%#`Q%>FU
zv^MGNEJig;VpiIs*%UU&#iHXx&=SLd(#k7!HsxpS?T^sib<*Bg8BsWyCX9o>-Bsl&
zQ2ek=A^r)QX}3GqBlBpH?bkQvioQ!mQ=ETB$<YTDF}zJC`SHTNUeD-MbvRFIFU|B6
z3=#CUJ(Ykuq@H{spjP|{eso5$D*{anK5Av0M||_g4iaa0r^E%8Rq9E`aLI_w1>^!a
zgg>m+xXw$-m7=dB|Gqna;m{i2pPM*#XRZG`cIAx|m{7y+3O1c;P{YSF7x^+;SJAZy
zi@XuniL`Od7&jLXXr_XCpqT+Q=7C6-VFW$~z7y(id>pI6Jj8$M@K(p;=NCIwXkU6H
zzkBD&r=YNLziDx2)napGrJlY-6W<-a2P>k_bRb126t0{A@-(awZU96QF;Nyg+hN_k
z7_y5s)bd=IODAA!u;ux+WBQ5XaMkPU&&%<RRe@Q$4+^74mu$uJ#pCRw7d!Q{-|2Yn
zLpMKG&?*Ta{{UQN`*fUHkIPTEut>h`s5((FUr3~^$7~b1cJns{c7=j)nQI_(snh=z
z2&YXhTY%Y7c`Xev`7r3FePVE$JD;qt9}wy_F!6AKxY7-Xa*E|>JIC^=Nx#`~DS9fF
zM+xJu`qe|kMFhrYsS+o5I>s<xwN`Uk!!BXfW8e$--g17SCQvh6i8b_l9KS<_PmI`U
z)grY2ex)Dc>s$hvDa&R@|0o9aX=ZZIBwW_%0G7#+Ehl1`#jZtYv%!MToqF=gcBs0m
z2hsp$V|3te;_+WGzHE7tp!ZVTP2V#?ozUxUTVhh6v5%jPKVI!A-!Re^pDzo($HIg(
z2E({)_g!L(Y+WB3Vz5F8wR^9iZcJWMqDIEG6rs2A4Mr9wF>GXc$MW()3_?o8gu4l3
zksIw;$mv;68Yya=G!Di`o9;5Q)p~=!zyT3&2W;CeI3j-BM0A9Ulk+zkL$}3{qj$!y
zj_)%*+iohJULMq%ZBsA%%tG9lb3M6FgUs#teOb+s#{pZu?vKzd5+_=&Uys(zlbRna
z3Gy}*W6a~3WPoFjVT9&Q)JA&+*4fmv=?4NAB+QEA-Jg!(byU}75MMHleu#veNmH0b
z+9}`N5F@|Yr4>lb0FBY`Y?ykd4r9Xw{oDHam(R~5WNHhxyDC8MdBl*439eEcvYU(z
z)Tx||S)e2eA0Uat4-(od?YISq%EfdKSv&DJ5kojgAJ<q2HT730eQ#$%T~H;RtH}iH
zbbYLXtb{TED1WpVL{o)XhQ_D4Hi*1tpnpS?+oypiS#p_}op{$`<j>Py$rdH72t9~r
zn(YQL|J;n{2Ld2JQak#{JU!%6f7yZd6bH3%|KKUD=bkVhZI5i%f5`sdaU4q+XYAp=
zzIjn65PR1G3T>IQ5Ad0Dz;b|y4`29$u+O8!_W*Pf(<qRq2Y8-*+wg}jd*-TNaQf-K
zjV;U%VCA~%>gtNB$0xAzR(W`j4>jPv7JpM-P4a#!qoXKp>L)Po^xx>;p683%uu_ls
zMVI~h27uJ1pj-SIO<V2oZV@9A#X{jGQd%;Gq5CHly)F54Wrj8cQmSbNh)zqKEp1le
z#QmBhF^hE0BsCfM#`Da_;K-R3+IG&=r*FC>hFCPz%lr-s9ZQb)qnJN!7zs3r4;st+
zQq6%pM5Bvjf%cLBmjvYuNzuT27yeyWZolU(>0N9Wy!E7g_=fA%4<W4a!;P2E=`Os=
z+h$9*J#9oigS?%M<TEdwlR__XJ2PMD=d&GqoDX+xAlg%PN1jrE+%_J~OPwl$mP;mt
zz1HXZ)#QF)tBCg|7KSvx<q;F@y!T$9mer=7DY!#ysH)))t!YPHABt?tX=8vnw^aFI
z&|}{A4+SZr=9!8<_XR;9FbnmM&BTagM9UuOG5yjN&-IjVkgbuWonkX88&jr~*R)PB
z_227BI^5b19z5#3@TIG4l(<Cmg<0HMw%s~igem7I>Ej)~w9aioG`a%{v@dA}aTdBL
zG9HJ%PC2v8SWXwrck<?IWDDjNBZgM!hs`UyaO+BU?2ZXFcbgi09j&tn<B~ZYtsutC
z*Y1xdk03mM4W+xidU}ZF4LzBST*e(6*gagm-w5%Ih@v_>AIcw}8)5(N`D44TB8$=J
zrP1r*cq$HZ7I&X7Lo}n%!LA{=4|`nVETB{?&CX(t@2<_^D@(jPvD2Ei%rslOR3YY`
zjuHXcK2X&wL;92gVL`;p4ZAZUyiDpOrI;Th!|T{gOU}N4;B_autS<PtqfPVuYM`xI
z8B6w=i)8Hb;`3bpdZv)|ap6f{go>K$n3%oDRSg=<<f%^)yL7x}A|^C5L+(6xE#iPS
zu_KdQ>pEInZp|0dMt6JH6B6fsSdE0OqaIbI`Eu+I;@>=Xt*sQ0aY<lRlKO3l>0TY$
zE~=G8?1z|uBgnzR4?dQvTW=dvIqM$v&fW_ax4l7&L<}jMckj)jsXs~^!oVdK-nKh{
zcIMgf7$K>-cCKv+4sCuTU-w<$q!v<7<c{Wz{P(;OjmE*z#t#k3$ap@F=_;wH_YI|=
zk$gtz5LLTAW_go@yDn$H0}<AJ=cK~&O`GKC@bLAyqMYfgyxzg#l~bK@Z+V2;5@!61
zXXgjIMEk8%g4<y`fN4F^2{FCv7UkaU6_a)JJb8MRX$m*rcU|}rzQB@&-TBi##1%EB
zA<i#(pNV^FZi6Coj7WYwV^vX=HWRvYkj}09us_ba7JmTQ7CWQkj)u|wxu&Wq{NukC
z50$;IJ8yq`_ubHNojokR47Dn90s~6JTHAuET=GK5j>b6S99L{uo1b|gY<)aChE0l0
zz-{YDXLe%Y<vrP);V!)BA*!4d96o&-oD}pv)EYM_j&^$%hk+8z6_5ldpq#kcz31+n
zakh15{CF<Da6a8N^_fpuygZWYD0*hcAoAqKtgO)!7xX&FNAaqvl_@SPf4V$-D12{&
z1ufn^?*2sxXT69NRfui$+i#-S?z>|PSejZlaU3Soq|VpsWpuZo0?<U@-P~Dax9dg=
zQ5Yw%1n@sCztih!gdt#a^qz&JnP2!rW)mffr`*(fgQFp;m~S*{)hdY#q6Ne?q=?iL
zsh_t(KmpvYiPyB9zj{5RGLW2gRJU<V)<Q#5vt+6($<cK$CfSy<{ZDnuuqs-8Uq60C
zgZkbypJ*ODPtre<^R0jZlZEtH_GnBneAs+)QtrR=tRamrXgW8BEJpEkehgW-B0%-c
z92dE1wH#&tMxSr@ulvUAIP05SG;}d_e0g{X#C%>buN_8@T`8etI>Gl3o^HZ|<;Ig;
zl0?^hemTe-zM)a`hfn|RZ&C#V1AlleJ`v2c6W|++KBF;&X(Syip+6J<>BEN)SgJ}W
za?d-6*08OL;>`{Nc4Q=d(+ph*<p`n=p4G^JPg5nv@k%`Ax11{<BXF81U1+>RZM0o{
zEG^mGnoxG?O^RQmt3)hN7XRW?550{5I?TjWRm{IYgP&@X(h`f%jiPNqs04suiln_V
z_Q%<NwYI30rM(4IL3&%+%oBNco!0{=fhvH-iD7fKIev?W!~MF>MF-|J^gFCvb^Scz
zX_Xei6xv|SsKyf{GVBio-X)5Tn}69<x!t<r5#qwH_=c})YNeZVJ4^RPeqhn(VPaz9
z<czw5z^-HC{y)S2gG_?kh^X_O$g6s1;ddf8{$b*ET>=y9fA6FfA*wX>?Gu&v*ki9l
zirT9ozM<`J7?WDkWcxXURRs~3uA1F-Xkt^c+UAogQ+eI~V9TVDp)W?;)lJkRyAv6I
z^+^V2Jvu>^=?9X4@7+S-Z8n#>Yr6HY_<7N<w#IaMP780<w{#QF>xtY(Fpx>EZ?1-~
zzO&dToKiNyzlVz}=EE^WTg_;`AaWw!4>v7X?s+c^Gd$e;Uhk>pt|uFxZk?yCnwTfK
ztO(FxT=%eS`;P<)3OcI_No9s<ibgjNxd4WbcJ{(G=&vYujt6*is*mY6M)5zG6WJFR
z?zl;xm}qs1RvB(qqn}_FVy;z;?s{Dl`}ESb1ZtGD!>)H!reZT(?~r^X!XT9qt}Cxs
zM2?qFi8al9_(IeP9;b*|F^cZ=)r;(IyF5a35gA+oI{AR2UHe(%@6o2D-`z1Ib%FQ6
zC(te?lIj#jCyjo+a)I@<93iEBgbJHF!$RXXm-M`7VT`|!Py2>pdY!-NP1u3W<HWaX
z4coeM=O@Y}>lqQdak!4~)q0b-Q~Hb5>o7`ceEBl}8MEYf#v*4j*1_qT>=tpp1*&@3
zxLvLoXCQxd%mjORGm6*vhR!HPpHav<<>UC}h}BJz1vqRcd6)Z?8E1a?b!_;ZdC)W3
z_KFrvp@e-TRTYcy)uKlO|Np-T=dMMZ1#rfzSS&!iVG`Z$h<RcFgihi@>bKzTyVVO4
zbl!Aq2Y3a~e!s8gQfCrOPgt)5p&Bu??Ha^2bi|#tQOx@i_ghF9r&dcioqU~^N_6|~
z6SH3rTF5@+!Es1=bLpwZ7u_2Wh#cdIM{p*_kd*IfxpUdq6L@t7M%P&da^UwyGS3J5
zU-9InQvIct(Ptbe+<oR=&*X)1tCjcoZ?kG{L5&4T4axB$a2!HE5K&1$;v-gfr*9Ph
zgb!tHVMM0im;QwEHIb;}%zs}_SZQe|Jo4bNxk<i@yo;anrf|KmyqHAWDIQxEpS5S>
zjzPhbi!Z9{#hb<ApK-CUd_Di|@XN5Z+gGoje}8@cz5b0kT6JOdjg8j1L9@5imoJ-d
zl{RfiG#nB!{X^blKDnvqd*$peq4cO{YSWDB215c;XLjt^!6xhaO50=R#uqoJ1et$o
z3)~yIn=(@LeD(~{RL^K-NOd{-O`pxE>i*dkB<&n8em+65inz*0-O4!I8V!>x--o(p
z+vpj_iZf89Hz}!nzKMH{<d-!HjNRU6DqN~&XSMAXc}R#a2n0p!5setC?XV;pp`@Uo
zVVBm(FNXh{fHd~%U5uM9V(+P%+T^9dG}og;!-Q+F@<*bCyvO71{VZ}_gS(xv<PBI#
zX}w4+Eol;8zkIo+)9Lvd8gO5Q2PT9I>1ED_mBZzauahTWH6PJ-1;|~;l<y_U?vSzq
zA$PK@rR6W8K%fi?bz+zd>uveHsMwH4>vpCqJ`XkffOn#xE?BIh$M3&VOrlaAVAbu*
z5=J<J9;KmR(N8|YQQwttd$lUt-PpWpwW>~_ok{9iTfXP8sId`hCFQ||+^URIflTIM
zy(p8qX%bm|5@kIFinL!S{TtGodn7n(``D(Jg0*u%>Hl&HUHesgs-w{IiUu9;hu*}!
z$L;X5K^;7%aEE%XW4rCjlH2<)0M8uGRWh-CnFsY|^wa<MF`%}|9w=(f$YFeHLR>V6
zXE+zbeMF)E_sMG>3qvao`M&g{e|J<jT=|~A!JK}l_a3A$4ClzGp(;45phx-~m4TuY
z*C^;ZUAS-{T<bg$z!x=*1J>Og#z`w>Hv9(Z8`Cfn0AzriN0`^J{dVBUjLHXuMo%+0
z+@ZQiWX!HvAUsF#BxM89g@&XZJ-8hpZ0lC<WWUK5w0-Jb<2YC7o<G`BZ_VUG@^*te
zD#a<L)<JLD!Zd5P0U09KQux5#d-MV5S$<cp$Y+2^5P!K-_DDAMi;rrUpkWHyd#)|x
z`?5^>Pa`r1f5e`cS2KpP>_4H;?NsA2%5uSi=K}|m`0Xdc5nke)H_?5G=@QA^w~w)u
zoujll9KxP8ya6j5NR%`&t3<xkzc)1=#D>^5PE~roVm(%?BOBVU--Rz%;Kh-RN9pFi
z(_cO4dZG<Z98rKZYG4&z;XnaG50wT2K7IDGF!U^}dCmGLqW1jz#m}GjcIrQwqg;FR
z7F0fdnA2k}%A`Hfs<n?atJ)V)Q+4D&;F~;pWl4pRqA9QxKX|`Rv;&`UfFni7j_RY=
zkjlC*EMXl%8ZAJPs20#M1mz|?-#0(+dTs%{Z$!AX8wvLm%%<--xwyo4vEllL=TaIv
zfgL9=L%%WPgNR}x8Ju9CrkZoa@6bo*i&0aS5;n=^KJE?1wTj=ZB*rhc_vC^P>1WW?
z(vrR`TPV|%YieEP6w)Y1XQvmotyoGspXbi;JBnlicY~Z5dpA>G5B_8af{-jSlD2)a
z4{PB?=kkvxFAi=Fs8z(X2kog^-qC;A^z1x$Y2jO<0f*gnFrY(!srbyF=*UPXZ+XH(
zy1Q_$)2K|dQFy|GnBnIR8fTNwQm?9KBv*QlD^xN5MosJ(TZMoFT$yxk3RfxE?oBQ$
zOul>I(x=hxr!#HEomSJ1jQiL2DT&A&vRa+R7Mf#W`JZH=5VOoeXSq&<E?FoZl6S0g
ze^+XTyHik3I7}Hc``BE1ZJ0S13ey;#uoUPfQ3kx3aQ4yB3BUXM_iw!o*!%=lD#Wg^
z0rW)7dx*BT5@l$6`}e5p-#^0$1?SW8_eIjh2KK}acs~h#j=d*~f<>8PkgPP6*wbO=
z9lM;JQ4B$H*(Jw4Vr6!x=+7lM>jwWyEY4JGT6uM*`kiWG%9(l16?QpjdTs<bFwHV8
zGW#&HMRwn~J)!H_(tT_Vz2MkqqT#>$22^s&u$k^8?LUG+Wkq4r)6Dy5m~mje__tJ*
z{$kD_I=f4-A{F2I(2<)TkXDfiwjMMv1tn#V-VRntJ3%2hj1W^EEeuoAtCc$D>N775
zv+<KYsefgM^MeS4C$1C=*b9^c7GzFDd@<GK3ie8()hPMtEE5OEF}~%#uh5sMJ#O1Q
zIBj61`W=cKCL&Ye5OQ+zu9bc0paz#wQq}BqKi?##7(9>;u!A{Z{WbXP3pj9}Apddx
z^|>fXd{(Y_rpn67(SPPUZZi%ORYb?9p^lMb*}tg?GIgZXE*GtDrmzROUyX7K8ej1Q
znk`^IKui;G%3l){A0CHeh~qW1VaB;HKDu-}cjjN-x)arb8*F%e<xr#?<gVktJK(*e
z){B?g65txcM?LFB9e@OCd8FuV_cr&wE_-(U)~2CPQ_S%A!*dp~aFpo;SYOFs>rJ3&
z(n}V(2w@O8Eqh;Y@1^@2bx|};yeCnyc5MG>*1A~QqI?-AIb&Ooq<!<<AEeJ*o^goi
zhpBJCbP2_U;z}U%irLNaYqD5_L+E#-*wnb^g~%!FH?87Vc*n)BLHQtWn(O)0m+=6Z
zLE+;4zmLSNv&?PFx}NkFrGfSfH{yb6`*u4uUH-ySsaG!TXI$k&yGOpYJ>p$zTF{$a
zP1O7GXQWO+R=7D;-7WF==7PzOo8wsJEh481FPY0TJoQx4FpNXUIFzx?lNKqjymRr5
zz8+^m+P!MP>0rH~6mb$wD1XiIdj0M6i|jeG9gq8lUET<gQ+B<e21uO8{Ug4U0>fML
zZ}w|l+BZbiwBM|lcfTN<`cH!Q;>rfXw}5Lh{~C_5d!^05+q~BaG(5_-wRFjsb8e0=
zTc#QYcT9cx(t8mU4C9>7#rd}tFLeZ(?1K6us3qg62%HubPhK%FFu-uFgV=u_>@Hi-
zUx&>pQB_lna)s%!{isK~XJ`lWK9gcLkCn>k*lSHIDJHb-FV~CIjQlkIUlq(!PAC5h
z32Ey9S|WMx>_;7<RcJb)YnDF6!3XTdZNs#O<KC+DDeYomd^(?1Ds40)gE>ywzs}9&
z9rlFPI$P+#+J9gE>TLhhIp&DUv)A+j55ETTZSxc}x+V1?mP2)^4i@vL6ZcdC$(Hk@
z9OPX3sE?&+btnJD4rX7zzAg^>>HM|f=kiX`+at>@iD!C;Ne64C&9kjBjPaSWXQwUI
zLVSO6*%Hrzjz)~sWyi&yF#+5QV3z!oyXl~R2K}P@SbaZL6X!v<V1ekVK}NeyPs#H0
zx~HkDXT&3E2=+~c7%CBi9nq=f<wCQ;4t4DZ)qyASG|z6>4b<#0)V;eOYRQTz&oj@5
z_Zg&9{qz99Q_S}>lg;e)ZTTE!ob$vpAaCJ0U*d=OoV~;4T1E<{&TAZNfM#M1&b^PT
z$0J^P&BZ=#RIN0F$q(BzqFd&OfjuSpQsdhlw|q<+!ms7_GXA@uLt#98oR`BtH_|E=
zUJ1V8axzl5q-i1l57>9h5f+Ax{ina;C3)JYz48mJ?V&;)USg*yVg97nm#H$1o>;0e
zW_;v2uuV^zWJM)scaL-1BI-r)2i<`nuO4-aKPlxl2e)RHHNI7ic6Mr?I<1mio=Zu?
zF^C&)LdK&{C6X?rt{;6@7eyq&JJt%*^-omTowU1SHXOq?boLx<a6Bhnsu4*_=~}3=
zeCGcyEKgS`I2l=d!Ole}w|mYFLUAUOV-+#FF>wJ-`RXf~8r_#BTS@1H-kjubTZCb`
zD`&-ul$3Ot(FH}5aZbaq?pdI$g(28zxvk8?Fe~1yJiXuaP4Gq=u<nz8VHW6_@X26`
zb>W2gNQb9QPQq8iYpFobEHwGMh-Mh_%Izf~dEmMBlP*w%&#6OV&d`ZVlo%E_me*V+
zF<MMu6*UvVqphYA$skRD37v{?uYlI*Es#pyQ=D~#ebbv1-7+b-+63TOIm^HybDH`R
z+v*umENrIDKud0xCb%Oi8}JsmA%L<e;~0C4P5p(uF)`MKiHGM{pT<Y(JiU@&8h4yd
z;ocPjMl?O<ZB13_7qy=$WyzjRjFzOLY08LFD7QLaPW;hMmFPM+OlntgLev<3`*sb;
zOH}CppqaKsl(>Tl0e3P>t|1&rKJ}qz^_7H<0mQlbs$e%aL){l~eB<=biJT1nft}*o
z$}EFA>toI?y>C<|ijH#QOhw)(+ZZC2KMHiwy7m6ng-lCLOKZ5Iob3&NG1FXy*ON7^
zg~H?0Yp*W9{`1SOC&3Wku8h-*rw5#)sRZ6(;}>D9w;5X;8^*b`T&d0-!R=sFp)^v-
zBF1XU<G8=6?1{7hhqZ=A@Fh33#DCA@V|CH_y!SUMA=B(4b?Hrw$=)8FsyT`~e2`J-
z%D+W8m}RNIfZT1-eXVOiB7BcDHnzMPrC$Zw&7!0m4jWJ{+j?SF@lNzM9WFiggFqaP
z`UMQ$f1)}Ei=F?cK6Wiq4(2RInn?Cuz#(FmW04`3mdMy9HSr#R>`WfqPlIZXZr&kP
zaQ0i(txIjHJ$W^lbd04R2pGi8bz2<AjM@hBZgXkdiRCw13!mKD&Iwbp(I|WIr^Tl(
zRo+r?q17FT_t7V6ZqF3Nr5Uo6{S~e*PvgK}El7;Ge@yqr|Ebr%!9|mJ<8H22q`0ls
zo_p(=-b}NK*$TGL>u~X4&XJk#lJL&t9&CUTcK5>00sGZG7l1{*Z${ezwch=94jaik
zUu&#&R%-kKMFcnz8aMqW6%@74{9weyE4Fv+{Cj0IpXVI?3x&i5_bw!QtxGY+W>V8P
z2zriGhbUbWypHt*t;Hd~V<_fAK4S%Vsb$!TZ^ZG>A5Cx+H&Tlq9d}$W!5YomP4qjh
z*gd*CuXU`L4}429er#6#<8V&A>Er`)k$(-@`|}H~${P{%Ta=$m*IH*gNr+*tVWFX9
z*IrvCWV|4EH7$C2m3RTsD0bD?lbXZ-RO03(Z-2&}+tLnGc$yaNIpSLblyrby2+lam
z#pLUp{}ryx7j9-8&KkrE*le$d-heGahULJ=t`%b3$NUjJgX^%Boj&LLT+a2?jR+R!
zjK-tSMT83n`lakYN;`-O(Wz)e^Md&-;KPDx_F2YueVf!YCru)iZ&t!M#e8)=Yj_KA
z3XTWo`!18)@2yFn{pMoy-Qx(q%%Nvb1gPGM%e(=2Ej5ZW6Ha1regT;klayv`iR{B@
zZEvLdm3HmRJaaSg{{SYS6rhz-#l9oBF7DZIB`n#x2_$tFZhZGB$86S0es|z-sYYl#
z;7x^XL*hk#VS-Fwd{+zg*=rh9`lrp3Nji2Pvw7&2BIU$<80L(}AbX1B7pKSIFqd)=
zpBex*Wvf!+el{es*7)>x(pBNyR+VKi7VLAo33|3%pE67=fQ-Oy+>x4=DQq2qa}}le
z0BLQ{J!aUbr<j%VPt3$->5R3XvYj;jvDW`s6C;SFY!{Gm2XC0gRawLvy_qVvtl|g8
z<_TC#k#<gEy}I(X``_4fh~Q`UulaMxx*8#kff!)eoAwQFG#U(8^h>b%AV=>6Jbw*(
zb+AB0v&$SpG$EcXKqs1y5QD7*cyBOz`}ly-q^f?yfW==0^%-D!I{kcJJixW_X`)Q8
zrna7n*XZ}JUt4g-Wd5n)1JcE-c;BLeyG5J-O*ESnKbD99xRD^}j;tSYDGa*VxC7Df
z^XRXvj&zdj6u<F|gXc~d85v!;Z~@=uV9?o+ap1c`Up$OHjqsh|HHqZy?wN1jBztvL
zKi{}Pa%}QFY%l1j#!sZ7J|#Q<p`oKg;@k*wL`&y<&ivwMtdc))Ab#WMg~`_KEgip!
z(}ZS_dxOPkYOgCP+BNbDk73|PElmkn7`-z3GTOjyy1#C(4CTl&%gFH8s}1hPC&o!L
z!H<X?7e~;3w!}$=k)~VBxhGDD;EN+xzQpVB-%ZMIN8C%PZ9}!#ID-GI^cN0ENRu|T
z`F@y!35ZxyZ~OsSav?9?9>oOLJ4$~32?riZ1~N@U5576Q3bw_CWUBS;TZ_~!Bi@yg
z#c#g0o<3ol%l5Gm;~kp9eI5Ws{6)7FE=S%5{Yl!?of|FVB<C(3f$ufp`G*Th)L!ge
zigbqvqmj-is~<eLff!w31p{WgG|&Cm;<Wp+L|n5J{=d|^t`5(ay{Dq8=V^z<B~$o!
zNFF#~q}jEThNc|%3|u4j7DzTk^S+bt$pQO-l=5*|e-EP1>u4N4Oj7Fxg6DCG4|?s_
z&!6Rx`WkWnGOnijn_Y2!H4UWIsvp!nVdF+*?POsoZRZ&J$wi*ialKy`)7w4W_9-dZ
znw#OBgsE~HVXr}^nfMbar@EbG4e;lVWZ%J!18!lO29mFU2QG@qP#$)VQxcasG{Sw=
z=pVeRt{VOEk0RSfpc}CF(u7zp1{pnHPH-(x_c)XVXeqj+1d67-I#hvDudb!53yZLN
z+|}0BhQxdnOI4^e6k|a_LFl)a@T)a8l(jn;u`H1dVsq*n!-Z?O!4k={FaoTbtdFu?
zfBV3zNl~~;5vIOr*%O19n%fpJT9xKU50~5ha{44N9J8xqEfpi9r*mDoJaNpd)y__3
zzlD!3^8fojNja^7r2vVVuWSwfF6LIj`4LFWLKop21lQKT5<*jb{8k|o0rr!u%HQau
zJkJ)PQRvi57}&ccV)+K0U-k8Y{7AY=aHLpCz^Ot+ipqFJh&=9+S|$2G1+=;h77?+S
zDr$aAO}%4#!+6$92f5w%Dis9<H7J^L8;NbAQE0&vW;5(|3w{TOpqnUIRW*8IPcMe6
zQGw&V(FV2J+{yn6=Es8sNvrC+U==f)U&t#djs2QBulcXML=XF~EuOr7{V)1OHXb(2
zy)gGrV0j5GlcX6q7({T&v7bMFB$b!qniq{wxC>N+F|ASz-md%&^)m1oQGNxN%~5qL
zA3)j{Z!LT?;DwaYmT^BVFZN}!Ck3X7|ACs*mVgO$$IhKVf+Khk=!Q91Rsa>(_C@eX
zcprKC?xmnpP4(-%bxl9m7fydv&5GkVI1fu!Y<PG)Yc0`2hA+Lx?_O#pXQ#ive@3g(
zj--4fGjOOE`E&jU>c5|`CF!`*VaJEJuen;=+toyQs}G$lOF1Ss_C<zF(L0vUdKzmw
zIl`UZuHQc=Wa(v8&E4~zHldcQj=hi1vaCa7s3F8$ez8U+Mbcd^v=+&CoT6g0nC%6d
z9h1;8Z>;4+%<?q3$r4Fn<3}Bfc&ZSZ>;@z~r#^<A*Z=qJBALdqeF*kutSd2A{(;{E
zR>1uc@Mz?D3bl%FzQvF~QsD?AI@mEu^HOHEw+)xhTxA^)8R78+5~My2>ruSMi?7&t
zsL_6T(=<M3A-P>%4#}X>jf15Z<GG$lnB3hlD6-#9_Q<+|7|~)Ja92v>e&-CqhfV43
zgjt!rFy}nqQ-GdgJE~v$haTmgs5*Y=?C&oXE$MHH^Wk3GU)7g>sziRJFAEC@qMdyn
z2dXej^<6W$tD~xD@;TstzfyhAf}<<^s6gLSj^v;1%I?84k7fTBcPM3c>wdm{F#?h_
zA0L)MeDx2~^&=88hy2asY$Go^f(Xsz{$WG7yEs&S%Qy4037SYZE(N|c&$=ImInm5%
zZSy9AN5_d!<N6$KHZ3GN=UozJ`d<`>of43uiWZFiBWNPB{;9;vHva?{M<0$uxH1F7
zMchx8!haZ~X8up#8PQ-$V!RJHi3p)J2&AUW_IZ`JzByGF&-n<~UzmF#5~w`LHfg11
znxp7LoB3;#T(-Fz#dJDWe67cCJnvU=_dLo@qOgHmbkQG=E>PD|l>L6UmHn+_=f+$x
z_Pm$n_I38{CjSI^BYKOGKS?5rHYQtJe3I`o)}m*J0AoHeXV}dlN1DhIi#Z?HG+a&+
zxp?TH|Dk)$i&z!ubI(w^r_JJB+jssK;o&*4$Fq3+heMhZ*zubG=_RG`Jun%H8pLws
z^@?KF6FdIcQ!}H$;3Y9zzt?`WocNH)c5o?KVSCip))p!6)PyX+`H@SD$bpNwnhg!t
zI<1PLJNyA6q}slqQ%kqd(9ooCeY&Xn%L{fIyx!2m>>i6r+~V%~N#VwxUHHw5NJxer
zy|13awjDUcJWlqpxXu@&zuNP`L!@fND}%9nW!8l^882{ejuYuVmku$L;+^KsJDaK!
z3$?#u7~b~q2C2|wiJPk|k0vW#>8H7<?62sfhs9l-%C7E(P?b$xS`HFd^B{i!qy5^?
zuQtsJ=zp7{BT9kH^tT@j-dAzK?Xs@;E4q)uEZgvN@WfcEO9!vbME<aYoQ0r;4My|_
zr+N?h{dB*-jQghnO3QKX0s;bRgbZ595r0d(leWg~jVLgc?bXZ)hb}9$Y>@ug2(->-
zzgR#?N%>k3RjLu|G1h0%#GtX8AqoW%in|EdH9wwBZ-5=JE8jn=s;YvfE+{6-i^o9}
z`9L$po0|cP)8wSXL(+7MuK&kt6ScOwij`PrNa)0w^rh#sjg;wscm)NXnVz1v6AOi>
z?(?saA*i;umChQ*zB1_aAOYY}5WJ#&d>H0#UvAoBH-q;DiQjR}#v{D#5~v9ofz(qL
zMmvt20f$KRU!p(sn({INwz=@w`x@`CVI+z;zZ$WcW@HVz?UYOl%Cn<H1mgTYZ10V=
z@D6hM<h^0Cek(TZ_%D{gZBysNW&US&Yq@&%(RqU{hdtY)<*PMC-b9&7vq`xfP?CxO
z9Fm@jy{PE&RefO*UScHL;?V@Mk|d3#lQWgPhPu>tb<YknDH16qV>1{S*eanC?dp~~
z{h>^Z@2Px)xh$$5sE<g0>f?+fRHnFxSC5K1b6q5`DEC5hR#jX(E_8IL+DNdsIqhCO
z&oDq&8g*>yXfL9X+OV%39rXYXX|o-d&2d@ye4tVdtJY6!i3JXtaizS6=dr`5ROj@;
zolUy8A!-iC1B+u3l9;wW|4j8E7w1q?@!avl#afvpU8;w{Q&Jd2M{WPMlSOPtedibt
zvuz&LkH6xea0^Ifu9W`yEib}K{XP*iE|Aa7)oY3^Ih)nbZz?4TZc8=+gV-FE^ZYX7
zm&b>m|0CA*7Cu!wON(9)4GAHcJW)tOa)U%yL)A=I`_5bti+GHoxTt94ew)JI`bXH=
zT$Qk<C|Ws={t9`^kpFAgYZq(XZIg*9Gd_C;^g7xXVc+eJq4~vLV^aUVv-2}N?t?3%
zj4O`-2EEcAz2l->Mw^teEorKKpH5V3T<QH;U4+kb%KQx4QEeC1M%*~RaKJy-{p8)b
zyxH9^@HeqEzVTiVjuT_bXL5dZSq=8-H0g<6smD2wLP?hbL)A#4zifu$l~(l6vUX8x
z+1X8H>gIcc&_GIxDQTA~nTJY*iv!uG5})MfM9wAQrxos$rMt1$Y8mWTgS88pl2m<H
zRxf&Y&^Nr5Q|TFfuv`mXf&`lJ(}A8z@S!zH509MZ?Vlg`nc9e#XJ5!Y6icz*DsRx~
z`O4Ju6(R<1j-(Yz9@wTXwD;*f-#ZGlE*--6xQW1ZiPdAg(cJDBX;aBp%sb~cu7x^V
zUEDhx%}PDHr?}G_zlN3dcBPGsnDj4Z!qYZ+{s@&82RUz5PKIw--lu9(EVn=6JxkBT
zch!^5u=UI4r#Pp&)0Qr3p-{rR)eK$~><8%I*4ftsBBF5aV5{uZR+=R+ACZcW8?WwP
zfng;{Q1{6mL#Nx|fZ#1@@B4k0&g+}Dt{tl>-35jtyw2M!#GRw>9(b3aJsz1330{98
zHRhzOzs}T|C1=!{of~@jh2MN!o$JJXx(R!gd;ck*D3UT32|fvV<{M0o7qv`3IAnZ?
zf)i~!*%MMC)g3^+kjm<!Nl(I4a`d3TM6#&4s6q`f6ns?>sO#XOPuD);yin2PH4`Z)
zx)9nmcY4mf;BCS0)$iZ0t}Sv6kE4ckQ}0osQ#sn@x^Q{Q5|fhU+N{iQ`Gf+6kII?n
zvV@?)4%W52DwMFR5u11JvE<Dc7Z;OmqlCnPIZy338$rfA$)8GtnsD~@-G1+d6BU=@
zWBT?SkTV3`1sbtoGy1LNo-U#;_<Cjc-AQ3Bm6w}uWx1M4j%S?Lk+-%g>UncZhweTF
zfs<Y3xpBEuUDCzDM-D#F=axUel%&~C<hmpU<90C3xJmU05lmwry%2OmDuGfZ27?p&
z&$ydrI-)f=7T-O**BHyd#XhhBm5k$M;&anM`kVC|7+f0M8VEuZc4@Ra?Mm{(gnPe9
zaWhsyD^c6)m@OT&(y#VdsGX4*S!_Sk;N9sso{QUAJ5GiZw`E8?b#!*9pN6C>>;EQ<
zjG{f5Co*4qezZ>V&ci1lL@(WYts?S}#V{h_RzRY%IKBe1o&$lt<LuwxtT-Fm7ghRU
z+_=$H)vK9HJuDu#tcfGAeLJ>Hez9DjuQuj+mO&&b7ZaEWrhYq{<UGejA|OXq29G=3
z{(gqI&&wm^QaVOv;kz_Rdf>TF0?&2CWGIJ>U%L!7VlV<wK5<erm;2ALk2v!bx(By9
znD*G$xEeQ`UA+3=mrkaBmTOWvZ3fq%Fcb7>T)$Ou2EPKen?foTkvQZ6^FsAaay8*)
zve3diAr5llQ4PgaA6~r{iVM#m^i`hKS_pM?a`J)p9zF00IC^LB@UX}J!e-_s$M@9i
z(#4$Awj16m;A=S%;{MUun%VLi%+6pRN^av?mBPyjuI-+$Zg-S?)P+huMok!?Fs;ty
z8F)T2?9qGj|7O*xhe^EQc)+-Jyn<{}tpiJS{rHfL2bB})*)y9(Rk-g2jqfwLYg94&
z{j1?-4VdfQ9kd+u@(x$He=5)J6~bOj+IgQRo~x0Ek6eH!fq56E6Rl8!0O8&eSLPoR
zgM7O4uRH(yw)+8m=6=ku#T73}b}qt?thdLU!O|8Qo>m4L5Yq6~88bK@x{oBjqot;X
z##tapl+7PSMU3mmuV+>NR2kp`{W_!^IDYH0F28;7GpRJL>q0Pnlxp7ye0TpG3@n>I
zvX_Rlx-R(9#up=s`6tyvs?ebHL6Z-AkbO=~Fy%ccX%SM`d6Z$HP-RL3e(h5z%f{E;
zHcV;RthYvRJ3)Zbr91$UV?7YycN5NZCu&x5zJEhzZO|f^9(NYSej^=Ep&xY=0OB_|
zQ8*GyL2jXT53P(I?(@c-HQM}X&LDs0_MD}*y=vP|eW)fMM%s6w3{3~O*y+<2AWMKx
zNx<f)%<yx`4|;${9PI4fVo4`FoY&H#te-u!q<dp2)_-U2?sVdkiNCqeY~~D2gXG)K
zU%<=0kfy%oi~&mE1SK4Cw2X;$@7X?q0TGi*&ytsiYHB7nlG{o|N_)HCEiNrBL2;D%
zxUsQO8qdKmoy4|#x8?@XEJ#`zZI_@Cdd;#Ni4QADcy9<Bjler7F+23tgS{iJy~TV9
zCkt;J3smt{-UnpO6e4hU-1~myiG0#OjW;qjwj&oyl^BAWaBj`A*cX(MC1)yNxpb$(
z4EB8c3Cm|>pOmVf1r~l2rVIn=5mnl8it-_l^wW>Y;0_D$cOZwycEa-`XVA@?E>+bI
zb!FV1NW$std&t)BBJ^Fm>NnQoD5loqE>w{wM+ePo2YCE@=(efUoi((f>)2~D?Z&iv
zAYxorMT_1t!<R)2gbv7}{K!g9#@2cmt}i@)+G$H&U3;qp6n3*e)CF6%e<CH3$v{8+
zyFNu%fAi4Cm5E(nV>`%dZb%SEVwo1En#r`u-<TDEi|$q4`Vu&F%-EKj`5>Te^dj!J
zfKlh9zu#%jCXZ)k?v=lxTf;W;(b{64t%qzV$VtNdpzegv;EK>WY(3{X%ATLFr99AW
zg~S{9FTBQkccpntbu_7hjy)YO0u(vLvX%CTQT0+{nsq(l&2L><vw+aPi#bYHrS<Kn
zAQ+qdku>~b^RdCURzz>HUXM-nGvk+6&MThFnG7enA4q?Wd#r8$CJQfEPpFaoeGCHE
zDa-Im%z2xB9*u{<P$lh(5n-7>t?=ll6P>ukupr5puhn74Qkn$qa6tjiVQ4HZ^XcGh
z#7jNMg{GoTmpCHgT8|)8?{rX$W->NcqF&=pi+))6ugXi<ceW&c08xcM^iC1QCn!A1
zNQ-JFTQ5AHe2e!+R%1)?T-3_6&1_)StD`S4Bxt)IaS{n6F2Kqn=#a{^w_QEtd{CXv
zTk1QMtCY9fK6a?oIpjoo00is~&;>6FL+gIYXKou?T-Gf18Xhvuj|QGyP(PG=?2xVl
zS?*ljN#t;ZN9?&IrNgGkm~qQ-|7->KPqJ&G!lWaEE@z?PZYqgwYs$+19$^0Ot&umu
z6x+}RhU%sHbFmOg{#(0U6(&u7i1zV!q7%?BWW#e{X=w?nZN{#;@MRX;F?o`ZnGf4&
zpg<}x-=8~w#wp{`=FYNvC9JDddXqa2RxE05Tf-0{j#(UX*We}UJN48esRWwfuFKC3
zl0+H>;GICgM41FzCfnN^vI+sBIbP;V`z{^c7pZFWXBQ;WUyNc>{}>AQO2y`g2I28k
z{cY=MLu6x$XCgcQv2f~jPX=94tKFs@L?Xk(bGJC(`n+z#6N&bISgJjsExaM-%QXD)
z&hT@=Y>8;5H^mU>og;!v^9A|~j(Kwk5J1bx1Tkvlj#@Vn#82LpQWJMjbs7sR--;ev
zj4h;N8{GZF1ZBJOx!WbhN5i<5>hFDoP~uvr`rnjqnlP)09uv2_wlo>o=<!tNWf8PY
zw>p8I<dScw<QI+ZZ|@NOWj4U$Imt}1yzi*Kr|Pro=;{pngPJvNj=w0OG6%+KZ_uv2
z?b1<L|6QljMtrbV=pT8|Uw301rx%H}abmGV>KX=^#-r1_|NYnlaP;G(Z2bO>CY5tl
z=RXy=hxvBI6|`cPOkA?K2~NEhQuu$I`ZCL**^YgEb9gI6;wZ8zIcq<a0YH*PfiGhz
zI}ervT-?4##L%dLqO`+t!Lmct!v@A+&{ADpaZ<W7WcH?h-v%qFpr5%N?$>^@&&p|}
zR8c)UWpq3*0Kfm~UnzNcc@Ytv%HJ6F!Br+G3Z)C_X=d~}(4=|eQ6nfL@NmW(9o`QZ
zQ=Dq7?aJoa*9$rJ@ti5q8et?;FVKJSks~)|k|U&-iOQOuRX>o7LVlOM%k$yu*Dop&
zW!WK`4K=iCu!4IoE+&ZY&8XVvsZ?F{`_BJ<VVT@r1RM?lt>_zXl&XWj>rKPYb9p;Q
z(1+<lX<5phy)h;xDsEPhBmqQ}zP!zaF_p-CLfcRHOo?YFRRzXjLUio4+R4n=@oQO+
z4tYar1KEl=;9;sJ)p;=gtK_z|eJRcd5=>{$fIMWqs(f!Qir+=|cIS*8F#!9?^%F+v
zyB=cxyE%?21p-d>;3i<d>0KSZm-Lk?k9l8?X^Awzel)+@MEv)>gZC?&z}C%6EyA4O
z%K9#B_&IC0I-Q%P9rwq?R@JMT3m|R(5u}Pkjh8+fy13khFbez4|Kn@$#m%u0Onpzj
zN$vWl!Mxu=@Oy}QcyIB>_)^uLwYh=4VA|=DSN`ti;3%DV2p&q*o1%NSq}^?AlXZ)q
zeFG~8>44jOo-E?f3K?Y9VABVCD`uQaH^&)2t0rUE2PMK*rHCks19ei-9Cy2{<}JPx
zWwPxfM|Ri#l<}%igs{2t<A>>WI2uhV73JmGcu(y9`0d+KT!P!?`LOmb-bOe$n}L}4
z{q3pDcTh+NnG6%<D<!-XEJDPa6S;BR#03X!l=}!E#sB1dT<OXtPLokYaC&691|Ar{
zY1RLamJl66+?SElPI1xH1`@?pv^?D0%1-U!;IMZQSjDXe>rYuAvC`@OS3FF4efwOM
zKtbI^of>Nr>$b+9%IP;4ngZw0tx4aLT>^ih3tK+=VNA<07Fo`xLp_9T+-ZK}BbAOp
z-zf%gYIYL9-!n-@?_S1U8)X0Iu+CL-CK|egd*;olMgdx%w^hH6?HvpNpL)~i;-<@`
z@sr6(X3Tf(gZ<P<EH;vPpA%-RIy|udH|OoX@bl5XhsRdMIgz3gkPndt=^issx){rK
z8Ikxb@}2$G!E=Q-4?*<XB~N&=h|#3@1{-Q&Z@Sc-!YSTKi3m91wpZf?WW40D2Gvda
z%nPwVPqJ;>P&6cqHjx+rMRPBg<>xwG{uUXG3mvY9vlIQs8?OD5{wqoG92gEB5*Ss1
z1k7uJXQujrI`GOiH#alB(;rBaHJSv!X?{c!^|mMNcn0mM=b7f0LdN?p4AL?HIT>b1
z7sQO$j`9D0b(F|+3lesZ>dEUX3;vza&hYW-&dWd@hB?ZQQMN$Zd>gKs0^Ecmcwhv;
z2+H3Ayqdo?_9$OVr(Rk?dnHx9@&c~oHZXi&#~PAegANmv8f<HWAxX@#auSTzZJ{R4
z_Vz^_YS7!<)o)ik1lG-Q(9vAZLMlgz$?XPVdb&H2V*Rx8D^N2dtgoh^w}5^sf%tn+
ztSXSA2?p6rFlj)UCRI=t3ccVhUNT<zgvc+_J{u^P*N7UgnG@qZUv4mR7{%Z+BmN0M
z3b<L@0$&Me!KY=ImZ4+_%F4<@T%claf~AcJUOo@5<-Zo>SSixjAOE$iB{3Br^%Cpj
zEBo=amHBB5be*N=(t-0KCNE%ii0#~LTYdUj-ab8=Gk^cKD&IZ`_k^>P8uXqrU+>NJ
zi=tK&zw-RPy{+IG=isu2bO$#>QRBhJEbOZVT==v%83X@rF6qMALqfJ|MeVJ7*A$6s
z;K#WOGSmLkTR58DoGz_R{`darh*+&6?&8m{qrL~MLwQn=r)E7#SM&AFy|*wK!+t2R
zHH9}EH=~jIsXBo4JHarkfr*w&&J#~%Mm}NDq|xv~yk`vrOAG^x?_2&tUy(f`7U6D9
zZh22RwjDmm?)(cqpVyY|t-Gy?Bd+E%vH>>a{T~)h6MO)jUhFUie+OuU`^(MLnp_oL
zzPW$$)?dZdeGjsb?O=RzI*l5JlGIrVeFyZk6AfOcME9hp?zC9lgryM-#H2A6`7qJ^
zTL12B@ZQ4qCwI;P$0vu5Y?c>lPsmyiz*YHZasbDxMCrRNQRkL(#oZ%N7%v<8OP2Q6
zulec2*LxnQ{F342ob>krr|s{q3;*|Uc*t7&ul=0Ox7lx9Q(T$~sm!G(Il}5l`enpC
z3jYMTD>_(MD8P}?@M6lHv+D|!1vp{hQoSN5sSO04d_sMo9y=!>-`SK0Ykhzila5TB
z+*x`;@j(ak$pYUy`wIVTt=R`eBQHV)qUF?WfdGhPM00YRXXw>;FNr@o2t;iE?mirx
zF^iVdko#t90gSDthDNdW#Jk^XUu&V@u(O|yrYXD0!s)EDmmcbJ>R5zdU_|t#7bWi_
zAB}U#fFMn1Z0U9XjM#ywqZKs)cK^PLa0#7|m@`gzmdBP1W7cktFYWoE)mWYWB{zEb
zc@e$RIL8m6jK8iMGC~iFEWN#De+V5Wp)a{MvY_s<_x{|dNMcu6w4sS#-1th3citwO
z^Q5ptvi&okk`j&w`;LXm%${`qGbm3qBo7^7T=;ao$b@{^6V=xVV>98~M7i?EqjtEK
zbL5@TKqm*3KBzk=GH-0M=db-Y?r1GYm=;EBI5GzAM2AX_@p5unLyLhIGxrb7O9{N>
ze@kDrdK;}+w}v+UiGdLab7lVcKIR0j@w3vhkHLr+7u8q$lOHyZ>#WERNi?LQr`6PL
zJOiV{f7Jb!HJElaH8u1XOW4ZLqkBa7<%VZ_foK}saLwCK(Dtv`yr#R1F}1Vnv@Yi6
z=AxYu-MR*uvbOItm1}h;KjVMi%Y8<r4Q)-x=cC;rf@02;hr-2=!4(yf1`ly$0s{lV
z82Y?mu>T+D@eyZ(&!Hg9;qb^}_EqX|0RPB1*N&LmBGAQV_ie3QEp;8`{2i!HGD_!U
z8-!k%q9l&I$)f>#m_bzKqK#cuQ6YI&N}Vhmmnbrgb4=QVASyM(0Fu)%eIC2wi(O5)
zDuniCd4Py@+{IXx$U|~U?J##lnH!8Am*bqA<V<q`Ki<R3hkPNkD87mZDjtun{P<)5
zwZJ7X72>$nYFGF;j{c`en72&(q7DcXf|yXY=PAeFG$5s<bqyk;#<;zmo6QGz$>#2A
z2rI9=#m*{DH1pI@&=R+S=N!#{Ny)lwG-COxdm`2LC`gDq^pW{0R^A$v@ATl?=+aM`
z9$x>`SoEK!V(BDjQAw?a5&Is|eN<KGT*o1fEX5b;?Ywz&HhW}_=~nKlv>D=d-MFK2
zRc!c<Hr>)m$~fegqB{r{`%V1MbHFh#xaVcKbz&L@fkCYM5-${{%zjx`5gzuR9=o#%
z%jiWXq7Z}zo8BN4{Dk#ruc*vFG`COU%zXC_8Aox+vq?HdoqH9P3SQn^e~zZZdi9%d
zrg~Sd1jCJmds7<Rj~g6bB7ILw*d|o%@)5jGrSRi|N9B2h0>l?KmHnk`n)7q6HoOfJ
z4GhLqgg8z)2{qO<2`xm7=EMQJ@F)M=_ol>j`{dBd?g;?GgkQR3X~eqk((Y+}3?rex
zcN>*{OfXGNoMT;KOBC@EvcrY!TAG^ht8sP_uRI(KSFd_~lbLXdwD<@QR$Zy&&hbb{
z8xPYo67RY2B5o4G&*+lt;w2q5u%fknNN+*%<^NfR@Z^YV?3BT5f!V`NfpBlT?#hjh
zHNpB<r`SlE-dxH#`e!}JF7Brhgk0xWPRo6_51VHFeol0I{1YhumrAB0sMka{yQwY#
zZDVwJ08HEZcD=&|j_x;I;?fe*S21Q{S|^#o=OLk~mi=oA5_s_1@1NrKG|Zsi`9CRm
z9V1rU4J0M5AVa~v&XY?lzmXV()3fWjgPiU1`=lw`e+05l<*kcFH}4}@@*>E<>Y73v
zr@QhwOLoIMPomoDv4m{<f?|33Me@==7N5P!hTIJ&hv=%yg(0Z&QS!3!f-vVJy*udF
zY!>x>oD@wBe}qVGgh%mk^efxCc;RycGaF<pWpq57d$+feXw~T0U0HL^LF?x()2KfU
zsUM$qc>HG%79#W(h*?*=M96Ndw0X><b<}lCEyS@5sTr6!=1)zd9=&2Du2#rTGuI5)
z*L=B^*2{9Lo6BY~<$v6%Lo|#FsT1Axx(EH=qNucaPI1O`_}ggiY{K+Tr*I$@5eYA;
zKjQ$I4vW`4?uUHNOt?ou_ezWZNb_gx2*mUs)ikUyyZIKF!lu!CpMQ1Lu9U5~R?ppx
zg94bPU<H<9%@8p@3p-<?zhz2(em<z4!nrR@>t+sIQeNMSw&zf`GyUTYb~b^9d2(4I
zUL04xDtl;TK85#mo@U36$tQ~dZx~DkjVn2Kq+Y1YClYRPPdr1$!67ZJu9idR1F%E~
z-`cm3`c)wM<=L|*NT~PqIhZ>^k#h$NZug9_slg7<V&8SIay>J70Rq<a3b2VVpNy6%
z)%j*6PwzyL>&B%~_!rOl8p&7{@+am#n}2zpXg?Fe_Kd~<Y|p@Zj@Li|7MJ<wk05Nn
znv-%58i&Po{<I}@ffz-avy=;ztb=Z0csmLVZV~V=_u#Sm0SF`-9{t6>Fwx{ANs^aa
ziO&nNaZ7~21LYGiZho}_VS-Q(ZS>-Y{l85diI$O|MrxlGsLrst3ThbN=)_EUq{@$>
zhGB9$ri&dgXw=LEtRwBwcF7A5|3pI7^}7siaB^Art1{ee`x5zwpATA${~cNh`-;D#
zf8zbuLdT8ubscqeeeJV8?>Z}Q1p!`_eEra+@?gB-QV~#gbFEXvxNTdsT+Q|llGW39
z8Jb{w))s(=mpaM#^lgkRsS=4N+KZn$fH|*)ZmY9N9^0)1B#c0t)wuy}K!fHb&i~%F
zx~N}7NBPAudE17QsCZT_0go@aDH$pGbQa{wSruP^REtKaaD8FszaohRT7P3BqgQxQ
zNWzihbJcD;VJ}o-{8jK}3*O4f$&s?HIo-Mlp!0t*_uk=L_I=#AJ+eo3HX(!*Q9_cL
z9Wt`YD58PN$|!`85!r;akVvw3N=n1XC>rV;DJ1jvI=k-cexBobj^}qge?Hf7|8d<%
zS6^S}`T4xZYrNm)zua2Gi8&IKE#WCb7|%$y2OGndTAw@pMl*StOKu2rGfl}f@~#$L
zT9NWUWeUI_a=|qWgH2&H5g(`<$!xgFJxLYmJ^DD~90OMWF*AoO%}J+T#rV`St$MHU
z%`hwxUZT9ehKUJLj^bjY6R^&qvpHFuV1G+hR48~u9pDwct0LD8*hok^XCT}K1y6fO
zAvlUlnD$wDmpG!j{V(D?e0<4zE#XNaivd48g;N{q@XWfWIJM0<ZHn~RHq=xMzj=F*
zRB?TpvG=akt+dlibX^B$<~)`*r2{fo(#8t$Ib`wV0jz%OxPu<0uOBn$h!NCgcOW;D
z@$hR&`g_H}7S2sU<4||%bHX|LPscpK^mTNK&F-Ilw<+C4$9en(J_Znb)}Dovf4L#y
zs1ef{pc69IcNtIhte!BwXQHO25Uz9ArX<)#IathmuxcJc4gqj+vC}??spaE{+{(Lk
zT#+kwZW_uPgI6TEcqUz(R+L9un+s?B9w4B(g1M?nE!kB$&3h*aIf{0!lf*8f2FHpC
z)08}#yvEa0=BYcU2`T8AE9iwZHwH_h%NnWUH2?<MY#G@QWm{j|=(PFw<9L^>0;!Fo
ziq3z{cm*P+6<=%n@K~+|y%cz;(R}zp5CbDd&o0h*(qP7%CRahU$JU=~TjD9oi_H`)
ztW>Hq5}rhyX1vkf%>FdqIbi4zCLtE@-EsJtQJjTG+{rh{u+otQ*VwyETyzOR6417E
zERo69{l`Uio>cv|wbt-&G*DhOql{~BJnimfE?!_LniSIZaDk24rusN<aN35=w;?^;
zuBLuY;$qO0re7{QB5R2}Swl4YmtH5jiz*G;E|2<MaS)S_3-tB#-gF3|IqNn)d05S3
zN#|@%mo0nSrZ%&ZKm(ru!h%M|%k@J@dGzi?XuaQruIra`Wz*mmESY08d8VM{gtkmP
z)IgkRR(p5k>$y84H@(?2$S${UsB2a_8ycOjH@ev(IV)&W^~t;3?f$-hogQd_0}iRU
zY<crfe1?Mfe-|an))r1(sDd!`I{E>4H2;9yIP)uysO&PHa6^oR*#kf0OhgMo<-RSm
z+5#Zw!0g1hf)WNn#-H*FYKvx@%(v0p1-!5FmL8@Bz-5&LSzW^{q)04ubW)b3tY=jj
z!s(fqu%ko^#ihhMrbufz_Xw`R38C`OSyN&6jq>)YxFOi^9k{l#^WzFMZ!5jfyUfju
zjV+%4;OG<3IX2e#_%4bmOv8(tiY*?C?S*X?z?~iHDUrQ2e-2|d>Tbeua};I<m?>^{
zfGPU<>Xx-hPX49HNYg(8_YOTU=-<2z{gq9($p^d1cn0v0nWFnP7?1JWj&7cyodoU!
z-G@=>qCBHS1sJKUTL&+<pCax}dmhjk%p{dZIvB0gcV9u@D{ydE<@|OO0K;PNjsDYK
z5snfFF$3M6-#=mg&k@>GcVS!Y&U&1GdixEUls1*yqyovGKFiwq3-^qGP6Jl92VamT
zedDBZg1nlwwwN}EY8+o>^OR{eRaE4PlySo}24Wg@PwrE8%5)vP$gOEobV>ARFHPsI
zXC10EQrlZauVM<!kBE<7iRNIa{+$Kjh?N;6Jc&+1q`sgWtlM^6XYDN%mKU$w+-=)b
z)}kFTV&qVi)BSW(r#kQJ%Nq;{rxZXq*lxOjx<X<Lr>jfNO9;L)bY?LRON#qL`W#~Z
zpT)(XPxK)xNq|-lG9o(iT2BBg$lg=F(T-5qw2Rpt-V1fh?w@)8S~8K6|IsD4xb2}c
z{ydIhKYo26{|WASk;vNNRhsf-hH{N{C<d}VS9NGQ|3=K(X?O$ujf3MRN`Z|6zs>+;
z+ZaT^PtwL*cgdm!4nGbw>pu|~5%!dJF^PbjZDuyqb+cUKlC|;0+!mmD=hnRiuMUsA
z53Rw>ik*V${>M?dZC~9kJR#EowLheEhyJom$#nj=cv>Oqu$aBpZCm5xurmZ)brgIV
z)bgM0%a$w#;<<^I{IMpSk8xVNa6qOuE+4HUh<0H+9|BqaKS^iF>u6a7WjmX==x$8a
z5iSKIzl|v4y76vbzY!c-mNGnWuS$mWN%OmQESgVYO%{JBPA%Ctempi)VK-`FHV}+@
zLOW^$H8u4EIGz&-O)H20u_f~vAZyrJ7$dEPlI>&8T>|!K@|pjnxNh7$4HTb`dq>y{
z%V?*Xb4q0XEa%s?Z3xMwyc}q0HWGyFIrr|JfH^DgRM+x0LJ&LB)TB9a{p_SC>>sl~
z6Q8k7)c*BJC(5Z1?z#U(UHf08F^Cgq+txu2uHts|CggSK`qt;)9!?JYF|MWeR@x<|
z#V5w*ws0UopUU)05~LgjXKmo!ueeH@o11?wWwsDgCn1%$PEAA}rZ<_AhVb`_O8~0K
zSI2^I0G=WDqXM!b9jvG#3I)~QFgQTlkE>%(f8hFKPAOB(g0o(aY=PgK1`JNz|Nr^g
zA2{pa%DJ0U#4T&n$8$kM<gcc@7x*N;J8B-%i$cO*j6Wq4Fihldx(iVp`h+n|K|~NA
z-|1?WNnQu{JVqgnq7(tL%_s%r`s$I+wDR+K54=ilVKZAD9<>GN%UUTJWh&DPeEz9=
z>JwuO5LR_m26#ICHw=IOc)wS=PYgE{<=ff>Fw~@SagZH2l-yT^ZVfn~KnP*HT8i#i
zDfj(51Qg^+G$|;bPNDT?n~`WX2UOh{IO`(M5~2y@FuqQ$)9xST$5!q&gT=-xu|vgc
z@ymxpS`qri4hkY_PaQix1FUiwcSWs)Psd`lEZ_1!UX=8L6JxM-6wmOR6fPRw(jWiJ
zjhJP*{05@>S|$n`-L*Fgh2&@wPUkc3NDW@+C?f$sI3|dU;GJOH-XlB@ud@|xo9P)C
zZdu-Zi3{x7AdTf5N6&sU>yLR4IFOl%=?2w<g#h4DKSzs-L$imL!{j%Hx!%1ob$#_D
z<5DAbUEt=fTm%e)3zE)p;|B<i3#ouZ-_G%Lq?ibXjZPSDdN+Ll(5hv*yS?d|IsjO#
z0%E1kgBSLNbKFYQg7n1nOmEfx@2#B=B~;2XN)i590toN}iYzCpb;mk?rsVN{Y@6J0
z6Nes?P?DbwqodV-02=_Y1<oj==trRZU+2->M}sWYS+s!fvz8p84{=>`d$(no{~t%T
zi$;cC=)U1U5nB%e@xIonR?_em2lLP9y$j1ZsejvR-Iv^+OS?Dm?W4Gov&Q?Edyq;S
zc-AE%67o@E=L>uX2qlZcHyk@>H`Exq4h&8|G8eE0Ftrx|qr8@$IC;7PX`q%BCRQM7
z(Ud9Yc_Uwri{)aX@McNokZpf?J=dQ2|Hx1vV_3y9thrqvt5v2oyC)+<;!f{-Iv4WP
zWKl)?O4QaEh(yWjGC1|6cw!0ek{6nF`5F2CEidyi2{4maIy;}L`Y<G)il?8VLHV+Z
zH(OS1IcZ^<<ERXYpOQ2j5)PbODh4L*{FVK%Jz!c>GUKEuHpqCO%R}+rg3#s{T)e4U
zY1Td2Ot&lb&MBTdJm<=jO>TzPs^<kqk32L9iEX#g&!=h#fXGBC(2NArr08RrSF8Jv
z5PCTMZ{w9?l}9c!j@f^IwJ{-#DpTW<C$b`f6{a5a&Knh)*6=)h)m@7k>0aO`E{Jyt
zIr{PP>%CGKlZ$CfIP3c010okC6meJaz>d8rh|0}9j90k5-T?_LYzV+4#Q3%lMX8#l
zDHa)~Gyi-ur@j{q%c7YzY$FnZ)OQlJ_3}Bu2ng@a{>s(3`!D!e@zL?W8Y^M7TnL-@
zQl35nENrB3hUpKc3;M!2(qCR)j!uc#nwz<nc@p#fQ1o=`UwQ*WIy;z<{kaEmfWe|b
zj@>&pmV4kfnp$8;^(4wrl-N4wB6D$A`$D<EvNcp8Th0akOneVe3=yh`Dr9HO^&Q@#
zen6)YK~r>hx{aU5PIp3I0?YHpKZ=6?xSh|C29nf{50t;heHZ_<`$2P{&T7|$n9);|
z{%9)8Wfc_4!P219EXldqiWH-DAyH_Dq7&hQLK#TFqED;`n4Bk=OAzhe!RYhm1tBP!
zkzi{84fqwKJT<%RX@b)I`j6bZN*s8d2VEh|ace(L!(qky#FLHy?<-8tSILsbDFiiw
z76H=Vv>BwM2pq5cTvqHk`8;<_b>6uAzwggeN?fiJTp(fCE8ZG&%b~8?$ZLJ++g4jO
z*(;OC>%tlFmyIB<u8>u(@41?Pc~-x@=(?(3LHtPX=YiNQ|KrUZC9E826DS$94k^6B
zB!+;cIZyq_%^(~^XcHqJ3q8i#x^W|=(tVPE6-@VKtNMk9kN|YT)bmd5^;~IYdEvVj
zVnV*KsQVotcsN)96v*pf7L+-$=hu1Fw2d8=(R%G<@h9;00e!&n#PbSLM1Az<K{!C<
z9$#}AE4hKYm8gRGzF9o8B}Xr`n+mDEz8*`bw%Nv&lwWrNJtdo)EQez{bm_8DSfDLX
z$QQH0K|yZTR3}pYKGbjH$!Wu{ZJOH5cT2hytKs9(W$HNphFJrJi1hRNX8JtseFnzF
z9Fu?Ufd)ev;<0kmoi|q%3LP4PYM)T5u<-9NQj>mgaoJ)Z7;6jk-7*dNU8xEft~%`M
z!*ZkJB!7+0gZBSJx7qEuuOkHt%#E1Owpxo}fg4lqqsdFwGtsk_?Cf|j0-|md10HbN
zF_}W9?Nj7PnS0@LfjuFQ+j?oqCE{Fx(){^_63+?fM6JYTDGp9fP9B~CG%^Tuou8=#
z|Ke=GfMLC6_q9mb;eAL~wAttV<4Y_;e3wLyni^f8s>5It$rwQI;nWXUxHH0LFo)cI
z+7grTX;dN7{&X2@&`TTAdvr&c=XC!fOI6JChmwl7&7o)z6&1xX{RsAN<_<K+K#dh=
ztlaNF<c&V#>vJj)WpK^4(?Ccze;eupcuJusC(z|0G}!F}Q<0Z0VKGkE6m^P;bB#*?
zpNRK78Y*$YJt6k&AJ-y*p6n9+&)f)EzPY9OW9RrwxX)rJvN;@e^PfRA9-%c=+w$Oj
zsc(+J780DY1~@-J(7y~Klm9X!9c(6Mm(u(9gxux470BEiifXL`8lOgYFrsjB;p$V<
z(sm9%lp>zhoF1IoH{XNO;<@z=ETyhGRo!cuvr!|!bj{R%Dh1MyN|TPR6ik9YL=kx!
z5(UMI>lIfRnilK5gnz01eLj{6x3|BZqc?JNK=Cs9D0O%8gDcJ|R&v*cE+ZMWRT->i
zIQ`3E{LPP_{E2}6;9Wy-9b|-Fu3n!WoHl=Y%=OZUKxAZO*RO-dCjtpp!gb4CxBrem
zX}X8I->n$D$%EL=MTjha*OPrgzjrLR!zb`SIWGA-2<1}S5cM29mVXh`C~l$DxTU!l
ze{$jTqL-NeVdzD&PBL07{rSUNqZ)7h&pp%j3?D(|XWhd&_W0~J+-IDK>&-swRz~@F
z<pxqF&C^)c;aad^ZYR=!P{^Xz`9}G}y2`>Q;bllBkAOH}y8c$;Gh!r$nExrJQ}a(;
zd5hJ+q7W3~Lx{Kz46MQ_M1i%X%%)~=Qmm(33;XwpsO;4SH7b1K(GJZFNga1YaW#yP
z0Tm3yxe8z|ql2>eW>WD!{PuE6O6Fj2<3y1hvK5>uR{8e9pc#}<_ZpnS_S1t(GCuDz
zK*&J*PRd$JeE_l<IvLdxuS3X9;_{t1kg&RV2BQL!kP!6AoA^6d<_9t85=dlGgp6gW
zDXy5vL}Fqhj`@q)7c*!~^+&BC5bqC||2|C2Z6bunEG+9N2~fncY<l^YoGZ7}$GGvi
zLCO9rPu^Og=0ta&xn^*q#b?Q?FN?<TxwPWqgts`;KRo3PNEnY_Yq<IipT&EH$3AQd
zondq5Kl(rrvl_4|154q(GMULuDqca&$HJ>LiFe7Ui#NNQNvnTvpz{X|KGybR^fwCp
z5%uyAY75LJd_G;W48;-<&A5Txpazggfs95TLlRp62UMxfV`<DWVQxKO%=Eb{DdJS^
z;w+~-`tNnET6*(;CuS7l8xY<&XJ=<+mIs~hQ6WQGX9e04;<9eK)h{o^K2>_1B7f8f
zMwg(&4%`6<%T9`6l+jbzRC;dxB+CA|d<;2uUMVcOTr<NMOlSdbO}A-dJ^<O)EDP`U
zRCSEKNNqplC+)=7aQeXOTmyY4Q$8m&i^TFfc$fH2Fm(w1qt3!lp`B4$4U4$(nTVJ;
z9eVl8<~3>LTj$@+z^(X|T3xLIXjm8n8BzL7u|taCkHjQd1NU^HMmN1<pZ>`_AJT>8
zlUJ7!B%!03r1cdo(QB$BxXJU4w#mg~>cl!@-llW4p=^6_Ecf5u^+D!Fa#SkHvMq`;
z()$aXdA<_}N~hPR1E>?i&NTbPVFHFy4xtIw$i@zk+i7m*25Lu?X#74}gumP4Qr-G{
z4McUOh7+dWN9;<uSw71Dw-V#Eqm3^GrebM{+6&RNRK?aUoXx(eiuoLm*R@)y7#P6w
zcD}`tc+gDdnn8c?U#=q5dwzPvuDv-vE{>6raplLa6T~0@s{j=Bojkrkxz$wZLnY13
zUUN`(c+S7vEzm?KKJZMj#P^ZRleFQH3%PJ~J?ZO>lAAsD07F*-??c*w+WMAyUS>lw
zj|CczqXKV{fCRVQl}p_J0rlgnlXQhr9M!@RtPz;DlCP=TObA=PD?qXRbg^@uGD*SY
zlZmZx^9hSRsyT$g?HkSD$wE}H7|Rwu(qS`2Z+rB3?D;FlrT;0@b3kA^@7dFc4q@9j
zaF)A`#<M2)lL5HC&PI~Jk}+Zg^HCz6WBRAQ+gH(mDJS)g>qs7+OUZ2rWe8vNq+W=M
z5kg=bN=15maHc@6rfy<p<}kSF7!8!xYIz6yE7XyW0N0BsA{SKJl@y<#%f$_07a?$x
z?%4MTEvS?laSU<Xnd#}-y0FM)gWL_EIymgD1|{B-83CzMW(9E8X0@jZ8`d`YJT4Bp
z%W)eMl#*#J+<*tS0uWHmTY+_4f$3A`duv5n1+H&?|DeJD02nzxV6iTII>7l`aM1jp
zN@7<#B1Jc0yoA@cr}y<(`G16A3Te9puEfQqSjCiQMxHu^Uq(|i?D6oU;AQ_W_Wj%$
zWR54l%>lW@MgIBtIbLXU0z}>2v)D`Jc4qqkVX(G6KrH=0H;hZPh!7|XRnL$@Eq>$5
z1r-=R(Dl5Y;~zkdT0t;|crr)UR%v52N16YU)sJ(iuc-T=P@)Jz%gBr}KwMxR1{N*f
zvqf75o{_6+fWb5l)mPJ!Q>yqVk2m_B{)z_!W)ca(VM2BUqRHP~Y5&Ys_^{P~v%o*-
zRNeC2lvpPkB>hyGjkJifNp!Y|>FDmfFbt3P<ai@ixp}H#z)?bYm`s{BMf&gvdEJpM
z2Z_<e5QQlK{XqG?B?f&)gx`@?I^*0>Lal_z4stZfofCT2CwK<XhrQPQ=%$yg_F#h>
zm!RM@Cn@bXv5p0!1b~V@WEc108<4Y5G6RcvyS=JnIIRxk^`-AgCAgLU1seZ5Eum=|
zm0*uzpQPP+Fc^|}cql3(tH7i2v$Io#fRbX6e|wt1UBYF^e;lgu$zIwf0$;o7I;hH2
z*8#Pp2KP&|sZXHRxzt81xc~u&jCL^<8?{uxlY*9Mo<`_x?Nsmsn!mELg6Iline0)6
z4RuMeb|rIIJBH505&`yGJ_L%$p=ZwBNH%PN8Gf438~&fbu|HA(viv(SGl8a7Iry1=
zU|=8)(z`{fIy@p&^J9&<c<V9ST=8wgM!q^k;inQ~=$93eV_K%st}ARczh@mj4&Vn7
z?+?_iZUMVBKx^3JPNI&O`u6RXHVq-dkr7S&0tyqiHQ99q@ANxT#Zyenia`zMLO7=X
z7r*{b9)AoB8prvB+Li!utpea!K^<z4seDt1FReTd&`cV*&q{=)D=WC=cQJ>cXc&l&
z6EUiy2A30<<27Q^8kk-F#_<W*ShrETWKK>@^xr$YhwfT+YdT;sc2)e>zmPETjqM%>
z&LV$pf>2H8sD*IdtYKkc;cNgr_25G@x49pHphQpc%7_%?1o$)}t6Qxt3jc*F+<M}1
zX~md#yYzNP_V2W6WMcb8Zq|~-d;P=H!o}NoaC&W<bq63cQVm^s{Z|Vi3by~=y&0si
z>8woQ{{lNQRSI*GC(ON;3f@CwrLVAIiTO+%44nKhRd7QN*MQeM_T!VzLD;REreUu~
z5V|~N3>B&P%j<^1cE+KD495^QX`Qh}trBe|=zX!<kAc&iz3~&3shcn{{vWMG>U~7E
zw#ZnW*pC#6I)y+#iCNJ~7*49mm7WXd%lCzXDax2gtM?RPQ`=X|$W}l0LpOM8dVf-T
z#6R?5^*c-|*!iJP?8hT0e0p!5qqGz`#sT_{(_OIL4h-l1eU15>-#tEi|5U;~NUw-;
zU$72SV5IzJtQd=dW;btOKWbC2d=ZX+z^glAq;BU#Fc77u{+&~=PwVc&>__SIj6>L&
z81$sJZxSYiSHnk<RCXb3p$xsi@_@VeExgpRQ5Yg8QBz0hf6KVUJ2?M;#vs25zW9Y1
zcj2M%aUo0hu>L|JjP#^ns7$k2gk_=^`AqzFKf17Mr<5inR?(3Ib9Db9+KN_O-u_{p
z|56ZO_K(C6>}R9W98X0{HgL_wcN2az7hgn-M<fN|_sPnu{?AbY^L!zC%E_=8o=!TS
zcj;lSeJ!5%!vP_VGi=s{Q1%Iq4yaju`bkj1H-^rVp_I9-6yKFUMNYG*2(3cmjZ|H~
z)i7my5x2x=YreT-O}Ss!#!<dB``oPokL~bMVk&6s9!4cIJK9GM|JGusy5E$ViHVCB
z0m{JdMwKVgaTv%x5KZeMy(FZ}#l^+0EttKCCc>)J^uklj)?`F}8ej+?sY=5kbo}1m
zF$Gncppu&&H6gL+NfPS>#?Z9C{EViiCMu92EWU=#N8Zo)N@zN!UKj{J2i^91>zw?*
z&<rL+@z;&~GdAd-8-dO|(Zb2e3E_cYiEt0#;X%a;bHcUvd8mDpOHg13y@G56YeYeF
zQuL!YnM^_7N-P1aa!HgqR3#Ofz^`%_H9d@Q{d3p%SDDhNn!hYIt^+4`K%7MyS?X!B
z#N|W&^KyS*iq}}fZZVBreJJ$HEd3+)U}fTj>gan;4*oTO#en^Y!Qwj;f7l|+eY}=}
zSVUO0tADGV`ecO05M{t1I7toa%I(<^6*Lgzz&Dilg@W#rjzAj_n96QR8df^h=J}=@
z6g8^t32vjQ8o}ovdOBOxmAgVFuOLsUn9bhg({TAIa@P`2s0Y8fjgSZQFL?pjIU@VU
z;a{j=8NVmqlKEA=%(PuXv~~Dy@-aXaK#jkd^FBYtA(2Ecu{-<eCTLgY09<e8Y%x-V
zOvUMun=VEne0rH4a}xKz4kDu|oY@jH#dfMXPnub829{fZCjZWzLreq*V!3QNyrlg<
zR~&D4Q`AlU5fL=L64708ytBtC33DJX()7iPe8OSN49P7;@W`u%i<QFv)Eh+a8=6rg
zKP=GmNccfh)+AKU?A=qJ5B8vR;PzPZU(UW<9Vm@<4H6q<HGdGB-ybjAv@Fh&sDQ;Q
zI~^-rsQbmgW=t`eZizv?0MunCEt-eQnd`-4K9r17wxgyL;oDc8RV~A8G0_Lfy717^
zKiCz4Pveb~G+Q_t0tFkG4!kcJULDRB7K>wFf2_h$mFg<bZezdfn*_Q;^32y{r(|L|
z7w=48o#Edbvc%%QE&lSKfsfk?ya5eHeyhYOAcQi;OwB$UBNG<#L}~kXec{NU_J@|^
zvbq0~>9M-npd-&8L$|Ws=bg=g7jw)Bw#Bl!AHI21;TN->eSy=eo1wg?)FJyre8JGo
z6&7Q^G-CFvA)#J5`p$2F=IjAUCYWLAd?+7J@)S{CbmNT~I!~<bML}mh5%u_2UVGCt
z8fZh2@R1c78orWc)s$`?ZgzGhus0`u28&;XN{^0okb@^>vx#6H7wG_z{@mGPsVm#X
zN;CJM50tvM_O{f_700$RXA%(+Sj2l;y<Q|5&0$u$Yiz8nc@3gcQXc3L5QC^#EXkzI
zfGcRZpV^%v?{H{@i4!XL`tCjg{zNyOSd93<enLjlzjeoo!h=Yf3%h;BEQgB-YIVJN
z8q(KmWA`q1+v7fa?o+;o-(#Df<$#<sukxzy1N)oG+d@M_@1DH7jJ_4)QFMI_rAWoI
ziCs0HpQIXkztDDd{h*HVNq?@I)V}+ZR5mC)w0Xe$_?c0uwPThOmx@&{GkzMW_^504
z-Tq8(NRX7FcV`;^k>c;Fq)!t&Gdwj!g*%e>JJo#sLtXdL#yJ3W9&b_HL_5l^DjrD9
z=%BE=(6RU^DVhQUt?3>vFD|BRvF@dxdhD=r?`EjGp-Y#SIz`><?BnR&^HI&WP*w(C
zFFuiO=#57*>~Zy-j0V)AP)Op!lf44ky$1Sql7!`xiknL!MgUTL-9mP(d>OU1Oklb>
z+B?DwuqzlGcn4$n$P?QxLD`#!8`l)Ff9{DI0lz8Q&NCKs>p=adY59y3`>P*ouQ&Us
zNl$!Dcz(IM?bYFFd5<O8gW43KoOS%jyN}PF(sz^TRz8hyGju7*$io4Xdm``OFsd|b
z7}B&$k+a(|-$%&0^A(AWjQmYLW%W45LYW_A4W|cA7MA+Uj1694IZ`(vo#EH%%s;s^
zLz%AGCT%n(AZ7$(Psm$djSPa!!G15@{tCMtQj0_Zs989D5D4LYR2#@HH<a~b5)!cf
za#m%*MZ(l@Ro#w#@4;cV0Rl7K8G<}01$b3o%)b$$3LP51Kfl1-F@6*Ngw(u%<>f^5
zA{YNb>;itm?UbJ7+X7{o`>bC52wfJVfT}Nu1P}riI|&~j=cTsj5tK8K+umGqCc5pi
zK1S<wL>!n;?xhv~xO(kcH}h$qlt2D%JzM64NP=LOaK^Jo)*?MNR$V|-{^T;Xy*rTn
zw=mM4KJ`=y*2gPQtPx<tQ+D=&=n;e`qa@L&L$&*=q3=aqt^1h!*>Na#?8jgzI2{hU
z0@MyrkMAmBBbMsBTW|`Gp*8x?Im8Og%lCzZVi~K|1=(I7==WU^yNJUmO&rF7u9ruR
z<SY2eC{j_?Gl}+C9Aq`_r<~j-s7M2y5^vnePfztf;iG{e60i)KQbs%QkP~6Yx}QIv
z0nd5zO^t|5;!;4h_{H1RV&%)wa8uH2en&t3L{v!3zYrdI(_!Q)v24blK0JEa7=I>v
z^!7co!i%!IKMrFQ)Q0h78@SxjA{Za;;p3>=Ii3Q^1?v%rhCqcny=<2t--B5XQQw@Q
zlUkv%C6z&Q+DFkc1wlWcROt&0G1^tXk2!!lJcCWeQ6nIIVpkLbi;<a;u<loJcE*+Z
z(>)txv2(n&?xZ3vcWlqo=*#Be@x;nk)lZL7YB(OQS$^pUcxR~R^r#V7L{cr9%^-tc
zX%}CBww?EoR8z~`vW7(WbF=lSTPzYMI{MDPl$DO%;&?QxZ<ozh_p>)k7rMH-5I(th
zpVom)D;OeNBc#qtA1bRxW}{0Na8=co+4lPXnoW7CEW{QOeePLrobbNazqY9<=yp{c
z-!E+Qw4CCPe&G4q*YRXGQDUtB$z6ALLZQY;W@YHhXv|`L7!?fUXiA5=ucx5opcasL
z$Q6;`wtN(W%y)bp8%*Y@97-q+lH8`WgzINlwuI6NAg<|I;a6y`Oox;Ai;^{*{YCSn
zXiYz|$I3?2mv>UQ0$h#KVa$Ronq{(<JOJeL?VJ@a2B5A^TGtf3k3YENPiw=wZJM`V
zLBmSxHTJxyMCU$DRD0F4|LGUy)zO_X@C1=%yi(d2GH_+jn%)vrNb$29MkIcH?@F`&
zvS+|MD1qyDY;3HI!=tKGUM;L6tMG4VD7V|XIf?sf^uKw_9sdDPG!ZP-&aqTyN6MCs
z92xc-c-DDJsXs_3G2X(B-p;QWy_)HIZ(3X8Ykw+#^*fvoHmd&{kEU@~UTD9v+}eA3
zeJ!{+24r|l4^!?3INQ-hpt@b!Ymv2&rn0?Wo!;J3HNM4vbI21n{0N$}dY_oI*FUeX
z<N{YR>^oxTC;c@mvt%t>E=J_mcfc7nU6TrKJ(qEDb<rY5|DpN)_6@2Q%xKA9$T#vR
zXhFR3E}ytc%)@zCceQC>6l%VggE3cPj#sPu$;xEuz9+S9c2miHnEvOJ7`BZ$hHs+V
zRSKPr>95|SLE3Q#KMlXY*>DruZFg7{Kl0$p+t7;Tnz4|Gu<YG6^V?Bw-Ue>NOIj@I
zl045o7`yF-09Ma_A+>eRLC7*Z-BwZRd)2$sSw+aCE9e*7zWw_N!r}Y9!oj7u((ka|
znE(AjRfYGe7z*#0bbF~+Zd{)~Oj;XTUme3SAA$RN(BJOxe#<jBG&lVtHsz*#KOk_q
zthmKH;6sUQ?L;|K>?zyrddfcU9-cV4Co^zMVDAwDxk7~$#U7vie#HY1#O!A6*V}!d
z<Gzcxq^f@6+cyt*kWiX#f3yC1-_hkeg{mA(#JsLv!JtDxMJk35WX0eIWba<QP5Q)<
zUO5z`Q~B%}>Z$C@_vbh2?6w$wRePT)H+3Z8gL%cV{na08HJYZ^mqXWQkhdBu>d8Ko
z5bKAbG?IB|v!2VHLF{d;<De}__M}7UVqvLd<=wsMlDDaV4A-;$(4$yYW*6PLC-*gD
z$bUyuYI$lB@zwLTdg7z+Yc%;>3Te#8jRL|Q&_H#(*2HpaY7i8)B~JpR4^)i&8Db9r
z7V^!0ncydAW6uyrr#;4HBuHm{xp7?`3@LiYo$1GV?hMtQ+B`2%_nN_9J(e=q8P7WR
zW88=bT62IZ6}fZ45@r>6ox6R<!%o#-=h%Gm(f3|!_KiL5CLF$Z15Sa%ZyfP&$Z6Xo
zGgv!n+~cEh*y`{=kPZM_xZ68H2W1=9e3Ue+dG#Z`t?2&n3+q(7p`<&3x2`z-UU!{&
zJW(W7y<?YXfr~c1Oo3FvHH9s)Q|IcfIkhT<MYUd1gp1R&?+d4*rXpt}r>9{R|17Je
zWSI6aQes<Rd-Ru}=WjdZu4j&n<_u;`+18BiS$J#bu&H=d?epW3N00azg)|-`6Lge{
zGG|udckt1m|3t?8S^Q#lbcE!M;VT$}a$?q00Sg~o)n9~_b9A`+F?9qLL`Gk`;)IGD
zV%bmgPdvg7-thKxu79yNvZ7E*B;4PPHCNBUe;pl0q{>gZU&7Mid5Rb?ijlWcnb!Ec
zruSKq7QFtVbbMEtO=_O2s#A%(swYL2?`=Jrm>s5=`$gFNQ=u=svMBglQ<i7$^QcCo
z747!48ajAly3d&;#TWf>6K|V{dHP5=WO4wZ#vbotW9y4kM!mUh{vb1V){}A$X*zY@
zjQTuh5Ih&N^|S`)&pRG0Q=r<%%BCXJyuS9k5f=rWG;9nF{aZa*MLqT&s>ErpDjV(N
z4Wr-7rjtVI5*{5FucLg^!-2*V09c)E*|y_-r<I+MF7@5!7oPE`ij-_8xly$+XYYDk
zGbi9Q(5+hFu1>z!R6LI^_Te8oC|*q>9RO`;{F%IpCq0#};!8dh|E7>he|w?gMK6-n
zM6@H1QuN*;G5nlxEhrZy>9MEpGnkcU)@}CT7Yk~Ei|p$+2DoO>L*_Sx+vrO#?>6Aa
z;(SToxc^0c;j@H_>_n%UO?(OlB&xVSk(URqU1`BDxF^yT<u!4O8dRp)!6if#qH#|2
zhi%)&jkb0>kNO4{#cHt#Rjs8;yB{!~63RoYGcE{yjIkR4#eh$5%oxN0oxhu6rDf44
ztjrL<mqS8a98rPTBd(l1nwdnCKCW$_aGB5Fe4m2)>7$QMKOJ~~@?v&XqKtY)1>U9*
zw_a)<z7a(Wh6lwE1D0Qvn&IpuN$dGeZwS6Q=9AV2hXQ;q<q$$1qLHwM?`g;jt(@7$
zcm6!;2Hdkw`)P7o?~o2Qb;{Y4J3$JB1Q@tF{}yfOTIB`m%mTno%02sqf~(+@j+1@P
zx#OW!`X`!)Og<gug_;(94xU_(<TnkR@{jvIz{XO|q44SIjt|X2oM;=Mk++{NLR14Q
z=s8fHA5v$_9$N_Hv|ppUyZc;g`-YB$m)iD&Nf)f?Z2dbKfrfrYcR|c~1c~^5adrZk
zQrMVKcM$f>yAHRO6hD$~FmJyp6kmG`Bi8=&4{v1B$iM$iLt}R7|Dpf4|I^hG6mxcX
z?5Uij;TmG4I@+#PlRc}aG02+vPixbE{t=d+b>DFMV>)$WhTCtfg=6R7z;9fK^Z7)2
z;J&-b$&)`(2H<9`uR`ceV8$nC1m9cp&jr)uw3uGCb-Jdcps+|g5f^ozD`oA?{Ma78
zjJ^JtaCRK$0b>0z%%aL%#zEZY+vr9v*LxRzM)Xgx6LVK+D%w5yL&}}DzBtC;#_BK1
zxP6vUee1=Wffuv6_ZkbduyWQcN>lGyU)lDOnI6*qMt7~*Y<f2pmnHl*`uh4nj*$yS
zP&}o}*<s@CjaV-5ftBF>a4B(|=*}c8YIw5l%_{d@fw7Y-;ZUOYh9mbv;<SwNO4+2$
zsV-(NYL&AMb}JdRQ-<H^?oANsIwd8l9L~9aiJV69(%8)B8E86)fp@1jY1<!_>Kd;}
z8X4W|rgB@8fZwoQ^>Pb#X*|QdMips~U0NwM=PF({Z7J1X@ET$<jiOlPiMZBuK<g0c
zOD9ht`M&*!l&utv&N9U_yYBa+Qy1$9S7OjuCf&zuN$QVsuA`4wS2l}sbosCsqR*JY
znZ$ft;LR)8O$JE}u}>Xk<yR`cHm(o7Iuc!3LKn*Nf^xqLN7!gm^T%)Ei2uOU5+1?E
zTfFO1witE$<?xVeTDSA0d_U>!c`D4@2jmM1w^?8q#3bZ+(gKfxe=bDU_ybh-@Kj9T
z<DofF21^Bk8l9`w=04$SQy=EkyyDe?evyyM$7y-nDA<oi@~Nwrg~#ewM=-j?S9#z8
zvT*MA&m=uR#H2MUDi_YUKZD|j#FiHXAg`z4K)1$`<mpC?UB~t~ysT<WbjD!AdhDVF
zBy|qkMHd60aq5~yqkt3|0>(6kMv?rE+~u8^*zN_#13=`c=ytA@eHE8CSQb`>Jl1;U
zRPqVODk}R#!=Ixu)O(Fr$lN6ki!=p5^<nP8&OmI8?X$#my=w&tem*(E*Th`<%o#dT
zK9FlCo(zy8r`OfoR{#uND_2p}M3~gKc<gwdFLD5SkuCp7$pD?6MfZlM^}5UFib&;k
zfv%a~n>TM3t5f7T9uuaFz7uZy%cM_-Z!=g&n?xR(4W@Z<ktaD)luu}P4Z_x0X;X6j
zK(=)E(ikSvtLS9Fk}rS<Z}%EFQaa1U9;>q@+5o}tLZ33w!2Fv4>_}14UVOzaEbVMl
zx8h{Szi`<o6mzoli6%W%7a=yuYWHE2@rK~!O)-l*qM10=l^fc`^zHwoI{>lVI7p~{
zY{{08FKwN3^d%EVKqj0_8+oYh7u4~sozdk$0nd-q1+`F|Z0`@>phqeQXMD@+<wChH
zo{l=4_0>~^>@@0qOm&Rg1-0YJV(c|fUF8$uYzxPnAz5XSI_D>)Y9_3^9)?}JPAIn+
znv2~m9pao-M7Otv)p3NwS}9KjTDi4IH%F6NOoYzxPY1;?r_5mRWEY!TPS-TpfxU0T
z*Hzo<NY&53A22eCl-u5|lcEyN!gWMBdIO{m@7!2}`+D89Y*MJivo^h;^DgQ3ndc0D
zaxrs2)9n6}%oVY7@;3hbUXQ80<xQOY?33%BEM`sKMOtIebUgokdxqA2vTbW}9jpl+
zXNQEiQb;-8TH7Q7Q|K9&Y#9q^>exIB8J$q^YMVk0k!SL02ai~+1gTl?an@6v)Y*ra
zoddj@d@#OA9c@;S$GbTH^Yq3r8Q0s@o5xIunaEfaGd{7q82%%U1StI*;E2X;(Hb7^
zhpz89?0%=nhnvaY8!vk|>D4$%fz`a<>5da#w01w#0v|b?l7(-6W;gK1j?_!_uS72L
z7P~OMk51!Ga0}8BG#J=lClS2wIToEAL0tR$b?FM4+oN^P8j2@x#$UTy7t3bW&toR*
z%%c0@qt4l$umIePBNAUGC*6`puvhAO(ukvIAi36Y-EKNMF)QsL3+)XI4}kLL9WXb4
zsS)ud!e5fD;8~1v)t<Ej7sK6-mJvsQ;&th998YC0acT2yGuyp>#9ibw(Y!u!4*?;{
zM_4w0IC`%aS3{<od1FZMoWPnlH0l>`^6WK=Nh?`(){;IUut{0kLff46x+#w(VGj!7
ziYV3MWs5iQk7VoKOaE>Y72$lOE3>PSm%Ny-b%Tw*BGQJ{OgB7fSJ;Em0EZ_RJ*Lwg
z&rKl+g*1-giC-Ci{&9Ty73Cm;Q48+}{u9wVwY~!!6S<Q4GhZj7G~6Hkgs^{<SZe{@
zt`9R@wzy=$dsB!*(sY1HQcOST={cjzd@m2J%F>w8D8Ii4x+#oVSXP8V=e3;UW1h?u
z7d<^a*4_J`;mNt`R8ZY9zRqFm5o!bSJR)wnE8^r40}r1{d(MlBH+c5)vi&3z(>{Bz
zLZkF|`~%U%%;{*h3huqzbU9s}m=7tie`I21ET~10W|S7Kd*)Ho$vWu0uDUD1q*z(=
z+Mx-qXYo5@%GCWnP)%kl;i!Cu6zcuY@pgH>Dyy#p`>4yz22DBmJzfp$Wuq&mnMh_?
z;A>;=i)?H;CPHm`hW)CqPr=t$!%m=+VZ7jeawQXezltuWVc$^I&X*S!_NxfrL%QB_
zDms0Li?uB!F<6h*)j;v0k|-6K5}Bg#%_P~MrEUQj>7^jb_>9La?!wMeCmk;tuBw+5
z%H8JQn&SLB8B$1V?=J~CF?U`HFf=ksd7JinXwl`sqPhq0Q{|_t$B8>xwD;jI7j}{T
zE7^|&sVp^H21+%z%kU$1sBcfc{p6S5WOz28P3s_ABr)9$Nyco?Wvvu)<Haqa91RRF
z!h|do=`&w3u!H#GstpTm<>14`^Y9)Ln9^LH8Llzu;C5qHG%b!C-+PLq$f^IDxh&gp
zou6N<-uRi{t0cBuCqKmBP*kA(z+iUKW^Y@PlQ?@qqPUO(MWl>a-2{dIAd`2SV5LL`
z)lIs+XD^>?+GZaAgxIylOC0+Sy>h9QY)0ztSC6c?EHz!YU+4u#7~mUn=9MP7S?NxR
zb9%mN%BG7#sJHs}i|bG}7`m|6-f9!~FptfLvP(}bS!#vf`6;fT*0J^D&rXVy<$pzR
zkh8F~w)@7q#X>vja?w?jkT33v(R?IbH=!e}V#MBR)>lRP9IiS!WT%81^c;2Cv|92x
z+QP^6f|ci@AB5$hq7bw3zg%tS9(={1b{Cs}<(nm9PI4!nq9^g_Rkz9-=(Hj>PfGte
z#1OmbY@p6RkA5GM+`ZByt1Qy1uAYgn!%jrdVDxA?+%2xApC~SQ=l;P*R+WS(Pe(Sn
zG}nUb!D|yY*6lbse@x!gh>^+;sG1i?igN4IUhhb8iK&Xy6HQ7UL2lTlJ4ufxeR*=9
zjzESnw?LeNJn@WMY|BYpm(3&1dL8R}`tecJeZB07ef|q)CBMnK*`A7}mGaWrQnW8V
zjcp2#K*`dma=8Zd#l%>izOf;(!I5#x_?RhAN3;t)0_OVQA>$s6=Q`UY&eI$-l1}s8
zA^M=p72eJ`wzJ{mig}h1W(WJ}b^ZAxDe=>}bp72osBXCke2mT*DuNxc&0BZ|H+{z6
zx>|RRS**??3g!3vrmpFS_?HZd-dL?WZs6_s3wa)gCyn?qyNfB+-ukRiscywH=*`L;
zM@q2c8O)X*zs>WCc3~7tLjN!RLu(lnv?n+ttno3u?~m(92FwfS`j>1Ft7B@pfFHsj
zR=15hYhx?uh{$5p(tPdX8}Wlqsq!avJM2b(aI>Y$C&JgsE#O^C*R&D2d%FTgv*h1I
z#j2|qNR3}ppjX%Jr1f)Ww}3K*%3)yv{E9XBVHQocib3<Qt+o46@p%7lUm$kwh{}kX
zqM{$#YeK^E?qP+OG^M*TB$L29uv)ztG^k==y=@`ox$i)Hv3W@+<V4qoi<^szF3YwL
zL3T5W+7SOs)^_KLPrec4Brv3x=C!WCdMTxyrnho<@@`IR*R<t(@w%x#fakZdI-{59
z7K!ZQ{w<a9WfL(NYGyQEsEr>>>g#~Cqd-4*qw9h^{u3MdS9oPOi0^}e_UBta`5CP!
zJtfLe*}*dDj&VNO0)?QyeA%9d>|j`GdRUnxJFw>5WcS3$4crgzLI~IoJ+hQEC00x1
zZ797_K^Da{EPh~M*K4~m8qFK#xxRS8@NR#~$bdK69uO8eSy{Jdw$ZV<p@(_iA-?o`
z#^h7UOs@i$y#2MrL<Kaa1P?vto=8(*Z170ocK$}SLz*gImOqen(4IRcR=nD(DJwnP
z5UfrDS>lA}3YBNX*2b}W)=G3#c(wje+=A~8!Am(&KhNbkiLMdL;jHT&qZPgjUGi-`
z^R@Ckz6xD9K*O)<j7nrbbKtCj?iSGJ>QaNRAB;87eb#ur-cURrOe4?AWd1VB`B?(6
zk3x3*S>enN&JJ3cKo@+MZQ&jk3uwUZ0YAn4gm^@8)M(6moK9~FI0<Z+K<sYKoTBYt
z%b>n_GCP*U720_?_>z`*IT$vyu>0HiT}}YXY+DJzII`eeEvaZ>>8X}-t~j8UZMRoP
zniiX!+Ft4!E$^o?D`0f&x{555YdiWZ+C&z*_+9=+%kF9(_TMV6%WlwBfsZAXUxziY
z6=e3&75Z^Vg3M0L?%KYCL&UtOh@tgRS+wnP3Bv?szxHuerSC#oI$28H(TwVBT0Ep{
z3(t$nPu=P9p(3|UIq1Ra7q>~BSf+i>Q%X1##ds>OV!W`@0pgA96sGw;L(@U4CQKuc
zv2aCJRL|DjJo)SfHrvRy1kZINruO-rmFGdG5E08n-X#p@5+`1Ybkkwa>YN2q-qWY!
zU7``hSIXR0FtX<36qL8E;8~LAdbF5%O7`ya)vy2^tqyj3pR);1Zd2^HQ*Hrxl4#|Q
zZ~ar^0*q+|dXegD*z60QZq7VF*n4U6s>$3-qsxmimAoPn4s92=-^Qr*i&&KMCZH$}
zTr|qUe#5={m2ED2E!Sxk|G03d2aBR+(QehG>ufapC}mL<8rWxZUG0oan#a}{K~e2N
zl<Tc@nXseSz(ViHXPkodrIW^6<2AsPyv9(K`d8HUl^l-C{B0W}zcn8D4KpAZyu^K@
zu^-dZrOdRq#>?pie|>X@zvC^FYB>a3sQO<9xE-?hYu^Zk+Y7^b%>mr=YZcWv4R$B$
zUpqg0fL5a(S@oP}^x~JoD`nRA?xr8*d2uXMrHfPJ2fFL@!y&cxMTkofs1RTL#l+t)
zzKAY-Ywct*pah3hOfD;gh_714Os7LSA_eD6JutP(w@0ofk9+>5hbW}JIc`4a!x4n4
z9luieU_Ra|(}xW$^JA6gaj`+ERa+@UtKl!!V6{rU@^0*(k`ygWou$lu&fPPkt}3?6
z{N=utaxS*PRs3LUw4+<&sR~}L`6NmQjYGQjTzzI2UQjgq{)~dv)>d4n*^|77%XS`j
zORQ{bYr~_Mx*_l6R>NP^b70{63Dy%~czyxEcwvn78Rq9hiTfIsd-h6D*d8noal1xv
zNAcJzdU9T3bii3~l?+_6npEIz(zcmKH$R^3;0M|@fKGX=q+Ijy+211p9PI3)=V$5x
zw0fS05N!}jkcE&R&9n<9tA4NW9An;ogWdLE#qmL<o4YVM#>yRM7Lqck$POSBJlGoG
zdkH|*`!p;W^A5;-_Zf`^Lg+B;*YZo<n{y*)bFzZ0jkX%I=txc*Y<)%s>T?XhjHlXz
z(KVp#p&)v!E*<vzeWdC~7&)bC5%A9D6M=n0T}o<{aiACXrmka&Z`J||ipc>)e+XQr
zFA0U%JoFVIpSrxYVG-y;Z&A?8nE2-!%W+3bTyH}uo_*mwHfvF9L<_zwcix+^IT%V_
znO|F@cu!>f(9`E;bB^~}e{FsEW@yExOzl;5kG?!&v`ew;-i<V}9AR`{@>W1WW|E4>
z2s@tg_EmuqSM}+2zqv1FyC`)qYLNEO4b~3N@0)Xj*rz!gv)mz60Fik9+npLxN>r@W
zgGPS0KH6}gZydq1XC5-V&hWf}pg(Zy#R<^uQp1VSm)bHg6js17#hn;Xl70BsE`Xt}
z=7}R&9D5VzeN}7UJW!CZ@pxH8A2J0V``|~E=#x_Rw}Lv!8?+DY(-JWdI8wgaeLP8W
z&S<H2fnJ8>f<ZG?Kdzr>@SK@M!ufD`2}RKQ?17<QQhF=Ez9KfUiFQv%zk2D!Y0v}q
z$b28wV~NufAAwJ|vZM@3js^eDF5W+g(PQdMO?cSHKU0q}<d?%uv5Z&xLEra!^@P1h
zL`v}7i~RtNUK%=Ry8Q-><Y5<10wi;Xq<x`7XV)Cm0X~vdEPHnC+?nC~{KDz;=XbF`
zh4PRL?#8WbEEGv2VTA*ij|?Wz#X%Jv-16M{-ioLP%rQLcm4<dsvHl$@mB$u;ykAIY
z=9M(M7G~vgn3UR8+U;|$aQW=OR3(T1vOAS(XkAJfl;SPj)q8s0!@OVfE#n8-+t41L
zaGwFOgwxHp?mpTu6LD^fT{X#AWuyw~r@<(eCs#MKBnh_L!_<tD!7+nNLcj|4)u3mF
zTkB5)J+=7$=-b_i14JB$gz@~neQMBRFqE{K0oM7fd46l#@quCZrWRiAyxXwk^|8S(
zQ)M)8VpG7o3(woN#Y@^wtpa9D-7v7Q(b^tEX<Sz*YW%)GcpH1Ib!WrM&mPFgCPP%c
zp~;!9{Vcehn}V`#{*4{rpHDzKCzxg$mZt#{?s>&i4QbiXe%zRA0aWMrBnjhMdMG6;
zgq*-MzqY8=Z->{lkLzzLB6~*B^K+}r1ukM<&@=7CFoxy20jaPp_a6UDwRTJrh^cOO
z@0OoDgi)1(XD8XTHSC4!Za$5o)8kxQ9$Qb-h*txc)+rP`XI3N_Jdt_qZu74vysXNI
z2|_x3K3Q6$I>g#LiB}@`!;eL;eLL8q9f&v_UEVQsV|Oaugmu5`k?Z1I=3lDp+co$M
zWNS&4Jql7OzmMIkzvvCY_@Qo}M{32huPjWoxK^{?M5u13Pwi^n>FGGf+DXidbj=r7
z!gTH|aFq|QzLB)gZ^;c=@;pcJxp@)_<JJ^AIwmtOMD%DDMw_yv9a@)OTvMLf%d%U%
zkP(9uUL2iGz~Z5bPQk0*L40>75W{ZV>c8O}+0iCw#<Iv|)5?|dSu5OCdVoQ0opk@X
zL2?|a+(hZZrrQr7`xEH#9(PJrxhU(#s=+irh^R>`7&s2Fk7c6A-|T~w*!SnFeS2=q
z_M}Mf6)@wK_S|W96T*JwF4V8se9C=cXyR}Id;X=4lAE4cgto#_DQ$C3U^tC+g5I;{
z_HbXFhrxAXqS2<8(mo3cf9X}9NwHvi9Lv3x`PcxRAMN(NB1)ITq};D^xE%Y@Qt^D(
zFUF)JNZpl}4S#G^0fb`sl2VjSJUQ&9>xghf$_u-eQ-|Mq0ZgUeqRM*cVhA%^S(HTA
z&u@$Gs{}(R#gZMARhj6nfPEB;&*yiQ^crBMcPz7%-r&hmz$kJY<U}PyYkrJs+P9NG
zanw0y<?1w1qIv2k?32sm9p5z3;y1hX?FUIKWAjZs(q;uzjjK`Ij!jkFiAT7nwwPU^
zi&{=i5%#@Hg4aQ<v3*t5@DV9;WQ~`6q2LQym2XhU0o9{O{=praH@6}=UiaZ1-CqXJ
zLjq?xOB6f5+wF58G7Q=`D3IBwPNpn!KdO90Orw6`=70FtyHn4*cQo)!h4FSZl79>4
ztja!3akt%Z`8+>>_O?j3a`M687yGz99p1>-`L+4GwpuRkBi|D3lK7;z*1gIQ2BgWu
zNh4nNxyp3u@uaJv4&hXp_WN*m^q%X@hh#?EY<KNov}!R)<h=y5UPtJQWPrn3qT?e)
z6zl96DOVV5T=?YOq@q8yP!7Fa*M8L83)^{-WCiW?E5{2vx+A|Bj$3}XlGyR*hU<@E
zwhas9yL`JP(t~hGD&sG9jhAW?cS5gXVLXDxfbyjah7-5c_IzO*72;sFF*%t+l6=f|
z2FuXzFmLX`DDmsbBdTmZM&F|v>ZTtVa&FtSRz2)<zmd}5q~YXMZ|`LK`j3dz)_=&<
zOa!+?T_EyE<abKSH0~Crp-$~CO&!OgEp>h|3+_jduiI+|&NCP+wR0a%`ChMe)reGi
z9s^G3HZAkK=0EXROMA<3m$C9CwQZ6M_)IY?t0U>CG@NVpT%d735=v!oJ<-G<k5|=K
z_@(Wc10fnRrc0YE`Ns+@g@wP1KTq*?VSRS@Q>Lq5v>b10Q+Rm-E~oUzhwGm?sZUt9
ze$g`*8)VLLb4ee`4PM~oz1QVO&YS*K<Q<KdV|IqnJ}ze!JC!csBP*jn-f`En&6YK2
z8K&Q|DCrGd`z7=z08>T5`jzwDE#P~<H=Mfi`kS;MNvHNrd=~RoFIm|6U*{x-Q>J*I
z(+0ZEc?_eWMKnvJ?)q8i*$l!IFIP-8@pJ2nW6*57`PEM?4+`AeteejHWt`{m{_(wL
zjD}W8qK+t`3%vB06&(Cqd_pzPLz`^6`xa;4XX&a?{%akRZ`mlM(o0lqF0DFvACY{>
zy<&CpWaX-7NqCkm{Z8uB!XN$Z7;K(1flMf>Ki!k@QSo8<^LROoHVwS_69?0@b1iRg
z7)$;;4F`&=@3T(lAK|L{EO&a(baO~ZZ(PB|W?#YWN7>5N;wnAJ&s(fkF#oOGP$9IQ
zPd|d>#uMh~b-~^g#$O?$v3;@BvV(ATc|IW2RH_E^Tlajr$nTTr?e)Rql{`7G%xnx3
z`w{K*>U6i?$Xm=dmHamfzCY;k;c3@f+&J{RfS`*(Hx3#KQx>K+i!d57STlc5<jUI-
z_xq))_~K57KuzC5m)}F0?)Bs043n>g)T9i;(@JjLY`9P=@yLT^g6{K&?ZOo(m=+wy
zQ5CgI;0rzLj%eg8?Dlyj-ZBzm?WW$=8z$kH#1<;#d7)2_x>D&pCnNv+q-1%~c0P&(
zs_jnuWL<u3d%jD|RRJQgRHix-j2J?Xp7_tLM;t%srs6E9R@Hn!G+yB$Ry$F!gxFSu
zMTkWtzdffs$W-!W9!0e45bsI`5%KAUX=!9r6W=`TJ$)nqMh4P(3{*Yv=-5_~-sTj>
zz?m~CBM<W+0UBsXS0%U?gC9)?9$e3YaWSFS@dFLQH)&yWpU2h%zL(}4c^Lvf#B5gJ
zdL2)`)BvjkxuK0m(h;Z--6Si6e?3#-pdit{?9GyK>du4mdw@l}rh-M6>h_O&hemDv
zU6VhIarz#Czns%Jf^_%boy_1F7ze*sykt_+vmKab7&Kn5O3y1bttqhVdk3DpdPX9F
zb(%6ws~-7&!2tq4k=s2xhRC9v#%_g?s#%oD3L?%KX;IZ&-qq`xTfP6>4k&!Wwzp~4
zn0=)9kY_}#<xj{zhqqMn8`kW384z=N5KTw->Y~W$z?J)Rib31sgVtAnbL<yH)~;mU
zx$WE(GI$BKl#sFq>z>HCl&6>G%-M&|PuK3RQeWFJFR{J-d(VTeo2tJkS$1jeJiypk
z@`>6nI^~zOvAK|<iw@jC-6vmMn4{v&l@N5Uh5KA3wR_*#+0UEwK1<d<;#+308Hr&3
z>iZlzdCOKV*3&3(%@2%ETr#XQ;M{AON4b+_p?6=ZX^yfd`<}$yA1w@9ovyg#zuTE1
z(vb4YSNJz;`KK!{9(;N9F4e=(zPbMQsNpcXBC1oF%|_h5!Mz><fjzRAOJ#LhQ-Mw{
z^Ca~TIhFV`FC5FVj+@8dpuU}B9J_TGijD;??mlzTPh|)1l=1G!^J{;ZI5H>aeb2$4
zRyM|DFZ?fLVwMXrTyKk`$lW@@R#2vqxH|8Uh0al)*MB4&$~5t@I!?TSPj92|v`P*G
zqyCh&0N0Bajhjh*1syV+9wyy+!W3#%^(PuvtLIqVRO$~7^V21dykocb2#}y;>GG+(
z-FT%+v)W*>t=G8(d%^M_?PB`R;a{V$mU7+W#z%Lo>J<o;d#DVPWc>%@@AtQ9HJxnx
zAV#+b$kFQs`NIuaIYQ+>Z$VS-A&U{6I$5qiwxp`6%2IG#q;^Z(QTARiP=vSo%I=nh
z3wcnOe#nlvaDq)DKd+lu9XI?N45~t4DWmz1<qLCeDl(gG5}b^coK0?YZm_&~@O%uv
zPPZ;Xo%X$5Uuq)A)<32nrn$YNc46q)gB;lq!N&YzPkI8qnYxkwWI-a`o}CmuF7K3a
zpDUSe!HYedVuR5a-?Wj*r_Im5u+l0qZ5s3r7344H4BL<(pQQDq#s9De-|{g_ig(c~
z%BP>6dFxQ}pj@`~(%qI~(tc_Eu*ZOx><;yuqiQsdvGnLKjz2C|_q~T<6e_+2-i62=
zXB#?SN7N@i4rWue&XUU0?famo+dK7GR$t-ek<Fw9%<-$)r2-j4F2<O1mKVodeO`L0
zJIl61x4VfgX@P!j$U~(?Gb<G6DlAj7QB>I_Ip++13b>K|$>%#LHpjX|`KGlL6C(5j
zKRhZ@CjTZ)wb|07hBa2Hj*vr$-#VEOD+%BY2f7x2-?)Nh;6qmo4t}F}P|aFS`jCG~
z(455t`xRqnm~0f;3J*@aAspXs{4rMs%iJR-DR-Znb1KBgdzq&CN0^?yV9fu$qcu9{
z^X6k2Ih5nGCkBnX7*9B6?~e2sS2>nXXRe>`cCqyQps}0zbDNFAb{%It{GM&0mOYkk
z`dQb1i@2oZXwa``NSwA!=Q8iro+M=*$kVOcK4|<#u#8l!QcCMM&DQMc2pMwo#J3yL
z!X9iperzww@p9}$->WzCR`>Q;-~`jzFBxC&Q=1$8$?)v<2`XLn<W9@`V;p69q=q7G
z5P0SIFa!PHGup-XCSgqE(Ri1_c^96W_cEhTq>oV2GBZwpj^xVFJ&B%n>3*=bcGEfS
z*xM{NSKE`$dB$tt$f+!nr-UW$ZQC&4eTBkN@BZy;BFBYz$`_4~Jub_iue?_u88|Ln
z$Cfm-G+m_JMSXT_)Hr$L!oIxkmCG6KIU={q9LTrCiv%a{KMP#mtTL&5Scol;n(ypw
znVglWl3dBYq2Ds9JwCEqR4=hn_4pieJfC|(Ppb!O{<b;|@>LFNsQ1d(4fbhR1%k!K
zbobcK=x9=}@Db;_t=qM4|G)&3#Ei=e5+8<3RELtvNDWJ0ZymY5OGb73MtoY3YiT9_
z^P9$->1<rjDpg)jBk7U}mnH5lHL8m$zWg_=DxTFQ<19T)=t71&IVx0NICS~Q_4_7{
zEOh#vcBs(kJsz6el<`sj5TsJ!7F#DVB65`^p;`cu4LDXZ(<q%&^Si2{8P-;lJ07aY
z_dVe_gH6B1{y3ieC;4QVbk52ntt@+PKQYS}KTmFW|Gj{2G1)V@_w0k-dm5MOGf9Go
z*)q9Qgzd3R!NGSMy4RuJv-H=inodZz5_1b>v^MC8{(p>pcR1Gn|8LnlvS;=lC428J
zTUNI0tvh67%ianZ*&-vMZn9;RkVMFiauY&!=Xrm=zjIyZ`kix~&+ocE|9!-LzsK|S
zd_LAw7^Xi^?SJKZOKO|NPpFA-5LoWS8YJn9*kMUAjE%$s!C&{g*ID!XV#s<3jjL&o
zP|W}4`;L*fKUxN%xknM7hAI?w&!J+QXO0vS9Z~Uw7=bQ=oxQv>kg~bjnJM&S{N~nF
zbSd%N^0okAc`1SKMcN}}_Pju~)2udtf2{#^T^63mn4eCP`AR-^p(nE&P3QYA5cDH_
zv)xVfpW_XU|FR09GLw4$>4x!|)ZTG28YayJtv^+vTjNAE<=g7zJg54AXQp?x#6)xJ
zDu))JE9y=>`-q9_>GPNQem8d}N0&dx{IRvqaNv?!JG6b7ln-U{Hx{cs?X;dloyzXC
z>*1>%3{z%If*KVu^qt1QCa9|D{lQkt=qMi1iQYA_<#`egJmYn#*WxGW3TGcaKPQMB
z&lR5!$do$N+uYJQ$j~Wsyr1R4jyeR{2rtjGy{nfuP2vaz+Y}tdS;+Ogige1AGG3zY
z)_;$m+)!vhRjf5?iDGGw{QZm3Ay*VF(1SbQ%hUtkheqW}qdc=4pfiyQEo`jFo9J#J
z(M%z(8Fo+qP-hBKY5DPHI&%IFUtWQec=BI37poL6TUe_8j34w0ETf-(^#w#XKMY2j
zEbscHTa`E}(MfCMK5dwlx0Ph=d*69+AoS#Y>|UchDP++!=**Xpy9p6V40;89XIuQn
z%xC+m5OMbjm(DNZw?SENT9$K&WZ012$SpCGcrpD{5>S9}T|^YwhJQ-M$@NjLC(XRg
zEUUaqN^X)%&TNjE^L@228-+9B4^MhXz6}=&>*LnIUCD%#!{dq3VxEhf`5%IIrI)?S
zO;2qg=ommm(DyhM+yPbik)~Ur^!p)JE>!T|5SRDsHL6!5=7>y%X(#dA6|-BTK@w<7
z>!CrY4mMl2*38JS@WlvR7v0>ZQ)tZ9@&+0A$QL!4)Z!N)SCZCu7l!s2NvBz|^m(9t
znuIQ`U!}F_c?n!)O*Md-y3(IYj*ri*+e+=yjRNkk;f+~}yp^F>LIA?eV57<Z%cJg1
z;EYr5P>A~FLj^qap5_PXgjn<kW40hcs2=uWrCQU718pK!?U0@aH83YsAg>f{t@(Zv
zYh)V+D1%JPNVaA2*==X@@&q(2Nb3j--|dIF>=mQ^MMD$g?XTtBtq;B01I6dMf)0+<
zbyn0Q)9H}mj_;tmJx(6c#0@jbSp;f2;-c43BIo%hy{uMQhYlC*bC92<yQi0>+iK@_
zz4pg>kc)>OSkhd0PldkZr0e0qs$z%7!=ALyIWEzlQ)2F6kLu5icPMe5D01~l@k^V(
zyxAyGV0g{CN+&^e<+;Wuz+~SOh&gp|dUB8lMiXw=!0~iNcAqpwyThG^ABjFRV^Jv?
z$<dP+Rd!!hbRSjNxrX?za1*g&cix%N04_n_p^d~Ux;BG-t-I*~sD!i-EAcxr0e-$J
zq$OV^%@DY?abZV#6fc`YAoE2Zb9nCLa4YdSyOQ>wDO2I4frbxID?YVg(Xpolf8jPm
zRPvq{KwF^XXA|vUm2mY_m30O|aMPLNR~6#9iJm_9F#gas&_Mw>`z%9!w2A(3DBflD
z&o>Ay*aE74fNbamyax)?kwUkm9S2EID2FhWK+i>DmRi<ka$4)_41l-Bmfp%>)lCZS
z*Q!R^n<a^W{8sSZ-<;CDAkLYG=-LkfPU4kK@>44?{<~a1oixHXDNFIG<E&koYp8!H
zI@FhpYWYKal1+nW+@vk*{8-F0uU)q=2PFsgI>?lYv{|{OjmVsSPW=jVN`}@XZUEo<
zvy@5K3g8zDYL|REk3{S~%a!I`Q@|HY<!tCoXKd)B(s`NK;3zNOu^`u?=nov>opWve
zIDwh(1J~)b97A<cMh^tUZL5=k>u$;oSO;<a%6t3S$>!8veBjwV^*W&en*>HArM$@1
z`*F#I=E!uv=A_lLhuNpY?B3W{MNiKw3HMw*B<kXhNF?%?u9%Li2vckMfZ_+Z%{_We
z&;BnCFAzuqGsfFetW8L0MCUN&VwCkSb=xeL6Z@L@DV>s%v`?!~Z84{oNzZVl`%8{0
z7)JXT$2=FP3df!k*frrD*?-kQCI<9nRBg$7RMbgBsm>#+7Wu03bPh#B2?Xl#G$)<v
zx4zb>-#%i8_HrtOe)o}aJyAwI)<i07d3U*NB1Iq7OQgXLbbWGf_iOva_;Wh*`*PD%
zve7>=F->8t=}ODWQi&SFqseM%6K1*mCz+Y;uJRLt!!!Cb63wo?>-)~PIF!A>dekaT
z*n=^|T|YOZh3!VY7~L>7V^L~k8ER7+>pz??woN8Wk6(ShJFt3oxH||`9}EiFHp$mG
z3o<>wo<G`Kg@MadT<_CN+y{)DV;6tIezMC*wq=WI!CUn&SWA__&(w^Y1qayjb*DmZ
zCKF3r5?AcXr%_W?6;=-tbh!hBeqf{*^Rxd^O=XpD?8MNZ&)DmxCNq7xEnmy=dB|is
z5z_#*vi{0CS#d^omUeTN1kXO}hCoFaV?|{L%R?G{1I%QvYgX!+(`y9x?Tbbt-u2p|
z4Y9D8r=~lyk2>072cz07NA^VDT;TO4kvIxoPnWgd00zRmu6)MKHzfJPxJ-oo-sKT*
z`9E|1!h*4M=n#hMSNW0nRN%jYb2pcx<2Ijs1qX6z8(OB=lhLUizE%UU<UJJK)-P2f
zcEns0sTjU<{09go_1IyI^rk~RsRS#Hrv>!-DOs5P7UNTMlIEn&Rn{FRp?~Hpr;c5}
zHuGqTt_2W{vU#wQylT9CU`Q^H#gSaO#-(o)Yo*z5lnwQV$&vNiMV#X=0Fsw1;={a#
zK1`Y}op{eMHdL5Q7pcFyqJr2gf5H$r-5|fvAF)TLf?{d16gsbDW&^(Rin%tS1{QJ%
zSjQ9iwv$wj@f>ZmTSE>>WUX@7!$?i&@$1hasIB(Ly^L$dk@*UbDM`tOm&ZcSZ!Tsq
z{@K#Q05KKr&>ZPZSp|SClX5DmI2tU-$?5B_wRYSdYFKA*r=OPP+3N#Q-olkx<$rqi
z0>E{jyW4hvow@~EcD>;n)>Pkm`7OPl;@Qzwy)3*EsM*J_jg?nkShl7VJaKTPIt_H`
zqKmF5Kv}HaW*7K67JJ@&_6F_6qZhyB<X+JIme&IK+KhuanFK3Cua?`jW@Klj49r$V
zY)DB_Et&TFL!}Afg{X>8AmRNg*?sR4u3y_}s;w&NU)!0dia>_P)s|z+xIz{uuW4=k
z+z*hf!?dlr&~cS7km*dXYT@!D{^cp$0sLp4Y)h~HLh>ENB%#?yv<a=O5vC1D5V&H!
zA@0s<nAKl$dV<>}E4{mLu>hk3*n9<k$?u?VdaHa=0yFw%_+CL1%F?#F`kZ<M-Z6t4
z5ft6MWNq>2By5<VmpWe7gU5mWs24RJD?>V|eN&!QN$br{f+#NRfwBig4qh-1upI83
ze!qb!hx@TqV0jaN`4jE{ro983UF%<<d4KfouY!;*uJ!9z`77z={3P?YE7Yn`ec`7d
z9ryxn!%pBZ&=TB<g4r~EU|Do>jb~p^Io<EdD@vIq=-s4kyFAZfn8T)W_ss=$+<%ey
zMD4_K@6I;^#$$IQy5q}}A0MXTJyU$*Ym=@N2!#6;GylzlXGgIE_jsG=o#Vc2!n0AO
zcS2MEz(+VxNN*v>ro<u-Q-YFfwOO!|iq<6_2Q3b`iyNk9Dj9$6iBm{1V`D4XrwdvY
zW1gGad{KkU(x6EoGhCCRoDp~|6XXZ|Jupp+dmVn5xCOwL13CooG-RdU?z`=}7+sK)
z>5ngN)JKG6z`=2cW(s2}|5qT*nU2hR0etw(-@eAXg3^S3IO&w&O1k~K=J2!Lh)ogr
z*1<?8NRfsJjAKBDVLxw1R#ut73+Kg4UlXVR)SLka8`{eX`G1Qshpc$FMmgF@b61|l
z)*6#J0CP;`sLS0|v}m#;5J=;_P!ga<wIAW@#Ae=b-uv)&mXqQiN}Ol!KuQo8rTyZm
zW9y}-DR+M@bcRFkLoe#K-xMJ|W(ve?5a30y4(nRGnO{~{OdA9B+C*%vZ6MtHLBrZz
z%w6^)@^&q?fd}@F_}4I3#?+dOPvb6o^Nbj7^AV}!gR)>3GuNt82-(pCZrUKA4WJoZ
zgE@2&7c8o_pr!;g#{woJ(D!}*RaVe3S;BeHVR6d;JOUvH6D%n9Rf6vW<O$!>3qBf1
zqc{1v5z}y0c>W_E<aToj!gT}R1J-@uU{?Txx%(Y&fN6Ol4D=|-@L9-CyCBYkTnizQ
z4^M8cgN1M7*4Zq`U%ZmIbBbTN{)W$Wj3&-tKMin|z@i~Rrsr0XRZxIVHw3$7Z^eyr
zv!0oF^!_v~xU(ZP>0Dh5@j@!J_QYg>3dmODl-5>|C!xgfaMcj+1d>pr6h5XzAdJZw
z1Cmze-=$TM_rNCtMvyLUoO+N)74*);>ump&OhVnF{O<}d;Q9!4Av06tUlm|WAH)|Z
z^5D6#|GyMd|6Q`B4ERe-1yG3t|Na30)5g<<pTGI99{{ZyRQd!jbdvoJ0bCf#g5<&f
zQc~GDwkk@1vdaskUKI~t+6S&Ai$_<0qUhf>V`CsEEOCX~@b8+js#KYk&42&nutuO{
ztgrLme;+$LJD%>NN00vfCt)FtjZ4o8?Y}DE^dW=0#1$^*|KNANxMS(^_07HK21M4~
zgWD2uFUg+FefFoBdCDvN1Z7H9j(4+Zmb{D?2_}P=ZIb<%hS~GolQc710+E!xAW9p<
zy_yN!G>1sZZ}c?*)JFh^c4mt*GFd|<k_Ii&Q?F@~mY{JGeVR7p*h-+CaGeb)tJu&o
z`!@8!js$5Vul5ro8PFJS6;X*c+;wb?Yv7B8CW%2NkaQ+lj`Xi7*lkK4DV^mT5EXU_
zBEgi;+hkeTMmNKFMdLF(&~)+*BVMd2gWHR?S)T)x+DE*y2fqps)K}t_S~-e~CZkel
zMLct}ve+-XM#b>E-`ag>T%FD$g<L{^2a*1V0ka(s#G9mV+#n;YvF>;?rUKyI^#qmy
zyqtMZ*^vr4i<iSx244w3(y3LL6|ZUig&N`khA!gy4Q7FVz81J=w%;@5EWQ^+HHaK0
zjNELJzDw%qd_`lA-@X*Pp9EQ@@QU9a{;;jv7y<ZaZ#5TJH9n9krL@0-++0Y}xOC~^
zB~2AY<8b9>mU(v0ZVIaXpU>+FbRiJr_QeP8SQ_OaFADlM#DaYzt`&~LX7$CiWUPwG
zl}c&DcX&izKZmjr`R<{Hl_=q`n-mK;UFMz;X#1#{MT)6D4lRS5`dG1<(K_iNyU|09
zgq{1AQ0XRr@BY^(0=W*hXubfqTN>H$C)zsF2l3&VCCraBGmtQrQW6HQW#5kG%)-hT
zJrdVrZnET*s_8bq!SR5|khV5`{zmK__QAj!JZXNsNaO8<E5@ww*UXe0Tazx&kblvo
z%EE@*PTGX3*n;<aAI`@6Ff{-v#9JZ)3pLchV(<;%80gwVU=)|Y=-9Hy*h@oq7>rWQ
zFiplX$H2}Cpgz%AAdFyqgAkKPS;4)k*9H(1N-_=P*RjfzC49XwR+bG_3up|OTM)+o
z$;|28pU?*J7dOoP5E7!5D|jA>Z4&2qXbOSvd6TV-jPCJ__kK)pFrfxX9E_@2wZzs;
z5t;9x>LS7B1f2;a)#O9CBm`+|Sfwz@{uFO`SYM(D8{g!-<|Ix88ULVJ109{od|@eO
z^8yH7hnLO$a}Au%LU<N$0)D{fM(Yh1TymltUcwSLi$^3$k{!q2^Fa-L0RE@_iX@S&
zEjVYprf=2kfSJ?ROK`EypPYtzoya?xdohObDg1fJ&x$WuU0p3JV-GS@X|)1F5n5?V
zM04F|u?xI+u&dDlj1-e4-$B17sU>evOL_(27}v<-tTI$Fkvk8^2w)hzvFQ2kO=8>~
zG5^a#*CFK+M25?;kX-#j+<o=oTACENC!C=vAXQNx_wHvFUCfOmqJ_=GTd8s<cnfvn
z?(D@LpvIFMKqz6Lx(GX@f>BsRic7FQLD$yGDlk4Gkvz~zofVmW0Bknw+5QX0b0@l*
z_ggp~pX6aDBYMpm8rk?{Ia9|n03UFgBD8nfSc5cw*w$7{9r4KqOgy_l7*25QZ_>A2
zQj-G*B*=T<_}vE)&*xcjha(8<LWjD-nGTAy71Mop`ZmyM;ewtJQxUx#J8(m{;Bx%d
zK5FLE^sVW5Ch5y7bHYhgQsNQ5zO=Y%BEkC`+_VN=M(V&P55=Q$E_-|7taXTD&rN`V
zibo#I5BI7x&yUjQBWb4783!taQ;2Xlxn^X+M6~w>$ip9BMDWN0qrpzUls`RYDQT5f
z2jlZoep;bYn~%&Yun9?>?l*|{f|cX29i+*yP@v>vi$q_ibY+o({I0e(Jl18wTZ^w5
zOG?t~gcp-(l<eTvJy0jmUjkQU`5APOAS@)CsVicYBbAkI!psNxVSZzEJTs~*>kW$Y
z8ro$KZS#*;C*?#v{UE=(6|AyXCw_l}`95qC9)iEUGWEz&Ed;t=^m^})n;#envbGk_
z4+v=-FTqqgDuKQx&!X`DxhCTZDpm!|w-}z%?WmcQ*8LCz0o`mqMvJOH+wh8KtY!_V
zG^^cMzVy}WVwA)X#Lr`#uXP6z4#G3g>1MrpPQ)4y(+yfa71iwulDjcjX~b}j!l4}i
z`_|@{`XaK(hNmDFq@8_)12hbdG>c@LEzLR=N4!5kSl0ywg9qCZ$@@}El~tZqss@dC
zWJdAWo;F~Q&-qI9veS??vq>lEs$MDiYRud80Pb>G!>;YEzZ&rd>EWAO+awa`B|m;w
z&)adxdY~%YDA~aiZXx$vT*PBCi}<#`ZHt${E4(p>HPEk0PwVR&+1A8HyF;~>+)lMC
zV4Ht+_-5jFs(40KpO#0{li(gZ;G<Q+10u)I+vp8St$~Z3{qehc1N24y2DvELtqT{^
z04C9SBCIN3s;IIH>V{^J9vVmXA=*P%^C&@a-Up9S+^z}s%AEbfhNt<=#?-j^aM77y
zU6mFGlS(#!X-V$DwH|-pNQr;|E&=XcffGxyti_bL?IosZ0|38z*)*c2!PStt?_L%Q
z?w;gp@`caq?;uSVs9DkNBQd?$*u_aoI5()av~$JorJ&><9P-Dd6Kt;Ej28i9>~viH
z+6?^yal9ai(<8zJqqvJf1Pq3U##;(sNoUR50~^Cwqcoy+W&nKv8{{T~gc9D~&U}4s
z)DAqL9f``fA#Hm-l2CA`d=cb}*03$jTIhrZOwiCGJDq|I4Y{1aH#&c<67O?A{_<3c
zido_j)wuwDjg>s}b~+jQnT>QmM=2IRf=BmxEj|R^9KzO>U|Dq?hzxx7#X58A@7cP1
zLA1*L9B+CzOl?3Y^sMbO7Gf-{4OEP#&x3pu0D=1lH)&NagRK~}352fIxBSrZ(f%R-
zj&K>5bs*)DTzIoTW?oi;D{8|Q3NJkFJ~v+!+ZI^9XC4JQ-BSwp2Mas(ZSW~Z1_P`X
z{AXJhf_5SAY3~=T*0@%qKgf(07~XS-IP<><c&Xs;uA4qGivGEbwfk!$Yjm{C&633f
z{e|41jib+}lMj=TJ&u4?ir~$!ED8&T^XfO4Fn>c0Vlb>VyK$UbPy!ND1B=qMYyGd@
zUYxjx##Q>b8UcM`Zw6Z|QMupVH$8@#7OJX;Raq1~Ex<3{24BqNL(TgeV~Uk5qBOIQ
zWPwzQlHAZK17my=S&ct=+kIacWk94eEBeJM6S^1<yjnogJArH{a}0AASOuA3C**v=
zoLnFi)HL}-)SXJo7Ra0Fdl1tz1E#KGl*P-t#In&RFm}y=m5c(;Q>q_3fO3Oi%@riW
z5KpaSXtZ9QYYn+;9U&3rU=EG`3+mh3eN`FrU<O`0i#ImJc%gdz8+f@2avp?%LV>4j
z4`%P`7KkOBp>%*xiQ%ArLoE>Dh$|-g;Lzi|y}AU#LH1Vxp&jX5%>;GZ`A+YZwFS`V
zP8i&XhPmuHxjhBNMBGrscsE+?@64@Vd?^NWsQOK(aH@GE(cFl<7?2z?_{{H*xCa>9
zrxv%*Zs2D%COo`U&<RvDoMTJBAeZ%QYVJ=QQ*gYyNwuMBEgDCjlN9?5Sxm3QSUckj
z3fw!~6rVm>n1J16@E=<9_}J62vfD@g$Ja@~RZTfFeym@Qr(;IKU?C_^r2W_xma<oj
z&fjEYt^z-;7qGMOA5M00#`|FC*x8dJckPmBrBN=RS2A*D^^9I!hVxiq47kk~Z`rW1
zjCtpPhz1EJ8^+T#y(Q^i?aE8=<R@yuGqE|NmSyx7x@BMq&nC2mLQ#$H1ltxPLBGc+
zt1CHs+d8QHBf6a7|MZv(|9gIa&KH+{!y9WK<S!q@-l3Bb!e-gYBRi}%EAqXT#irk`
z<yfAXj?95X!p~cLA;cfdwbKa6Ut-HXzm~BE#`|gP;4ovEp<ptp@E8|>xgIv~VwJ0F
zI%)dOn6&vU0f$fsgDPP0&kEk>C^e=-2CnA2w;-ADZd=0HZ_aa!6m5(s_sKwOn^CG6
zmcnKi0$^c=E7VUlHhhSLUdI)roYyt?rKb8A?aj-Ya_=B$vte~-oPqajOEU3`Q%H2O
z0aeuFmXJB7PrWoZJiU@ItFOZZI}CM7k>p)L<NaGbsjqBqMEN+N-<OOU(8q7WE#ZW;
z)JVF9@pMjj=OIZo;5;yj+W}O2fmBbEm_a_vR8)S=gH)GP8*Nj)_~}@NgC{&HFyQlR
z4vXcr1RjTV#{HpAtkHKyJ2TEju!Z2H{r4z2V+a^efV;ffa?aC)gq)->_rRnrxKEj$
zw2c?gcuzz3B0dZH$wSMg{4FSy+7#-@#0?cS(s=`}Fn6qZ=X}R!Lta183$d+-asEO$
zO8)bPU66C0)cyDYx1#l<^vu@%Ew}+G_E%8xa@9ANNTAz!Sp;EJ+8N3=1RKqdGvq-#
zr6a+Dt03}es1fwX+^)gGVoe|kF7nKH#EHB?OB<JSY)d1JY%pph8;1Q9>x3EeW(6O$
z8pxWgpqUx>yQ=doS9l2P$)<MW3@DzPlFLs8W<DH(jQ(tjkj4Ynv8Z`{2PI#xU;1EH
zDQfHXdx<00QL%$u6sM@BhQ{^8s&_QtCkogAFrr910j;I0hG}3zl-M3$9Lr9+?UI9Z
zBko(+sN64gP4W8Z2lBQ?#u)uO1z0O^KSny?E_E)&(hGK;`4K?#ARTh#^QhKDfEoGH
zX=GqX6+uq6Rt0TQV!+$=!Ux>z?8a)Or-nFPY4Z%HUpVTrX#t)9f<$jfgZ}n@B^Q#<
zxQcm=p}!Lf&KCGC=<gsA*?UkvPGz#^w_Sx1tN3%|Wr`kJg|pGoApC(w?>Aar>nwM^
z|0!!Oc(cyqnuL!6uMDi=JcATNne=(y(|bAd@D9ageM$_;vB&Xf-y7yLMB6e?A|3z0
zclb<R37SN*7=c#1+<CO#b+#%9g@!skU@_E?_s}+aU1O^5ty_oY^^pzdz?Tl<4_!k`
z{Njb86{IDM4s%h~%`Rl$wB)}spFqydIj}1a1bL*OI+Y)&Mm;WpA!ZaVB|7)=3YeO~
zjUa2^hxas<nI^J5QU-hCScAB&EzSDda<j^ZNNmEd*(ac-+kOcHRG=)#jq5!1n=Ey2
zbFe3(a^hCFZB35RN%WRYmb{lpg!GFQAiF^7{&rH?+n+VhNiSc30!K<=I9*6i8=>9P
z#ZkuaVd=Lq;`C0NL_{N7{o=P26rPC~v*QqZHqLx!xV-FdkXPFwK|<{Dy!`gx^Ize=
zf5924g5Vp03upEu>v<~+JQ|}oO6J4;GEu*RzzksZ4EUXlZLKEH+<ElBnBjb<e|QRx
ziX(v;T{i*2Wq=PSm*S4<e(@!P3ki-A5T8D~4swCAtaU5l-i^uX%qZP+4kVm9Kf|hx
zqwwqj-VI3i*BswPa|!zcf{dZcq>~SDp5W~^;B80alNY>VY$2bBl8Mr=gEgdqZs@DG
z{+)78LR_&*aJ1;^=`k4R=Ky9xub34+r<m!0LJrrdh*Z0F9soXvRM{yw4Z^joa$T##
z@==^=MuLRYFrEE=y<V7^JCHUn%raZVy6@yS2*VZLy71QzpF^h%-S-d`oXF1_g&Fe&
z>rgmGisaF7vwAWeT8CfsrAhh@HCI;(Bw5x#5el_c2N3bovBs5YiuXU)wdld3Q_LrK
zv={}bniWhf@St^f3LC-JWHk@SWBCPr(KHXj7n=1E%aJUQSzC@WPaJ~STOLL`@cn(t
zo}X0Lv<VnjjkmSucC8cAKxDG}FGBqF^uYV-he0PsUXQTyGY6j+%ylkU$YHZ(<2wis
zsaX5wRO&!8prfPH=h_ZuonKfx)*;QV>INLG8@5K_LtfiSa~krK%qM0LoB$_JC_JyQ
zGwBTsspo^uiZVOciWq8Gio@}r$+q?x(=p{&GqeTAwH*lkf}K6Ty!Ll?kS=_fh2FUH
zpQ^yu=Ia#+Rbk;opCqqqdl}AHQ{Wfipl|vESYerpb=9*1Ta=z90?q^7kcxKaM_y?r
zA5l&8-7F3cXmMZVhg_j+3CCc011G3@<Z11Vo1KI+TY66te!eX99ihMbZFn1Sd}*Xa
zgl~ZLW$9<T_v9up#V9A})uBh6pr?HC<|nUtu`Cad=Jx`;2A&MH@L|4eEd<-EM#Adf
z03DR`A<uJasD3ZiKYq!Hgr@`@#Mk5^B61k{VK@R(Q_=}LK$AB2&9ilWKx|4~*Ml|@
zia$L$XMaCtL+<b5*RO}r)Q6$<u45@Y(uaI%SdMrk=u%q2vRX$LMHAJ$2aTnCE(If?
zyd*sI=nQaZD`Bi%ddaWCgd~EUboIG6(sca84xYxlFf%!dV~t-(afm_4(CjW2UTuIU
zmu*4*eV>&%tdchpF)&&|fg}Gb=Ci1<H8c$#E^yP<!BQH~6X<9G3~}r6?V<(Pi@F0i
ziX;8g^KRU0K84`8s`}A@w-2n&NXtUrtS&dKJ7uHof$ToX&)}~-o5FCm(s-*OY~L4;
zma2L?VH=a)TW(eBJj%UUIysKTeW#|8<r+7>wTM8D#+QElq|)C6q$(?$A!WD{#0QD(
zPykN%MucXYU87h4gy;%8f<GmHin=*`L;PU1KqSf9Q|~d^31AK|0MN5Cg}%2IL+_l5
z)tTF~q~-aW5m_kVi;>^YbmI*?qw(?UZ+?1UoQ1&a(I!%9GQhW9Mtbv)rMIL*o!_im
zxsPLO`@2WvU4EZE{pSHS+P!HY#3D=TlM17d#Pp<16B6p|whh>#nL+gfu{<B3iYUra
z<49-NQ*rBeSxbZ*?Vx)q=#SYGX);1{FWv0wfz4j^Q=RM!<>DhJ?vF`jvoGEN(glhK
zp9?TcD5<4Fz?_D{vH}Kvbzwm=^W;~HFE8Qd11tnj4b$HQC%-FbcMJ?K<=<fw6xe|c
z0Plf@Hj(9cMH!(?I#pt1AJxcMui)J$5+E08i?>JMRgljtL!C?87<}M1cNZc@-X+mS
zrSO<FEP|zhrd%(fP34W?EnCzeUt24i^zuT5{;}{-LKfxm=^$Hb17r7<;sn%`wgZN9
z{)sl?cAdrNwdE9?bnHje$>H$!_Be2vA<z>+7VPX)FDys*iFte9z_0;sJE!xJM8P+B
zpS6E=2mEUPed{MVm*Z7-R|Z!>(a<S}IcRA!f~ojSlfthBZ<K(S(YKaAjb{SAjPy*^
zF_ZhW_LavkFa|9r3$10BzV=@S+rT*-8|nAN{UJ*J@#BruD>F|86_*+v(tO8Iqmy_<
ziq<T5W(@`n8D4qK(_Pzq`S34rGR4+xEk2q?Im_HH7BiTMpG4LJeC2>)Pe`K*1Ka@}
z?ZddH*(Xh%j;(pNUZfAkj@C1tvB@ArW(53+uLUk%9{xcNX)J3tA6CR&C!&>}q=3?=
zsA0a&QoQrPhl(Tgv&n7v|69-zWPcPI@w+TMw2DTI^7lu*Llw3`Oqcs5Qx(w(R>O@w
zP+caX1aH46SO}IipF%mJgOmWIdLB}vYn=`0IYMW<EXea8WE4!&IAjqwMKP4q;(V0#
znKyj{j&|&VKFKa?b4TNfi#Um<EE9O)O{AG0DbdFZL^n>^$@E4Dvmra;Fl8fmrpMv=
z9pV$FD|Qc66e2$Zht#tM@OGLQO?77JX<u@@@s~C0vn3s3=7UYqEBo6fgf9Eg1DqJa
zH4tHKvh28-4(?mDC#(gG1D{~(8&T)D^!FqgC8lxZp9{^@L#%kYH~ou`a^}*YavO_A
z)Y6Ehgg$`ie|(D7NtvYcP&wk^PU(!{!-VOO;C6BPFiZ3`K(K7yc98(1jR=~v*!=Ja
zPe6HrI#zzI)c2$8p8_egU*WKF(CfhNCYV@ajz$ELI*#|j02?xO@)Wq}bh7(FnL~qK
zn9dSLY}c`Z@WipOiPWuoiFISyt}Mke6UPd9FDX2M42IqaCdELMOVa~z0Rah)gv<X0
z1|>*kH|O1eA*lIUWNbwPIAX)xor;``LJ<&r=J99qOX?n|@vQtmh*DembOStd&ePKY
zyCWb58$INHJkgm1ypwDO4u#wpY*hrfHCz2InjKpQL(QLRsm(aWM4(CVy2vm33lK>d
zgWf>-<{lsY;T_s;=#(Y$Yb$fIvie&11sIq%ZWXY6%MtdeP$Rvnh!{Ni<9lRr^>8G4
z$f{l<jy@8Dc2VP@V*khJ<o9^uA~D0`P}rUJ9%76u)@R)S&8*i<ld4cMgYdQ(8@4!>
zD_(Ye5@ss9kkjjKVEvw*2&BUrnz%P<+K&I{1pz_wOtlf0d6!|aTwU$MQhvj-_>UHU
z4Mn74(G{ZE8$HIsx>f!M&^#0r6tshrSMuYX`}6&cFxme$|K)D&flliS`vQP`*XoD-
zR*)L*y>W&v;{315jKH<|!6Nz2b0=!LG^GsMpnIZ*zq;`hg*x`H&h9B*K0x(w>{x+r
zF5{l7qp2YnxDK=md!EoKYGCmU@)5kv;upCCoI7}Ho6OSQvMHg%ltOl=i}qZVhr(7E
zyzmI3N75rhwt|2yJ4vA+T>)ZO1g5jlxCm_YB{Bea#D%=fbQ*x=j|kIypu|<lvC$C^
z8d)8$mbCgPr^V_Y4@&?ekj17>(jh_&&6PBC-$~YPm~M*JyM9-${<>`wdJkp_bf=_e
zE%uv$Bnt=_S%wX==yxgn9+D8V_+SaGRosU6HuGZxwsKv#Bpj9I^LnOLCO0lXieTct
z0I>*-_lD!l&ZpirAEA@?HK=%i4Is$Q%*a?>09tTQNXq&G?WKOxfj%+|sCbRk<>Cfj
ztx8jW>v>YFKl2)JH{Ug_%Y%{jj=~<DpcSh#dQ11zciQO><k(5P%-dSI3Mk5MdF@7D
zs9&tUJO_;@yc2lY%n>rjm&+o(u9iSZgpp)$Q~sIJTQ!owuqCCp9aq=U)x;`=Vj_Ef
zkLL$8dz;ck{B0#X#wjX@OujIe%d~x+Xo0A;5GDjxTrSzm_Ej-OEP!skq~#2z(@>sk
z<-(=&IJe*}x1HXl8pVnkzLhI@C#1#vU{BNf$qmp_mx-Xc2!m&R;C!s`V>*TfGrJvb
zpLtu>P7&x<5S~lu%waFfC&-09R=Zu(lpmtWxxfc4?mO>LlSE5i@D)*?!&J-7awE;|
z2wG!9^?&m3+`-ZdFEd!QCoNkTlo-8|ih2dJ+?#D~-G`TmS266lEPw~G;OR4#Ypw_r
zT|4UnkjmzQ5iqpBUegT`RGF0`0B~lfsxR)BlK~u3E~l%9qkRsr<TDK@b6;TSfT%X$
ziXLr2*HZIY249R_28bOceytRs+-;W4VepYCXrB~BYT^%Ol8IYwLYJ3(<bOs46)~bg
zg0;0W^yo9l$(upJO%$W97X~!e>MqIm-=KLgjChVm4b8%{+eWyEB&t8i(tj@eCoYpA
zz**3~zM(^?62L#;gdT~D;zWy=I`p!I-yjGn&0Bs2OEVd6!5mUupM#*9NuI5?c*Pr#
z$oJc_{s>qrir=-M)r7nPNveU@e*v+#4K>7lS^js-Ujn^TIm6<UorUGKysq5C%`YDX
zk!$W+Zb1)edWjY3l-3Au(n|U{0+bFN3M`X#5XD>tAPg<@=Fw3Ly%_Q)P9WpAjUEOD
z@vw*w$))pHq3n|>_ki^HHJ4d{*e4!qAsk-zk>S${YpCb1f5`s>Fg3;RIamc6P0vt!
z{#<-cz<EV%HOi=f{4IPml|VXiuL3&$b#{F{9~jgtbyRyFkly$q*^v4&d#E`*2Ga?M
z&MUaVSh0-WOFH^hs71w5`M)6{3EXAi<w4Ixy}Au`oKF_#q31_{Q=9Bom1b?mBPr-D
zB`Db+ssC)8hrz35*WSbb2*MgZ;)I{O>Iipt9`P6RIAQL_U3mlUT>X0m@-V+quzuRr
z%C+*tpZx-bA3XP{OdZG-8C-%RKoKxp!Di+j<7blqrHv57#^SEruPPOT=&DtPbzE2Q
z&beB|oR&OXU`>Ur=pe}F_;yaC`p`Ik)76`uc@FqQd%po=G^Ha5)2ymm0O4xU!O$9*
zYZY=j&@I8QwiS|NVMzvqxQe^<H+G@t8q<U7qFxXPUvuLMKtPq8ZnJVjSd={o$l-pS
zBjiN(@hAdLhZ6s0;Mm}V`u$-1)0aE<pNh!&C40n?=yaBIjohz+nsW}Q{CG#`6gzGi
z6D{X~YxvJDlH}UE-A?BJyztHAUQNLl9BdgK99mgB=GTbc8E#D5gdR}F1l}xKQz*{v
zd`l4rG3t1A#t)8`;#mGbdqQ<Ul<KikjCNZEI_AoF^@!dHTFWko_zn7&_uwYSiQ(vx
zPLKzy`vsd#Ra#0P<B8EX{){WS#Y<VJ9M?2Zzck+#GKPLZxhiC7=LW9DCFhhl9#}J9
zx7vC)VIpaojE<UW^<|1N8ne{A4JXZSi0BxOTgXPCPbKTo7vtD2Hjxy;9YBncay31G
zQ|Y#qFSg2x<PQNXl{tPTT5I<HuMqTtPk$aqz;19PmHr)CfEAB2f_T?$hVVhgliIbf
zJ{fKq`1sRc3cAH2>O0SF5w<zfbcFQ=>w-#AZ$16?2rC}$a1!c}iDVy-NE%&{uTOXD
z9oOENgkI*PHio*~YRHQgBOFv7V&3199xK>sOK55%RtNxN5AMN8NUmDZQ${?0kcM{~
zHUmLL$;5Amf)3#m#a3^}_y~1jZSf31XnlgnqQGVRmUqeY>#b@&yXLKPeu?s`h!xB8
zDWA5F1kZmaj6b|78hITr!(@vKmY1z^+#=To`5?e;Vi61Q8&rm!Zd}8-M8*v^-e`jK
zc|Uo`%T7Ct5Vj*=Q96cq3lIwa%X(D%S*=+TQF)Hf9L0~X`n3b{GDow{;^O<Gjcx}4
zXF@;<I>MHaH0nGDE7yuldj`4}B>T5dvpgzi5M7(LsQtuIN%T#tj9S`KBSfS;^*^kI
zMikE6ojI?`)Is-x*pC)(hP}t*?)HS7@!YD0rpbe?b|wsf<})7u=v6*)U^>7tS{CBU
zFrP$~E14XB{bxLP-(^EV{}7JLIhB!mvIkiogYRE+U?<P%#vs`(CnAkUeHU9*CSM*K
zdunD5K>>ZdvheJSL=RJI<q??<R6bIKjV83<8<FJQzC(Py6OQv}A~6joC)TP3Kl43O
z$o5RfDB@Wdc^TEvUp+}-RPcDvOKj4TPej_yI_HXMrVcDM)a*On<PQT`*h1=Ptd&N(
zcj!@F%-6+nxgnLI?R>8{_>zL3k689;Ww-<*8FZKkqW~s{MMP#TY}o(TLy}IWyNrdA
zNPPA*i*Kd_h&oZaJ5~BDeGxJqU{DR}Fme0?-C5c^M021(OUk3pb0fC~Mdg`X->s*K
zZ&wXB!4I<-uGEEyqj)P<RE%Ho!d|N1?W^UEbMQzWLbyUnjVdPe;7S~LKRA_-#`?U|
z^{BL?T$(H^p5u&c19_6W1w5(7D<~t{qUrNZULE`wY&-<MJ<iGH$8~YP01@OfshNZW
z=lriu+54v&CI~_vke{XRNksosSE3ic$2nl^)xXEih*iRB2Y8~4b?-#t_4B`0Gh3}5
zaeNbh%VW~1dALTO`6wGzF+4&Is8yILXqP-BvxcrwWv^+o@WFQaFPYWh?8NOYz4Up<
zvapfL<JwBv3yRKG7ME<Ur2T&ky+O-dd>>hnpDi$~V*G;is$p987?EC{!|90ZFg`Rl
z`f<hsh7kTEqX9Ck4EDhPw7Eh(Y3Jh0XTaZqC)ybU<4n@=SU^t#bn`@8FqyRjAnBNv
zuMshR2QlL$BDY^{gbz`cUN+2^dH9>??<Y7L<uXUVYPoB{JELm_&{}5=x?P;(<RKqw
zk;-Q_LuB$Cdn8I-3d2ZYoY9Roi3zw#@VS#L;=i3qG$?isj-`<up?J)Kx3#<LtwUZd
zL*J2*BDwJQ;`ZI(!Q%N9)1&l8+~cIGL9cckt}IwtefP{Y6_H9WE(l@l8+S#GncWrT
zcKgT+j7;;>)4zgMZNVZEXZ^XgNc)e9e2@yuh)S?K#GwwHZp{c>$r9b6KUM`G<o8V2
zB;<zv)Ye6e{4Ds{Z~r7HiGgB9fc%!kaIUa561Ec9B%shK7|An`&#|lp+!aqQz6Mx8
zXscFic(~qF?dD7T=Mb5MIGCcXJFV}S9=vxR@}f(g>SY+ig8rqf0T`$Y_^rx?!iE<R
zO8{OXEj47dhkOuKG<}}Z8h4;qYe+;J#M3mfZb9x0_isHc^v};s!h9VHH;(CaP?~+U
zocnH&>#EW$U$&nl2a=GImwiq6qe`s6b-^MIWFzC%OLIa`Rpb;RBKKkL3zF?EVns^A
zN`v(ue6L}^CFQjNw`u5sH?)1A^wrggI<vXT6~T|A4-Cz$7qSktAwav8LLohd94+6F
zQmJfPKsk2qE%)Ic=gKiR(MKA4ai(>ZIsSpET<@)8{UyceJt+JyZr##=ICyY1#olL#
zWVgV`@MNWkm<S8Jn=wywNq5M*nEd&a2p%Pz0Dy9MfDtUBu&%i{;wAtN%7eS+%xBM)
zIFOG_s+@QC;C($P4-qt$vxsi#nj8BBD0rfCx+@c$1{t{9uE~fMa;KIX%Z64o7P@Ml
zYr4Z|a>3B_!*j5weFXip2ojaE7%ie6iw+uko8{bnD4r%<kILyj1w6U>Al7N$!W#J+
z@PYcaWrB7Y0!z6Xss4=l46?dANHIxCa|-m1EmGVu^#+!JC4u?DZTA<iaUw}9nH!D`
zaeOuJ4Q7GDLOq{vhIqa}2EuSB(Fq@b8h-5bebw^jpO>E9D1cO%wa2k5LoF>Qcidgn
zXrxG3J7PbhkiUZK<_brnNa?(n3qf|Nu{x5cI}^abBw}F`sbeq~CsOipF8Gqq2&4=O
zA~~d&jiL9*{`Gc<?}y!p*YQSE8J3^YlQiZ+UEOHXII(~Y{b=SdXhy$1uX_zf_L99A
z)IjE-3f=o?PZ=g%#js~NU94^zVSdmKS3B!c7{2q)pZ#E9oQAJTAfYUi9~{&O>(5w`
zCE3kd1SR<Dyq|8z$D*|c3&M_{_xeO5nM3ivyn8iij|ntUy-_8J7wua|p8KLh(HdVN
z%cokcVa0TJ;)w|Y5;+R-mbB3=o^gr`>D7N`yjx02k=8#+R@;WdX^%d!aT6iVrXnBN
zOB{-3WTDh<fEzt=(YKday!bb)XyGwhQ(0N|0#z;Bl8PGAsp$Zs*%Mf^ren=?Oc2_(
zFVQAh&<AtSqua{_Bh%HiAVNP17syV$gWv+&E67BD5}}(njo$EwsKT4hB(2G#E!4v|
zeOL2fMJ%2mJtIE_NQSD*Fa1fjPrK}Wxm!(`TfE6~6!TZS$CA>3i_^SjL*TCcDPOh*
zZbns>_PHo6XV_wFu|hn<aouN1_K)3EP0k+$W0kqG?x*7)_qn>tX648`MbA3l^LVm+
z4~COx(`6~`@AI;kVk`6|2?}S4f%50m8)E+)haDto`Q5FO1DS3Vc=g`Z46~ptiWU^k
z<dV;Of<G}7Y%#wpS&;oD=;Sev=O#(^ME}4LLXP5Ib<kh1OJZS&E`h3q6R^AQLM_Vd
z8Th+^@-T>kO(CT@o9f$Z|H@E~OqjDK8r-&Q713BMmcS#S4^We#V%k8zTNJXV`QkJU
zn`Kk}@9{^#$i*B7(*O^(8?}ldkQlP`dabHPmA2BSxaVdbsPOh(-?1d+TZ17l8G(}I
zsYNb*U8Zm+t(oM_%8@;Xjod!JAGIo>H@`FDpl|i?C_K9*QP$6Y`QWl4MJ327c%>u3
zUNKl|a(eXv&}Z3kbzz%pSFB`GaPBz$y_(N&Ar6o$Os_^k;9Q`99haR@eX4NhJ^+--
zZPV(-`1TQT5U0jtJNkDjp$EpdnJFR7pxf0~wyhmXqV}o-eaQkuSf24bO&H$$TE0N{
zhM8`N1;XjmlwK#~A$tzdTUMpD{sRc@kxw!wJp5kn15sLGi4tF<D=Ik3tJgjVU=V#x
z(O|woe+SP91Sc_a)r+kI7F9y^?~Mjq-m{k9n91=iE>%y3l-#sf)#_3KZm!Th%a6t1
z8ZZ6oBO3nvo4fsnVv6>2?8#+ZG@vq=u0U4<j3*>=bMTZaI$j9Qib%I8w=#%%JPx6K
z7|375md1IN?F6{=>fVUm7P?T>KTpatOAC_kLStVKozKHIC7E=pzd+9#;_jAEHV`>&
zx?n)niRBJ=%EY@&pS6DB*hsJy=GT@bi)^+H9%?6HNKR`}Z8j(xjrstvLhi8rJPjk|
zWV<6$IrEB^Mlk7v|I7$1$ZHQ!H;AIuIIqsUJ9tDA*bYoY)ta0}!r0iP3YR{)AHLzv
zGi#k_IWztDyo(lO$?>iT9%QedQ>YpV^@pui)<x)uxY!mb{O~BNIPVHR29=6<?8$AR
ziA4d)gwwuPH8DIt4B-3sE7x4TC749GakslQPf<djssa$qa})BB!EmquI!^KY;1}8P
zhKObZ%snrDnQ=Ez7GS?f>!la-(3qxyaaM*gt(Akjgk%XfT#K=Z^?*R&dmqcHnWNZn
zLPO5fREX*8w1uW}K<hKL(PDq5w?BU3z~Q3g6nFN~xlU2-Z_d@ps~-&ET!ZIw);WCQ
zGkQ{fZNV}f{sJ|yGKPXNtqLk%PAJ7DdL*V%A^m?tu`pUa0?eMc2gYc-;cXCe4r&{p
zkPz<qN*|={S63FY9w;ij1eR<Ym_dU=d~}ck912YnX!LcvRV`{&f%)E8N|m$UQ+ltq
zCE%VzATs0ya$9P6sQHZNN{Ij3aQ_FO@RYuz{2#$e2V>K-T{lis4K(u0E4>$cp-O!R
zos4l(7t;*ICk#Yu)I5gKcS}5-v@ShijR6p?xS$hKM6zO9vrrW?gcRHgp<W71>_cz-
z%!$#EQi>whl1_3L=_<<{DaCb$AYyS5+7uaRPoeeCO`k^t1WSY4pw(vfCu@VR7B9I^
zn?XGu`!oBP3;f??GiX$vgNq9mldmdmV&V$-1cQ^PA-UZY+7is6Q^CElN>GM2u~+i9
zbG$^TAka%CEm?5`4`-Z@Zx;@=v{?6~DK9gi?~naEZ&}0LavfoorPsi8q<@*16s|Xr
z`>WW4nYu^n3^<m@NR}xFGKNIQ7c@-`k3#Mro$blf{QtiP&D-{WzJyojE69rcASYnr
ziOx56c?D+4;ZA_M$+G#IEJJCrJnJf&N4{D@&7^wDRYbN|+5RG>=Fn1TNDQ{E);00C
z-+hG28LC!z>&}rVJ<NJ(_b}3+=0A4=F@uKPiVnII5hXp4n<}`;>j+E*2zU(DDPjMB
zgh^9=ttQUvZpddd0FVo2+nN(|-2cf3w;T2fO0??O_JOkxWQyNFItM-iusaDNfs$fH
zf<$tl6U5BW%;^t<Bqta2h%;z2-$zd5+PP`?@NgdlFDm$#wg59U3d_pkQ*upMR1wdq
zMOSaWg!WS>C~>71Q1+1*fw4eo=+87lzK`8$x;j((9RTB1EK3_8h*L2$qpGUZHhM}r
zc)u#tOZ+DT4%u9j91ca*|NMI#D=`@ot#tqa1>E6LZR$5b3k$-@5P(sFk4M(fvce1g
z(s&07txW=K3(Pxq`{IAYAf96nKlT2%AOJ1r2JdgXv|1Q9!Tb3(Yb_3zy4?Z47w|$u
z|NHZ&r+$;&A5#`SzCh<Q<_OSdm6SM9vYWS{U|wkb7%b=uY5$rzj$|AhNZ{?`t#d_J
zY{dYcIuyO%L{flHko}YhqY0`5M)pYxKfbdY78%P1XaJ3BKZ<Nf_w++yk+id_Yh)yD
zW8o%cNqLqGYWC;1&u*pwi1hBtsh7)M0-Ms699C^H0Du61p$Qph0Z9R{q5P07yWvyJ
zuQNjomw^4ZEEXiRn8c2QP2%`^{iW*lR#T7N*O~LeE&}hKwZp}LNt~cL5X4srR04VO
z;bDivwUDb1Yd7;|74}Emb2Ze=RX9eM6jB%eetqz(iuc9+zYE_;8**Jx9ep{|55y4;
zlSLh>#0jzlh>nDTghuyg16M^6Y1}thS>4#H%=D!&w4A5jgwMT_yI+TVd-m-;oAk=V
z6{5mkhQ*+|+FIYDCz5gJh3hlFWM4Xam;PL=kCj&=F6R9P9~h=vi2Zk}F{lEZS0taa
zCUM)29O^A>eyHBR;L8>{_W^0AD;d=dQLP9iOXkv_jw2w7@4LD?v;5<SrvC-oO{!rl
zvWMe2u?_JG8eUb1#DaukY^%NV$$P<ATCHhnQ)>MAm3^N-9{|><PZ<{9)umvuj$O?1
z^6Bl={Xs{b<o5RVzBe_&3aPF7-?6@7Q^{gfU$43C=jR9DEXb4P;esDH=P|%jR?%jg
z<)V?}KPxcwa^&^v*8)(60fn`%(Z(<hgdAWW*XH+e>>u0PK%CX+GY(9FE19cip(^Dy
z4o=RDEv6gx(e?F06EmPj_u(0ngTUtgnXt26^=T3bC5usNYb@M}$oDELDt*vnxkwGk
zEWPH?4T@)|T3KI@3mXTKz>gM}z`!FYIr;+eqz2^~GT&E03&Fim`B;H2yHm&?!+4TK
zpd{(#BS|4bx~~{(3Qubn^D5UC<gu*ih-;OEvZk>0e;F|U=VDQ{&JRZ8@mU<nUMp2E
z4j^=O^lW-H4<tp&LDK%i*e19k&3CSQihnItGS4ZUi1lnO(_^MoJ9xHRWsl);PDCdX
zPetnl7vxa0Wp){Fw(f%2rj+H19otU|vu14J8j?5SAZ(zQ3fKU$xtcoRE)sf6$O%)l
zG0u4K5|)^$3(^D7pWL9nKv{PSs36EH<qEK|`{Hs$O2@vhN+twAF{7UFZ<Zti_91r@
zNU9D6pC@{J#3kgN4Fy66R^yP+i@pEwK{w!+Yug?8ft_@-I?Q<sYHI2L`}OxvFvt5n
zS<1J*0S5yk)h=ZldvQgevsy+aQ;&fJ)$8;rS<-83`1^QSg>1>_{2rL06(d2=$0QXH
z|7}N6H#jILnMs!JjYbnIUUGfs1zo5G-T39%I5&#Kb(Xgq5tw3N`AdbI)Y2BP67rc!
zC{a_(egndkP3+}YuPO&;XE>?a0Eb`BlZ2-l8qWa`Mw}h{ha{SP#H&H)>T-jB$p_}a
zjYdijaVrVI>mh7!zs%*U1Um}XjDyVOORYI(#13vkmg@7S(yRIy0?Z6z8-<MamuH{x
z`CXg^ZN%%p2|JgX@sdzNHQfJY{gp*TgyOHUU~oq2I9nQla&U<k0MB<ctkWKUi&u`!
zgPgG!Ay%u+4OQ$5=Y3vKyJ6W3!G{Q(4mvQI0OIW^W3{AjRRCP;(~FCXX$3!J;}qJP
zv2rn;>hZ*|YZ4TltZF`Y%dD(;A=s>CQD2aJJT1wy_1I-lc{*MSo60jHspckVh|#=e
zV_ck|QAJW~tN58I$gS;2WMpJm+1U6@Yd26RA|Vp(JIyWzs2zBUVJ~=hZg1KnMNS?b
z9=Nyg>RqF|w_1<hPr0b3YOQWb*Hfk7qXA;&m#wYfXJPx<2_nReZ`_^`Xj^GOf_B#8
zQan3Pb0mjVJ(9S%xXlVc-Kj~AM(u$H1B!GTs6gPQ_74b9k(6CCA`w0Yy5H9W@Mbu!
ztwFEGs+y4YDB9+o+>SFSQzG9^tBsVMRkx%vMNA~S@5AnR0O?A_F_1|FLU-PX5HSpc
zEZhLjj_6)^W0}nX^cYX*B~~s45xS!KV|in?<ciEy4o>LU6zHq$+Tgt>VXkGyA|OkG
z*X+p+2b@sCGJ_c}4Wj;WO|=p1cd3J_6s4QkmZ{!~EL*W@ai{Mng<U7ut#0jCQ8g_~
zbsGTF+1vW~L8pGIj+!V)%|k$PIi6Q~ixfjdFzc=WA24yO7;g)#7lL<}vE`KbZD)su
zG&87sdRgMBRfvfnM{mU*_Zp1lQT3GmNe3wW?BdIJy?wm0o;2(6@o^E{d1&r2F)_zm
zyZhS#DFRhNGbE%B5u6s&DslP4UC}2HW?^8S18N?f{~qwdw$_C2MXSe5hLq|?J!^l7
zLGNc0_Y?)?)n)ehL=aB0@!GvDIRGK~*v}>7<CUS<SjQG8Bq1l=9%*gLYZpRC<EJ2S
zXLBCcFM{1ehM8<QPh^7kHQr-jfqFMehMNb}eY2t9zj9P-%n~H|NG?QbN#*H^SBg<G
zY8T>4ySg>ono1{1aG~jn9Dm=X*B)|wbr#$dYOgyx<#j$o&2(-212PWk;SjP&D)NV~
zdc<m3AfUETz^QS5`fzu*`w-w^!l99f63ZAdqJeZTymV~mSzVA+Ua{}tYZEu~u|xKs
zi#0FUGmG+)6Q9AS74;CGW1$QV4$k2<(aQMsG?CWZ?tnRNfSDYXltM00lvK}`)sN6N
z$9Xa)5Tsdn>CzW`&-_THCrNHtiRdj=`#Q@jE1>De4d)zk&?SVg7&3_H4YbQwtD10h
zaqQ0-8S&MBNBM{X!i}~?H^?+%3_8a4i@mB96&VbMGaOs*fQ=wPv1AeG8TLc<vGHsn
zoF^{RUU`o%qmzoin~|R~e>pxmVO?gD31l8(yp%`DR$t0OJL~m(JT1=l-g{N_Ia-XZ
z^zqxbZ%i$h>Lgx$8g85q3kz$&fZ7*pzzt+D7&gmL9^!e&AbH}sWkm{S#&urOp9~k8
zCfpw4`>?Cs1z<|o&`U1Se$zafE$$E&=n5(#7_|-X5}BR8dRf#CkBkt`0@#+_H0>3_
z6FLqr3Bk~B!tO*0L;iqE$~N(y_c<E|eZDOh!LdNrV%a<cdaW`g44ccpp4%az{%FVG
zDQF}mLz&OG!wL51Do>=U%+KceeHoPu@41QddoRb>G7XZ^X}uaaU&P#EaVA}-w_!A<
z9B!T;Oxy68kRu}_ixKwx1CIo$6^t6t<3^}GtIYa^u8pO^__Ml{DTLXE3<^&_5lq1<
z7v*KT>$aCpjH|-6Y=S++WtT2Pcp8ZND<oiw$_8Iqc217kr!nw$xWMp`CGcB{E~9Zv
z>>6<pp6NTQX6)ezsen^wu#9LJuC~N%y$wF#JvoOm2@V_&7Z+~2e3;|3t~H<ogRZU<
zUAaPi|1BZO*9lTJZ1i#?i_otmgoIFxn5?oI=3Q7Ian~9im_~_9czAdZi>EIqpp&pg
zhN=@26SG{AKd_xFy2UML1$1JO$OkMlh?VD!<6uwbl?N{xOUwKdX6tC}oK;+k9z>CR
zcp<^~bfRxphRjy>%a=Dhil`|l*a>2`)E?-?^dL%G##4jux3k{^gUKx7&(F_^1mohp
ztz+}j-~)*E@NA`dS0Los%5Jlhh7K)P@MLz=-<tXAl@WE9gL9TxJho7vL*mwmetZP3
z&(4txR9S8cZ~fH==-N_c-GeY9k81v2!Yn04H}2@|eI+h=lj?7@+6Ip%!7TCX#wZCp
zXrE%Xs3M|hx~~`&nm_i~uLjp4iBJlWj%=e$a;&2V@`JiEQ;*@#GdQNx)6;(%es@5Z
z55|B$JeHS5jt9*%=FXrhQ_#Dd_GdgJB{Wasq*8HLdFh2eo6O+s>`YBY#xnFl#*iL1
z4CuRPE7MTMe}Ab?A7y&Yi)gkXU|5k8ZcVH}=`K60o~99Y#G}K<i(}j<H`^~J=m>9>
z#%-aWZJrct@t%K!U1^AZbT_8KW?eLJbOBTpoJu2Z$Z_3ryFbigVpJD2f&x4|)f(xn
zgV7l>4s^Gk*&%&Lq31X9rkb~Ci>Pfuf;yC9RBM*lmUt+IO)Ov3U9II5B+;;8;~C>#
z>y}zMF@pqYb&{JmDEQlgVJ%yV)H|FSSx!zI(Wq@BmLOM>{ktH~FysD&K*v{1e|zbi
z%3j&0L@=w%)>e%D<}J4KF$TJqEz8}%V9taI@0o-08XoRGWyu#fZec~dPR!-Ymm#O6
z!VKi0*E={+o12MUCHI|sdwNJQ%ss`MSVuVr>{%R(<tA*w@2ZLxRm0Grb-I2>gq=^J
z<rFGs^I}R}2{e5?_r~5NzRODrLwA0oV1|VtEi`KhlS#Ia4U?vNhI+e6oy9$9=3RQy
z>&7OS(?bDga4Fgll%PY80CwVQ?ei}08+t)k4%VhmFr~uw!kV{y3#9_YcE-%GZ9cEO
z5JchR?RgW3UaVe@(ufGh7-5_0{hb{JX=BKX4qSt4N;zybv1#Pdnwv{K{KI*FYnJ*i
zbyW6m0vHCwUy#kw(|JtZti7akDcAtBzIndN-^>yfOCsRW2ReePJ8_KY)hf>_0H}kw
z`^koRpG)v0E7M%SX^=)aAp3l4K(hgpsACub0rXepuPp2VEoX<@G=H5OX5V+-1C-gF
zo~>DugIMN?IpZ6!cwoMxVuPFg%0Yx%%qsm7AX9EoWJ+{qlWEGtdB#g3-^OFuA=B4T
zTU)>F`9t7S8rm5Pm2autbcEJ1?Cc1BEn0<a?+E`aB_-v>ix+sfBI0ciUC+c{cxn*&
z$2_M?$1WdxBkKLF9VlFL&-(!ZB1-rcz2R(a4fI5^1;PKTy|)aja$Ud01p(=hl5V6!
zknS#N6$B|!LO?*6NGaV&s-Sd-A}CH8L>iS4P+&@fPLU7<0VU4;;%}Y(-~Vgx^Z9%@
z>slYyrLvs!eV^x!F~&V^_yQ^O#^cXzm1(|&pRHp|rDew?4oJ2n-@FM0n}r?=dP-K^
zDv!DBWIVy;7LO^pn&mk}II=!-4`44{DJLCw4-XFx4i4yT^8;Oaona&7PryfE%0Fc#
zqC*K*(V31xOVU~U9iQ0UC5D-hhLshus$JSt*pYl`<><&=aaAZ`b9qcqW&y@A*z<bd
z>28j26YhZaN;Mv)eY0h})KYC}IzoMHrG$h?F_K4$&GKk3R$ZH0Y6)tGFj{GBNKX(%
z)Xb$6Nz#5kTx)n@A`|si5KF~3Rj*a{v$nPtip4_jAu7#lM(T}8Eb=ARy30_MW4r6?
z>tDx{WKyca;B2I+l9E!4Xh0fm|A#1UW#fYO->J-go}}XpHv4drVclT9HxAw;%mKjG
zBsR#LIS#s;p)r?&&MSolZMkWro}~M;5b)ZlxXznrFRI02_zey8kLFyuHnG%}9u3V2
zQ5K@Omv`Z!4e7_m$EPiRGpjlITbPpMvQmpbkqt6bdGH$wr#BBdw)vgLioO{WkIJ3?
z`^N9sj<#7);nM#Crpaqbu(VjaG2G(EjOU<@jm_35A#OfS!5{73G@S%6X!76R6_?AD
zR27&!e|`3~Da^8jd<iS+<m*E*d(~Lm;PJBE@z6DU!93{^LHS_<=1k=8{Fnu3BleYd
zau*CCKtpEC-44Odv{+r1PZFj~7+s=+hl~zjq9i}jlcMYZ^k9XQY{QF|srx$Qsxeix
zhB17ajWAO#+)8zpMm#|RS<MI{B{(J}YStpqr0i^MF@pyJOcsB;kNd(EnmI5z6vSRQ
zHAxPYp4J!<DQSe9^L8}kcSud*C}K3z>AWQ^-+bO-vAk~MOdmnR)UTo4zP4gySp<`~
z;Ad9D4q4Ivavq5PUfT#=sU;L<^R~->C(FD^`S&WH3xaXSGXGZ8>J=zNA|tPRhae@E
zBbi<6@F!vGdQX_L=yLpkj{`BV8o!139AoOz5UPWj>w7+RxJV$#y6iknV%F|L(f&xt
zGOP-j2GxHcpqXS0=^7eFvvfA4pfgikfq{RZi?C_*AtGpml9-Uyry7)HGvJbi_u$DB
zD{ycR3J&J+-wKAyO?kufhm1t4GXzTP<^1Fl8@b@$wS|QXpt%~zRh}u<r_XTHMUC$g
z`@{^pUjcJM=%r2qC4O)K=<a72y~kLdG01~(YR)nmm7UG9Om|O6P7~m`QhAl?DM>RS
z*AfuHm09Srx(a>4Q*pZ7ywO2;+-qM`tu5x*tWpt6-wI)6PlAzPrNL*070}l&Fm`o!
z!wd_xuqNadFmo!)s)^{sLE6id^C~wZEmQ=xsBh9RBbl0ROQ0734s}e6|IZs6LCi`S
zHq@C4{^uA81V~9p!ZCDct7a1=yVobgKX7qy;P_Ktc>CA*iQVJHK&C`Asid3q`{@%=
z6l_Xv<6@IJ0Nw`=)7u7d@XB^e7hETXQ?ROa%R<O!6nO5&j;o#onXggs^i7);5m6>1
z8!4s*Xa|9auO+d!hUqJS4V;q2PPhDlI({ZQvQGmkT*c@#tQa|;lSC-pHa4bIOc}fl
zfk3g8k>hLO4dQ`7-;e4^2C^f)FPiTjFvfjt82DORsLf7`&bzFtr4F}ZZG7BfSArSY
z69TUmj#nNfM)EtZ2`m7BN<ZWoNIjl{V8-F2mb|<?GcHL?T8tX=IH=Qf(Nhp+N>3tk
zI#DZ~&A8J*Iz^gA40h+tzXlcZ5Mx`vrQ456Y$O)<deblm)sZz!w?I?MGl3d8Ar#`e
z{-HRY+vvtuEEWNapa+2y6IUwN7l&5S8nYLQK}+J1IC8@2c1nDwm1OWVB^GLb{O{LA
z;N*6q3ZGBFa0m2fY;r!mgM+ug62P$uj?GhRyXVkvzCnS2IhuHGABy3MtXCV5IG~~G
zW=M~$RiJg-0Urmf%D9KPNoDnv%*!WFo@~CZt`>t|SgkTQc9-6^A~gR5p+d0bNUykh
z3R%(#y&v58XLoX5^9|GWmdPdHLknORYM_y%^6hEL1U4o1{5dMPTXrq)G}T{Zjj!e9
z<*8+UuhQKdPldltZ?irUW>-^f_MuC^lK<{oO*%Rdx@AxWkhyDXYuCAq5OlMk8eoQQ
z%e0N#s6@+b+7;uWEA_j8vaJHbReO6o+l#5)Y%pP>T0)0MDMWDia!;TN2VCCxZ>1Ou
z*Dm%)yCI<(zUCpM;n={rgwqK0@N=<`x+W;wQpM}>5BcYRtB3BezsbVH#6<4wi<rd3
z?afWoN3BNA&Se?h8p#hIMn#o}G}~5b^A<9S)4^915Gr`|{P}aS8z0$4M96JSu09qW
zN)|ecW-_dTxh&`jU|VHJ3>6nt92XnBuXFQ{BBq_l*epcXl@n(#m<{r|``Ovq0l452
z)(s1vARi@t@nw{_VE}6Axl*ujrWi3u%M2Ptf#Upad%HahNx<R|b?6LuVaHD2bMqTF
zo2~-La<QVw+H_oNC^=fJ=sq`Q4LEAmFdqGf$XM&$$5G06dr|tEVWyNO?<hL{zA6Y{
zC70=yB9JoQ)XkDI0F>K>?s)o#SO*uR@a?4p-E4_0I@4{K%ec`i5jZ+zQ?IWJDlgiy
z#DKx~+aCa>jAaFqboBI0r?2+UU{m_av}A9<m)Wy>Mf0`*E)?A`$(K18a5sJA>b=lS
z7VyY`0>Yw*NkK%Tq-`FDrJ-9L_ux%r{~;v(ywcR<<Z6IL?|7VX-j$-DNP>o})&FPr
zz`*?|AF%zhm35F25I~9}$&00%Q-qGDG>r`nvE_NjoF6~6+&ySK!@jn#z~x~V5fK4$
zbNo}p>I{sG0kGP3k^pW}<XrNiv<!ruAVB3eQWF2h(D5~(<o2ODN0vB4+t4Mb4Ue5Z
zZ4z8*jh_l~^l^En#|um7AraIN>ZUi^S1V44gc4X<(k&7D*OPAcxGNlE4Gi<JmneTp
z^PdMMbhByr%JuAf$?kQ;g^WuX5HsF=wtVMKiR79X8`<h9aEK^SeHIWRivZbw9|*a-
zA38671PU?l51w`8<mC9C6V1$jKk199<qs4gA9?ur%3!V<%JSvGGYrUKhOU#=M~26r
z{K}RItbPN8E)R$}g?oq0k&tgy*6#tK<I}-31<}`u9OkULx*~7%L~G{lNkgvHdiy;u
zO%|$1K;j0TNE`W7zIpQo47tw18HGj47D#(Z%5YBO9b>GL#C|8F{Ra}y=iIP`dfq*>
z<!QVuZ(ebrs*%i+K%5SDM5G@^hGCbV^1Z{L$J9h)JUPuc($dluui<$6u6@q@XcwQ5
z5P{!glDq<dn}ZYX0kiob5bzK&#b7m@sHo`ZDwOuH#r)>RB8RN3Kj6d0WMOekcPW<u
zS(Et+w#q3c`MeRZ8JrA`C|#0s4F*Vd&lRXI-JJBUDdHA0eTs3DuE3vS-5=Ys*oM5&
zf0m*w6A1Lw)z&*3oUS*3-~%LM>l@&`H7Ch!TLR8&<lEmlp=d)G;XSI1@!-)qAD5Wu
z>+8z`O-}_&?0sUdNOdmj7MUmY>nGF5LX+KLkwU~M(xqN-p#%&+$yf<;lcNM9{i*Pp
zpgnIRqd@?8;i$<#WZ0uTt1(cd`fTqs(rQ&a;&zf9mEy#IGd!vbO||{z&Q9r6P*9LF
zo~o;>KtFhEi-Uh_<EPjguua4ef>&usSmkuR7grSypP*JGP+83Fk*UA{6^<4167^9=
zvnSh6cu8^ah@9cJ+2`hNfi2A|Fh$<)&PLWJ1dx{!kbvX_Rqz6wXZ=+*vZ16ubFn9R
zRqOWskNBTzf1l)~Mvf7{YI$E^ZaQQ%yt@#p7|CmL3Fc5X4TqCKPG(XeiI5_YC5*N^
zwaBi42seQcOGFW>-2zJsC|a>ghcIp`qYGL#9{<<Y5TWdthja4JBTI!}Ffq0bDj#L>
zjuff#_BzNYPyN!u?K&TxrlGA3x0wk|F+jlk0vfzaESR0x<G!2lf*~NJL+8Wj0K9`W
z>!sYHgHe;ze?}`Vl1S0Jzk{u9L`ET(@O;TRhUnE;3Pw!9Y!Hgfqd?P%bi^!}!5fla
zGVA%Iw8HJM`|}q_C1s6&0m%T<JKFEBos5KVr)~;e1!ovdwutj7v#^;c{Q{V$8g<U^
zdUIHN$r=X9+|Ooh6Q+Aub6IDVNm~D?-`waaDE$orTxg8*qPpHobcQuG$-DW1+6cza
zNv?V-s?#^N4MAO4Ylgkl{uOX)u{9J51qFHN?`m?lrUz%noFRmJ>JuhHDLJRs0w@l#
zNmvCCCPTx+DW931vQ~L63c9fm^*<5?9lN!U^;`ootq(Z3G{K{&GL08uY2hOEy;L$X
z6!+D7XysQXUy;ld5H|*evxb_V86y$CA0FNToysu&GF&RyqsIg2jZBOxUYV<_^T+45
zNtcM8k-nka`wBHj%p)LaXZfz2N7g%zQ)6N@diCl~d)h;v>;fw77;W)hJQj(dKmggO
z5@MWdy^PtGhFXCB07yaQE3rKLz1BYsQb|#c4{N71U|(~4mZd}w(k~ikKLr~)$Kcof
ze{+o<W(qh1frwB+SXJ3_UkJcVF#XtS4CD6u4VjtT3?CzGbBUmOxK>S6#Z+A|l8jrg
zp15%-_DEh<wmqHiRAx-g6axFnzmh=%*6(u@=fdOqt8vZc_wsDk{$_6roQ<$4P$dDZ
zz#IG;r5~rt3&Af$m{KsgL$LA-e%NZ1r;jb2S_k_Fb&3!=k_+@J>{U3MGpYN(@V7fX
zE1>5w;kavsKuj+#JeCYy?Isvtr>oxD+0oYLy+kfWe;ii`(M)8w&CO{Js6QBA2dfu%
zz$#LM9@RpH0_Y1bM%dLC>KEu6QXMg5(W(HNL8ti(yl@NE%(;%^N|=dNYmlrg&Z6L%
zlji(#`r~;lLv=+dYMvOZd)&z`c4|kR$G<P7K1X%ZlXGB%3F0}mhTaz6QuSQ=gf@Vh
zBVieFL=m6T1d<Q@HfG6c-FINDot<*3UNz68I!2Y(IYaNE5Puj=Yo>?&YZL`gaKsPL
zOkM&uTiPU%5mEa1k&A6S{x8VTQwi6hVE6~?1&RbhYxxhDg>%+-Hhx$=C1wHNj(X&S
zyqsK><;y6yy84qaw<aj%zqtrrTIr&;IX9kaOFZ1ZeEnt<Tw{5NfVzfxKJhfC-gLx@
zJ~Jtda^7>Jgm(Yw#eA}g(WxmGmK=z<g-qd-$v)#AWwCNJ@_FdF)1Au22AB)#u_qY0
zH(n4Aklsr=q?l^w8QN=CN_A`MYN|Fyy~_}<74EyI<R<-;V1V>U^%Uyc2mB+Nv(o?j
zwX|q#7>&}BJyH{;G2!atV(n9ZO~%J|;QqNj<#%KC)KCn-nB7O;4h2JX95KRT6;xSX
z(AA~9vU^!(hBxyOdX1WsJc^z8Rm(6N9P15$%Lt`2CnxkmKtdTnPqXE_xu_eM3HEY8
z^L|D}UAFwo0@Kf{JuNvqgq~_`ZKbS)2m;`M7RR~LqUtHAygRkkS|L}!QrwHF?seD=
z0e56js*EzPT+O_oPD?tK5c?MWq=xigTn9_>Dzbx&7AiXc{JtzMZmkz>v9hYFsya4x
z>1P5@p&b==S>;eIl@pU#n4VS))egv(;T_D4Co|YK-w8cg&J*sp0;XA;`d!INOwb7d
zDF)F1CgxXR;BdI?wG|2GDi|Tw7{Lp^h-Uhzy2nX1DPV%ZoA4O6?RRamzcBQJ@8<N#
zh*_$;^i&?qj|&<93WJu79CP6jUQp@gI4re|pE|DdyU&}pnDV<xa}r+O1i%1BwF5Wi
zHK7q29jAuN%_?RW!j16=7~q0G!?+DH_Lyt{-`}IH>;M*dxB$5xvYe)2cyTxt_*0>G
zx4`za+n0%rEoq!8X`4H870mg6g5)s$vag*T`-Dfah|I|_ss<X7+#KIU<-gc*^%R6y
zs-q$%JUvV>XgPj6L-clR;@J}y@(CT&lFm4tR}BwfUF(Kfzu&=cU-)zmYO=-9*OZ^8
z)yqU<fP{FTb|<3#-qBt3R8(wC3?)S;K9pFJBRZj)>a3i8qxMP>NDH=CwyL$DY7Yb6
zG%|LRbC8`u3tC)PSN8!mqV~*Dl-qw^_;KwVfE)n-=LJ&8oc%BXqKy>EIYVcoCA=`P
zH8D=kY?CUQpINWR+e1E}$qE3v)L}Qj0;EWnhHmvJRKn?tm)fD|t$=4!3d0Z_m_!1C
z_oPy@b9U<v*RFk2F)yclv<n|Z{?vI*4&jqREw`G!{i0AT={bU7FQaQsbLYC4a<MO8
zLHk5cdN5)Q+_i@>*S8L|RqCnm0w>(>TF-!=!YdZx(F34IWt!6pqX@}{$_thyM)yxI
zT?5QYr!YO8Mn-D*bB8~O+sQ-21+AOMh&h}sr5~))QBMI;N*ORr=2pK7BoOB(es^gl
z=m*p8RNg_13bhhXf9*3uSSgN{*8tXb=JkMpShXB#NkUBG$FFUN-`lWe+=}A88qEvX
zwKc=<b+ZavdEcNS1dyEC?0lX!UMM#gn&~~IDYK$LJM9?E>A{OpRR^O8VO<Xlq$l<8
zyU9H6w>NsN)sJ6L4UOj=PNnzw+1CQXe^4K{qinCHKnxS+9wrQxv=#}n;TmufFtcWS
zW(daD%O0SvXi3S30x_C&9PMr;laP^-0S1ZCK-W1BJ3xHsHA5!m=2RBUL5MDMy4DKL
z*Z!_omhrpA5ThoD`oN^f3;<`#X-6_C_yEqoR&l<b7kh*X?82g;C&`VLnx2?wfSd_6
z7%!&9u00G!5}O(u3kFOEA)`gKI=57ZyJmdT2HvFY{WmNYySNx}^Q0o*<7HKsCLUS)
zd8T}>r&8n~LMrAy#qx^{)DTms7uj>W#|T$S)M_gb`^%OJT~VtjPtVueq|zaTVS|NL
zCTO%g0Hv=cp+<%SsIKSSd3@zYIpmJYenEdQTfuuf;i=j!gL${1F7=!_jq6SJuQ*1a
znC0T+1e*WE*JwP#+-N(EDD$b+s8E3G7{kcVw%09w>NEIz>zvJi?fwLNZXGE!a2n3p
zBT0ayCHXPzE|2Jj3Y@bSsKda5L-^4~m|xJn`xZZtGhFw@3$c;jOswC;#6-TJAVbYm
zs)9LDraSm3)pNrPA?c3juNp5&ZiyaLhY`DXFN&)+{bc~XisT}Pw>FD@C|=yG`J=};
zp9cXj8!hfWe$hITqqyyqF-@voUS2?d7t)8@wZr(b{`18SPAJz-JtJr22$)MP=_|!l
zr3TRl!S6}l3chlM@!cr~`FfRI7dhjnVR*NrBo>+wM`rQfGw;tBmIa-pP+kDjOqq{U
zQ&*cQuRZx&nO+PvBs|=Q{<%PJ*gu>p&Cv)A4J^D&_Ta1ao}tqp!YRNiLhOQUSnGSZ
zz+UW(2~VY;l;?C^!&~8+W(zZ&&u&B78;HHw`nV<yAXw|oou5=uDl043YEd$}7uCN3
zl}aOkT=kw$u54cbFs1vv+9Rz7+zxP#jw;J{k04liQKpzdWWBme^D0h<Y8znqawtlN
zq?C$d>A5X~SE3B*X+mE}ZQiJOHH^@o+zo!UpzyMOSWv;UcR}8|7>to<4@|d|Z+))k
zK&b?Ad>anBJw$>NlOg9hdxA$%BU8ZkYJ)faOjt72`t%YKXE{#=<hz9Ql{CC8TLce~
zg6QxsC)u)PZxg(U^<N$`<glQ$p6A6quQ(q?{}jE<_+x8}=6ielpWz(f1?G!A`6UYS
z&z}?Hq-wvrKCLJ%T?b;0*kCtivOaI;rf=7efMhD5-&{yi=47?Ldi50PnUKj+?LaWG
z%+E>WHZoABP>Ec%skXy$lRi9JnUEO0g_Fx<3v6GRT&jZ4si_NPw~e((2Q`U7ygLr&
zW$I>1C!v|dhS_xtU{j%)PwvnE24aKZS73$u!lDJg#cE3r*^y-<6wzJx+J0vh<A-<$
z{iG-;%#9N{=X=q`^kTrQp<t3gD6B<ah}hNjj81KSP1{Ot8^^4tOE-;6PeDrgD-)I&
zS*+3InJ|l}&+znpW4a(DqP8De%>`1P_FI3pmd?CF2;YR_p@&huM!5M)e_#l@Of<rn
zRzGz@2re<m&z$pz7rA`-KFwU;%G2hJckWyyg-)^eQ~(bT&jWt5s2leJ;D9Oa7_U24
z9z(BF(5%DVgM9hW=92qxL1cV9N%I{jES#SXf_|{;M^L?Mz$5E%4;kO_HRv=VqoOw1
zseyk6O5e`{gfFAZa54k8usESu7GRMO8^n&;g7sYhKt|rGi<KLbwKDvHwjWQgxTq)(
zry~^9)RB(KXPgQRX`cH3Ww|3Om1Shc+uK8fBo1vsp>r=2bPsT|{(xntGcLH3y@j?g
z-znj)fMJ2;`_v#o`bRhyR1<UKzIQ@g;ALXMj?Oo6H%K6=N)Ug%@yzQHn%)PK8>;te
z!Pp@Vw|BY9wyCz+-7~n4l5Ar<0-!brJ*}0v{=NJELL1?ka!7#ziW%C?lG{{UyXUC{
z#W>^N=h}OvmsUqlYMQo26*3xCVn$XzfKq$v@Z3=O!=*mb;OL@Ii(44wC|fu6Mi4my
z`@0*pir{L;I8x}|^dQ_|9CZ`vmYqODvxRQuR>teuCe~+RU;zJ1uVHpLN~yfuQL8YA
z&O!U3ehy+SEbn{<d0}1^98=x`4kFrzwtA<v4{R!ApAR7L&BIB2Kof2-TLk(hz9{u~
zIf_=VZU{|ytY{r|YA!7=>tUdi&>|tGroccrv9GzrX{ZFC4zopp2GLw8P<XM*WcS$J
z{6MzuA{OOX8E$Zf1Zs$sBfPl#_q8-)Hcq1xK#L??YI5gJ{hi7O!%3`}Ld8^RCy^^W
zgT*Ha^*I~0xI`<-{kCBh<dyR7g(RHQvwL8eixn0}PyGh{hgb!<LfxjN0W|aWO)bsM
z#$O?`mFP+Wd}*bVBXRLv8BgCQX<|?T!HNrOKm)}WZou2ol^OR~$~^l0T~x*`V1ryK
zW38M7vpPRNKRe5AXbQ6+fTYJ<gJNHpU~!HKs2PD@(W~7=_Dv7g4d*JpL;aAHWQ3Rj
zHmkX~xa|G{7LgilwO1m6Sqn<~KOx_rQB6%vBT{a4)ed?XL?A7o5d2#b<3R>V19WBp
zWdXUrF$mJG_O^h)Kv1qP0+w_%Q1ERIOlJr&!VeQpqY;ZGh{<Max^)ljn_Rx&={}^@
zVwh%}5*YWhxcy+YI|uk)^Bj!?s<XYQ_^zzg)m5+`DgCU>&5eh)Y7prLL_6Tuia%Td
zXu#wDU~9kR=H{}w)nyo&J7BJ!fB^8{pz(7zC)U6uAWru=ov6*z7gN<{K9v_8Fwgjb
z<;jM_dfs^`<csN#ogL9jPtTBgSzBjiXJ_9@+k}aJn8&!FumAQV>d)`r@Wa*y<R^j=
znIY7K99zj8>dt?l<N+kO=yEDT=Z8VmrERqq!UtVlk|8Fd9|a%R%AhQo8tpth59Sfo
zQ{&M#L|xCJQ)sHJ6bvAN%T8^^un)u^6j8ey0vNJz5nhQynqx}ou&nLq(CX@Mabt=G
zi4<EOpIYxrI81+KcqQTAnS%#*cXvle&D~<wuG=82fYeheZ}yh!IWMc<3u06Fch0MI
zQ=8e)cp`^$XZtrL6lVo}d7Esy&y{69TB{=u26i7XD7it!2QV9~S9sQs>X2$rZdX&K
zKu;YLhxz;wCS$-6KZA8lP(Hf2vg$;+=E~mYWv*^%Ie?my$KTEG5+caeyIgMCH8H_}
z`#{+0VTqX8Br<Q14um@#I%77v26#A-K9Uz}cy_g5hma!7`hZh~2zZu2Y7py(M^$)@
z=)r0$?0JA-`-2v`jE=#Q(AnxIFuJZOihCAWfda^qOQ-Bzg+n@PyWQ+v|Ha*l=)gA-
zMDRTtfK=h@V?fAD?RS_16E$^pmnj@wn`a?kj9y7$g@zjw{Bi%H$+!m=@d_p;YWBN;
zoHYmkp<^2T1MA5y+GM3!z;nFx5o@M`TO|Fcb21Qc#dAxKwIH6T(4{UGHzBm@c2BOB
zsp)AvTIul3zlwq9Wo3LD^AE4PjFt^Uk3UwNnV0#tFrK-Xm$yyfdm2qz%g>L=LeXd|
z*(Zh3(a{<CYO=I7pvhz&2a4u21B0$KFEp2`B;>lAqc5Sz>d*z%YCdD2@esl~RFGfL
z#O0VxfLCy})R5&$!pYaWRcTayRKQ!hgt7A9)-&HQ`~XF8G7do0;6^4PpekiPa59Dk
zl09$&tgNi}S<|DNf8iLMv~Hzjw843V^HlfalUKbVyK+mUJy_}mw;vn3?X@xt?;TIm
z(A3^|&uHPkbkh-xO{EVh_Z7VO3Gnb@_B43*x>rGYpd1{ahk%;lwmfuA!vu|lr{1CE
zt&UM@N5UGJW_&6%6Gw<(Zpl@8{pCerq(i!%sDy9dWUuEF<qk*HprItif>}vKMC4}W
zMl1-fX-uD9d2o5?SQ56kyPH>j@zE7rcg*UyZ<Zjx@^xY5SpK!Z*XH+Au?$$CXlUx$
zk5A`Bqwh@!b=V2Xr%Vp~gT8C{j!k354e>}fsTv*eFhb$4Mc=SHcBbtJ=sS&>C>5ty
z(3&6~C6!6{DWAP>f^onV(%fi*SX3Z@`Cxzo+;T3o<q=U)0)rtWc5u9a3rqb>{Y1vA
zAftysekARbHS6vHSh1?L#jLPQtRa3c;Qo{Yohv{Hw57GO#}5PVC5cNbB-K#?Yx*wo
zfG3gzaT(ILav*LszJj;qF<gK@^+PMZ6+DB=q+reXSU3yr)F_CwhnWVk6#Cu=w;qM!
z85$bahQw4O<08gv!Nb5}VJ0TFvBT;UmG7wkl4{A<AdbN7ETfzc-_({YBwjIwrE_xF
zOs*FM6s#-D%K~a&z{F7f`q0<X(~|p0qJho}euYgjAfi>#@c#FiuC65j(zq~WGa=8@
z&UK(5;ly+T3?5(IMZifVhls4#*4Ap@U_mzSHDPCz)$>qY7tz4R#m2V#-X~W5lHc?x
zHK_7BsKd)Jum&k6o*|A|F@WYlY)~Z4Wf;Q%2H}mr`XlJTbvAvrVV--U$xpOM121+~
z%@%Y@nlemVZx~)w>8`A=D}zPR=n+_T@Yj3FgpsJFF+&;82dl<sLEBN*6>&eN6Htyh
z;&#!}>u<}LO*!vyTwkM*{&1|eo_nm#LjxG~W%*ZJ#-|uTFpc*}@x4t*g^DoX=EUd2
zOXi?FgDX+i2l2%0IspLz^xHq6lNq;%*YEI((!L3x-S}VRs&SPLK)CIGz+#<?EG0K~
zZS-Pgj-dPvmr(K8`04hrsH}eWrBZq9I$e=j!9Vg&xUHKkA08GKUPIV^gge~lA51xN
ztMm4{v$YA5_@CgW<pb#uJgEDpK(HBJ@&@X>k3|uy-BMXN)|zmvAldQu3F8ceXyHC%
z9JmAm=dl$RC^d`yw}u<@YVzsbfmVqW=*p1+?sExQAb9B+06p;1(i|~~i<p{g+Kxu`
zw*vzMmxynpqtKEOCZTp{r2o@TY}E!oPdgM(1J!SkGIlA&2#qGeP=t@_?MS`wN&uCn
zfmJmokA?6n$moVE#YhYy)*q13tG`ITAc<nS%cz}?6J8>=F{JpNJq<dwOR(9hO2kU~
z7ObsD^gzjlFdBr6862IWeT7)Bv&<6)PeKt~7%tG4!z7TG6i2MB6k(9sEQ9z`%?;X(
zcoDYjC!SGdPD#|7A!3q|7>#}}06eB^GSP4IafU0#<7k%=tyHr$@Es%g6jKOT+5PEr
z2Lxxx@mM-F?~&Hrc$vnuj4-5Pj$#(Om=t?s4xevt3_;XSd~U8^J93Cx!JM}u{gOS`
zb(5c--VVt`0@U((hr<u^0{~RS{gacL8kR+5Y4Vj4-!}9}@ZJd_7RGicDd(kUEgox=
zeAO_3VUzYquBXn$gl@0*hiSv|v;rcY_QvfJ$`6T_hTfN<t-{+^8;*a=f^_f6Hf2Uz
zDM0QSCN&NBh29R4gQ7wG;!t1!)?MudQn){f2vKWP_lV#$W_ZBWS2?8`iD0*HYeD^G
z&Y~DYhi2ksJyqb~We!J{lF@V8bGbLPHcYh95zZq9{9q;Br<-Lfejntz#76`w#*n@H
zG8g-gM3d8LIU+hb{_N<x(mdg06W?_76QOMGufLJHiJ^yRjGbCsp3Ixm^t9BF3<pu%
zK^y4E8<RvV8oYUgSfn6h%(3@zvS)rU5qkvtl(<%jL~V+6QXnM0QGMeY^Yxo&v`+lG
zp;O>-!|n_q&l~Z=vHWkVFJDci!jo;rUp6yvC8Bu7$QLW2a^bNE^{We9O?FDNxSGjQ
zH$Rfj<cy*86?zwgjWe;#AIw|DRDS5@<m7A(gQwJN9D66=a$PR!>gx923JMCUOD&Wp
zdU{I1si}U{zH4@n@3-AY7pfDJPB4gK>0U=@b>-rT&2~)t1yhbzMix66&0V#uxJwer
zi`!Ks>8o1z)%?KWtFK&$n;QY1$|yIC$+OvrMRe55V=2Q8($P#8^>WoT;>d~1Iy*H4
z;L9}iqhQ0tiSmRfvw|;F)yZ12y+t51nHRq2ljZ5YySHZ|K)1tK(mOl(x|ox-C=1Z!
z+zF3w2dccuAvOo8i+}KUF($X5&<iDqEXY(59*$2XWH9G9kZ_YONX-$@*?e+!YcdBg
z)lXHlxm8zQ#XaT#CTQ7Coz$pU-lJc<OiE2J$aHI}l;iTjLXM+#-z{5>2<t|{zH1H-
zoOQa<m>?*-Em&?JH)(npMc-v}frwXXUrdGDi(gD_C0M1d%OT5$Qk`@nT&N|oM{o<~
zJ$3JP>p_evHFPdc?izB2nAiz~0U6Qe4Y=i9bG^^RP`#xNd)&IezRxFG{ST<^*;2Ml
zM9rHw034b2X^=^%Uts1$$$(A$3r3#3TJT~G?f>zyp1>KOZ+s2*OU4C*b`Dw=1@sgf
zzIXDqG{>fpD`AlZZ_j9v9l@N0CR~Dxx0+yz{nRG~231@tF93_j<?a8>Qb4<X7Nyd2
zzH+t1>B5O@zH`i;H$b02r=7?wo4SS!$}tX5DARuGhOF61j*dcfW)Y9UQ{icN_{o67
zAEwaJAYcZj0FOs;%hPTEYr>TBY;|p{l0G=@=PaLv>m8ZlBOEYWF`w`_v05$hf~Pf%
zK#k8``fiSQaSRALz*>$F-2~dMc~T%2R)+G!x!bU@O6t(Fa1>)3mZ0fHgrW9L!&I8I
z9Gn{O*<C4lo&7*BaY6nFoFU-wmbe$4TS>Z0=vIei(cN@w<4y*p&rgVZFf=#@lWb5N
zu(RnAV-B{ynPrti<FQp7W4lky!r`U%GUgtwFgneq&EI!e^ozZx!Rxn=oPtcJc}t2*
zS{psJ8z}PsNiY9ml<G3XOp;dVo|_Y65cnNXM=%9!Ouq~v19rt5#QVK@3^0M{uV23a
zBLeqb0K41E)1wzoy+#ST_W*D_%R%$?rSNg35|NNJ+6L;7dP$k9@Etp-{^V_6obagq
z-k&Kld!}>Mh$l2O^hcN&wX=(ZgM(euv4Vh~w4XwG|26tgAzz@XbA~+$t5Q%|bE=oW
zy7p!(9^*DhK2!8dPOpSleF2{Nfy9k0Ip4T1Q=CJq?_8TATcG=Vg|`l}-_FY&m*7Xw
z<U$9#1txqBY){mX(js-SrWstCR7JZ620S3QLBmYldcpKFkLHR&mW)Zd)6J&70z|)l
zxisr5-f2gOKMKvPUsWq2N;UZS-RlYqx!zd&PrR0YgA$zK_q%<Y`U`81nx5k=oy@l*
z#NUp`IwDp}z7p-8d~iOzh<lO+sEZ%(YgvF@lDx>macQ0llgL782_qR=Y^1|+Hq;s^
zG-#%)*Ry&s7^}UOd6y_l?w+o;{R7k$Z@nw7-3Kc}m4~r&47baRd5d4Wx8420jH$tC
zpOZdU!f^3_7YP5nL2TU=R3RWiD_8}2e|)??)CAwwSQIp%6B_Ql&U!#D=^~c0C4<b+
z!^QHLX;lo4xE+VXE#?o*2n88gam|$Dw&xdsYU4urq(HqE!4W#t_`1X2-+x$n_<NZ}
zO#$~!obM{4SM$YHk|N!tS7^voV7SK_l1LXHZmqPMHExdjyW2)&Op~nR9<>`=uNg&{
zG0v+ng@{$UPW$N>qE1pxEZT9GuBZf%y!H~kiZGNd!spNX!tljt)k*X7Rjx8(l0W9J
z(#yE{sCw0ZKyl$AiI0nV_6PW#KkY#+IH;6;7!nH72gHAlre+vC48?6oyh>LH#%VwU
zSwywW_D$2^rW6D+=0j**wr+PeJ5^tooW63sDPO3?z1+PC<Vh4ybPA)X<i&ynFo}F?
zAVM$JX2wqohED;-8MC1}OEPWOPpvEbxHSadNUl#ic7e^7&dc4UWK&W_HLX{@ag@LR
z4&&)=zRW|kf>H@DEUq)tZi4Y%Uexxu2lrqItoCX>fp9jriPKiQyF#WkqE=?wl((Ir
z`laX;rBw?U{tW)$El`N1d%x!y{dqUzQ#iKCXvEaaHm4=~Vd~@4k0_VDMEiI8Du1@}
z8C=lmmrKk0CoPAKiPIxZQ{fEi6am4TX%5AF-QJHV0B#s<8er5DBJp?7s|$I5Y%lx~
zFC%gOw2tSv4VYvEM<@_t#6cyTp}#1<&#KE>d#Z2(I6K6H@%_t`&K-`wSNL(KEt!!R
z?7VV&9npSS^)YCoNC%LKAm<SKus&4b4DR!UL((gL8O^{UsMt!L9al|o;D&`K73SrL
zAZg_@l#MIlS}bTLj}x5pd|P0CeHV>pI;1FImh;i^H^gWkgXN})d#bO}MXoZ^5ijQ{
zxyaCwN}6Lqwo&DH=iIXWha5!fws+`qj(Ti=2(p|ep^Ut|I#*CUD<*LjY;+1{@Ppx`
zTLF&+r&{ktO~)8+m)B|QvlSC@Zl@H_F^oBbkqIG#^*9I*L!TE^37w-wXJ=(mS_4EP
z$!QBr$|qwNthNir!%M2-c9BNE9c}~#DVv7IK_Sy;kcaR^%5?2;KAv5Mgnugk6d9w2
zpym)Kk!NOaBcY=Y##1Ql{*Ce16e?N7{KKWDcOL<Uk4z$Q*bMQ%$&Gy%KG2q(Jq4mC
zcD5?lE0O9+t5II1enuu8V&5gtS$$ruvT2cXWh$qg3A;fepug#8J^C(RFU8zz5^^Q`
zmEj~>!R#kG-q!n-Bz`|^AMZ~aUh#Hya9pX3_nWuXoHHd=`mWB^Y~N3<CQ(Hl`u{&1
zxBvWdXIv`JT4d!XB3F@JPFJyt^yb!BGT3u&?g~6x?d+U8bOt<{Rb<N>*kxrIobsY8
zBuyH<rF7knphbh}1n?F;%>%_+w;zYBgVRXvhRa_GhtJi|K(ts}8=sZTWN*QvgAsx2
zZ|TPQcfUba1kXLS)F-G>Wkzn@)^>RA49;G#a?@=FkC=o61I~6R8Q*1^7A+zS*`s@K
z|8-6X>fRn3+1e8q7q4fnR^54%&yM~%gj*1CJg7;-%>48*kqkS#9Z0}E-+}7CfbwFU
z(;%x3KW}xRBGB8<v)0*|DsU9aoUD%kc4o?AAY0TNPxab2i$Zl2tJ&+jLYeRt=pkc<
zDS^kTgiC}M`R)q}d_N(EQT>}5G?~B>Ft&p3W`VBvba?ig2co=#-P_NbtEp_uF5bFz
zEB`HY;t#^*e(*mP8`}d%L6Z)hSnMyy?A<UtwS&SYo)27-!0#%>fzivgXzyaeEBOp(
zJ6{zURD97Z2OwK^h=d;I+0Mc7pJUIxV`(|DmN(rge8RQaSecUQ>SJIxo?E^okTw4N
zJU>4n^{LQ6tPxca$Xk8Vxo0Q}ZWyLsQ1BM2qTGtddYXmw879PBxSJMo*G4aBzVfGE
zL?wAckhBu_HEusw2k%}@Wtq+Nh@CHL?2_EqFz!nK2o^e*Gmx+@Orn9dy81Y22*R=Z
z&7xEFtDt%v#%%<dokMGLGfXzRUEmtM4FR@~OX=QW)+Ht&GnhfrX!;V)cHHMr@osgE
zk`%agECF3dOAQ#&!D+*|f%?$R-|atRlqCoTi+D=$j!=U90wU-6W#7oNi!1Ohx&QJj
z`7fWQ6aA$6dg2zW>6QdlA#|A;>(Cz}I|Evx-3zsOnMSd&PqkDIMq%CsRLVP5uMUXs
zy+)N57j-KJ(E5Kj*?-HoFR?t327h@@Y`ayP!a^GJBd;T+%}aJaEORf@uQmHuymEW?
z@3+H(h5BCt=snFs2>ezVfgGnm8Y^`^E<Rp8+eyAeP#Iw%(B+R3(;hzlwLG6qxSqg-
zF)hIurc9yI2f4;KGD7Sues=cOk8*Fv7}Ngy@SuaQ0SG$6@DW{g@k^~6@LfLkYCuaD
zw*5i(imU7X+ur&f4oPdgZn@Eg87hbB$>;0Wn~Ab%e*RioZ%w&}U&8zCN|>?wIrP*Q
zn8a^i&HyCp>3u|XSFOTZ0K)(ud)>BrI~g-$Kv7n06QFa!fPA}|ZH<L;j^)SZPD09O
zJ}UJ_Rkb^$?=c65UToU`{eQJ(^brf_<vY0s4NuSN3{E*o$t{3%`oEn^O-oZ$P}rOg
zp}d)=U1BsEvqyt;rCM7c|EDn{AcEmns$faqga(c2yUa{KJW4+4<Z9d7Fi@Lm?J32!
zripJ8Q+fT&T^x72K{TTEpFV-b#XKm_J*Jy2ul75_*MiSd2Kc{ZVq+?F%`g;B%LH6X
zIn>pV3_zC<1R~nYmoM|*?&2K#ybKNx=Yk8gpgo0G)ll*Y#GEdT@7yvK1JM>~I+T=@
zAy|FA{u|RR)?eVT^4~gbI!`^<rvCi*2;;i$^BFvFghgFZIr#T(C}vEY3c%e;Vs5%<
zrx%)#sdAqpG`*D6!;-R{pFah!)bhROM6}2-J7bx8R-1yDxL?lfZabinxn)#8`9V;j
zS@mrURw4q#R;e%1_Yu|MIbtx~U<7ad@}?u^$H(2XE56+hY4mHIiUAKEK4#pJSzLXY
zu&4XxaQ6wXM4$M7I!vGrg60GuT_$i0h9N#MMA429_}mf*^Ck@rZ0Q~EKqpxMj|}Wx
z#=-xWTa-gp-@G7mV`qn6p4u}M7H>9s&b@)bM6Wz<QFb}V?~+%b8Z2T$#=r)F2LqQF
z85s5m@&P9d7zlzDm;qpc1tW>{*=Iq~4I<NBcbE;%SEU)(-orp^urfc-*{8n;XlMx_
z%CM1<GWzSezlsO$Ph-%3L(bd+IFlH&y0{2*TQMxFaGR_p+OCF=`T8}o%Mqk^Y|5-(
z@<7f7Ps_H(0bk%04-Bvyy91Q~G=o~?f*UNDq_eF7G(U^D0!q?$#r;21d*pzot8jIj
zBJvfJ7Vw4+Be@GtCFT)gg(D=i0xCJ3OEDxhlPO6_6iRAw9epXS+<TXH0Qva{R$zX9
ze!8shBbj4l)Q%p~ZEDOyBS5t=4j4DcuRoLzv1x7PkNg28DiGc<AC9a)>-B~nB46~4
zHVo0pP_&XOlQJarE2pH_#pbi_oK~~dp1MnVEisjFJ;ZqM&wMv(oQ-1M_ImwlZF<6a
zer0^JzH!u(q$mZv%4;H%xHWRTh@{9o4|t!Bto**vw8D#@i-jsv(guHSZy!LrHLQ0P
zNT4cYQH9ud1oq*wcXBGV7BT6!4rEvz0s7Xyb*`C(g#|wI{Z%MY7F2+uct1Ve3Zenf
z@n~{I+=8b-jUM&@ivoVg@i!3r*j>UI+;AI!Q4!istJ$$H^#^uK(|H<6f&=QH4cS=O
zc<Z-1c@g+$vrEAv$72OHtwFJEgxPFmA<8fBY|J}0fm;F&?a+@7l_7R&b9uZja;#py
z@(5slFo2NvtCKw~FOPkc)d%ptS!h`EsDxd<EicFYJ_7qk)Y@lDz|28lQ+ZEA>9{|0
z5JIBZnX#JyD94lo=F2|EegW9D6TyaVh0#Xgui)E7*MffI#u<;TpZe*1RLsl?he4ps
z*Gf1O`k9uV{xYx`<32vY_K#Ay7Zw)mn`+J;CMCpSVLj`EqBD+R9bSfxvUrTAuYm{{
z8`T9T7Ul^eShoRaK%BRs*c*F3#>*qZaV@mZz%<RYAc(a^;XCyg|6IC^h(U5CU|tS*
zIaapcN+<!0QpC&Mb@=n#HS#p`w+S+z{;|xcmitm5Oj&u2^LPq8OgTKa#C`WAKmoci
zCJu;JA56{LeKa$hnc~U>wC7#TxGf0xt}xbg`$Ek=Trh;XbLS2K*obX|53PuGMwC`w
zO2?rC(M>mHP?N&x1`vUIW)nhB$JVuzRly)e+Y)wO%u&8~UsS*fRvQRW{NO_BR7^wc
zas9M7KmP&7+a_V&RODg>45C9BUF<E6W;$Ryb5j8LZNROV=9lz+%s+xRiTW%sz@2LA
zG46FHi9lCFP}SNFTh*#6{Ok=(zavG!+!>P-^7j)#!Ho=htR$Vt_gz55u%#fL9Ewlf
zMWA*nYq8HXQ70ZU);vs3&a0go4+$=10e&tjjlE#lh>n7E*j>uCi7S}3XFt0pi2ts(
zgNB=VcVJrkkB^?yk^xK_fABT;l-jjEFHl-|W~@U-DUWUBJvAEspOUzkfN@X|;^Y86
z&WO0RR(i2c$+ZbCsw~I@YC3>p0;-VjkRMzO0-`D0nSxMoY8r3gK8KC$y3nekYL6fR
zRUg4u;@K-!aVzZX>-z?~L1@1!pjIpZ0jc(arwkvzpd2>fm;r!fjB9ku$?5FC3~b?n
zvmJNxHrcW0SjR_#aLYbol}<2%>BUq{O-=1dIen<3vAFq^@0Dq%8-3&d{kg6U<)3uV
z1twuCaI)2FA*!WC(Y+&V@bP&P#c9B?xWb2Ta~yjo$io!-q}d6KA{dBF-UU05$Oj)#
z@#A>#>D1P`q&eB*)D~?D(M)TZpYL_Mg|y9(4_Y7cE)P&!cupDy9DG@tz%0HT8Jeix
zsulPzndOHo2qc#v9`ElXPxGvsbkMW$QYa3ANLDVD>;zb-q^BJB#gx6hJ!nJ-SBVX7
zC*$6^IquO|!wo`iQ6OJoj%q$@Hw9$bDUNIuJ^tV^0^J#sTlgkm=nnXt2Vb?HoF#vE
z9^vt<3y~J?O_%b<BVr7+-~IxUpqxDy?by`E7W2fj%mO{7b^f2gK!R=po~D)za}{R$
zCh5?D@UG!Z!>a}TQbKGjzisP2jCO(y6?FVy&eYj7(#O?)`t<4a<Jl|tSz(ZA0|~zh
zzA!`bL$kXZ3tH~dF?)YBKNlu^@-8?CdvnWCK_cC`?+NfQMC%?d(YE)_?8qz(7n~pZ
zPxm_tPpwMSy1p8Q(+_Tg?BrMv`iX6IWu=TK#6-PPMTz24Al&8DpoIpA0M3b66-iC7
zBgk`Cb7{i4B4f`C8bQ*XeR$DHlOB@MyNcBbwG;}l3x(Px5Hc;eX?4tPaUm83PD$#W
zrHEJ3>Su(TCpeD_1R5wN3!-NSbCr8+D@ITtz#mp8a>pblLO_e(V}R?}iN=&^!KB}D
zOBy_iq5!`in8r811G28gK6oPbfwQkeL6F<t4Q@zRfX3V1P2jIesi!;#$>we7s+O$x
zHxMv!??vIZehOJN)PI}dixI`X|M?^Nt>4CALer#EP$!nk!c*MDPcNvT>y|gkf2{IN
zLWh2VY10kh`~m)UM=}gJ-6ZGHh8F*U&5N@bxLlVYd~f<A7S`WiK%J1Do~{)9JMUQ-
z$vT`M7<+dirU?Z>0g0TP+?&O@aX6P3U@dQ|ZTTpA$~gj12=nJQib1zv)1GHueKgCN
zGci%d-?nQKX9()Z3S*<pw&R@E@{T8H+dchO#%ln2DvJgRaDH&qr3sks2*w;hJ+<AX
zKSza!t3#mmBFh_lZdy#dnk;%O%=;%A{w`aM;?UASJY|5tyal`~^DnqH+_Hn_m6yl{
zm}IMA#$P9?7vb16SJ-WrUZbv^oO5$>`qXysUJzBmbI>3<u#rKv(AIjS@b0^+>FAT%
z(b44iyOP4XyW7#?IO{pq`P_>irgq3*lK+>>3b6(5W7JL~j4**Z@-dyvjdX1djn{qc
zb?rvBAa2|jVcvs^9tm-}t>QnSg%Y)GW#(~w^Z*7vRxou&3bGFzxmvIFkOvLJbg5<^
zs9K!mVFv2YNaqItc*je2xHi&$tOBh*Zq_WW3sQP(gKf<_{{Fy3y24R(Xx0!xoW>Ry
zbzl5cLam%(`~yWAJj19(mDpW<llyV0j&r?iI^Gu?*a#y!Op23}mKm06J76yDV1FOG
z53V0FKM^Qbgxj`2yM)=f(}MVT>WY3|)5kJbG4K~ujUP}J78w~Ae?q0xdkbh@)l?0S
z2LGQW+-D6|R1Rzw1@TCJsivD4v|B*qI5O887js_Yl7RuKRI*q{M+f-C>*VTfS}4hQ
z>*kEh18oEKD7awtc4M!_2TR7>V_*pSGV_S{8Y_YJ=Uy4B{kLV%E;^FVKK$wA{kctd
zJm5dJ1$0Okm+q0q2wx?sgfmM24B&haO~wKjxj?-Z&Pa=lUvnCLUz(jg@kgX@=REA$
zTV7dtI?a_<gq0S@Y4=ji_Z+JpeJ%nLE|28>c<#0nC&(mpHB`+XCvR;&HS&IEl^$&!
z;P+Mj(|?RSLdh^p%s0h*UJhykpzGlZTf%fQqSG8!MMNeOd0P0V5M|;>0J7%>;8vh7
z3sUYl6mZbigg#e$zKfha03CPP?v)moAeGF!@1f%yAHI6k+ID+qIJO=se)#==`u3HK
z`Pt;e#Bnh(#`luf!MMlW)m#NM7jey1;I?<Jz^GX%=RtaX1U%3p-s_~-b?>Gn*DSw(
z`D3(mF~Qe!F>*%L)co`JQ@rnHxn1;r4In*$(xWC^(ok3Jr8dzx#!EdKN&-+x(Xl-M
zHP$<|Qe;rM9Geb<$|TwF&2|D>h=}7i{nH;lrrVLhJCy&jPVdskaO+KsuO~F#FZ|Gf
zU^><B7o1^za!d&{o;#W*5}*aR)FWj4v+Uk0ZekhKJ2j(~qL(UP^3C#m482M=hiSAu
znKL5~WlU3#90X)VlmNb1+?;YgDm8VTd{R2cad{s)$Bv-0ZMsOa-4bAw`l+30yZKg2
zCeC&qi`lwcU0PaN_xqskfV@eQz4iEl?uiN6bLUKhxzhwenUZ%nmdckQ?<dl8pC22W
z?PKWiZ+~@x1j&I{5#Hl3Pc}?k%F7vUOfF1g9+||Z)Qrb$lIZ!TQSM`&Nvp2gH0ls0
zabU7*+RAg7*q^v`j>=<NU@rS{U1Z;N<5f5f{<bvdp|1n+#?(1|1CiTDhry$5S5D&t
zR=O}Qj&F`=QpW-uL(`sEVs$<6N@b|`oa4A;hL68H?uGoPzped~;Z5ycHW9tI6CAwG
z@PNCg8-Z3frNlQsa#^^aS&OJ99Xya4ztp(adxKGYdjN%uvUhZ-2lHJEHeLnSy&(7y
z!0mj8_GV1`T*Dg(GbTr_x-_srcN_**g3nwFrj!Q*X5;TE_=KH(?`gKUrNhj!VuK{R
zsF<~H<Vy^fhm<&|hBWKf+8Re?4rJi`@Nk=LBT0_5y|??z@(%DMMT3PPny~-G${o>q
ziP`Dg|9lcq*sV>z(nmfCv>N`9^LHfsaOIkyqrJq|w@6&(fBZCJSRT(j>bp)U51^u}
z;)~aP?}h$9A0Z3-PR*&nEJfL2c`Q=CuZE%WeaCI>Lt4K6!Zn51z|+6i?@C3X3|d}J
zLAV5%Q}@B;4SR1gbD0X32S=@Zu7_Xm9Xde=yRpGQ&zANiZ@}d5v16YBRnTBf+S{QQ
z9c+onA>hrIXrRiPhtmk};J!h-F*AQ(lQ`{>fWTJV5yokbpGddeDHyxd3vcAnSC6xr
zPVY!F9zKp^NiCSRD*S}nbw)k~vi*DS8n-bkF718S%e@<_fYE{?bhJm}(iiY5D)WDJ
z#?k^Tb$Sd%!ik~Fj=T~}@fvqY>314aJO2QUPl-&}0^g2!I@Vmp5?iTM_&!bi>}=Z5
z<*&i&RlCtw|M;yw;cLr7@U+$)q0irOgu|{qVNY`D8Er%VflTwcHMr?FUc&ha7@V)T
z%F%PmANUj?1`X~h*Qta~YGoIG8FO&N;anT9Q4dzQb^+}%1v+7}SEt!R(yZ3P7r(5o
zKD#vE;TiWfc&k(<jQZ+YxP}wo{q)8B3_ZeNmb(Y`Wj!qbn3<<O&R_;aX?Dg#bGko+
zjgm)K{MN=`y*3Aty_95vRb)=a?@y?sugXWz#T)AMHnnBeNR=%kQ@E3~-p)0kif~li
zwmefA>KH9|`E4=_vwTCs@VI@bH$x#V6=5Bmk&3}C3$g?L`?E6r*S+bq_3}i`FXevf
zj-j|u+7cjocyS9e+Y66nMj=@GtX=KV$fup0c2t`};FC)oL~R>lQtZ12h3+I7wMpIZ
zY?$r@1bhh>-}T3b;cD~x7l*Hi$jCsXy9VvX*jb0CCzdDr`iOk19?qRq=?5o$lVG}T
zId&8{D~>Wc<A%bpY=IKhH5PAnW4Y4$&t1qhz3-it)s=D@OY*>7p+rq&=0f@@*V5(-
zq<<Dvcenj+$G&mwiPq5HZ26JkVqiLA_ulquecFvm(KC5DDeX#(X6qAcM}OLmtiUT6
z^6%K$YeI=hNrUjJjOY4)AMpVgJ<}3c_uD#w*3-{V+r1KhSByp;X6BZu#UJuI)pYa;
zf9lOt!7Ht|?l=w_ON_av;UT>cHd0M{n8gS&Dt)&zBf7nM)GJBdlsaw0NLM^D)?vN2
zw++{9K5bgCmLa)mt8+9E%>>#KsI=r~gghLd<OP`YmAPJAx|e>m|5X|44k)88=BCu}
z!A?q5MW*1|Q>q|%>WE*pe8Aje7*L{;_4#RkDPj5mzeruL<?&+)HA>*(p)oVIK46hj
zyE6H9=2n~BI@2mWUPoe>=X!|rU`Gwhm+jX#Zn-((Tk1O*l)Fm<(V+~a=Zys;o=uT5
z3v*Ec%d6|Zbqozr-rmsKJ^bCA5UDa%5OrJ3-mH;X9*}~s<29$t#@X)fw!eL=e|5dl
zKJ+OuPn{7JU$$A+_Fg)YLM$H`8TkmfDU=ih<;H~al<W2}NH;9Z|4g2HNZM^Kg_gf+
zGvf@6JhM67sf%%OV-~GC6j0I4+&fZivvDD7ZfP;8E3@}4{!TED%yVArna|UM^`FIG
zsdA)*k{?v-cyq~gStc17dExb>Jg7D=FjE!3{^a>(-ZtGkdrh}Gb8*Be!r|8TDE{_4
z->-mk?m>P=|1|2T?P%u+*^UQ7s=LXKs>YdRrshHwm#;1mKu!7{8h3y*`{L;>h)21L
zyih2usftPrA<h4MY4);r@TGBt4@!H;NgT<9GCmU;deQZmBKPD4K{{6G3>*Ua(Vjkc
zv69q<(**~)S~J0q&rnq!zKc@5z^Tn)#t>J&;w}wJjcvG%KlOF!+IxCVJ%|;!_{rOF
zZ~f@-7Tge@cy)Dmzu3`c+-1u14K5?RqZN$>xA7v7^$cxy9I5zF-U=duRyyp49(3*V
zeTlO)PO3sV^Mr;zbe)W`hWMjB=U<Cor{XI~E==f7f4EA34TQZ%j_~yqE;`*;9m~fx
zNh~w)J-Ew=r9`%^LFEKMSz>Ig$vyGHlcP+o6uvQ!Ygfn!;<7<R?zysf#+)T}5`+Z8
ztn%N4l6mqLZ}5bEknOU>{ay?K6FXAlT42^LzWpu8!63L3Rr;2iz&{|MKpXbJpkadj
zYb<S&8;&_m1<8Y`3U&Ouza>@Ja220H7xW%jK>%4n3b8!X?x+nl)2M1<{xqesR$!$Z
zRn5!bKdAdG2gWOI(EEVC5!n5Y@hpZOvg-WF7m<i9a%$1=_|R*K^rW1&rl=Q?DIv{I
z;CC!y?iuZIm)>ZDOAb;;nCVh;MjTiHZG$<<xw$!AT`9RxhqdqumB_p+#<FFc=A-a?
zCN5=izV26WtZ{ayfei+SiCdr@fIFxuG`BOWW^y!yt7~p<Zfu+kUYxE3E*>z*R91=H
z2O00J!UPsTQ}<8YXQBPleP5uVM#WP6GCL%5DPBk`)Kl6ukus)XH&0$B>=}*jl`6@b
zI@_IYgAop4g}4G@8yLGweEAZ*Ueb<~wFoYT605$-^ETF$D^0DD+1S_s5Lgas8MvpQ
zC<FR-RJm4#b5zy`OSydNRZ*49_l}yM91(K$9v2c==&<VJ$M@rUyl@fnhSbN+nfd23
z`soC_((N(t#Yj7le-li`Q4;_2pJV^}<xA1-(#O9~+F=1+YJdL#={4W~_lN&4d>V)M
Yl&)$RWernrpMZaKH4QbY)a=6k7kqm;RsaA1

literal 334122
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%0D^D-;9%vjSF!PeJj?}XHt4@&Wdno?`<E~jbv
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
QiMXtUsH{ktu&)3A2ckfRj{pDw

diff --git a/doc/modules/benchmark.rst b/doc/modules/benchmark.rst
new file mode 100644
index 0000000000..71b84adde9
--- /dev/null
+++ b/doc/modules/benchmark.rst
@@ -0,0 +1,141 @@
+Benchmark module
+================
+
+This module contains machinery to compare some sorters against ground truth in many multiple situtation.
+
+
+..notes::
+
+    In 0.102.0 The previous :py:func:`~spikeinterface.comparison.GroundTruthStudy()` has been replaced by
+    :py:func:`~spikeinterface.benchmark.SorterStudy()`
+
+
+This module also aims to benchmark sorting components (detection, clustering, motion, template matching) using the
+same base class :py:func:`~spikeinterface.benchmark.BenchmarkStudy()` but specialized to a targeted component.
+
+By design, the main class handle the concept of "levels" : this allows to compare several complexities at the same time.
+For instance, compare kilosort4 vs kilsort2.5 (level 0) for different noises amplitudes (level 1) combined with
+several motion vectors (leevel 2).
+
+**Example: compare many sorters : a ground truth study**
+
+We have a high level class to compare many sorters against ground truth: :py:func:`~spikeinterface.benchmark.SorterStudy()`
+
+
+A study is a systematic performance comparison of several ground truth recordings with several sorters or several cases
+like the different parameter sets.
+
+The study class proposes high-level tool functions to run many ground truth comparisons with many "cases"
+on many recordings and then collect and aggregate results in an easy way.
+
+The all mechanism is based on an intrinsic organization into a "study_folder" with several subfolders:
+
+  * datasets: contains ground truth datasets
+  * sorters : contains outputs of sorters
+  * sortings: contains light copy of all sorting
+  * metrics: contains metrics
+  * ...
+
+
+.. code-block:: python
+
+    import matplotlib.pyplot as plt
+    import seaborn as sns
+
+    import spikeinterface.extractors as se
+    import spikeinterface.widgets as sw
+    from spikeinterface.benchmark import SorterStudy
+
+
+    # generate 2 simulated datasets (could be also mearec files)
+    rec0, gt_sorting0 = generate_ground_truth_recording(num_channels=4, durations=[30.], seed=42)
+    rec1, gt_sorting1 = generate_ground_truth_recording(num_channels=4, durations=[30.], seed=91)
+
+    datasets = {
+        "toy0": (rec0, gt_sorting0),
+        "toy1": (rec1, gt_sorting1),
+    }
+
+    # define some "cases" here we want to test tridesclous2 on 2 datasets and spykingcircus2 on one dataset
+    # so it is a two level study (sorter_name, dataset)
+    # this could be more complicated like (sorter_name, dataset, params)
+    cases = {
+        ("tdc2", "toy0"): {
+            "label": "tridesclous2 on tetrode0",
+            "dataset": "toy0",
+            "params": {"sorter_name": "tridesclous2"}
+        },
+        ("tdc2", "toy1"): {
+            "label": "tridesclous2 on tetrode1",
+            "dataset": "toy1",
+            "params": {"sorter_name": "tridesclous2"}
+        },
+        ("sc", "toy0"): {
+            "label": "spykingcircus2 on tetrode0",
+            "dataset": "toy0",
+            "params": {
+                "sorter_name": "spykingcircus",
+                "docker_image": True
+            },
+        },
+    }
+    # this initilizes a folder
+    study = SorterStudy.create(study_folder=study_folder, datasets=datasets, cases=cases,
+                                    levels=["sorter_name", "dataset"])
+
+
+    # This internally do run_sorter() for all cases in one function
+    study.run()
+
+    # Run the benchmark : this internanly do compare_sorter_to_ground_truth() for all cases
+    study.compute_results()
+
+    # Collect comparisons one by one
+    for case_key in study.cases:
+        print('*' * 10)
+        print(case_key)
+        # raw counting of tp/fp/...
+        comp = study.get_result(case_key)["gt_comparison"]
+        # summary
+        comp.print_summary()
+        perf_unit = comp.get_performance(method='by_unit')
+        perf_avg = comp.get_performance(method='pooled_with_average')
+        # some plots
+        m = comp.get_confusion_matrix()
+        w_comp = sw.plot_agreement_matrix(sorting_comparison=comp)
+    
+    # Collect synthetic dataframes and display
+    # As shown previously, the performance is returned as a pandas dataframe.
+    # The spikeinterface.comparison.get_performance_by_unit() function,
+    # gathers all the outputs in the study folder and merges them into a single dataframe.
+    # Same idea for spikeinterface.comparison.get_count_units()
+
+    # this is a dataframe
+    perfs = study.get_performance_by_unit()
+
+    # this is a dataframe
+    unit_counts = study.get_count_units()
+
+    # Study also have several plotting methods for plotting the result
+    study.plot_agreement_matrix()
+    study.plot_unit_counts()
+    study.plot_performances(mode="ordered")
+    study.plot_performances(mode="snr")
+
+
+
+
+Benchmark spike collisions
+--------------------------
+
+SpikeInterface also has a specific toolset to benchmark how well sorters are at recovering spikes in "collision".
+
+We have three classes to handle collision-specific comparisons, and also to quantify the effects on correlogram
+estimation:
+
+  * :py:class:`~spikeinterface.comparison.CollisionGTComparison`
+  * :py:class:`~spikeinterface.comparison.CorrelogramGTComparison`
+
+For more details, checkout the following paper:
+
+`Samuel Garcia, Alessio P. Buccino and Pierre Yger. "How Do Spike Collisions Affect Spike Sorting Performance?" <https://doi.org/10.1523/ENEURO.0105-22.2022>`_
diff --git a/doc/modules/comparison.rst b/doc/modules/comparison.rst
index edee7f1fda..66451c0e87 100644
--- a/doc/modules/comparison.rst
+++ b/doc/modules/comparison.rst
@@ -5,6 +5,10 @@ Comparison module
 SpikeInterface has a :py:mod:`~spikeinterface.comparison` module, which contains functions and tools to compare
 spike trains and templates (useful for tracking units over multiple sessions).
 
+.. note::
+
+    In version 0.102.0 the benchmark part of comparison has moved in the new :py:mod:`~spikeinterface.benchmark`
+
 In addition, the :py:mod:`~spikeinterface.comparison` module contains advanced benchmarking tools to evaluate
 the effects of spike collisions on spike sorting results, and to construct hybrid recordings for comparison.
 
@@ -242,135 +246,6 @@ An **over-merged** unit has a relatively high agreement (>= 0.2 by default) for
 
     cmp_gt_HS.get_redundant_units(redundant_score=0.2)
 
-
-**Example: compare many sorters with a Ground Truth Study**
-
-We also have a high level class to compare many sorters against ground truth:
-:py:func:`~spikeinterface.comparison.GroundTruthStudy()`
-
-A study is a systematic performance comparison of several ground truth recordings with several sorters or several cases
-like the different parameter sets.
-
-The study class proposes high-level tool functions to run many ground truth comparisons with many "cases"
-on many recordings and then collect and aggregate results in an easy way.
-
-The all mechanism is based on an intrinsic organization into a "study_folder" with several subfolders:
-
-  * datasets: contains ground truth datasets
-  * sorters : contains outputs of sorters
-  * sortings: contains light copy of all sorting
-  * metrics: contains metrics
-  * ...
-
-
-.. code-block:: python
-
-    import matplotlib.pyplot as plt
-    import seaborn as sns
-
-    import spikeinterface.extractors as se
-    import spikeinterface.widgets as sw
-    from spikeinterface.comparison import GroundTruthStudy
-
-
-    # generate 2 simulated datasets (could be also mearec files)
-    rec0, gt_sorting0 = generate_ground_truth_recording(num_channels=4, durations=[30.], seed=42)
-    rec1, gt_sorting1 = generate_ground_truth_recording(num_channels=4, durations=[30.], seed=91)
-
-    datasets = {
-        "toy0": (rec0, gt_sorting0),
-        "toy1": (rec1, gt_sorting1),
-    }
-
-    # define some "cases" here we want to test tridesclous2 on 2 datasets and spykingcircus2 on one dataset
-    # so it is a two level study (sorter_name, dataset)
-    # this could be more complicated like (sorter_name, dataset, params)
-    cases = {
-        ("tdc2", "toy0"): {
-            "label": "tridesclous2 on tetrode0",
-            "dataset": "toy0",
-            "run_sorter_params": {
-                "sorter_name": "tridesclous2",
-            },
-        },
-        ("tdc2", "toy1"): {
-            "label": "tridesclous2 on tetrode1",
-            "dataset": "toy1",
-            "run_sorter_params": {
-                "sorter_name": "tridesclous2",
-            },
-        },
-
-        ("sc", "toy0"): {
-            "label": "spykingcircus2 on tetrode0",
-            "dataset": "toy0",
-            "run_sorter_params": {
-                "sorter_name": "spykingcircus",
-                "docker_image": True
-            },
-        },
-    }
-    # this initilizes a folder
-    study = GroundTruthStudy.create(study_folder=study_folder, datasets=datasets, cases=cases,
-                                    levels=["sorter_name", "dataset"])
-
-
-    # all cases in one function
-    study.run_sorters()
-
-    # Collect comparisons
-    #
-    # You can collect in one shot all results and run the
-    # GroundTruthComparison on it.
-    # So you can have fine access to all individual results.
-    #
-    # Note: use exhaustive_gt=True when you know exactly how many
-    # units in the ground truth (for synthetic datasets)
-
-    # run all comparisons and loop over the results
-    study.run_comparisons(exhaustive_gt=True)
-    for key, comp in study.comparisons.items():
-        print('*' * 10)
-        print(key)
-        # raw counting of tp/fp/...
-        print(comp.count_score)
-        # summary
-        comp.print_summary()
-        perf_unit = comp.get_performance(method='by_unit')
-        perf_avg = comp.get_performance(method='pooled_with_average')
-        # some plots
-        m = comp.get_confusion_matrix()
-        w_comp = sw.plot_agreement_matrix(sorting_comparison=comp)
-
-    # Collect synthetic dataframes and display
-    # As shown previously, the performance is returned as a pandas dataframe.
-    # The spikeinterface.comparison.get_performance_by_unit() function,
-    # gathers all the outputs in the study folder and merges them into a single dataframe.
-    # Same idea for spikeinterface.comparison.get_count_units()
-
-    # this is a dataframe
-    perfs = study.get_performance_by_unit()
-
-    # this is a dataframe
-    unit_counts = study.get_count_units()
-
-    # we can also access run times
-    run_times = study.get_run_times()
-    print(run_times)
-
-    # Easy plotting with seaborn
-    fig1, ax1 = plt.subplots()
-    sns.barplot(data=run_times, x='rec_name', y='run_time', hue='sorter_name', ax=ax1)
-    ax1.set_title('Run times')
-
-    ##############################################################################
-
-    fig2, ax2 = plt.subplots()
-    sns.swarmplot(data=perfs, x='sorter_name', y='recall', hue='rec_name', ax=ax2)
-    ax2.set_title('Recall')
-    ax2.set_ylim(-0.1, 1.1)
-
-
 .. _symmetric:
 
 2. Compare the output of two spike sorters (symmetric comparison)
@@ -540,32 +415,4 @@ sorting analyzers from day 1 (:code:`analyzer_day1`) to day 5 (:code:`analyzer_d
 
 
 
-Benchmark spike collisions
---------------------------
-
-SpikeInterface also has a specific toolset to benchmark how well sorters are at recovering spikes in "collision".
-
-We have three classes to handle collision-specific comparisons, and also to quantify the effects on correlogram
-estimation:
-
-  * :py:class:`~spikeinterface.comparison.CollisionGTComparison`
-  * :py:class:`~spikeinterface.comparison.CorrelogramGTComparison`
-  * :py:class:`~spikeinterface.comparison.CollisionGTStudy`
-  * :py:class:`~spikeinterface.comparison.CorrelogramGTStudy`
-
-For more details, checkout the following paper:
-
-`Samuel Garcia, Alessio P. Buccino and Pierre Yger. "How Do Spike Collisions Affect Spike Sorting Performance?" <https://doi.org/10.1523/ENEURO.0105-22.2022>`_
-
-
-Hybrid recording
-----------------
-
-To benchmark spike sorting results, we need ground-truth spiking activity.
-This can be generated with artificial simulations, e.g., using `MEArec <https://mearec.readthedocs.io/>`_, or
-alternatively by generating so-called "hybrid" recordings.
-
-The :py:mod:`~spikeinterface.comparison` module includes functions to generate such "hybrid" recordings:
 
-  * :py:func:`~spikeinterface.comparison.create_hybrid_units_recording`: add new units to an existing recording
-  * :py:func:`~spikeinterface.comparison.create_hybrid_spikes_recording`: add new spikes to existing units in a recording
diff --git a/src/spikeinterface/benchmark/benchmark_sorter.py b/src/spikeinterface/benchmark/benchmark_sorter.py
index 5f3e584b20..1f2dde3b32 100644
--- a/src/spikeinterface/benchmark/benchmark_sorter.py
+++ b/src/spikeinterface/benchmark/benchmark_sorter.py
@@ -15,7 +15,7 @@
 # )
 
 
-
+# TODO later integrate CollisionGTComparison optionally in this class.
 
 
 class SorterBenchmark(Benchmark):
diff --git a/src/spikeinterface/comparison/collision.py b/src/spikeinterface/comparison/collision.py
index 574bd16093..cff87e7a57 100644
--- a/src/spikeinterface/comparison/collision.py
+++ b/src/spikeinterface/comparison/collision.py
@@ -171,72 +171,75 @@ def compute_collision_by_similarity(self, similarity_matrix, unit_ids=None, good
 
         return similarities, recall_scores, pair_names
 
-
-class CollisionGTStudy(GroundTruthStudy):
-    def run_comparisons(self, case_keys=None, exhaustive_gt=True, collision_lag=2.0, nbins=11, **kwargs):
-        _kwargs = dict()
-        _kwargs.update(kwargs)
-        _kwargs["exhaustive_gt"] = exhaustive_gt
-        _kwargs["collision_lag"] = collision_lag
-        _kwargs["nbins"] = nbins
-        GroundTruthStudy.run_comparisons(self, case_keys=None, comparison_class=CollisionGTComparison, **_kwargs)
-        self.exhaustive_gt = exhaustive_gt
-        self.collision_lag = collision_lag
-
-    def get_lags(self, key):
-        comp = self.comparisons[key]
-        fs = comp.sorting1.get_sampling_frequency()
-        lags = comp.bins / fs * 1000.0
-        return lags
-
-    def precompute_scores_by_similarities(self, case_keys=None, good_only=False, min_accuracy=0.9):
-        import sklearn
-
-        if case_keys is None:
-            case_keys = self.cases.keys()
-
-        self.all_similarities = {}
-        self.all_recall_scores = {}
-        self.good_only = good_only
-
-        for key in case_keys:
-            templates = self.get_templates(key)
-            flat_templates = templates.reshape(templates.shape[0], -1)
-            similarity = sklearn.metrics.pairwise.cosine_similarity(flat_templates)
-            comp = self.comparisons[key]
-            similarities, recall_scores, pair_names = comp.compute_collision_by_similarity(
-                similarity, good_only=good_only, min_accuracy=min_accuracy
-            )
-            self.all_similarities[key] = similarities
-            self.all_recall_scores[key] = recall_scores
-
-    def get_mean_over_similarity_range(self, similarity_range, key):
-        idx = (self.all_similarities[key] >= similarity_range[0]) & (self.all_similarities[key] <= similarity_range[1])
-        all_similarities = self.all_similarities[key][idx]
-        all_recall_scores = self.all_recall_scores[key][idx]
-
-        order = np.argsort(all_similarities)
-        all_similarities = all_similarities[order]
-        all_recall_scores = all_recall_scores[order, :]
-
-        mean_recall_scores = np.nanmean(all_recall_scores, axis=0)
-
-        return mean_recall_scores
-
-    def get_lag_profile_over_similarity_bins(self, similarity_bins, key):
-        all_similarities = self.all_similarities[key]
-        all_recall_scores = self.all_recall_scores[key]
-
-        order = np.argsort(all_similarities)
-        all_similarities = all_similarities[order]
-        all_recall_scores = all_recall_scores[order, :]
-
-        result = {}
-
-        for i in range(similarity_bins.size - 1):
-            cmin, cmax = similarity_bins[i], similarity_bins[i + 1]
-            amin, amax = np.searchsorted(all_similarities, [cmin, cmax])
-            mean_recall_scores = np.nanmean(all_recall_scores[amin:amax], axis=0)
-            result[(cmin, cmax)] = mean_recall_scores
-
-        return result
+# This is removed at the moment.
+# We need to move this maybe one day in benchmark.
+# please do not delete this
+
+# class CollisionGTStudy(GroundTruthStudy):
+#     def run_comparisons(self, case_keys=None, exhaustive_gt=True, collision_lag=2.0, nbins=11, **kwargs):
+#         _kwargs = dict()
+#         _kwargs.update(kwargs)
+#         _kwargs["exhaustive_gt"] = exhaustive_gt
+#         _kwargs["collision_lag"] = collision_lag
+#         _kwargs["nbins"] = nbins
+#         GroundTruthStudy.run_comparisons(self, case_keys=None, comparison_class=CollisionGTComparison, **_kwargs)
+#         self.exhaustive_gt = exhaustive_gt
+#         self.collision_lag = collision_lag
+
+#     def get_lags(self, key):
+#         comp = self.comparisons[key]
+#         fs = comp.sorting1.get_sampling_frequency()
+#         lags = comp.bins / fs * 1000.0
+#         return lags
+
+#     def precompute_scores_by_similarities(self, case_keys=None, good_only=False, min_accuracy=0.9):
+#         import sklearn
+
+#         if case_keys is None:
+#             case_keys = self.cases.keys()
+
+#         self.all_similarities = {}
+#         self.all_recall_scores = {}
+#         self.good_only = good_only
+
+#         for key in case_keys:
+#             templates = self.get_templates(key)
+#             flat_templates = templates.reshape(templates.shape[0], -1)
+#             similarity = sklearn.metrics.pairwise.cosine_similarity(flat_templates)
+#             comp = self.comparisons[key]
+#             similarities, recall_scores, pair_names = comp.compute_collision_by_similarity(
+#                 similarity, good_only=good_only, min_accuracy=min_accuracy
+#             )
+#             self.all_similarities[key] = similarities
+#             self.all_recall_scores[key] = recall_scores
+
+#     def get_mean_over_similarity_range(self, similarity_range, key):
+#         idx = (self.all_similarities[key] >= similarity_range[0]) & (self.all_similarities[key] <= similarity_range[1])
+#         all_similarities = self.all_similarities[key][idx]
+#         all_recall_scores = self.all_recall_scores[key][idx]
+
+#         order = np.argsort(all_similarities)
+#         all_similarities = all_similarities[order]
+#         all_recall_scores = all_recall_scores[order, :]
+
+#         mean_recall_scores = np.nanmean(all_recall_scores, axis=0)
+
+#         return mean_recall_scores
+
+#     def get_lag_profile_over_similarity_bins(self, similarity_bins, key):
+#         all_similarities = self.all_similarities[key]
+#         all_recall_scores = self.all_recall_scores[key]
+
+#         order = np.argsort(all_similarities)
+#         all_similarities = all_similarities[order]
+#         all_recall_scores = all_recall_scores[order, :]
+
+#         result = {}
+
+#         for i in range(similarity_bins.size - 1):
+#             cmin, cmax = similarity_bins[i], similarity_bins[i + 1]
+#             amin, amax = np.searchsorted(all_similarities, [cmin, cmax])
+#             mean_recall_scores = np.nanmean(all_recall_scores[amin:amax], axis=0)
+#             result[(cmin, cmax)] = mean_recall_scores
+
+#         return result
diff --git a/src/spikeinterface/comparison/correlogram.py b/src/spikeinterface/comparison/correlogram.py
index 0cafef2c12..717d11a3fa 100644
--- a/src/spikeinterface/comparison/correlogram.py
+++ b/src/spikeinterface/comparison/correlogram.py
@@ -128,57 +128,60 @@ def compute_correlogram_by_similarity(self, similarity_matrix, window_ms=None):
         return similarities, errors
 
 
-class CorrelogramGTStudy(GroundTruthStudy):
-    def run_comparisons(
-        self, case_keys=None, exhaustive_gt=True, window_ms=100.0, bin_ms=1.0, well_detected_score=0.8, **kwargs
-    ):
-        _kwargs = dict()
-        _kwargs.update(kwargs)
-        _kwargs["exhaustive_gt"] = exhaustive_gt
-        _kwargs["window_ms"] = window_ms
-        _kwargs["bin_ms"] = bin_ms
-        _kwargs["well_detected_score"] = well_detected_score
-        GroundTruthStudy.run_comparisons(self, case_keys=None, comparison_class=CorrelogramGTComparison, **_kwargs)
-        self.exhaustive_gt = exhaustive_gt
-
-    @property
-    def time_bins(self):
-        for key, value in self.comparisons.items():
-            return value.time_bins
-
-    def precompute_scores_by_similarities(self, case_keys=None, good_only=True):
-        import sklearn.metrics
-
-        if case_keys is None:
-            case_keys = self.cases.keys()
-
-        self.all_similarities = {}
-        self.all_errors = {}
-
-        for key in case_keys:
-            templates = self.get_templates(key)
-            flat_templates = templates.reshape(templates.shape[0], -1)
-            similarity = sklearn.metrics.pairwise.cosine_similarity(flat_templates)
-            comp = self.comparisons[key]
-            similarities, errors = comp.compute_correlogram_by_similarity(similarity)
-
-            self.all_similarities[key] = similarities
-            self.all_errors[key] = errors
-
-    def get_error_profile_over_similarity_bins(self, similarity_bins, key):
-        all_similarities = self.all_similarities[key]
-        all_errors = self.all_errors[key]
-
-        order = np.argsort(all_similarities)
-        all_similarities = all_similarities[order]
-        all_errors = all_errors[order, :]
-
-        result = {}
-
-        for i in range(similarity_bins.size - 1):
-            cmin, cmax = similarity_bins[i], similarity_bins[i + 1]
-            amin, amax = np.searchsorted(all_similarities, [cmin, cmax])
-            mean_errors = np.nanmean(all_errors[amin:amax], axis=0)
-            result[(cmin, cmax)] = mean_errors
-
-        return result
+# This is removed at the moment.
+# We need to move this maybe one day in benchmark
+
+# class CorrelogramGTStudy(GroundTruthStudy):
+#     def run_comparisons(
+#         self, case_keys=None, exhaustive_gt=True, window_ms=100.0, bin_ms=1.0, well_detected_score=0.8, **kwargs
+#     ):
+#         _kwargs = dict()
+#         _kwargs.update(kwargs)
+#         _kwargs["exhaustive_gt"] = exhaustive_gt
+#         _kwargs["window_ms"] = window_ms
+#         _kwargs["bin_ms"] = bin_ms
+#         _kwargs["well_detected_score"] = well_detected_score
+#         GroundTruthStudy.run_comparisons(self, case_keys=None, comparison_class=CorrelogramGTComparison, **_kwargs)
+#         self.exhaustive_gt = exhaustive_gt
+
+#     @property
+#     def time_bins(self):
+#         for key, value in self.comparisons.items():
+#             return value.time_bins
+
+#     def precompute_scores_by_similarities(self, case_keys=None, good_only=True):
+#         import sklearn.metrics
+
+#         if case_keys is None:
+#             case_keys = self.cases.keys()
+
+#         self.all_similarities = {}
+#         self.all_errors = {}
+
+#         for key in case_keys:
+#             templates = self.get_templates(key)
+#             flat_templates = templates.reshape(templates.shape[0], -1)
+#             similarity = sklearn.metrics.pairwise.cosine_similarity(flat_templates)
+#             comp = self.comparisons[key]
+#             similarities, errors = comp.compute_correlogram_by_similarity(similarity)
+
+#             self.all_similarities[key] = similarities
+#             self.all_errors[key] = errors
+
+#     def get_error_profile_over_similarity_bins(self, similarity_bins, key):
+#         all_similarities = self.all_similarities[key]
+#         all_errors = self.all_errors[key]
+
+#         order = np.argsort(all_similarities)
+#         all_similarities = all_similarities[order]
+#         all_errors = all_errors[order, :]
+
+#         result = {}
+
+#         for i in range(similarity_bins.size - 1):
+#             cmin, cmax = similarity_bins[i], similarity_bins[i + 1]
+#             amin, amax = np.searchsorted(all_similarities, [cmin, cmax])
+#             mean_errors = np.nanmean(all_errors[amin:amax], axis=0)
+#             result[(cmin, cmax)] = mean_errors
+
+#         return result

From 40161366fcca747c81a40f5f2416474934c6c1cb Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 7 Oct 2024 10:46:04 +0000
Subject: [PATCH 078/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 doc/modules/benchmark.rst                     |  2 +-
 doc/modules/comparison.rst                    |  4 --
 src/spikeinterface/benchmark/__init__.py      |  2 +-
 .../benchmark/benchmark_base.py               |  2 +-
 .../benchmark/benchmark_clustering.py         |  4 +-
 .../benchmark/benchmark_matching.py           |  3 +-
 .../benchmark/benchmark_peak_selection.py     |  1 +
 .../benchmark/benchmark_plot_tools.py         | 12 ++----
 .../benchmark/benchmark_sorter.py             |  8 ++--
 .../tests/test_benchmark_peak_selection.py    |  1 +
 .../benchmark/tests/test_benchmark_sorter.py  |  4 +-
 src/spikeinterface/comparison/collision.py    |  1 +
 .../comparison/groundtruthstudy.py            |  3 +-
 src/spikeinterface/widgets/gtstudy.py         | 43 +++++++++++++------
 14 files changed, 51 insertions(+), 39 deletions(-)

diff --git a/doc/modules/benchmark.rst b/doc/modules/benchmark.rst
index 71b84adde9..faf53be790 100644
--- a/doc/modules/benchmark.rst
+++ b/doc/modules/benchmark.rst
@@ -103,7 +103,7 @@ The all mechanism is based on an intrinsic organization into a "study_folder" wi
         # some plots
         m = comp.get_confusion_matrix()
         w_comp = sw.plot_agreement_matrix(sorting_comparison=comp)
-    
+
     # Collect synthetic dataframes and display
     # As shown previously, the performance is returned as a pandas dataframe.
     # The spikeinterface.comparison.get_performance_by_unit() function,
diff --git a/doc/modules/comparison.rst b/doc/modules/comparison.rst
index 66451c0e87..a02d76664d 100644
--- a/doc/modules/comparison.rst
+++ b/doc/modules/comparison.rst
@@ -412,7 +412,3 @@ sorting analyzers from day 1 (:code:`analyzer_day1`) to day 5 (:code:`analyzer_d
     # match all
     m_tcmp = sc.compare_multiple_templates(waveform_list=analyzer_list,
                                            name_list=["D1", "D2", "D3", "D4", "D5"])
-
-
-
-
diff --git a/src/spikeinterface/benchmark/__init__.py b/src/spikeinterface/benchmark/__init__.py
index 951a865ff9..3cf0c6a6f6 100644
--- a/src/spikeinterface/benchmark/__init__.py
+++ b/src/spikeinterface/benchmark/__init__.py
@@ -4,4 +4,4 @@
   * some sorting components (clustering, motion, template matching)
 """
 
-from .benchmark_sorter import SorterStudy
\ No newline at end of file
+from .benchmark_sorter import SorterStudy
diff --git a/src/spikeinterface/benchmark/benchmark_base.py b/src/spikeinterface/benchmark/benchmark_base.py
index 7d5f17e948..b9cbf269c8 100644
--- a/src/spikeinterface/benchmark/benchmark_base.py
+++ b/src/spikeinterface/benchmark/benchmark_base.py
@@ -259,6 +259,7 @@ def get_run_times(self, case_keys=None):
 
     def plot_run_times(self, case_keys=None):
         from .benchmark_plot_tools import plot_run_times
+
         return plot_run_times(self, case_keys=case_keys)
 
     def compute_results(self, case_keys=None, verbose=False, **result_params):
@@ -445,4 +446,3 @@ def run(self):
     def compute_result(self):
         # run becnhmark result
         raise NotImplementedError
-
diff --git a/src/spikeinterface/benchmark/benchmark_clustering.py b/src/spikeinterface/benchmark/benchmark_clustering.py
index 36010e6065..1c731ecb64 100644
--- a/src/spikeinterface/benchmark/benchmark_clustering.py
+++ b/src/spikeinterface/benchmark/benchmark_clustering.py
@@ -163,16 +163,18 @@ def get_count_units(self, case_keys=None, well_detected_score=None, redundant_sc
     # plotting by methods
     def plot_unit_counts(self, **kwargs):
         from .benchmark_plot_tools import plot_unit_counts
+
         return plot_unit_counts(self, **kwargs)
 
     def plot_agreement_matrix(self, **kwargs):
         from .benchmark_plot_tools import plot_agreement_matrix
+
         return plot_agreement_matrix(self, **kwargs)
 
     def plot_performances_vs_snr(self, **kwargs):
         from .benchmark_plot_tools import plot_performances_vs_snr
-        return plot_performances_vs_snr(self, **kwargs)
 
+        return plot_performances_vs_snr(self, **kwargs)
 
     def plot_error_metrics(self, metric="cosine", case_keys=None, figsize=(15, 5)):
 
diff --git a/src/spikeinterface/benchmark/benchmark_matching.py b/src/spikeinterface/benchmark/benchmark_matching.py
index db5a00dc1a..c53567f460 100644
--- a/src/spikeinterface/benchmark/benchmark_matching.py
+++ b/src/spikeinterface/benchmark/benchmark_matching.py
@@ -63,12 +63,13 @@ def create_benchmark(self, key):
 
     def plot_agreement_matrix(self, **kwargs):
         from .benchmark_plot_tools import plot_agreement_matrix
+
         return plot_agreement_matrix(self, **kwargs)
 
     def plot_performances_vs_snr(self, **kwargs):
         from .benchmark_plot_tools import plot_performances_vs_snr
-        return plot_performances_vs_snr(self, **kwargs)
 
+        return plot_performances_vs_snr(self, **kwargs)
 
     def plot_collisions(self, case_keys=None, figsize=None):
         if case_keys is None:
diff --git a/src/spikeinterface/benchmark/benchmark_peak_selection.py b/src/spikeinterface/benchmark/benchmark_peak_selection.py
index 7abeaaacc9..41edea156f 100644
--- a/src/spikeinterface/benchmark/benchmark_peak_selection.py
+++ b/src/spikeinterface/benchmark/benchmark_peak_selection.py
@@ -10,6 +10,7 @@
 
 from .benchmark_base import Benchmark, BenchmarkStudy
 
+
 class PeakSelectionBenchmark(Benchmark):
 
     def __init__(self, recording, gt_sorting, params, indices, exhaustive_gt=True):
diff --git a/src/spikeinterface/benchmark/benchmark_plot_tools.py b/src/spikeinterface/benchmark/benchmark_plot_tools.py
index c1683c6360..a6e9b6dacc 100644
--- a/src/spikeinterface/benchmark/benchmark_plot_tools.py
+++ b/src/spikeinterface/benchmark/benchmark_plot_tools.py
@@ -1,7 +1,6 @@
 import numpy as np
 
 
-
 def _simpleaxis(ax):
     ax.spines["top"].set_visible(False)
     ax.spines["right"].set_visible(False)
@@ -28,7 +27,6 @@ def plot_run_times(study, case_keys=None):
     run_times = study.get_run_times(case_keys=case_keys)
 
     colors = study.get_colors()
-    
 
     fig, ax = plt.subplots()
     labels = []
@@ -58,7 +56,6 @@ def plot_unit_counts(study, case_keys=None):
     if case_keys is None:
         case_keys = list(study.cases.keys())
 
-
     count_units = study.get_count_units(case_keys=case_keys)
 
     fig, ax = plt.subplots()
@@ -95,6 +92,7 @@ def plot_unit_counts(study, case_keys=None):
 
     return fig
 
+
 def plot_performances(study, mode="ordered", performance_names=("accuracy", "precision", "recall"), case_keys=None):
     """
     Plot performances over case for a study.
@@ -121,10 +119,9 @@ def plot_performances(study, mode="ordered", performance_names=("accuracy", "pre
     if case_keys is None:
         case_keys = list(study.cases.keys())
 
-    perfs=study.get_performance_by_unit(case_keys=case_keys)
+    perfs = study.get_performance_by_unit(case_keys=case_keys)
     colors = study.get_colors()
 
-
     if mode in ("ordered", "snr"):
         num_axes = len(performance_names)
         fig, axs = plt.subplots(ncols=num_axes)
@@ -195,7 +192,6 @@ def plot_agreement_matrix(study, ordered=True, case_keys=None):
     if case_keys is None:
         case_keys = list(study.cases.keys())
 
-
     num_axes = len(case_keys)
     fig, axs = plt.subplots(ncols=num_axes)
 
@@ -238,9 +234,9 @@ def plot_performances_vs_snr(study, case_keys=None, figsize=None, metrics=["accu
             y = study.get_result(key)["gt_comparison"].get_performance()[k].values
             ax.scatter(x, y, marker=".", label=label)
             ax.set_title(k)
-        
+
         ax.set_ylim(0, 1.05)
-        
+
         if count == 2:
             ax.legend()
 
diff --git a/src/spikeinterface/benchmark/benchmark_sorter.py b/src/spikeinterface/benchmark/benchmark_sorter.py
index 1f2dde3b32..c27d75a775 100644
--- a/src/spikeinterface/benchmark/benchmark_sorter.py
+++ b/src/spikeinterface/benchmark/benchmark_sorter.py
@@ -2,7 +2,6 @@
 This replace the previous `GroundTruthStudy`
 """
 
-
 import numpy as np
 from ..core import NumpySorting
 from .benchmark_base import Benchmark, BenchmarkStudy
@@ -45,6 +44,7 @@ def compute_result(self):
         ("gt_comparison", "pickle"),
     ]
 
+
 class SorterStudy(BenchmarkStudy):
     """
     This class is used to tests several sorter in several situtation.
@@ -126,15 +126,15 @@ def get_count_units(self, case_keys=None, well_detected_score=None, redundant_sc
     # plotting as methods
     def plot_unit_counts(self, **kwargs):
         from .benchmark_plot_tools import plot_unit_counts
+
         return plot_unit_counts(self, **kwargs)
 
     def plot_performances(self, **kwargs):
         from .benchmark_plot_tools import plot_performances
+
         return plot_performances(self, **kwargs)
 
     def plot_agreement_matrix(self, **kwargs):
         from .benchmark_plot_tools import plot_agreement_matrix
-        return plot_agreement_matrix(self, **kwargs)
-
-
 
+        return plot_agreement_matrix(self, **kwargs)
diff --git a/src/spikeinterface/benchmark/tests/test_benchmark_peak_selection.py b/src/spikeinterface/benchmark/tests/test_benchmark_peak_selection.py
index 92ed0f94ae..a6eb090a9d 100644
--- a/src/spikeinterface/benchmark/tests/test_benchmark_peak_selection.py
+++ b/src/spikeinterface/benchmark/tests/test_benchmark_peak_selection.py
@@ -2,6 +2,7 @@
 
 from pathlib import Path
 
+
 @pytest.mark.skip()
 def test_benchmark_peak_selection(create_cache_folder):
     cache_folder = create_cache_folder
diff --git a/src/spikeinterface/benchmark/tests/test_benchmark_sorter.py b/src/spikeinterface/benchmark/tests/test_benchmark_sorter.py
index 03ac86d715..2564d58d52 100644
--- a/src/spikeinterface/benchmark/tests/test_benchmark_sorter.py
+++ b/src/spikeinterface/benchmark/tests/test_benchmark_sorter.py
@@ -15,6 +15,7 @@ def setup_module(tmp_path_factory):
     create_a_study(study_folder)
     return study_folder
 
+
 def simple_preprocess(rec):
     return bandpass_filter(rec)
 
@@ -75,14 +76,11 @@ def test_SorterStudy(setup_module):
     # import matplotlib.pyplot as plt
     # plt.show()
 
-
     perf_by_unit = study.get_performance_by_unit()
     # print(perf_by_unit)
     count_units = study.get_count_units()
     # print(count_units)
 
-    
-
 
 if __name__ == "__main__":
     study_folder = Path(__file__).resolve().parents[4] / "cache_folder" / "benchmarks" / "test_SorterStudy"
diff --git a/src/spikeinterface/comparison/collision.py b/src/spikeinterface/comparison/collision.py
index cff87e7a57..12bfab84ed 100644
--- a/src/spikeinterface/comparison/collision.py
+++ b/src/spikeinterface/comparison/collision.py
@@ -171,6 +171,7 @@ def compute_collision_by_similarity(self, similarity_matrix, unit_ids=None, good
 
         return similarities, recall_scores, pair_names
 
+
 # This is removed at the moment.
 # We need to move this maybe one day in benchmark.
 # please do not delete this
diff --git a/src/spikeinterface/comparison/groundtruthstudy.py b/src/spikeinterface/comparison/groundtruthstudy.py
index c662ca38da..df9e1420cb 100644
--- a/src/spikeinterface/comparison/groundtruthstudy.py
+++ b/src/spikeinterface/comparison/groundtruthstudy.py
@@ -1,5 +1,3 @@
-
-
 _txt_error_message = """
 GroundTruthStudy has been replaced by SorterStudy with similar API but not back compatible folder loading.
 You can do:
@@ -13,6 +11,7 @@
 ...
 """
 
+
 class GroundTruthStudy:
     def __init__(self, study_folder):
         raise RuntimeError(_txt_error_message)
diff --git a/src/spikeinterface/widgets/gtstudy.py b/src/spikeinterface/widgets/gtstudy.py
index f32a15e429..5e160a6a5a 100644
--- a/src/spikeinterface/widgets/gtstudy.py
+++ b/src/spikeinterface/widgets/gtstudy.py
@@ -11,6 +11,7 @@
 
 import warnings
 
+
 class StudyRunTimesWidget(BaseWidget):
     """
     Plot sorter run times for a SorterStudy.
@@ -25,12 +26,15 @@ class StudyRunTimesWidget(BaseWidget):
     """
 
     def __init__(self, study, case_keys=None, backend=None, **backend_kwargs):
-        warnings.warn("plot_study_run_times is to be deprecated. Use spikeinterface.benchmark.benchmark_plot_tools instead.")
+        warnings.warn(
+            "plot_study_run_times is to be deprecated. Use spikeinterface.benchmark.benchmark_plot_tools instead."
+        )
         plot_data = dict(study=study, case_keys=case_keys)
         BaseWidget.__init__(self, plot_data, backend=backend, **backend_kwargs)
 
     def plot_matplotlib(self, data_plot, **backend_kwargs):
         from spikeinterface.benchmark.benchmark_plot_tools import plot_run_times
+
         plot_run_times(data_plot["study"], case_keys=data_plot["case_keys"])
 
 
@@ -48,12 +52,15 @@ class StudyUnitCountsWidget(BaseWidget):
     """
 
     def __init__(self, study, case_keys=None, backend=None, **backend_kwargs):
-        warnings.warn("plot_study_unit_counts is to be deprecated. Use spikeinterface.benchmark.benchmark_plot_tools instead.")
+        warnings.warn(
+            "plot_study_unit_counts is to be deprecated. Use spikeinterface.benchmark.benchmark_plot_tools instead."
+        )
         plot_data = dict(study=study, case_keys=case_keys)
         BaseWidget.__init__(self, plot_data, backend=backend, **backend_kwargs)
 
     def plot_matplotlib(self, data_plot, **backend_kwargs):
         from spikeinterface.benchmark.benchmark_plot_tools import plot_unit_counts
+
         plot_unit_counts(data_plot["study"], case_keys=data_plot["case_keys"])
 
 
@@ -87,7 +94,9 @@ def __init__(
         backend=None,
         **backend_kwargs,
     ):
-        warnings.warn("plot_study_performances is to be deprecated. Use spikeinterface.benchmark.benchmark_plot_tools instead.")
+        warnings.warn(
+            "plot_study_performances is to be deprecated. Use spikeinterface.benchmark.benchmark_plot_tools instead."
+        )
         plot_data = dict(
             study=study,
             mode=mode,
@@ -98,13 +107,15 @@ def __init__(
 
     def plot_matplotlib(self, data_plot, **backend_kwargs):
         from spikeinterface.benchmark.benchmark_plot_tools import plot_performances
+
         plot_performances(
             data_plot["study"],
             mode=data_plot["mode"],
             performance_names=data_plot["performance_names"],
-            case_keys=data_plot["case_keys"]
+            case_keys=data_plot["case_keys"],
         )
 
+
 class StudyAgreementMatrix(BaseWidget):
     """
     Plot agreement matrix.
@@ -128,7 +139,9 @@ def __init__(
         backend=None,
         **backend_kwargs,
     ):
-        warnings.warn("plot_study_agreement_matrix is to be deprecated. Use spikeinterface.benchmark.benchmark_plot_tools instead.")
+        warnings.warn(
+            "plot_study_agreement_matrix is to be deprecated. Use spikeinterface.benchmark.benchmark_plot_tools instead."
+        )
         plot_data = dict(
             study=study,
             case_keys=case_keys,
@@ -139,11 +152,8 @@ def __init__(
 
     def plot_matplotlib(self, data_plot, **backend_kwargs):
         from spikeinterface.benchmark.benchmark_plot_tools import plot_agreement_matrix
-        plot_agreement_matrix(
-            data_plot["study"],
-            ordered=data_plot["ordered"],
-            case_keys=data_plot["case_keys"]
-        )
+
+        plot_agreement_matrix(data_plot["study"], ordered=data_plot["ordered"], case_keys=data_plot["case_keys"])
 
 
 class StudySummary(BaseWidget):
@@ -171,8 +181,10 @@ def __init__(
         backend=None,
         **backend_kwargs,
     ):
-        
-        warnings.warn("plot_study_summary is to be deprecated. Use spikeinterface.benchmark.benchmark_plot_tools instead.")
+
+        warnings.warn(
+            "plot_study_summary is to be deprecated. Use spikeinterface.benchmark.benchmark_plot_tools instead."
+        )
         plot_data = dict(study=study, case_keys=case_keys)
         BaseWidget.__init__(self, plot_data, backend=backend, **backend_kwargs)
 
@@ -180,7 +192,12 @@ def plot_matplotlib(self, data_plot, **backend_kwargs):
         study = data_plot["study"]
         case_keys = data_plot["case_keys"]
 
-        from spikeinterface.benchmark.benchmark_plot_tools import plot_agreement_matrix, plot_performances, plot_unit_counts, plot_run_times
+        from spikeinterface.benchmark.benchmark_plot_tools import (
+            plot_agreement_matrix,
+            plot_performances,
+            plot_unit_counts,
+            plot_run_times,
+        )
 
         plot_performances(study=study, case_keys=case_keys, mode="ordered")
         plot_performances(study=study, case_keys=case_keys, mode="snr")

From 7cbbdef6725a6b596dcfa5bf7cd3cd13cab03766 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Mon, 7 Oct 2024 15:11:34 +0200
Subject: [PATCH 079/344] clean

---
 src/spikeinterface/benchmark/benchmark_sorter.py | 5 -----
 src/spikeinterface/comparison/__init__.py        | 4 ++--
 2 files changed, 2 insertions(+), 7 deletions(-)

diff --git a/src/spikeinterface/benchmark/benchmark_sorter.py b/src/spikeinterface/benchmark/benchmark_sorter.py
index 1f2dde3b32..39dd6a0c74 100644
--- a/src/spikeinterface/benchmark/benchmark_sorter.py
+++ b/src/spikeinterface/benchmark/benchmark_sorter.py
@@ -9,11 +9,6 @@
 from ..sorters import run_sorter
 from spikeinterface.comparison import compare_sorter_to_ground_truth
 
-# from spikeinterface.widgets import (
-#     plot_agreement_matrix,
-#     plot_comparison_collision_by_similarity,
-# )
-
 
 # TODO later integrate CollisionGTComparison optionally in this class.
 
diff --git a/src/spikeinterface/comparison/__init__.py b/src/spikeinterface/comparison/__init__.py
index 648ef4ed70..f4ada19f73 100644
--- a/src/spikeinterface/comparison/__init__.py
+++ b/src/spikeinterface/comparison/__init__.py
@@ -30,8 +30,8 @@
 )
 
 from .groundtruthstudy import GroundTruthStudy
-from .collision import CollisionGTComparison, CollisionGTStudy
-from .correlogram import CorrelogramGTComparison, CorrelogramGTStudy
+from .collision import CollisionGTComparison
+from .correlogram import CorrelogramGTComparison
 
 from .hybrid import (
     HybridSpikesRecording,

From fbbb89fe27f01897bdbb363de6e9a3742adc00f2 Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Mon, 7 Oct 2024 15:46:08 +0200
Subject: [PATCH 080/344] Matched filtering with both peak signs simultaneously

---
 .../sortingcomponents/peak_detection.py       | 103 ++++++------------
 .../tests/test_peak_detection.py              |  27 ++++-
 2 files changed, 59 insertions(+), 71 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/peak_detection.py b/src/spikeinterface/sortingcomponents/peak_detection.py
index 4fe90dd7bc..ad8897df91 100644
--- a/src/spikeinterface/sortingcomponents/peak_detection.py
+++ b/src/spikeinterface/sortingcomponents/peak_detection.py
@@ -631,47 +631,31 @@ def __init__(
         self.conv_margin = prototype.shape[0]
 
         assert peak_sign in ("both", "neg", "pos")
-        idx = np.argmax(np.abs(prototype))
+        self.nbefore = int(ms_before * recording.sampling_frequency / 1000)
         if peak_sign == "neg":
-            assert prototype[idx] < 0, "Prototype should have a negative peak"
+            assert prototype[self.nbefore] < 0, "Prototype should have a negative peak"
             peak_sign = "pos"
         elif peak_sign == "pos":
-            assert prototype[idx] > 0, "Prototype should have a positive peak"
-        elif peak_sign == "both":
-            raise NotImplementedError("Matched filtering not working with peak_sign=both yet!")
+            assert prototype[self.nbefore] > 0, "Prototype should have a positive peak"
 
         self.peak_sign = peak_sign
-        self.nbefore = int(ms_before * recording.sampling_frequency / 1000)
+        self.prototype = np.flip(prototype) / np.linalg.norm(prototype)
+
         contact_locations = recording.get_channel_locations()
         dist = np.linalg.norm(contact_locations[:, np.newaxis] - contact_locations[np.newaxis, :], axis=2)
-        weights, self.z_factors = get_convolution_weights(dist, **weight_method)
+        self.weights, self.z_factors = get_convolution_weights(dist, **weight_method)
+        self.num_z_factors = len(self.z_factors)
+        self.num_channels = recording.get_num_channels()
+        self.num_templates = self.num_channels
+        if peak_sign == "both":
+            self.weights = np.hstack((self.weights, self.weights))
+            self.weights[:, self.num_templates :, :] *= -1
+            self.num_templates *= 2
 
-        num_channels = recording.get_num_channels()
-        num_templates = num_channels * len(self.z_factors)
-        weights = weights.reshape(num_templates, -1)
-
-        templates = weights[:, None, :] * prototype[None, :, None]
-        templates -= templates.mean(axis=(1, 2))[:, None, None]
-        temporal, singular, spatial = np.linalg.svd(templates, full_matrices=False)
-        temporal = temporal[:, :, :rank]
-        singular = singular[:, :rank]
-        spatial = spatial[:, :rank, :]
-        templates = np.matmul(temporal * singular[:, np.newaxis, :], spatial)
-        norms = np.linalg.norm(templates, axis=(1, 2))
-        del templates
-
-        temporal /= norms[:, np.newaxis, np.newaxis]
-        temporal = np.flip(temporal, axis=1)
-        spatial = np.moveaxis(spatial, [0, 1, 2], [1, 0, 2])
-        temporal = np.moveaxis(temporal, [0, 1, 2], [1, 2, 0])
-        singular = singular.T[:, :, np.newaxis]
-
-        self.temporal = temporal
-        self.spatial = spatial
-        self.singular = singular
+        self.weights = self.weights.reshape(self.num_templates * self.num_z_factors, -1)
 
         random_data = get_random_data_chunks(recording, return_scaled=False, **random_chunk_kwargs)
-        conv_random_data = self.get_convolved_traces(random_data, temporal, spatial, singular)
+        conv_random_data = self.get_convolved_traces(random_data)
         medians = np.median(conv_random_data, axis=1)
         medians = medians[:, None]
         noise_levels = np.median(np.abs(conv_random_data - medians), axis=1) / 0.6744897501960817
@@ -688,16 +672,13 @@ def get_trace_margin(self):
     def compute(self, traces, start_frame, end_frame, segment_index, max_margin):
 
         assert HAVE_NUMBA, "You need to install numba"
-        conv_traces = self.get_convolved_traces(traces, self.temporal, self.spatial, self.singular)
+        conv_traces = self.get_convolved_traces(traces)
         conv_traces /= self.abs_thresholds[:, None]
         conv_traces = conv_traces[:, self.conv_margin : -self.conv_margin]
         traces_center = conv_traces[:, self.exclude_sweep_size : -self.exclude_sweep_size]
 
-        num_z_factors = len(self.z_factors)
-        num_templates = traces.shape[1]
-
-        traces_center = traces_center.reshape(num_z_factors, num_templates, traces_center.shape[1])
-        conv_traces = conv_traces.reshape(num_z_factors, num_templates, conv_traces.shape[1])
+        traces_center = traces_center.reshape(self.num_z_factors, self.num_templates, traces_center.shape[1])
+        conv_traces = conv_traces.reshape(self.num_z_factors, self.num_templates, conv_traces.shape[1])
         peak_mask = traces_center > 1
 
         peak_mask = _numba_detect_peak_matched_filtering(
@@ -708,11 +689,13 @@ def compute(self, traces, start_frame, end_frame, segment_index, max_margin):
             self.abs_thresholds,
             self.peak_sign,
             self.neighbours_mask,
-            num_templates,
+            self.num_channels,
         )
 
         # Find peaks and correct for time shift
         z_ind, peak_chan_ind, peak_sample_ind = np.nonzero(peak_mask)
+        if self.peak_sign == "both":
+            peak_chan_ind = peak_chan_ind % self.num_channels
 
         # If we want to estimate z
         # peak_chan_ind = peak_chan_ind % num_channels
@@ -739,16 +722,11 @@ def compute(self, traces, start_frame, end_frame, segment_index, max_margin):
         # return is always a tuple
         return (local_peaks,)
 
-    def get_convolved_traces(self, traces, temporal, spatial, singular):
+    def get_convolved_traces(self, traces):
         import scipy.signal
 
-        num_timesteps, num_templates = len(traces), temporal.shape[1]
-        num_peaks = num_timesteps - self.conv_margin + 1
-        scalar_products = np.zeros((num_templates, num_peaks), dtype=np.float32)
-        spatially_filtered_data = np.matmul(spatial, traces.T[np.newaxis, :, :])
-        scaled_filtered_data = spatially_filtered_data * singular
-        objective_by_rank = scipy.signal.oaconvolve(scaled_filtered_data, temporal, axes=2, mode="valid")
-        scalar_products += np.sum(objective_by_rank, axis=0)
+        tmp = scipy.signal.oaconvolve(self.prototype[None, :], traces.T, axes=1, mode="valid")
+        scalar_products = np.dot(self.weights, tmp)
         return scalar_products
 
 
@@ -873,37 +851,28 @@ def _numba_detect_peak_neg(
 
     @numba.jit(nopython=True, parallel=False)
     def _numba_detect_peak_matched_filtering(
-        traces, traces_center, peak_mask, exclude_sweep_size, abs_thresholds, peak_sign, neighbours_mask, num_templates
+        traces, traces_center, peak_mask, exclude_sweep_size, abs_thresholds, peak_sign, neighbours_mask, num_channels
     ):
         num_z = traces_center.shape[0]
+        num_templates = traces_center.shape[1]
         for template_ind in range(num_templates):
             for z in range(num_z):
                 for s in range(peak_mask.shape[2]):
                     if not peak_mask[z, template_ind, s]:
                         continue
                     for neighbour in range(num_templates):
-                        if not neighbours_mask[template_ind, neighbour]:
-                            continue
                         for j in range(num_z):
+                            if not neighbours_mask[template_ind % num_channels, neighbour % num_channels]:
+                                continue
                             for i in range(exclude_sweep_size):
-                                if template_ind >= neighbour:
-                                    if z >= j:
-                                        peak_mask[z, template_ind, s] &= (
-                                            traces_center[z, template_ind, s] >= traces_center[j, neighbour, s]
-                                        )
-                                    else:
-                                        peak_mask[z, template_ind, s] &= (
-                                            traces_center[z, template_ind, s] > traces_center[j, neighbour, s]
-                                        )
-                                elif template_ind < neighbour:
-                                    if z > j:
-                                        peak_mask[z, template_ind, s] &= (
-                                            traces_center[z, template_ind, s] > traces_center[j, neighbour, s]
-                                        )
-                                    else:
-                                        peak_mask[z, template_ind, s] &= (
-                                            traces_center[z, template_ind, s] > traces_center[j, neighbour, s]
-                                        )
+                                if template_ind >= neighbour and z >= j:
+                                    peak_mask[z, template_ind, s] &= (
+                                        traces_center[z, template_ind, s] >= traces_center[j, neighbour, s]
+                                    )
+                                else:
+                                    peak_mask[z, template_ind, s] &= (
+                                        traces_center[z, template_ind, s] > traces_center[j, neighbour, s]
+                                    )
                                 peak_mask[z, template_ind, s] &= (
                                     traces_center[z, template_ind, s] > traces[j, neighbour, s + i]
                                 )
diff --git a/src/spikeinterface/sortingcomponents/tests/test_peak_detection.py b/src/spikeinterface/sortingcomponents/tests/test_peak_detection.py
index fa30ba3483..7c34f5948d 100644
--- a/src/spikeinterface/sortingcomponents/tests/test_peak_detection.py
+++ b/src/spikeinterface/sortingcomponents/tests/test_peak_detection.py
@@ -328,19 +328,38 @@ def test_detect_peaks_locally_exclusive_matched_filtering(recording, job_kwargs)
     )
     assert len(peaks_local_mf_filtering) > len(peaks_by_channel_np)
 
+    peaks_local_mf_filtering_both = detect_peaks(
+        recording,
+        method="matched_filtering",
+        peak_sign="both",
+        detect_threshold=5,
+        exclude_sweep_ms=0.1,
+        prototype=prototype,
+        ms_before=1.0,
+        **job_kwargs,
+    )
+    assert len(peaks_local_mf_filtering_both) > len(peaks_local_mf_filtering)
+
     DEBUG = False
     if DEBUG:
         import matplotlib.pyplot as plt
 
-        peaks = peaks_local_mf_filtering
+        peaks_local = peaks_by_channel_np
+        peaks_mf_neg = peaks_local_mf_filtering
+        peaks_mf_both = peaks_local_mf_filtering_both
+        labels = ["locally_exclusive", "mf_neg", "mf_both"]
 
-        sample_inds, chan_inds, amplitudes = peaks["sample_index"], peaks["channel_index"], peaks["amplitude"]
+        fig, ax = plt.subplots()
         chan_offset = 500
         traces = recording.get_traces().copy()
         traces += np.arange(traces.shape[1])[None, :] * chan_offset
-        fig, ax = plt.subplots()
         ax.plot(traces, color="k")
-        ax.scatter(sample_inds, chan_inds * chan_offset + amplitudes, color="r")
+
+        for count, peaks in enumerate([peaks_local, peaks_mf_neg, peaks_mf_both]):
+            sample_inds, chan_inds, amplitudes = peaks["sample_index"], peaks["channel_index"], peaks["amplitude"]
+            ax.scatter(sample_inds, chan_inds * chan_offset + amplitudes, label=labels[count])
+
+        ax.legend()
         plt.show()
 
 

From e0f1011bddb424ea9a284bce91d73d7a79021283 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Mon, 7 Oct 2024 15:46:57 +0200
Subject: [PATCH 081/344] After release

---
 pyproject.toml                 | 18 +++++++++---------
 src/spikeinterface/__init__.py |  4 ++--
 2 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index 4cbcb23b3d..a43ab63c8e 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "spikeinterface"
-version = "0.101.2"
+version = "0.102.0"
 authors = [
   { name="Alessio Buccino", email="alessiop.buccino@gmail.com" },
   { name="Samuel Garcia", email="sam.garcia.die@gmail.com" },
@@ -124,16 +124,16 @@ test_core = [
 
     # for github test : probeinterface and neo from master
     # for release we need pypi, so this need to be commented
-    # "probeinterface @ git+https://github.com/SpikeInterface/probeinterface.git",
-    # "neo @ git+https://github.com/NeuralEnsemble/python-neo.git",
+    "probeinterface @ git+https://github.com/SpikeInterface/probeinterface.git",
+    "neo @ git+https://github.com/NeuralEnsemble/python-neo.git",
 ]
 
 test_extractors = [
     # Functions to download data in neo test suite
     "pooch>=1.8.2",
     "datalad>=1.0.2",
-    # "probeinterface @ git+https://github.com/SpikeInterface/probeinterface.git",
-    # "neo @ git+https://github.com/NeuralEnsemble/python-neo.git",
+    "probeinterface @ git+https://github.com/SpikeInterface/probeinterface.git",
+    "neo @ git+https://github.com/NeuralEnsemble/python-neo.git",
 ]
 
 test_preprocessing = [
@@ -173,8 +173,8 @@ test = [
 
     # for github test : probeinterface and neo from master
     # for release we need pypi, so this need to be commented
-    # "probeinterface @ git+https://github.com/SpikeInterface/probeinterface.git",
-    # "neo @ git+https://github.com/NeuralEnsemble/python-neo.git",
+    "probeinterface @ git+https://github.com/SpikeInterface/probeinterface.git",
+    "neo @ git+https://github.com/NeuralEnsemble/python-neo.git",
 ]
 
 docs = [
@@ -197,8 +197,8 @@ docs = [
     "datalad>=1.0.2",
 
     # for release we need pypi, so this needs to be commented
-    # "probeinterface @ git+https://github.com/SpikeInterface/probeinterface.git",  # We always build from the latest version
-    # "neo @ git+https://github.com/NeuralEnsemble/python-neo.git",  # We always build from the latest version
+    "probeinterface @ git+https://github.com/SpikeInterface/probeinterface.git",  # We always build from the latest version
+    "neo @ git+https://github.com/NeuralEnsemble/python-neo.git",  # We always build from the latest version
 
 ]
 
diff --git a/src/spikeinterface/__init__.py b/src/spikeinterface/__init__.py
index 97fb95b623..306c12d516 100644
--- a/src/spikeinterface/__init__.py
+++ b/src/spikeinterface/__init__.py
@@ -30,5 +30,5 @@
 # This flag must be set to False for release
 # This avoids using versioning that contains ".dev0" (and this is a better choice)
 # This is mainly useful when using run_sorter in a container and spikeinterface install
-# DEV_MODE = True
-DEV_MODE = False
+DEV_MODE = True
+# DEV_MODE = False

From c4eb8a540fab74b5712d744a30886867fa1f68f3 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 7 Oct 2024 14:59:33 +0000
Subject: [PATCH 082/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/core/node_pipeline.py        | 17 +++++++++++------
 .../core/tests/test_node_pipeline.py            |  7 ++++---
 2 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/src/spikeinterface/core/node_pipeline.py b/src/spikeinterface/core/node_pipeline.py
index a617272753..a72808e176 100644
--- a/src/spikeinterface/core/node_pipeline.py
+++ b/src/spikeinterface/core/node_pipeline.py
@@ -87,10 +87,16 @@ def get_trace_margin(self):
     def get_dtype(self):
         return base_peak_dtype
 
-    def get_peak_slice(self, segment_index, start_frame, end_frame, ):
+    def get_peak_slice(
+        self,
+        segment_index,
+        start_frame,
+        end_frame,
+    ):
         # not needed for PeakDetector
         raise NotImplementedError
 
+
 # this is used in sorting components
 class PeakDetector(PeakSource):
     pass
@@ -474,7 +480,7 @@ def run_node_pipeline(
     nodes,
     job_kwargs,
     job_name="pipeline",
-    #mp_context=None,
+    # mp_context=None,
     gather_mode="memory",
     gather_kwargs={},
     squeeze_output=True,
@@ -506,7 +512,7 @@ def run_node_pipeline(
     The gather consists of concatenating features related to peaks (localization, pca, scaling, ...) into a single big vector.
     These vectors can be in "memory" or in files ("npy")
 
-    
+
     Parameters
     ----------
 
@@ -533,7 +539,7 @@ def run_node_pipeline(
     skip_after_n_peaks : None | int
         Skip the computation after n_peaks.
         This is not an exact because internally this skip is done per worker in average.
-    
+
     Returns
     -------
     outputs: tuple of np.array | np.array
@@ -596,7 +602,7 @@ def _compute_peak_pipeline_chunk(segment_index, start_frame, end_frame, worker_c
 
     recording_segment = recording._recording_segments[segment_index]
     node0 = nodes[0]
-    
+
     if isinstance(node0, (SpikeRetriever, PeakRetriever)):
         # in this case PeakSource could have no peaks and so no need to load traces just skip
         peak_slice = i0, i1 = node0.get_peak_slice(segment_index, start_frame, end_frame, max_margin)
@@ -676,7 +682,6 @@ def _compute_peak_pipeline_chunk(segment_index, start_frame, end_frame, worker_c
         return
 
 
-
 class GatherToMemory:
     """
     Gather output of nodes into list and then demultiplex and np.concatenate
diff --git a/src/spikeinterface/core/tests/test_node_pipeline.py b/src/spikeinterface/core/tests/test_node_pipeline.py
index 3d3a642371..deef2291c6 100644
--- a/src/spikeinterface/core/tests/test_node_pipeline.py
+++ b/src/spikeinterface/core/tests/test_node_pipeline.py
@@ -87,7 +87,7 @@ def test_run_node_pipeline(cache_folder_creation):
 
     peak_retriever = PeakRetriever(recording, peaks)
     # this test when no spikes in last chunks
-    peak_retriever_few = PeakRetriever(recording, peaks[:peaks.size//2])
+    peak_retriever_few = PeakRetriever(recording, peaks[: peaks.size // 2])
 
     # channel index is from template
     spike_retriever_T = SpikeRetriever(
@@ -212,13 +212,14 @@ def test_skip_after_n_peaks():
     nodes = [node0, node1]
 
     skip_after_n_peaks = 30
-    some_amplitudes = run_node_pipeline(recording, nodes, job_kwargs, gather_mode="memory", skip_after_n_peaks=skip_after_n_peaks)
+    some_amplitudes = run_node_pipeline(
+        recording, nodes, job_kwargs, gather_mode="memory", skip_after_n_peaks=skip_after_n_peaks
+    )
 
     assert some_amplitudes.size >= skip_after_n_peaks
     assert some_amplitudes.size < spikes.size
 
 
-
 # the following is for testing locally with python or ipython. It is not used in ci or with pytest.
 if __name__ == "__main__":
     # folder = Path("./cache_folder/core")

From 2a4809b1567970a3f8d9ee5fc397de80d6af32cd Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Mon, 7 Oct 2024 17:03:14 +0200
Subject: [PATCH 083/344] oups

---
 .../sortingcomponents/tests/test_template_matching.py           | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/sortingcomponents/tests/test_template_matching.py b/src/spikeinterface/sortingcomponents/tests/test_template_matching.py
index f23ef007ea..7fdd64bca5 100644
--- a/src/spikeinterface/sortingcomponents/tests/test_template_matching.py
+++ b/src/spikeinterface/sortingcomponents/tests/test_template_matching.py
@@ -77,7 +77,7 @@ def test_find_spikes_from_templates(method, sorting_analyzer):
     #     comp = si.compare_sorter_to_ground_truth(gt_sorting, sorting)
     #     si.plot_agreement_matrix(comp, ax=ax)
     #     ax.set_title(method)
-        plt.show()
+        # plt.show()
 
 
 if __name__ == "__main__":

From b70ae9b20bf061314e71b6e5cf9ff0551db36010 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Mon, 7 Oct 2024 18:35:18 +0200
Subject: [PATCH 084/344] clean and debug

---
 .../internal/tests/test_spykingcircus2.py     |   4 +
 .../internal/tests/test_tridesclous2.py       |   3 +
 .../sorters/internal/tridesclous2.py          |   3 +-
 .../sortingcomponents/matching/base.py        |   5 +-
 .../sortingcomponents/matching/circus.py      | 754 +-----------------
 .../sortingcomponents/matching/main.py        | 154 ----
 .../sortingcomponents/matching/naive.py       | 113 +--
 .../sortingcomponents/matching/tdc.py         | 326 --------
 .../sortingcomponents/matching/wobble.py      | 501 +-----------
 9 files changed, 20 insertions(+), 1843 deletions(-)

diff --git a/src/spikeinterface/sorters/internal/tests/test_spykingcircus2.py b/src/spikeinterface/sorters/internal/tests/test_spykingcircus2.py
index 333bcdbc32..b51abff570 100644
--- a/src/spikeinterface/sorters/internal/tests/test_spykingcircus2.py
+++ b/src/spikeinterface/sorters/internal/tests/test_spykingcircus2.py
@@ -4,12 +4,16 @@
 
 from spikeinterface.sorters import Spykingcircus2Sorter
 
+from pathlib import Path
 
 class SpykingCircus2SorterCommonTestSuite(SorterCommonTestSuite, unittest.TestCase):
     SorterClass = Spykingcircus2Sorter
 
 
 if __name__ == "__main__":
+    from spikeinterface import set_global_job_kwargs
+    set_global_job_kwargs(n_jobs=1, progress_bar=False)
     test = SpykingCircus2SorterCommonTestSuite()
+    test.cache_folder = Path(__file__).resolve().parents[4] / "cache_folder" / "sorters"
     test.setUp()
     test.test_with_run()
diff --git a/src/spikeinterface/sorters/internal/tests/test_tridesclous2.py b/src/spikeinterface/sorters/internal/tests/test_tridesclous2.py
index 58d6c15c8d..b256dd1328 100644
--- a/src/spikeinterface/sorters/internal/tests/test_tridesclous2.py
+++ b/src/spikeinterface/sorters/internal/tests/test_tridesclous2.py
@@ -4,6 +4,8 @@
 
 from spikeinterface.sorters import Tridesclous2Sorter
 
+from pathlib import Path
+
 
 class Tridesclous2SorterCommonTestSuite(SorterCommonTestSuite, unittest.TestCase):
     SorterClass = Tridesclous2Sorter
@@ -11,5 +13,6 @@ class Tridesclous2SorterCommonTestSuite(SorterCommonTestSuite, unittest.TestCase
 
 if __name__ == "__main__":
     test = Tridesclous2SorterCommonTestSuite()
+    test.cache_folder = Path(__file__).resolve().parents[4] / "cache_folder" / "sorters"
     test.setUp()
     test.test_with_run()
diff --git a/src/spikeinterface/sorters/internal/tridesclous2.py b/src/spikeinterface/sorters/internal/tridesclous2.py
index 57755cd759..f34471017b 100644
--- a/src/spikeinterface/sorters/internal/tridesclous2.py
+++ b/src/spikeinterface/sorters/internal/tridesclous2.py
@@ -226,7 +226,8 @@ def _run_from_folder(cls, sorter_output_folder, params, verbose):
         matching_method = params["matching"]["method"]
         matching_params = params["matching"]["method_kwargs"].copy()
         matching_params["templates"] = templates
-        matching_params["noise_levels"] = noise_levels
+        if params["matching"]["method"] in ("tdc-peeler", ):
+            matching_params["noise_levels"] = noise_levels
         spikes = find_spikes_from_templates(
             recording_for_peeler, method=matching_method, method_kwargs=matching_params, **job_kwargs
         )
diff --git a/src/spikeinterface/sortingcomponents/matching/base.py b/src/spikeinterface/sortingcomponents/matching/base.py
index d25e751ff8..0c58f9b09b 100644
--- a/src/spikeinterface/sortingcomponents/matching/base.py
+++ b/src/spikeinterface/sortingcomponents/matching/base.py
@@ -32,11 +32,12 @@ def compute(self, traces, start_frame, end_frame, segment_index, max_margin):
         spikes["segment_index"] = segment_index
 
         margin = self.get_trace_margin()
-        if margin > 0:
+        if margin > 0 and spikes.size > 0:
             keep = (spikes["sample_index"] >= margin) & (spikes["sample_index"] < (traces.shape[0] - margin))
             spikes = spikes[keep]
 
-        return spikes
+        # node pipeline need to return a tuple
+        return (spikes, )
 
     def compute_matching(self, traces, start_frame, end_frame, segment_index):
         raise NotImplementedError
diff --git a/src/spikeinterface/sortingcomponents/matching/circus.py b/src/spikeinterface/sortingcomponents/matching/circus.py
index 51f5cceacd..5bce943fc0 100644
--- a/src/spikeinterface/sortingcomponents/matching/circus.py
+++ b/src/spikeinterface/sortingcomponents/matching/circus.py
@@ -17,7 +17,6 @@
     ("segment_index", "int64"),
 ]
 
-# from .main import BaseTemplateMatchingEngine
 from .base import BaseTemplateMatching
 
 
@@ -129,6 +128,7 @@ class CircusOMPSVDPeeler(BaseTemplateMatching):
                 "units_overlaps",
                 "unit_overlaps_indices",
                 "normed_templates",
+                "overlaps",
             ]
 
     def __init__(self, recording, return_output=True, parents=None,
@@ -162,18 +162,6 @@ def __init__(self, recording, return_output=True, parents=None,
 
         self.num_templates = len(templates.unit_ids)
 
-        # if "overlaps" not in d:
-        #     d = cls._prepare_templates(d)
-        # else:
-        #     for key in [
-        #         "norms",
-        #         "temporal",
-        #         "spatial",
-        #         "singular",
-        #         "units_overlaps",
-        #         "unit_overlaps_indices",
-        #     ]:
-        #         assert d[key] is not None, "If templates are provided, %d should also be there" % key
         if precomputed is None:
             self._prepare_templates()
         else:
@@ -474,397 +462,17 @@ def compute_matching(self, traces, start_frame, end_frame, segment_index):
         spikes["cluster_index"][:num_spikes] = valid_indices[0]
         spikes["amplitude"][:num_spikes] = final_amplitudes[valid_indices[0], valid_indices[1]]
 
+        print("yep0", spikes.size, num_spikes, spikes.shape, spikes.dtype)
         spikes = spikes[:num_spikes]
-        order = np.argsort(spikes["sample_index"])
-        spikes = spikes[order]
+        print("yep1", spikes.size, spikes.shape, spikes.dtype)
+        if spikes.size > 0:
+            order = np.argsort(spikes["sample_index"])
+            spikes = spikes[order]
         
         return spikes
 
 
 
-# class CircusOMPSVDPeeler(BaseTemplateMatchingEngine):
-#     """
-#     Orthogonal Matching Pursuit inspired from Spyking Circus sorter
-
-#     https://elifesciences.org/articles/34518
-
-#     This is an Orthogonal Template Matching algorithm. For speed and
-#     memory optimization, templates are automatically sparsified. Signal
-#     is convolved with the templates, and as long as some scalar products
-#     are higher than a given threshold, we use a Cholesky decomposition
-#     to compute the optimal amplitudes needed to reconstruct the signal.
-
-#     IMPORTANT NOTE: small chunks are more efficient for such Peeler,
-#     consider using 100ms chunk
-
-#     Parameters
-#     ----------
-#     amplitude: tuple
-#         (Minimal, Maximal) amplitudes allowed for every template
-#     max_failures: int
-#         Stopping criteria of the OMP algorithm, as number of retry while updating amplitudes
-#     sparse_kwargs: dict
-#         Parameters to extract a sparsity mask from the waveform_extractor, if not
-#         already sparse.
-#     rank: int, default: 5
-#         Number of components used internally by the SVD
-#     vicinity: int
-#         Size of the area surrounding a spike to perform modification (expressed in terms
-#         of template temporal width)
-#     -----
-#     """
-
-#     _default_params = {
-#         "amplitudes": [0.6, np.inf],
-#         "stop_criteria": "max_failures",
-#         "max_failures": 10,
-#         "omp_min_sps": 0.1,
-#         "relative_error": 5e-5,
-#         "templates": None,
-#         "rank": 5,
-#         "ignore_inds": [],
-#         "vicinity": 3,
-#     }
-
-#     @classmethod
-#     def _prepare_templates(cls, d):
-#         templates = d["templates"]
-#         num_templates = len(d["templates"].unit_ids)
-
-#         assert d["stop_criteria"] in ["max_failures", "omp_min_sps", "relative_error"]
-
-#         sparsity = templates.sparsity.mask
-
-#         units_overlaps = np.sum(np.logical_and(sparsity[:, np.newaxis, :], sparsity[np.newaxis, :, :]), axis=2)
-#         d["units_overlaps"] = units_overlaps > 0
-#         d["unit_overlaps_indices"] = {}
-#         for i in range(num_templates):
-#             (d["unit_overlaps_indices"][i],) = np.nonzero(d["units_overlaps"][i])
-
-#         templates_array = templates.get_dense_templates().copy()
-#         # Then we keep only the strongest components
-#         d["temporal"], d["singular"], d["spatial"], templates_array = compress_templates(templates_array, d["rank"])
-
-#         d["normed_templates"] = np.zeros(templates_array.shape, dtype=np.float32)
-#         d["norms"] = np.zeros(num_templates, dtype=np.float32)
-
-#         # And get the norms, saving compressed templates for CC matrix
-#         for count in range(num_templates):
-#             template = templates_array[count][:, sparsity[count]]
-#             d["norms"][count] = np.linalg.norm(template)
-#             d["normed_templates"][count][:, sparsity[count]] = template / d["norms"][count]
-
-#         d["temporal"] /= d["norms"][:, np.newaxis, np.newaxis]
-#         d["temporal"] = np.flip(d["temporal"], axis=1)
-
-#         d["overlaps"] = []
-#         d["max_similarity"] = np.zeros((num_templates, num_templates), dtype=np.float32)
-#         for i in range(num_templates):
-#             num_overlaps = np.sum(d["units_overlaps"][i])
-#             overlapping_units = np.where(d["units_overlaps"][i])[0]
-
-#             # Reconstruct unit template from SVD Matrices
-#             data = d["temporal"][i] * d["singular"][i][np.newaxis, :]
-#             template_i = np.matmul(data, d["spatial"][i, :, :])
-#             template_i = np.flipud(template_i)
-
-#             unit_overlaps = np.zeros([num_overlaps, 2 * d["num_samples"] - 1], dtype=np.float32)
-
-#             for count, j in enumerate(overlapping_units):
-#                 overlapped_channels = sparsity[j]
-#                 visible_i = template_i[:, overlapped_channels]
-
-#                 spatial_filters = d["spatial"][j, :, overlapped_channels]
-#                 spatially_filtered_template = np.matmul(visible_i, spatial_filters)
-#                 visible_i = spatially_filtered_template * d["singular"][j]
-
-#                 for rank in range(visible_i.shape[1]):
-#                     unit_overlaps[count, :] += np.convolve(visible_i[:, rank], d["temporal"][j][:, rank], mode="full")
-
-#                 d["max_similarity"][i, j] = np.max(unit_overlaps[count])
-
-#             d["overlaps"].append(unit_overlaps)
-
-#         if d["amplitudes"] is None:
-#             distances = np.sort(d["max_similarity"], axis=1)[:, ::-1]
-#             distances = 1 - distances[:, 1] / 2
-#             d["amplitudes"] = np.zeros((num_templates, 2))
-#             d["amplitudes"][:, 0] = distances
-#             d["amplitudes"][:, 1] = np.inf
-
-#         d["spatial"] = np.moveaxis(d["spatial"], [0, 1, 2], [1, 0, 2])
-#         d["temporal"] = np.moveaxis(d["temporal"], [0, 1, 2], [1, 2, 0])
-#         d["singular"] = d["singular"].T[:, :, np.newaxis]
-#         return d
-
-#     @classmethod
-#     def initialize_and_check_kwargs(cls, recording, kwargs):
-#         d = cls._default_params.copy()
-#         d.update(kwargs)
-
-#         assert isinstance(d["templates"], Templates), (
-#             f"The templates supplied is of type {type(d['templates'])} " f"and must be a Templates"
-#         )
-
-#         d["num_channels"] = recording.get_num_channels()
-#         d["num_samples"] = d["templates"].num_samples
-#         d["nbefore"] = d["templates"].nbefore
-#         d["nafter"] = d["templates"].nafter
-#         d["sampling_frequency"] = recording.get_sampling_frequency()
-#         d["vicinity"] *= d["num_samples"]
-
-#         if "overlaps" not in d:
-#             d = cls._prepare_templates(d)
-#         else:
-#             for key in [
-#                 "norms",
-#                 "temporal",
-#                 "spatial",
-#                 "singular",
-#                 "units_overlaps",
-#                 "unit_overlaps_indices",
-#             ]:
-#                 assert d[key] is not None, "If templates are provided, %d should also be there" % key
-
-#         d["num_templates"] = len(d["templates"].templates_array)
-#         d["ignore_inds"] = np.array(d["ignore_inds"])
-
-#         d["unit_overlaps_tables"] = {}
-#         for i in range(d["num_templates"]):
-#             d["unit_overlaps_tables"][i] = np.zeros(d["num_templates"], dtype=int)
-#             d["unit_overlaps_tables"][i][d["unit_overlaps_indices"][i]] = np.arange(len(d["unit_overlaps_indices"][i]))
-
-#         return d
-
-#     @classmethod
-#     def serialize_method_kwargs(cls, kwargs):
-#         kwargs = dict(kwargs)
-#         return kwargs
-
-#     @classmethod
-#     def unserialize_in_worker(cls, kwargs):
-#         return kwargs
-
-#     @classmethod
-#     def get_margin(cls, recording, kwargs):
-#         if kwargs["vicinity"] > 0:
-#             margin = kwargs["vicinity"]
-#         else:
-#             margin = 2 * kwargs["num_samples"]
-#         return margin
-
-#     @classmethod
-#     def main_function(cls, traces, d):
-#         import scipy.spatial
-#         import scipy
-
-#         (potrs,) = scipy.linalg.get_lapack_funcs(("potrs",), dtype=np.float32)
-
-#         (nrm2,) = scipy.linalg.get_blas_funcs(("nrm2",), dtype=np.float32)
-
-#         num_templates = d["num_templates"]
-#         num_samples = d["num_samples"]
-#         num_channels = d["num_channels"]
-#         overlaps_array = d["overlaps"]
-#         norms = d["norms"]
-#         omp_tol = np.finfo(np.float32).eps
-#         num_samples = d["nafter"] + d["nbefore"]
-#         neighbor_window = num_samples - 1
-#         if isinstance(d["amplitudes"], list):
-#             min_amplitude, max_amplitude = d["amplitudes"]
-#         else:
-#             min_amplitude, max_amplitude = d["amplitudes"][:, 0], d["amplitudes"][:, 1]
-#             min_amplitude = min_amplitude[:, np.newaxis]
-#             max_amplitude = max_amplitude[:, np.newaxis]
-#         ignore_inds = d["ignore_inds"]
-#         vicinity = d["vicinity"]
-
-#         num_timesteps = len(traces)
-
-#         num_peaks = num_timesteps - num_samples + 1
-#         conv_shape = (num_templates, num_peaks)
-#         scalar_products = np.zeros(conv_shape, dtype=np.float32)
-
-#         # Filter using overlap-and-add convolution
-#         if len(ignore_inds) > 0:
-#             not_ignored = ~np.isin(np.arange(num_templates), ignore_inds)
-#             spatially_filtered_data = np.matmul(d["spatial"][:, not_ignored, :], traces.T[np.newaxis, :, :])
-#             scaled_filtered_data = spatially_filtered_data * d["singular"][:, not_ignored, :]
-#             objective_by_rank = scipy.signal.oaconvolve(
-#                 scaled_filtered_data, d["temporal"][:, not_ignored, :], axes=2, mode="valid"
-#             )
-#             scalar_products[not_ignored] += np.sum(objective_by_rank, axis=0)
-#             scalar_products[ignore_inds] = -np.inf
-#         else:
-#             spatially_filtered_data = np.matmul(d["spatial"], traces.T[np.newaxis, :, :])
-#             scaled_filtered_data = spatially_filtered_data * d["singular"]
-#             objective_by_rank = scipy.signal.oaconvolve(scaled_filtered_data, d["temporal"], axes=2, mode="valid")
-#             scalar_products += np.sum(objective_by_rank, axis=0)
-
-#         num_spikes = 0
-
-#         spikes = np.empty(scalar_products.size, dtype=spike_dtype)
-
-#         M = np.zeros((num_templates, num_templates), dtype=np.float32)
-
-#         all_selections = np.empty((2, scalar_products.size), dtype=np.int32)
-#         final_amplitudes = np.zeros(scalar_products.shape, dtype=np.float32)
-#         num_selection = 0
-
-#         full_sps = scalar_products.copy()
-
-#         neighbors = {}
-
-#         all_amplitudes = np.zeros(0, dtype=np.float32)
-#         is_in_vicinity = np.zeros(0, dtype=np.int32)
-
-#         if d["stop_criteria"] == "omp_min_sps":
-#             stop_criteria = d["omp_min_sps"] * np.maximum(d["norms"], np.sqrt(num_channels * num_samples))
-#         elif d["stop_criteria"] == "max_failures":
-#             num_valids = 0
-#             nb_failures = d["max_failures"]
-#         elif d["stop_criteria"] == "relative_error":
-#             if len(ignore_inds) > 0:
-#                 new_error = np.linalg.norm(scalar_products[not_ignored])
-#             else:
-#                 new_error = np.linalg.norm(scalar_products)
-#             delta_error = np.inf
-
-#         do_loop = True
-
-#         while do_loop:
-#             best_amplitude_ind = scalar_products.argmax()
-#             best_cluster_ind, peak_index = np.unravel_index(best_amplitude_ind, scalar_products.shape)
-
-#             if num_selection > 0:
-#                 delta_t = selection[1] - peak_index
-#                 idx = np.where((delta_t < num_samples) & (delta_t > -num_samples))[0]
-#                 myline = neighbor_window + delta_t[idx]
-#                 myindices = selection[0, idx]
-
-#                 local_overlaps = overlaps_array[best_cluster_ind]
-#                 overlapping_templates = d["unit_overlaps_indices"][best_cluster_ind]
-#                 table = d["unit_overlaps_tables"][best_cluster_ind]
-
-#                 if num_selection == M.shape[0]:
-#                     Z = np.zeros((2 * num_selection, 2 * num_selection), dtype=np.float32)
-#                     Z[:num_selection, :num_selection] = M
-#                     M = Z
-
-#                 mask = np.isin(myindices, overlapping_templates)
-#                 a, b = myindices[mask], myline[mask]
-#                 M[num_selection, idx[mask]] = local_overlaps[table[a], b]
-
-#                 if vicinity == 0:
-#                     scipy.linalg.solve_triangular(
-#                         M[:num_selection, :num_selection],
-#                         M[num_selection, :num_selection],
-#                         trans=0,
-#                         lower=1,
-#                         overwrite_b=True,
-#                         check_finite=False,
-#                     )
-
-#                     v = nrm2(M[num_selection, :num_selection]) ** 2
-#                     Lkk = 1 - v
-#                     if Lkk <= omp_tol:  # selected atoms are dependent
-#                         break
-#                     M[num_selection, num_selection] = np.sqrt(Lkk)
-#                 else:
-#                     is_in_vicinity = np.where(np.abs(delta_t) < vicinity)[0]
-
-#                     if len(is_in_vicinity) > 0:
-#                         L = M[is_in_vicinity, :][:, is_in_vicinity]
-
-#                         M[num_selection, is_in_vicinity] = scipy.linalg.solve_triangular(
-#                             L, M[num_selection, is_in_vicinity], trans=0, lower=1, overwrite_b=True, check_finite=False
-#                         )
-
-#                         v = nrm2(M[num_selection, is_in_vicinity]) ** 2
-#                         Lkk = 1 - v
-#                         if Lkk <= omp_tol:  # selected atoms are dependent
-#                             break
-#                         M[num_selection, num_selection] = np.sqrt(Lkk)
-#                     else:
-#                         M[num_selection, num_selection] = 1.0
-#             else:
-#                 M[0, 0] = 1
-
-#             all_selections[:, num_selection] = [best_cluster_ind, peak_index]
-#             num_selection += 1
-
-#             selection = all_selections[:, :num_selection]
-#             res_sps = full_sps[selection[0], selection[1]]
-
-#             if vicinity == 0:
-#                 all_amplitudes, _ = potrs(M[:num_selection, :num_selection], res_sps, lower=True, overwrite_b=False)
-#                 all_amplitudes /= norms[selection[0]]
-#             else:
-#                 is_in_vicinity = np.append(is_in_vicinity, num_selection - 1)
-#                 all_amplitudes = np.append(all_amplitudes, np.float32(1))
-#                 L = M[is_in_vicinity, :][:, is_in_vicinity]
-#                 all_amplitudes[is_in_vicinity], _ = potrs(L, res_sps[is_in_vicinity], lower=True, overwrite_b=False)
-#                 all_amplitudes[is_in_vicinity] /= norms[selection[0][is_in_vicinity]]
-
-#             diff_amplitudes = all_amplitudes - final_amplitudes[selection[0], selection[1]]
-#             modified = np.where(np.abs(diff_amplitudes) > omp_tol)[0]
-#             final_amplitudes[selection[0], selection[1]] = all_amplitudes
-
-#             for i in modified:
-#                 tmp_best, tmp_peak = selection[:, i]
-#                 diff_amp = diff_amplitudes[i] * norms[tmp_best]
-
-#                 local_overlaps = overlaps_array[tmp_best]
-#                 overlapping_templates = d["units_overlaps"][tmp_best]
-
-#                 if not tmp_peak in neighbors.keys():
-#                     idx = [max(0, tmp_peak - neighbor_window), min(num_peaks, tmp_peak + num_samples)]
-#                     tdx = [neighbor_window + idx[0] - tmp_peak, num_samples + idx[1] - tmp_peak - 1]
-#                     neighbors[tmp_peak] = {"idx": idx, "tdx": tdx}
-
-#                 idx = neighbors[tmp_peak]["idx"]
-#                 tdx = neighbors[tmp_peak]["tdx"]
-
-#                 to_add = diff_amp * local_overlaps[:, tdx[0] : tdx[1]]
-#                 scalar_products[overlapping_templates, idx[0] : idx[1]] -= to_add
-
-#             # We stop when updates do not modify the chosen spikes anymore
-#             if d["stop_criteria"] == "omp_min_sps":
-#                 is_valid = scalar_products > stop_criteria[:, np.newaxis]
-#                 do_loop = np.any(is_valid)
-#             elif d["stop_criteria"] == "max_failures":
-#                 is_valid = (final_amplitudes > min_amplitude) * (final_amplitudes < max_amplitude)
-#                 new_num_valids = np.sum(is_valid)
-#                 if (new_num_valids - num_valids) > 0:
-#                     nb_failures = d["max_failures"]
-#                 else:
-#                     nb_failures -= 1
-#                 num_valids = new_num_valids
-#                 do_loop = nb_failures > 0
-#             elif d["stop_criteria"] == "relative_error":
-#                 previous_error = new_error
-#                 if len(ignore_inds) > 0:
-#                     new_error = np.linalg.norm(scalar_products[not_ignored])
-#                 else:
-#                     new_error = np.linalg.norm(scalar_products)
-#                 delta_error = np.abs(new_error / previous_error - 1)
-#                 do_loop = delta_error > d["relative_error"]
-
-#         is_valid = (final_amplitudes > min_amplitude) * (final_amplitudes < max_amplitude)
-#         valid_indices = np.where(is_valid)
-
-#         num_spikes = len(valid_indices[0])
-#         spikes["sample_index"][:num_spikes] = valid_indices[1] + d["nbefore"]
-#         spikes["channel_index"][:num_spikes] = 0
-#         spikes["cluster_index"][:num_spikes] = valid_indices[0]
-#         spikes["amplitude"][:num_spikes] = final_amplitudes[valid_indices[0], valid_indices[1]]
-
-#         spikes = spikes[:num_spikes]
-#         order = np.argsort(spikes["sample_index"])
-#         spikes = spikes[order]
-
-#         return spikes
-
 
 class CircusPeeler(BaseTemplateMatching):
     """
@@ -948,18 +556,6 @@ def __init__(self, recording, return_output=True, parents=None,
 
         self.abs_threholds = noise_levels * detect_threshold
 
-
-        #if "overlaps" not in d:
-        #     d = self._prepare_templates()
-        #     d["overlaps"] = compute_overlaps(
-        #         d["normed_templates"],
-        #         d["num_samples"],
-        #         d["num_channels"],
-        #         d["sparsities"],
-        #     )
-        # else:
-        #     for key in ["circus_templates", "norms"]:
-        #         assert d[key] is not None, "If templates are provided, %d should also be there" % key
         self.use_sparse_matrix_threshold = use_sparse_matrix_threshold
         self._prepare_templates()
         self.overlaps = compute_overlaps(
@@ -1107,341 +703,3 @@ def compute_matching(self, traces, start_frame, end_frame, segment_index):
 
         return spikes
 
-
-
-# class CircusPeeler(BaseTemplateMatchingEngine):
-#     """
-#     Greedy Template-matching ported from the Spyking Circus sorter
-
-#     https://elifesciences.org/articles/34518
-
-#     This is a Greedy Template Matching algorithm. The idea is to detect
-#     all the peaks (negative, positive or both) above a certain threshold
-#     Then, at every peak (plus or minus some jitter) we look if the signal
-#     can be explained with a scaled template.
-#     The amplitudes allowed, for every templates, are automatically adjusted
-#     in an optimal manner, to enhance the Matthew Correlation Coefficient
-#     between all spikes/templates in the waveformextractor. For speed and
-#     memory optimization, templates are automatically sparsified if the
-#     density of the matrix falls below a given threshold
-
-#     Parameters
-#     ----------
-#     peak_sign: str
-#         Sign of the peak (neg, pos, or both)
-#     exclude_sweep_ms: float
-#         The number of samples before/after to classify a peak (should be low)
-#     jitter: int
-#         The number of samples considered before/after every peak to search for
-#         matches
-#     detect_threshold: int
-#         The detection threshold
-#     noise_levels: array
-#         The noise levels, for every channels
-#     random_chunk_kwargs: dict
-#         Parameters for computing noise levels, if not provided (sub optimal)
-#     max_amplitude: float
-#         Maximal amplitude allowed for every template
-#     min_amplitude: float
-#         Minimal amplitude allowed for every template
-#     use_sparse_matrix_threshold: float
-#         If density of the templates is below a given threshold, sparse matrix
-#         are used (memory efficient)
-#     sparse_kwargs: dict
-#         Parameters to extract a sparsity mask from the waveform_extractor, if not
-#         already sparse.
-#     -----
-
-
-#     """
-
-#     _default_params = {
-#         "peak_sign": "neg",
-#         "exclude_sweep_ms": 0.1,
-#         "jitter_ms": 0.1,
-#         "detect_threshold": 5,
-#         "noise_levels": None,
-#         "random_chunk_kwargs": {},
-#         "max_amplitude": 1.5,
-#         "min_amplitude": 0.5,
-#         "use_sparse_matrix_threshold": 0.25,
-#         "templates": None,
-#     }
-
-#     @classmethod
-#     def _prepare_templates(cls, d):
-#         import scipy.spatial
-#         import scipy
-
-#         templates = d["templates"]
-#         num_samples = d["num_samples"]
-#         num_channels = d["num_channels"]
-#         num_templates = d["num_templates"]
-#         use_sparse_matrix_threshold = d["use_sparse_matrix_threshold"]
-
-#         d["norms"] = np.zeros(num_templates, dtype=np.float32)
-
-#         all_units = d["templates"].unit_ids
-
-#         sparsity = templates.sparsity.mask
-
-#         templates_array = templates.get_dense_templates()
-#         d["sparsities"] = {}
-#         d["normed_templates"] = {}
-
-#         for count, unit_id in enumerate(all_units):
-#             (d["sparsities"][count],) = np.nonzero(sparsity[count])
-#             d["norms"][count] = np.linalg.norm(templates_array[count])
-#             templates_array[count] /= d["norms"][count]
-#             d["normed_templates"][count] = templates_array[count][:, sparsity[count]]
-
-#         templates_array = templates_array.reshape(num_templates, -1)
-
-#         nnz = np.sum(templates_array != 0) / (num_templates * num_samples * num_channels)
-#         if nnz <= use_sparse_matrix_threshold:
-#             templates_array = scipy.sparse.csr_matrix(templates_array)
-#             print(f"Templates are automatically sparsified (sparsity level is {nnz})")
-#             d["is_dense"] = False
-#         else:
-#             d["is_dense"] = True
-
-#         d["circus_templates"] = templates_array
-
-#         return d
-
-#     # @classmethod
-#     # def _mcc_error(cls, bounds, good, bad):
-#     #     fn = np.sum((good < bounds[0]) | (good > bounds[1]))
-#     #     fp = np.sum((bounds[0] <= bad) & (bad <= bounds[1]))
-#     #     tp = np.sum((bounds[0] <= good) & (good <= bounds[1]))
-#     #     tn = np.sum((bad < bounds[0]) | (bad > bounds[1]))
-#     #     denom = (tp + fp) * (tp + fn) * (tn + fp) * (tn + fn)
-#     #     if denom > 0:
-#     #         mcc = 1 - (tp * tn - fp * fn) / np.sqrt(denom)
-#     #     else:
-#     #         mcc = 1
-#     #     return mcc
-
-#     # @classmethod
-#     # def _cost_function_mcc(cls, bounds, good, bad, delta_amplitude, alpha):
-#     #     # We want a minimal error, with the larger bounds that are possible
-#     #     cost = alpha * cls._mcc_error(bounds, good, bad) + (1 - alpha) * np.abs(
-#     #         (1 - (bounds[1] - bounds[0]) / delta_amplitude)
-#     #     )
-#     #     return cost
-
-#     # @classmethod
-#     # def _optimize_amplitudes(cls, noise_snippets, d):
-#     #     parameters = d
-#     #     waveform_extractor = parameters["waveform_extractor"]
-#     #     templates = parameters["templates"]
-#     #     num_templates = parameters["num_templates"]
-#     #     max_amplitude = parameters["max_amplitude"]
-#     #     min_amplitude = parameters["min_amplitude"]
-#     #     alpha = 0.5
-#     #     norms = parameters["norms"]
-#     #     all_units = list(waveform_extractor.sorting.unit_ids)
-
-#     #     parameters["amplitudes"] = np.zeros((num_templates, 2), dtype=np.float32)
-#     #     noise = templates.dot(noise_snippets) / norms[:, np.newaxis]
-
-#     #     all_amps = {}
-#     #     for count, unit_id in enumerate(all_units):
-#     #         waveform = waveform_extractor.get_waveforms(unit_id, force_dense=True)
-#     #         snippets = waveform.reshape(waveform.shape[0], -1).T
-#     #         amps = templates.dot(snippets) / norms[:, np.newaxis]
-#     #         good = amps[count, :].flatten()
-
-#     #         sub_amps = amps[np.concatenate((np.arange(count), np.arange(count + 1, num_templates))), :]
-#     #         bad = sub_amps[sub_amps >= good]
-#     #         bad = np.concatenate((bad, noise[count]))
-#     #         cost_kwargs = [good, bad, max_amplitude - min_amplitude, alpha]
-#     #         cost_bounds = [(min_amplitude, 1), (1, max_amplitude)]
-#     #         res = scipy.optimize.differential_evolution(cls._cost_function_mcc, bounds=cost_bounds, args=cost_kwargs)
-#     #         parameters["amplitudes"][count] = res.x
-
-#     #     return d
-
-#     @classmethod
-#     def initialize_and_check_kwargs(cls, recording, kwargs):
-#         try:
-#             from sklearn.feature_extraction.image import extract_patches_2d
-
-#             HAVE_SKLEARN = True
-#         except ImportError:
-#             HAVE_SKLEARN = False
-
-#         assert HAVE_SKLEARN, "CircusPeeler needs sklearn to work"
-#         d = cls._default_params.copy()
-#         d.update(kwargs)
-
-#         # assert isinstance(d['waveform_extractor'], WaveformExtractor)
-#         for v in ["use_sparse_matrix_threshold"]:
-#             assert (d[v] >= 0) and (d[v] <= 1), f"{v} should be in [0, 1]"
-
-#         d["num_channels"] = recording.get_num_channels()
-#         d["num_samples"] = d["templates"].num_samples
-#         d["num_templates"] = len(d["templates"].unit_ids)
-
-#         if d["noise_levels"] is None:
-#             print("CircusPeeler : noise should be computed outside")
-#             d["noise_levels"] = get_noise_levels(recording, **d["random_chunk_kwargs"], return_scaled=False)
-
-#         d["abs_threholds"] = d["noise_levels"] * d["detect_threshold"]
-
-#         if "overlaps" not in d:
-#             d = cls._prepare_templates(d)
-#             d["overlaps"] = compute_overlaps(
-#                 d["normed_templates"],
-#                 d["num_samples"],
-#                 d["num_channels"],
-#                 d["sparsities"],
-#             )
-#         else:
-#             for key in ["circus_templates", "norms"]:
-#                 assert d[key] is not None, "If templates are provided, %d should also be there" % key
-
-#         d["exclude_sweep_size"] = int(d["exclude_sweep_ms"] * recording.get_sampling_frequency() / 1000.0)
-
-#         d["nbefore"] = d["templates"].nbefore
-#         d["nafter"] = d["templates"].nafter
-#         d["patch_sizes"] = (
-#             d["templates"].num_samples,
-#             d["num_channels"],
-#         )
-#         d["sym_patch"] = d["nbefore"] == d["nafter"]
-#         d["jitter"] = int(d["jitter_ms"] * recording.get_sampling_frequency() / 1000.0)
-
-#         d["amplitudes"] = np.zeros((d["num_templates"], 2), dtype=np.float32)
-#         d["amplitudes"][:, 0] = d["min_amplitude"]
-#         d["amplitudes"][:, 1] = d["max_amplitude"]
-#         # num_segments = recording.get_num_segments()
-#         # if d["waveform_extractor"]._params["max_spikes_per_unit"] is None:
-#         #     num_snippets = 1000
-#         # else:
-#         #     num_snippets = 2 * d["waveform_extractor"]._params["max_spikes_per_unit"]
-
-#         # num_chunks = num_snippets // num_segments
-#         # noise_snippets = get_random_data_chunks(
-#         #     recording, num_chunks_per_segment=num_chunks, chunk_size=d["num_samples"], seed=42
-#         # )
-#         # noise_snippets = (
-#         #     noise_snippets.reshape(num_chunks, d["num_samples"], d["num_channels"])
-#         #     .reshape(num_chunks, -1)
-#         #     .T
-#         # )
-#         # parameters = cls._optimize_amplitudes(noise_snippets, d)
-
-#         return d
-
-#     @classmethod
-#     def serialize_method_kwargs(cls, kwargs):
-#         kwargs = dict(kwargs)
-#         return kwargs
-
-#     @classmethod
-#     def unserialize_in_worker(cls, kwargs):
-#         return kwargs
-
-#     @classmethod
-#     def get_margin(cls, recording, kwargs):
-#         margin = 2 * max(kwargs["nbefore"], kwargs["nafter"])
-#         return margin
-
-#     @classmethod
-#     def main_function(cls, traces, d):
-#         peak_sign = d["peak_sign"]
-#         abs_threholds = d["abs_threholds"]
-#         exclude_sweep_size = d["exclude_sweep_size"]
-#         templates = d["circus_templates"]
-#         num_templates = d["num_templates"]
-#         overlaps = d["overlaps"]
-#         margin = d["margin"]
-#         norms = d["norms"]
-#         jitter = d["jitter"]
-#         patch_sizes = d["patch_sizes"]
-#         num_samples = d["nafter"] + d["nbefore"]
-#         neighbor_window = num_samples - 1
-#         amplitudes = d["amplitudes"]
-#         sym_patch = d["sym_patch"]
-
-#         peak_traces = traces[margin // 2 : -margin // 2, :]
-#         peak_sample_index, peak_chan_ind = DetectPeakByChannel.detect_peaks(
-#             peak_traces, peak_sign, abs_threholds, exclude_sweep_size
-#         )
-#         from sklearn.feature_extraction.image import extract_patches_2d
-
-#         if jitter > 0:
-#             jittered_peaks = peak_sample_index[:, np.newaxis] + np.arange(-jitter, jitter)
-#             jittered_channels = peak_chan_ind[:, np.newaxis] + np.zeros(2 * jitter)
-#             mask = (jittered_peaks > 0) & (jittered_peaks < len(peak_traces))
-#             jittered_peaks = jittered_peaks[mask]
-#             jittered_channels = jittered_channels[mask]
-#             peak_sample_index, unique_idx = np.unique(jittered_peaks, return_index=True)
-#             peak_chan_ind = jittered_channels[unique_idx]
-#         else:
-#             peak_sample_index, unique_idx = np.unique(peak_sample_index, return_index=True)
-#             peak_chan_ind = peak_chan_ind[unique_idx]
-
-#         num_peaks = len(peak_sample_index)
-
-#         if sym_patch:
-#             snippets = extract_patches_2d(traces, patch_sizes)[peak_sample_index]
-#             peak_sample_index += margin // 2
-#         else:
-#             peak_sample_index += margin // 2
-#             snippet_window = np.arange(-d["nbefore"], d["nafter"])
-#             snippets = traces[peak_sample_index[:, np.newaxis] + snippet_window]
-
-#         if num_peaks > 0:
-#             snippets = snippets.reshape(num_peaks, -1)
-#             scalar_products = templates.dot(snippets.T)
-#         else:
-#             scalar_products = np.zeros((num_templates, 0), dtype=np.float32)
-
-#         num_spikes = 0
-#         spikes = np.empty(scalar_products.size, dtype=spike_dtype)
-#         idx_lookup = np.arange(scalar_products.size).reshape(num_templates, -1)
-
-#         min_sps = (amplitudes[:, 0] * norms)[:, np.newaxis]
-#         max_sps = (amplitudes[:, 1] * norms)[:, np.newaxis]
-
-#         is_valid = (scalar_products > min_sps) & (scalar_products < max_sps)
-
-#         cached_overlaps = {}
-
-#         while np.any(is_valid):
-#             best_amplitude_ind = scalar_products[is_valid].argmax()
-#             best_cluster_ind, peak_index = np.unravel_index(idx_lookup[is_valid][best_amplitude_ind], idx_lookup.shape)
-
-#             best_amplitude = scalar_products[best_cluster_ind, peak_index]
-#             best_peak_sample_index = peak_sample_index[peak_index]
-#             best_peak_chan_ind = peak_chan_ind[peak_index]
-
-#             peak_data = peak_sample_index - peak_sample_index[peak_index]
-#             is_valid_nn = np.searchsorted(peak_data, [-neighbor_window, neighbor_window + 1])
-#             idx_neighbor = peak_data[is_valid_nn[0] : is_valid_nn[1]] + neighbor_window
-
-#             if not best_cluster_ind in cached_overlaps.keys():
-#                 cached_overlaps[best_cluster_ind] = overlaps[best_cluster_ind].toarray()
-
-#             to_add = -best_amplitude * cached_overlaps[best_cluster_ind][:, idx_neighbor]
-
-#             scalar_products[:, is_valid_nn[0] : is_valid_nn[1]] += to_add
-#             scalar_products[best_cluster_ind, is_valid_nn[0] : is_valid_nn[1]] = -np.inf
-
-#             spikes["sample_index"][num_spikes] = best_peak_sample_index
-#             spikes["channel_index"][num_spikes] = best_peak_chan_ind
-#             spikes["cluster_index"][num_spikes] = best_cluster_ind
-#             spikes["amplitude"][num_spikes] = best_amplitude
-#             num_spikes += 1
-
-#             is_valid = (scalar_products > min_sps) & (scalar_products < max_sps)
-
-#         spikes["amplitude"][:num_spikes] /= norms[spikes["cluster_index"][:num_spikes]]
-
-#         spikes = spikes[:num_spikes]
-#         order = np.argsort(spikes["sample_index"])
-#         spikes = spikes[order]
-
-#         return spikes
diff --git a/src/spikeinterface/sortingcomponents/matching/main.py b/src/spikeinterface/sortingcomponents/matching/main.py
index 2af170a75e..484993c657 100644
--- a/src/spikeinterface/sortingcomponents/matching/main.py
+++ b/src/spikeinterface/sortingcomponents/matching/main.py
@@ -61,157 +61,3 @@ def find_spikes_from_templates(
         return spikes, outputs
     else:
         return spikes
-
-
-
-# def find_spikes_from_templates(
-#     recording, method="naive", method_kwargs={}, extra_outputs=False, verbose=False, **job_kwargs
-# ) -> np.ndarray | tuple[np.ndarray, dict]:
-#     """Find spike from a recording from given templates.
-
-#     Parameters
-#     ----------
-#     recording : RecordingExtractor
-#         The recording extractor object
-#     method : "naive" | "tridesclous" | "circus" | "circus-omp" | "wobble", default: "naive"
-#         Which method to use for template matching
-#     method_kwargs : dict, optional
-#         Keyword arguments for the chosen method
-#     extra_outputs : bool
-#         If True then method_kwargs is also returned
-#     **job_kwargs : dict
-#         Parameters for ChunkRecordingExecutor
-#     verbose : Bool, default: False
-#         If True, output is verbose
-
-#     Returns
-#     -------
-#     spikes : ndarray
-#         Spikes found from templates.
-#     method_kwargs:
-#         Optionaly returns for debug purpose.
-
-#     """
-#     from .method_list import matching_methods
-
-#     assert method in matching_methods, f"The 'method' {method} is not valid. Use a method from {matching_methods}"
-
-#     job_kwargs = fix_job_kwargs(job_kwargs)
-
-#     method_class = matching_methods[method]
-
-#     # initialize
-#     method_kwargs = method_class.initialize_and_check_kwargs(recording, method_kwargs)
-
-#     # add
-#     method_kwargs["margin"] = method_class.get_margin(recording, method_kwargs)
-
-#     # serialiaze for worker
-#     method_kwargs_seralized = method_class.serialize_method_kwargs(method_kwargs)
-
-#     # and run
-#     func = _find_spikes_chunk
-#     init_func = _init_worker_find_spikes
-#     init_args = (recording, method, method_kwargs_seralized)
-#     processor = ChunkRecordingExecutor(
-#         recording,
-#         func,
-#         init_func,
-#         init_args,
-#         handle_returns=True,
-#         job_name=f"find spikes ({method})",
-#         verbose=verbose,
-#         **job_kwargs,
-#     )
-#     spikes = processor.run()
-
-#     spikes = np.concatenate(spikes)
-
-#     if extra_outputs:
-#         return spikes, method_kwargs
-#     else:
-#         return spikes
-    
-
-
-
-# def _init_worker_find_spikes(recording, method, method_kwargs):
-#     """Initialize worker for finding spikes."""
-
-#     from .method_list import matching_methods
-
-#     method_class = matching_methods[method]
-#     method_kwargs = method_class.unserialize_in_worker(method_kwargs)
-
-#     # create a local dict per worker
-#     worker_ctx = {}
-#     worker_ctx["recording"] = recording
-#     worker_ctx["method"] = method
-#     worker_ctx["method_kwargs"] = method_kwargs
-#     worker_ctx["function"] = method_class.main_function
-
-#     return worker_ctx
-
-
-# def _find_spikes_chunk(segment_index, start_frame, end_frame, worker_ctx):
-#     """Find spikes from a chunk of data."""
-
-#     # recover variables of the worker
-#     recording = worker_ctx["recording"]
-#     method = worker_ctx["method"]
-#     method_kwargs = worker_ctx["method_kwargs"]
-#     margin = method_kwargs["margin"]
-
-#     # load trace in memory given some margin
-#     recording_segment = recording._recording_segments[segment_index]
-#     traces, left_margin, right_margin = get_chunk_with_margin(
-#         recording_segment, start_frame, end_frame, None, margin, add_zeros=True
-#     )
-
-#     function = worker_ctx["function"]
-
-#     with threadpool_limits(limits=1):
-#         spikes = function(traces, method_kwargs)
-
-#     # remove spikes in margin
-#     if margin > 0:
-#         keep = (spikes["sample_index"] >= margin) & (spikes["sample_index"] < (traces.shape[0] - margin))
-#         spikes = spikes[keep]
-
-#     spikes["sample_index"] += start_frame - margin
-#     spikes["segment_index"] = segment_index
-#     return spikes
-
-
-# # generic class for template engine
-# class BaseTemplateMatchingEngine:
-#     default_params = {}
-
-#     @classmethod
-#     def initialize_and_check_kwargs(cls, recording, kwargs):
-#         """This function runs before loops"""
-#         # need to be implemented in subclass
-#         raise NotImplementedError
-
-#     @classmethod
-#     def serialize_method_kwargs(cls, kwargs):
-#         """This function serializes kwargs to distribute them to workers"""
-#         # need to be implemented in subclass
-#         raise NotImplementedError
-
-#     @classmethod
-#     def unserialize_in_worker(cls, recording, kwargs):
-#         """This function unserializes kwargs in workers"""
-#         # need to be implemented in subclass
-#         raise NotImplementedError
-
-#     @classmethod
-#     def get_margin(cls, recording, kwargs):
-#         # need to be implemented in subclass
-#         raise NotImplementedError
-
-#     @classmethod
-#     def main_function(cls, traces, method_kwargs):
-#         """This function returns the number of samples for the chunk margins"""
-#         # need to be implemented in subclass
-#         raise NotImplementedError
diff --git a/src/spikeinterface/sortingcomponents/matching/naive.py b/src/spikeinterface/sortingcomponents/matching/naive.py
index 2f548b9175..387fae65b0 100644
--- a/src/spikeinterface/sortingcomponents/matching/naive.py
+++ b/src/spikeinterface/sortingcomponents/matching/naive.py
@@ -6,15 +6,7 @@
 import numpy as np
 from spikeinterface.core import get_noise_levels, get_channel_distances
 from spikeinterface.sortingcomponents.peak_detection import DetectPeakLocallyExclusive
-# from spikeinterface.core.template import Templates
 
-# spike_dtype = [
-#     ("sample_index", "int64"),
-#     ("channel_index", "int64"),
-#     ("cluster_index", "int64"),
-#     ("amplitude", "float64"),
-#     ("segment_index", "int64"),
-# ]
 
 
 from .base import BaseTemplateMatching, _base_matching_dtype
@@ -32,7 +24,6 @@ def __init__(self, recording, return_output=True, parents=None,
 
         BaseTemplateMatching.__init__(self, recording, templates, return_output=True, parents=None)
 
-        # TODO put this in base ????
         self.templates_array = self.templates.get_dense_templates()
 
         if noise_levels is None:
@@ -64,7 +55,7 @@ def compute_matching(self, traces, start_frame, end_frame, segment_index):
 
         spikes = np.zeros(peak_sample_ind.size, dtype=_base_matching_dtype)
         spikes["sample_index"] = peak_sample_ind
-        spikes["channel_index"] = peak_chan_ind  # TODO need to put the channel from template
+        spikes["channel_index"] = peak_chan_ind
 
         # naively take the closest template
         for i in range(peak_sample_ind.size):
@@ -80,105 +71,3 @@ def compute_matching(self, traces, start_frame, end_frame, segment_index):
 
         return spikes
     
-        
-# from .main import BaseTemplateMatchingEngine
-
-# class NaiveMatching(BaseTemplateMatchingEngine):
-#     """
-#     This is a naive template matching that does not resolve collision
-#     and does not take in account sparsity.
-#     It just minimizes the distance to templates for detected peaks.
-
-#     It is implemented for benchmarking against this low quality template matching.
-#     And also as an example how to deal with methods_kwargs, margin, intit, func, ...
-#     """
-
-#     default_params = {
-#         "templates": None,
-#         "peak_sign": "neg",
-#         "exclude_sweep_ms": 0.1,
-#         "detect_threshold": 5,
-#         "noise_levels": None,
-#         "radius_um": 100,
-#         "random_chunk_kwargs": {},
-#     }
-
-#     @classmethod
-#     def initialize_and_check_kwargs(cls, recording, kwargs):
-#         d = cls.default_params.copy()
-#         d.update(kwargs)
-
-#         assert isinstance(d["templates"], Templates), (
-#             f"The templates supplied is of type {type(d['templates'])} " f"and must be a Templates"
-#         )
-
-#         templates = d["templates"]
-
-#         if d["noise_levels"] is None:
-#             d["noise_levels"] = get_noise_levels(recording, **d["random_chunk_kwargs"], return_scaled=False)
-
-#         d["abs_threholds"] = d["noise_levels"] * d["detect_threshold"]
-
-#         channel_distance = get_channel_distances(recording)
-#         d["neighbours_mask"] = channel_distance < d["radius_um"]
-
-#         d["nbefore"] = templates.nbefore
-#         d["nafter"] = templates.nafter
-
-#         d["exclude_sweep_size"] = int(d["exclude_sweep_ms"] * recording.get_sampling_frequency() / 1000.0)
-
-#         return d
-
-#     @classmethod
-#     def get_margin(cls, recording, kwargs):
-#         margin = max(kwargs["nbefore"], kwargs["nafter"])
-#         return margin
-
-#     @classmethod
-#     def serialize_method_kwargs(cls, kwargs):
-#         kwargs = dict(kwargs)
-#         return kwargs
-
-#     @classmethod
-#     def unserialize_in_worker(cls, kwargs):
-#         return kwargs
-
-#     @classmethod
-#     def main_function(cls, traces, method_kwargs):
-#         peak_sign = method_kwargs["peak_sign"]
-#         abs_threholds = method_kwargs["abs_threholds"]
-#         exclude_sweep_size = method_kwargs["exclude_sweep_size"]
-#         neighbours_mask = method_kwargs["neighbours_mask"]
-#         templates_array = method_kwargs["templates"].get_dense_templates()
-
-#         nbefore = method_kwargs["nbefore"]
-#         nafter = method_kwargs["nafter"]
-
-#         margin = method_kwargs["margin"]
-
-#         if margin > 0:
-#             peak_traces = traces[margin:-margin, :]
-#         else:
-#             peak_traces = traces
-#         peak_sample_ind, peak_chan_ind = DetectPeakLocallyExclusive.detect_peaks(
-#             peak_traces, peak_sign, abs_threholds, exclude_sweep_size, neighbours_mask
-#         )
-#         peak_sample_ind += margin
-
-#         spikes = np.zeros(peak_sample_ind.size, dtype=spike_dtype)
-#         spikes["sample_index"] = peak_sample_ind
-#         spikes["channel_index"] = peak_chan_ind  # TODO need to put the channel from template
-
-#         # naively take the closest template
-#         for i in range(peak_sample_ind.size):
-#             i0 = peak_sample_ind[i] - nbefore
-#             i1 = peak_sample_ind[i] + nafter
-
-#             waveforms = traces[i0:i1, :]
-#             dist = np.sum(np.sum((templates_array - waveforms[None, :, :]) ** 2, axis=1), axis=1)
-#             cluster_index = np.argmin(dist)
-
-#             spikes["cluster_index"][i] = cluster_index
-#             spikes["amplitude"][i] = 0.0
-
-#         return spikes
diff --git a/src/spikeinterface/sortingcomponents/matching/tdc.py b/src/spikeinterface/sortingcomponents/matching/tdc.py
index 226b314b6d..8ec5fcb1d4 100644
--- a/src/spikeinterface/sortingcomponents/matching/tdc.py
+++ b/src/spikeinterface/sortingcomponents/matching/tdc.py
@@ -13,15 +13,6 @@
 
 from .base import BaseTemplateMatching, _base_matching_dtype
 
-# spike_dtype = [
-#     ("sample_index", "int64"),
-#     ("channel_index", "int64"),
-#     ("cluster_index", "int64"),
-#     ("amplitude", "float64"),
-#     ("segment_index", "int64"),
-# ]
-
-# from .main import BaseTemplateMatchingEngine
 
 try:
     import numba
@@ -313,323 +304,6 @@ def _find_spikes_one_level(self, traces, level=0):
 
 
 
-
-# class TridesclousPeeler(BaseTemplateMatchingEngine):
-#     """
-#     Template-matching ported from Tridesclous sorter.
-
-#     The idea of this peeler is pretty simple.
-#     1. Find peaks
-#     2. order by best amplitues
-#     3. find nearest template
-#     4. remove it from traces.
-#     5. in the residual find peaks again
-
-#     This method is quite fast but don't give exelent results to resolve
-#     spike collision when templates have high similarity.
-#     """
-
-#     default_params = {
-#         "templates": None,
-#         "peak_sign": "neg",
-#         "peak_shift_ms": 0.2,
-#         "detect_threshold": 5,
-#         "noise_levels": None,
-#         "radius_um": 100,
-#         "num_closest": 5,
-#         "sample_shift": 3,
-#         "ms_before": 0.8,
-#         "ms_after": 1.2,
-#         "num_peeler_loop": 2,
-#         "num_template_try": 1,
-#     }
-
-#     @classmethod
-#     def initialize_and_check_kwargs(cls, recording, kwargs):
-#         assert HAVE_NUMBA, "TridesclousPeeler needs numba to be installed"
-
-#         d = cls.default_params.copy()
-#         d.update(kwargs)
-
-#         assert isinstance(d["templates"], Templates), (
-#             f"The templates supplied is of type {type(d['templates'])} " f"and must be a Templates"
-#         )
-
-#         templates = d["templates"]
-#         unit_ids = templates.unit_ids
-#         channel_ids = templates.channel_ids
-
-#         sr = templates.sampling_frequency
-
-#         d["nbefore"] = templates.nbefore
-#         d["nafter"] = templates.nafter
-#         templates_array = templates.get_dense_templates()
-
-#         nbefore_short = int(d["ms_before"] * sr / 1000.0)
-#         nafter_short = int(d["ms_before"] * sr / 1000.0)
-#         assert nbefore_short <= templates.nbefore
-#         assert nafter_short <= templates.nafter
-#         d["nbefore_short"] = nbefore_short
-#         d["nafter_short"] = nafter_short
-#         s0 = templates.nbefore - nbefore_short
-#         s1 = -(templates.nafter - nafter_short)
-#         if s1 == 0:
-#             s1 = None
-#         templates_short = templates_array[:, slice(s0, s1), :].copy()
-#         d["templates_short"] = templates_short
-
-#         d["peak_shift"] = int(d["peak_shift_ms"] / 1000 * sr)
-
-#         if d["noise_levels"] is None:
-#             print("TridesclousPeeler : noise should be computed outside")
-#             d["noise_levels"] = get_noise_levels(recording)
-
-#         d["abs_thresholds"] = d["noise_levels"] * d["detect_threshold"]
-
-#         channel_distance = get_channel_distances(recording)
-#         d["neighbours_mask"] = channel_distance < d["radius_um"]
-
-#         sparsity = compute_sparsity(
-#             templates, method="best_channels"
-#         )  # , peak_sign=d["peak_sign"], threshold=d["detect_threshold"])
-#         template_sparsity_inds = sparsity.unit_id_to_channel_indices
-#         template_sparsity = np.zeros((unit_ids.size, channel_ids.size), dtype="bool")
-#         for unit_index, unit_id in enumerate(unit_ids):
-#             chan_inds = template_sparsity_inds[unit_id]
-#             template_sparsity[unit_index, chan_inds] = True
-
-#         d["template_sparsity"] = template_sparsity
-
-#         extremum_channel = get_template_extremum_channel(templates, peak_sign=d["peak_sign"], outputs="index")
-#         # as numpy vector
-#         extremum_channel = np.array([extremum_channel[unit_id] for unit_id in unit_ids], dtype="int64")
-#         d["extremum_channel"] = extremum_channel
-
-#         channel_locations = templates.probe.contact_positions
-
-#         # TODO try it with real locaion
-#         unit_locations = channel_locations[extremum_channel]
-#         # ~ print(unit_locations)
-
-#         # distance between units
-#         import scipy
-
-#         unit_distances = scipy.spatial.distance.cdist(unit_locations, unit_locations, metric="euclidean")
-
-#         # seach for closet units and unitary discriminant vector
-#         closest_units = []
-#         for unit_ind, unit_id in enumerate(unit_ids):
-#             order = np.argsort(unit_distances[unit_ind, :])
-#             closest_u = np.arange(unit_ids.size)[order].tolist()
-#             closest_u.remove(unit_ind)
-#             closest_u = np.array(closest_u[: d["num_closest"]])
-
-#             # compute unitary discriminent vector
-#             (chans,) = np.nonzero(d["template_sparsity"][unit_ind, :])
-#             template_sparse = templates_array[unit_ind, :, :][:, chans]
-#             closest_vec = []
-#             # against N closets
-#             for u in closest_u:
-#                 vec = templates_array[u, :, :][:, chans] - template_sparse
-#                 vec /= np.sum(vec**2)
-#                 closest_vec.append((u, vec))
-#             # against noise
-#             closest_vec.append((None, -template_sparse / np.sum(template_sparse**2)))
-
-#             closest_units.append(closest_vec)
-
-#         d["closest_units"] = closest_units
-
-#         # distance channel from unit
-#         import scipy
-
-#         distances = scipy.spatial.distance.cdist(channel_locations, unit_locations, metric="euclidean")
-#         near_cluster_mask = distances < d["radius_um"]
-
-#         # nearby cluster for each channel
-#         possible_clusters_by_channel = []
-#         for channel_index in range(distances.shape[0]):
-#             (cluster_inds,) = np.nonzero(near_cluster_mask[channel_index, :])
-#             possible_clusters_by_channel.append(cluster_inds)
-
-#         d["possible_clusters_by_channel"] = possible_clusters_by_channel
-#         d["possible_shifts"] = np.arange(-d["sample_shift"], d["sample_shift"] + 1, dtype="int64")
-
-#         return d
-
-#     @classmethod
-#     def serialize_method_kwargs(cls, kwargs):
-#         kwargs = dict(kwargs)
-#         return kwargs
-
-#     @classmethod
-#     def unserialize_in_worker(cls, kwargs):
-#         return kwargs
-
-#     @classmethod
-#     def get_margin(cls, recording, kwargs):
-#         margin = 2 * (kwargs["nbefore"] + kwargs["nafter"])
-#         return margin
-
-#     @classmethod
-#     def main_function(cls, traces, d):
-#         traces = traces.copy()
-
-#         all_spikes = []
-#         level = 0
-#         while True:
-#             spikes = _tdc_find_spikes(traces, d, level=level)
-#             keep = spikes["cluster_index"] >= 0
-
-#             if not np.any(keep):
-#                 break
-#             all_spikes.append(spikes[keep])
-
-#             level += 1
-
-#             if level == d["num_peeler_loop"]:
-#                 break
-
-#         if len(all_spikes) > 0:
-#             all_spikes = np.concatenate(all_spikes)
-#             order = np.argsort(all_spikes["sample_index"])
-#             all_spikes = all_spikes[order]
-#         else:
-#             all_spikes = np.zeros(0, dtype=spike_dtype)
-
-#         return all_spikes
-
-
-# def _tdc_find_spikes(traces, d, level=0):
-#     peak_sign = d["peak_sign"]
-#     templates = d["templates"]
-#     templates_short = d["templates_short"]
-#     templates_array = templates.get_dense_templates()
-
-#     margin = d["margin"]
-#     possible_clusters_by_channel = d["possible_clusters_by_channel"]
-
-#     peak_traces = traces[margin // 2 : -margin // 2, :]
-#     peak_sample_ind, peak_chan_ind = DetectPeakLocallyExclusive.detect_peaks(
-#         peak_traces, peak_sign, d["abs_thresholds"], d["peak_shift"], d["neighbours_mask"]
-#     )
-#     peak_sample_ind += margin // 2
-
-#     peak_amplitude = traces[peak_sample_ind, peak_chan_ind]
-#     order = np.argsort(np.abs(peak_amplitude))[::-1]
-#     peak_sample_ind = peak_sample_ind[order]
-#     peak_chan_ind = peak_chan_ind[order]
-
-#     spikes = np.zeros(peak_sample_ind.size, dtype=spike_dtype)
-#     spikes["sample_index"] = peak_sample_ind
-#     spikes["channel_index"] = peak_chan_ind  # TODO need to put the channel from template
-
-#     possible_shifts = d["possible_shifts"]
-#     distances_shift = np.zeros(possible_shifts.size)
-
-#     for i in range(peak_sample_ind.size):
-#         sample_index = peak_sample_ind[i]
-
-#         chan_ind = peak_chan_ind[i]
-#         possible_clusters = possible_clusters_by_channel[chan_ind]
-
-#         if possible_clusters.size > 0:
-#             # ~ s0 = sample_index - d['nbefore']
-#             # ~ s1 = sample_index + d['nafter']
-
-#             # ~ wf = traces[s0:s1, :]
-
-#             s0 = sample_index - d["nbefore_short"]
-#             s1 = sample_index + d["nafter_short"]
-#             wf_short = traces[s0:s1, :]
-
-#             ## pure numpy with cluster spasity
-#             # distances = np.sum(np.sum((templates[possible_clusters, :, :] - wf[None, : , :])**2, axis=1), axis=1)
-
-#             ## pure numpy with cluster+channel spasity
-#             # union_channels, = np.nonzero(np.any(d['template_sparsity'][possible_clusters, :], axis=0))
-#             # distances = np.sum(np.sum((templates[possible_clusters][:, :, union_channels] - wf[: , union_channels][None, : :])**2, axis=1), axis=1)
-
-#             ## numba with cluster+channel spasity
-#             union_channels = np.any(d["template_sparsity"][possible_clusters, :], axis=0)
-#             # distances = numba_sparse_dist(wf, templates, union_channels, possible_clusters)
-#             distances = numba_sparse_dist(wf_short, templates_short, union_channels, possible_clusters)
-
-#             # DEBUG
-#             # ~ ind = np.argmin(distances)
-#             # ~ cluster_index = possible_clusters[ind]
-
-#             for ind in np.argsort(distances)[: d["num_template_try"]]:
-#                 cluster_index = possible_clusters[ind]
-
-#                 chan_sparsity = d["template_sparsity"][cluster_index, :]
-#                 template_sparse = templates_array[cluster_index, :, :][:, chan_sparsity]
-
-#                 # find best shift
-
-#                 ## pure numpy version
-#                 # for s, shift in enumerate(possible_shifts):
-#                 #     wf_shift = traces[s0 + shift: s1 + shift, chan_sparsity]
-#                 #     distances_shift[s] = np.sum((template_sparse - wf_shift)**2)
-#                 # ind_shift = np.argmin(distances_shift)
-#                 # shift = possible_shifts[ind_shift]
-
-#                 ## numba version
-#                 numba_best_shift(
-#                     traces,
-#                     templates_array[cluster_index, :, :],
-#                     sample_index,
-#                     d["nbefore"],
-#                     possible_shifts,
-#                     distances_shift,
-#                     chan_sparsity,
-#                 )
-#                 ind_shift = np.argmin(distances_shift)
-#                 shift = possible_shifts[ind_shift]
-
-#                 sample_index = sample_index + shift
-#                 s0 = sample_index - d["nbefore"]
-#                 s1 = sample_index + d["nafter"]
-#                 wf_sparse = traces[s0:s1, chan_sparsity]
-
-#                 # accept or not
-
-#                 centered = wf_sparse - template_sparse
-#                 accepted = True
-#                 for other_ind, other_vector in d["closest_units"][cluster_index]:
-#                     v = np.sum(centered * other_vector)
-#                     if np.abs(v) > 0.5:
-#                         accepted = False
-#                         break
-
-#                 if accepted:
-#                     # ~ if ind != np.argsort(distances)[0]:
-#                     # ~ print('not first one', np.argsort(distances), ind)
-#                     break
-
-#             if accepted:
-#                 amplitude = 1.0
-
-#                 # remove template
-#                 template = templates_array[cluster_index, :, :]
-#                 s0 = sample_index - d["nbefore"]
-#                 s1 = sample_index + d["nafter"]
-#                 traces[s0:s1, :] -= template * amplitude
-
-#             else:
-#                 cluster_index = -1
-#                 amplitude = 0.0
-
-#         else:
-#             cluster_index = -1
-#             amplitude = 0.0
-
-#         spikes["cluster_index"][i] = cluster_index
-#         spikes["amplitude"][i] = amplitude
-
-#     return spikes
-
-
 if HAVE_NUMBA:
 
     @jit(nopython=True)
diff --git a/src/spikeinterface/sortingcomponents/matching/wobble.py b/src/spikeinterface/sortingcomponents/matching/wobble.py
index 242c35cc84..581eb78a77 100644
--- a/src/spikeinterface/sortingcomponents/matching/wobble.py
+++ b/src/spikeinterface/sortingcomponents/matching/wobble.py
@@ -4,7 +4,7 @@
 from dataclasses import dataclass
 from typing import List, Tuple, Optional
 
-# from .main import BaseTemplateMatchingEngine
+
 from .base import BaseTemplateMatching, _base_matching_dtype
 from spikeinterface.core.template import Templates
 
@@ -729,505 +729,6 @@ def enforce_refractory(
             objective[spike_unit_indices[:, np.newaxis], waveform_samples[:, 1:-1]] = -1 * np.inf
         return objective, objective_normalized
 
-# class WobbleMatch(BaseTemplateMatchingEngine):
-#     """Template matching method from the Paninski lab.
-
-#     Templates are jittered or "wobbled" in time and amplitude to capture variability in spike amplitude and
-#     super-resolution jitter in spike timing.
-
-#     Algorithm
-#     ---------
-#     At initialization:
-#         1. Compute channel sparsity to determine which units are "visible" to each other
-#         2. Compress Templates using Singular Value Decomposition into rank approx_rank
-#         3. Upsample the temporal component of compressed templates and re-index to obtain many super-resolution-jittered
-#             temporal components for each template
-#         3. Convolve each pair of jittered compressed templates together (subject to channel sparsity)
-#     For each chunk of traces:
-#         1. Compute the "objective function" to be minimized by convolving each true template with the traces
-#         2. Normalize the objective relative to the magnitude of each true template
-#         3. Detect spikes by indexing peaks in the objective corresponding to "matches" between the spike and a template
-#         4. Determine which super-resolution-jittered template best matches each spike and scale the amplitude to match
-#         5. Subtract scaled pairwise convolved jittered templates from the objective(s) to account for the effect of
-#             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
-
-#     Notes
-#     -----
-#     For consistency, throughout this module
-#     - a "unit" refers to a putative neuron which may have one or more "templates" of its spike waveform
-#     - Each "template" may have many upsampled "jittered_templates" depending on the "jitter_factor"
-#     - "peaks" refer to relative maxima in the convolution of the templates with the voltage trace
-#     - "spikes" refer to putative extracellular action potentials (EAPs)
-#     - "peaks" are considered spikes if their amplitude clears the threshold parameter
-#     """
-
-#     default_params = {
-#         "templates": None,
-#     }
-#     spike_dtype = [
-#         ("sample_index", "int64"),
-#         ("channel_index", "int64"),
-#         ("cluster_index", "int64"),
-#         ("amplitude", "float64"),
-#         ("segment_index", "int64"),
-#     ]
-
-#     @classmethod
-#     def initialize_and_check_kwargs(cls, recording, kwargs):
-#         """Initialize the objective and precompute various useful objects.
-
-#         Parameters
-#         ----------
-#         recording : RecordingExtractor
-#             The recording extractor object.
-#         kwargs : dict
-#             Keyword arguments for matching method.
-
-#         Returns
-#         -------
-#         d : dict
-#             Updated Keyword arguments.
-#         """
-#         d = cls.default_params.copy()
-
-#         required_kwargs_keys = ["templates"]
-#         for required_key in required_kwargs_keys:
-#             assert required_key in kwargs, f"`{required_key}` is a required key in the kwargs"
-
-#         parameters = kwargs.get("parameters", {})
-#         templates = kwargs["templates"]
-#         assert isinstance(templates, Templates), (
-#             f"The templates supplied is of type {type(d['templates'])} " f"and must be a Templates"
-#         )
-#         templates_array = templates.get_dense_templates().astype(np.float32, casting="safe")
-
-#         # Aggregate useful parameters/variables for handy access in downstream functions
-#         params = WobbleParameters(**parameters)
-#         template_meta = TemplateMetadata.from_parameters_and_templates(params, templates_array)
-#         if not templates.are_templates_sparse():
-#             sparsity = Sparsity.from_parameters_and_templates(params, templates_array)
-#         else:
-#             sparsity = Sparsity.from_templates(params, templates)
-
-#         # Perform initial computations on templates necessary for computing the objective
-#         sparse_templates = np.where(sparsity.visible_channels[:, np.newaxis, :], templates_array, 0)
-#         temporal, singular, spatial = compress_templates(sparse_templates, params.approx_rank)
-#         temporal_jittered = upsample_and_jitter(temporal, params.jitter_factor, template_meta.num_samples)
-#         compressed_templates = (temporal, singular, spatial, temporal_jittered)
-#         pairwise_convolution = convolve_templates(
-#             compressed_templates, params.jitter_factor, params.approx_rank, template_meta.jittered_indices, sparsity
-#         )
-#         norm_squared = compute_template_norm(sparsity.visible_channels, templates_array)
-#         template_data = TemplateData(
-#             compressed_templates=compressed_templates,
-#             pairwise_convolution=pairwise_convolution,
-#             norm_squared=norm_squared,
-#         )
-
-#         # Pack initial data into kwargs
-#         kwargs["params"] = params
-#         kwargs["template_meta"] = template_meta
-#         kwargs["sparsity"] = sparsity
-#         kwargs["template_data"] = template_data
-#         kwargs["nbefore"] = templates.nbefore
-#         kwargs["nafter"] = templates.nafter
-#         d.update(kwargs)
-#         return d
-
-#     @classmethod
-#     def serialize_method_kwargs(cls, kwargs):
-#         # This function does nothing without a waveform extractor -- candidate for refactor
-#         kwargs = dict(kwargs)
-#         return kwargs
-
-#     @classmethod
-#     def unserialize_in_worker(cls, kwargs):
-#         # This function does nothing without a waveform extractor -- candidate for refactor
-#         return kwargs
-
-#     @classmethod
-#     def get_margin(cls, recording, kwargs):
-#         """Get margin for chunking recording.
-
-#         Parameters
-#         ----------
-#         recording : RecordingExtractor
-#             The recording extractor object.
-#         kwargs : dict
-#             Keyword arguments for matching method.
-
-#         Returns
-#         -------
-#         margin : int
-#             Buffer in samples on each side of a chunk.
-#         """
-#         buffer_ms = 10
-#         # margin = int(buffer_ms*1e-3 * recording.sampling_frequency)
-#         margin = 300  # To ensure equivalence with spike-psvae version of the algorithm
-#         return margin
-
-#     @classmethod
-#     def main_function(cls, traces, method_kwargs):
-#         """Detect spikes in traces using the template matching algorithm.
-
-#         Parameters
-#         ----------
-#         traces : ndarray (chunk_len + 2*margin, num_channels)
-#             Voltage traces for a chunk of the recording.
-#         method_kwargs : dict
-#             Keyword arguments for matching method.
-
-#         Returns
-#         -------
-#         spikes : ndarray (num_spikes,)
-#             Resulting spike train.
-#         """
-#         # Unpack method_kwargs
-#         nbefore, nafter = method_kwargs["nbefore"], method_kwargs["nafter"]
-#         template_meta = method_kwargs["template_meta"]
-#         params = method_kwargs["params"]
-#         sparsity = method_kwargs["sparsity"]
-#         template_data = method_kwargs["template_data"]
-
-#         # Check traces
-#         assert traces.dtype == np.float32, "traces must be specified as np.float32"
-
-#         # Compute objective
-#         objective = compute_objective(traces, template_data, params.approx_rank)
-#         objective_normalized = 2 * objective - template_data.norm_squared[:, np.newaxis]
-
-#         # Compute spike train
-#         spike_trains, scalings, distance_metrics = [], [], []
-#         for i in range(params.max_iter):
-#             # find peaks
-#             spike_train, scaling, distance_metric = cls.find_peaks(
-#                 objective, objective_normalized, np.array(spike_trains), params, template_data, template_meta
-#             )
-#             if len(spike_train) == 0:
-#                 break
-
-#             # 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 = cls.subtract_spike_train(
-#                 spike_train, scaling, template_data, objective, objective_normalized, params, template_meta, sparsity
-#             )
-
-#         spike_train = np.array(spike_trains)
-#         scalings = np.array(scalings)
-#         distance_metric = np.array(distance_metrics)
-#         if len(spike_train) == 0:  # no spikes found
-#             return np.zeros(0, dtype=cls.spike_dtype)
-
-#         # order spike times
-#         index = np.argsort(spike_train[:, 0])
-#         spike_train = spike_train[index]
-#         scalings = scalings[index]
-#         distance_metric = distance_metric[index]
-
-#         # adjust spike_train
-#         spike_train[:, 0] += nbefore  # beginning of template --> center of template
-#         spike_train[:, 1] //= params.jitter_factor  # jittered_index --> template_index
-
-#         # TODO : Benchmark spike amplitudes
-#         # Find spike amplitudes / channels
-#         amplitudes, channel_inds = [], []
-#         for i, spike_index in enumerate(spike_train[:, 0]):
-#             best_ch = np.argmax(np.abs(traces[spike_index, :]))
-#             amp = np.abs(traces[spike_index, best_ch])
-#             amplitudes.append(amp)
-#             channel_inds.append(best_ch)
-
-#         # assign result to spikes array
-#         spikes = np.zeros(spike_train.shape[0], dtype=cls.spike_dtype)
-#         spikes["sample_index"] = spike_train[:, 0]
-#         spikes["cluster_index"] = spike_train[:, 1]
-#         spikes["channel_index"] = channel_inds
-#         spikes["amplitude"] = amplitudes
-
-#         return spikes
-
-#     # TODO: Replace this method with equivalent from spikeinterface
-#     @classmethod
-#     def find_peaks(
-#         cls, objective, objective_normalized, spike_trains, params, template_data, template_meta
-#     ) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
-#         """Find new peaks in the objective and update spike train accordingly.
-
-#         Parameters
-#         ----------
-#         objective : ndarray (num_templates, traces.shape[0]+template_meta.num_samples-1)
-#             Template matching objective for each template.
-#         objective_normalized : ndarray (num_templates, traces.shape[0]+template_meta.num_samples-1)
-#             Template matching objective normalized by the magnitude of each template.
-#         spike_trains : ndarray (n_spikes, 2)
-#             Spike train from template matching.
-#         params : WobbleParameters
-#             Dataclass object for aggregating the parameters together.
-#         template_meta : TemplateMetadata
-#             Dataclass object for aggregating template metadata together.
-
-#         Returns
-#         -------
-#         new_spike_train : ndarray (num_spikes, 2)
-#             Spike train from template matching with newly detected spikes added.
-#         scalings : ndarray (num_spikes,)
-#             Amplitude scaling used for each spike.
-#         distance_metric : ndarray (num_spikes)
-#             A metric that describes how good of a "fit" each spike is to its corresponding template
-
-#         Notes
-#         -----
-#         This function first identifies spike times (indices) using peaks in the objective that correspond to matches
-#         between a template and a spike. Then, it finds the best upsampled/jittered template corresponding to each spike.
-#         Finally, it generates a new spike train from the spike times, and returns it along with additional metrics about
-#         each spike.
-#         """
-#         from scipy import signal
-
-#         # Get spike times (indices) using peaks in the objective
-#         objective_template_max = np.max(objective_normalized, axis=0)
-#         spike_window = (template_meta.num_samples - 1, objective_normalized.shape[1] - template_meta.num_samples)
-#         objective_windowed = objective_template_max[spike_window[0] : spike_window[1]]
-#         spike_time_indices = signal.argrelmax(objective_windowed, order=template_meta.num_samples - 1)[0]
-#         spike_time_indices += template_meta.num_samples - 1
-#         objective_spikes = objective_template_max[spike_time_indices]
-#         spike_time_indices = spike_time_indices[objective_spikes > params.threshold]
-
-#         if len(spike_time_indices) == 0:  # No new spikes found
-#             return np.zeros((0, 2), dtype=np.int32), np.zeros(0), np.zeros(0)
-
-#         # Extract metrics using spike times (indices)
-#         distance_metric = objective_template_max[spike_time_indices]
-#         scalings = np.ones(len(spike_time_indices), dtype=objective_normalized.dtype)
-
-#         # Find the best upsampled template
-#         spike_template_indices = np.argmax(objective_normalized[:, spike_time_indices], axis=0)
-#         high_res_shifts = cls.calculate_high_res_shift(
-#             spike_time_indices,
-#             spike_template_indices,
-#             objective,
-#             objective_normalized,
-#             template_data,
-#             params,
-#             template_meta,
-#         )
-#         template_shift, time_shift, non_refractory_indices, scaling = high_res_shifts
-
-#         # Update unit_indices, spike_times, and scalings
-#         spike_jittered_indices = spike_template_indices * params.jitter_factor
-#         at_least_one_spike = bool(len(non_refractory_indices))
-#         if at_least_one_spike:
-#             spike_jittered_indices[non_refractory_indices] += template_shift
-#             spike_time_indices[non_refractory_indices] += time_shift
-#             scalings[non_refractory_indices] = scaling
-
-#         # Generate new spike train from spike times (indices)
-#         convolution_correction = -1 * (template_meta.num_samples - 1)  # convolution indices --> raw_indices
-#         spike_time_indices += convolution_correction
-#         new_spike_train = np.array([spike_time_indices, spike_jittered_indices]).T
-
-#         return new_spike_train, scalings, distance_metric
-
-#     @classmethod
-#     def subtract_spike_train(
-#         cls, spike_train, scalings, template_data, objective, objective_normalized, params, template_meta, sparsity
-#     ) -> tuple[np.ndarray, np.ndarray]:
-#         """Subtract spike train of templates from the objective directly.
-
-#         Parameters
-#         ----------
-#         spike_train : ndarray (num_spikes, 2)
-#             Spike train from template matching.
-#         scalings : ndarray (num_spikes,)
-#             Amplitude scaling used for each spike.
-#         objective : ndarray (num_templates, traces.shape[0]+num_samples-1)
-#             Template matching objective for each template.
-#         objective_normalized : ndarray (num_templates, traces.shape[0]+num_samples-1)
-#             Template matching objective normalized by the magnitude of each template.
-#         params : WobbleParameters
-#             Dataclass object for aggregating the parameters together.
-#         template_meta : TemplateMetadata
-#             Dataclass object for aggregating template metadata together.
-#         sparsity : Sparsity
-#             Dataclass object for aggregating channel sparsity variables together.
-
-#         Returns
-#         -------
-#         objective : ndarray (template_meta.num_templates, traces.shape[0]+template_meta.num_samples-1)
-#             Template matching objective for each template.
-#         objective_normalized : ndarray (num_templates, traces.shape[0]+template_meta.num_samples-1)
-#             Template matching objective normalized by the magnitude of each template.
-#         """
-#         present_jittered_indices = np.unique(spike_train[:, 1])
-#         convolution_resolution_len = get_convolution_len(template_meta.num_samples, template_meta.num_samples)
-#         for jittered_index in present_jittered_indices:
-#             id_mask = spike_train[:, 1] == jittered_index
-#             id_spiketrain = spike_train[id_mask, 0]
-#             id_scaling = scalings[id_mask]
-#             overlapping_templates = sparsity.unit_overlap[jittered_index]
-#             # Note: pairwise_conv only has overlapping template convolutions already
-#             pconv = template_data.pairwise_convolution[jittered_index]
-#             # 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[overlapping_templates, spike_start_index:spike_stop_index] -= pconv_scaled
-
-#             objective, objective_normalized = cls.enforce_refractory(
-#                 spike_train, objective, objective_normalized, params, template_meta
-#             )
-#         return objective, objective_normalized
-
-#     @classmethod
-#     def calculate_high_res_shift(
-#         cls,
-#         spike_time_indices,
-#         spike_unit_indices,
-#         objective,
-#         objective_normalized,
-#         template_data,
-#         params,
-#         template_meta,
-#     ) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
-#         """Determines optimal shifts when super-resolution, scaled templates are used.
-
-#         Parameters
-#         ----------
-#         spike_time_indices : ndarray (num_spikes,)
-#             Indices in the voltage traces corresponding to the time of each spike.
-#         spike_unit_indices : ndarray (num_spikes)
-#             Units corresponding to each spike.
-#         objective : ndarray (num_templates, traces.shape[0]+num_samples-1)
-#             Template matching objective for each template.
-#         objective_normalized : ndarray (num_templates, traces.shape[0]+num_samples-1)
-#             Template matching objective normalized by the magnitude of each template.
-#         template_data : TemplateData
-#             Dataclass object for aggregating template data together.
-#         params : WobbleParameters
-#             Dataclass object for aggregating the parameters together.
-#         template_meta : TemplateMetadata
-#             Dataclass object for aggregating template metadata together.
-
-#         Returns
-#         -------
-#         template_shift : ndarray (num_spikes,)
-#             Indices to shift each spike template_index to the correct jittered_index.
-#         time_shift : ndarray (num_spikes,)
-#             Indices to shift each spike time index to the adjusted time index.
-#         non_refractory_indices : ndarray
-#             Indices of the spike train that correspond to non-refractory spikes.
-#         scalings : ndarray (num_spikes,)
-#             Amplitude scaling used for each spike.
-#         """
-#         # Return identities if no high-resolution templates are necessary
-#         not_high_res = params.jitter_factor == 1 and not params.scale_amplitudes
-#         at_least_one_spike = bool(len(spike_time_indices))
-#         if not_high_res or not at_least_one_spike:
-#             template_shift = np.zeros_like(spike_time_indices)
-#             time_shift = np.zeros_like(spike_time_indices)
-#             non_refractory_indices = range(len(spike_time_indices))
-#             scalings = np.ones_like(spike_time_indices)
-#             return template_shift, time_shift, non_refractory_indices, scalings
-
-#         peak_indices = spike_time_indices + template_meta.peak_window[:, np.newaxis]
-#         objective_peaks = objective_normalized[spike_unit_indices, peak_indices]
-
-#         # Omit refractory spikes
-#         peak_is_refractory = np.logical_or(np.isinf(objective_peaks[0, :]), np.isinf(objective_peaks[-1, :]))
-#         refractory_before_spike = np.arange(-template_meta.overlapping_spike_buffer, 1)[:, np.newaxis]
-#         refractory_indices = spike_time_indices[peak_is_refractory] + refractory_before_spike
-#         objective_normalized[spike_unit_indices[peak_is_refractory], refractory_indices] = -1 * np.inf
-#         non_refractory_indices = np.flatnonzero(np.logical_not(peak_is_refractory))
-#         objective_peaks = objective_peaks[:, non_refractory_indices]
-#         if objective_peaks.shape[1] == 0:  # no non-refractory peaks --> exit function
-#             return np.array([]), np.array([]), np.array([]), np.array([])
-
-#         # Upsample and compute optimal template shift
-#         window_len_upsampled = template_meta.peak_window_len * params.jitter_factor
-#         from scipy import signal
-
-#         if not params.scale_amplitudes:
-#             # Perform simple upsampling using scipy.signal.resample
-#             high_resolution_peaks = signal.resample(objective_peaks, window_len_upsampled, axis=0)
-#             jitter = np.argmax(high_resolution_peaks[template_meta.jitter_window, :], axis=0)
-#             scalings = np.ones(len(non_refractory_indices))
-#         else:
-#             # upsampled the convolution for the detected peaks only
-#             objective_peaks_high_res = objective[spike_unit_indices, peak_indices]
-#             objective_peaks_high_res = objective_peaks_high_res[:, non_refractory_indices]
-#             high_resolution_conv = signal.resample(objective_peaks_high_res, window_len_upsampled, axis=0)
-
-#             # Find template norms for detected peaks only
-#             norm_peaks = template_data.norm_squared[spike_unit_indices[non_refractory_indices]]
-
-#             high_res_objective, scalings = compute_scale_amplitudes(
-#                 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))]
-
-#         # Extract outputs from jitter
-#         template_shift = template_meta.jitter2template_shift[jitter]
-#         time_shift = template_meta.jitter2spike_time_shift[jitter]
-#         return template_shift, time_shift, non_refractory_indices, scalings
-
-#     @classmethod
-#     def enforce_refractory(
-#         cls, spike_train, objective, objective_normalized, params, template_meta
-#     ) -> tuple[np.ndarray, np.ndarray]:
-#         """Enforcing the refractory period for each unit by setting the objective to -infinity.
-
-#         Parameters
-#         ----------
-#         spike_train : ndarray (num_spikes, 2)
-#             Spike train from template matching.
-#         objective : ndarray (num_templates, traces.shape[0]+num_samples-1)
-#             Template matching objective for each template.
-#         objective_normalized : ndarray (num_templates, traces.shape[0]+num_samples-1)
-#             Template matching objective normalized by the magnitude of each template.
-#         params : WobbleParameters
-#             Dataclass object for aggregating the parameters together.
-#         template_meta : TemplateMetadata
-#             Dataclass object for aggregating template metadata together.
-
-#         Returns
-#         -------
-#         objective : ndarray (template_meta.num_templates, traces.shape[0]+template_meta.num_samples-1)
-#             Template matching objective for each template.
-#         objective_normalized : ndarray (num_templates, traces.shape[0]+template_meta.num_samples-1)
-#             Template matching objective normalized by the magnitude of each template.
-#         """
-#         window = np.arange(-params.refractory_period_frames, params.refractory_period_frames + 1)
-
-#         # Adjust cluster IDs so that they match original templates
-#         spike_times = spike_train[:, 0]
-#         spike_template_indices = spike_train[:, 1] // params.jitter_factor
-
-#         # We want to enforce refractory conditions on unit_indices rather than template_indices for units with many templates
-#         spike_unit_indices = spike_template_indices.copy()
-#         for template_index in set(spike_template_indices):
-#             unit_index = template_meta.template_indices2unit_indices[
-#                 template_index
-#             ]  # unit_index corresponding to this template
-#             spike_unit_indices[spike_template_indices == template_index] = unit_index
-
-#         # Get the samples (time indices) that correspond to the waveform for each spike
-#         waveform_samples = get_convolution_len(spike_times[:, np.newaxis], template_meta.num_samples) + window
-
-#         # Enforce refractory by setting objective to negative infinity in invalid regions
-#         objective_normalized[spike_unit_indices[:, np.newaxis], waveform_samples[:, 1:-1]] = -1 * np.inf
-#         if params.scale_amplitudes:  # template_convolution is only used with amplitude scaling
-#             objective[spike_unit_indices[:, np.newaxis], waveform_samples[:, 1:-1]] = -1 * np.inf
-#         return objective, objective_normalized
-
 
 def compute_template_norm(visible_channels, templates):
     """Computes squared norm of each template.

From 3de7caddc60ed896c5e9aac30bcbaec4e45c0dbd Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 7 Oct 2024 16:39:43 +0000
Subject: [PATCH 085/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/core/node_pipeline.py      |  2 +-
 .../internal/tests/test_spykingcircus2.py     |  2 +
 .../sorters/internal/tridesclous2.py          |  2 +-
 .../clustering/clustering_tools.py            |  2 +-
 .../sortingcomponents/matching/base.py        | 15 ++--
 .../sortingcomponents/matching/circus.py      | 78 +++++++++----------
 .../sortingcomponents/matching/main.py        |  1 -
 .../sortingcomponents/matching/naive.py       | 17 ++--
 .../sortingcomponents/matching/tdc.py         | 25 +++---
 .../sortingcomponents/matching/wobble.py      | 25 ++++--
 .../tests/test_template_matching.py           | 13 ++--
 11 files changed, 102 insertions(+), 80 deletions(-)

diff --git a/src/spikeinterface/core/node_pipeline.py b/src/spikeinterface/core/node_pipeline.py
index 057bd9d683..540ee59fdb 100644
--- a/src/spikeinterface/core/node_pipeline.py
+++ b/src/spikeinterface/core/node_pipeline.py
@@ -96,7 +96,7 @@ def compute(self, traces, start_frame, end_frame, segment_index, max_margin, *ar
 
 
 class PeakSource(PipelineNode):
-    
+
     def get_trace_margin(self):
         raise NotImplementedError
 
diff --git a/src/spikeinterface/sorters/internal/tests/test_spykingcircus2.py b/src/spikeinterface/sorters/internal/tests/test_spykingcircus2.py
index b51abff570..df6e3821bb 100644
--- a/src/spikeinterface/sorters/internal/tests/test_spykingcircus2.py
+++ b/src/spikeinterface/sorters/internal/tests/test_spykingcircus2.py
@@ -6,12 +6,14 @@
 
 from pathlib import Path
 
+
 class SpykingCircus2SorterCommonTestSuite(SorterCommonTestSuite, unittest.TestCase):
     SorterClass = Spykingcircus2Sorter
 
 
 if __name__ == "__main__":
     from spikeinterface import set_global_job_kwargs
+
     set_global_job_kwargs(n_jobs=1, progress_bar=False)
     test = SpykingCircus2SorterCommonTestSuite()
     test.cache_folder = Path(__file__).resolve().parents[4] / "cache_folder" / "sorters"
diff --git a/src/spikeinterface/sorters/internal/tridesclous2.py b/src/spikeinterface/sorters/internal/tridesclous2.py
index f34471017b..a180fb4e02 100644
--- a/src/spikeinterface/sorters/internal/tridesclous2.py
+++ b/src/spikeinterface/sorters/internal/tridesclous2.py
@@ -226,7 +226,7 @@ def _run_from_folder(cls, sorter_output_folder, params, verbose):
         matching_method = params["matching"]["method"]
         matching_params = params["matching"]["method_kwargs"].copy()
         matching_params["templates"] = templates
-        if params["matching"]["method"] in ("tdc-peeler", ):
+        if params["matching"]["method"] in ("tdc-peeler",):
             matching_params["noise_levels"] = noise_levels
         spikes = find_spikes_from_templates(
             recording_for_peeler, method=matching_method, method_kwargs=matching_params, **job_kwargs
diff --git a/src/spikeinterface/sortingcomponents/clustering/clustering_tools.py b/src/spikeinterface/sortingcomponents/clustering/clustering_tools.py
index d93a4c257d..08a1384333 100644
--- a/src/spikeinterface/sortingcomponents/clustering/clustering_tools.py
+++ b/src/spikeinterface/sortingcomponents/clustering/clustering_tools.py
@@ -602,7 +602,7 @@ def detect_mixtures(templates, method_kwargs={}, job_kwargs={}, tmp_folder=None,
 
             sub_recording = recording.frame_slice(t_start, t_stop)
             local_params.update({"ignore_inds": ignore_inds + [i]})
-            
+
             spikes, more_outputs = find_spikes_from_templates(
                 sub_recording, method="circus-omp-svd", method_kwargs=local_params, extra_outputs=True, **job_kwargs
             )
diff --git a/src/spikeinterface/sortingcomponents/matching/base.py b/src/spikeinterface/sortingcomponents/matching/base.py
index 0c58f9b09b..0e60a9e864 100644
--- a/src/spikeinterface/sortingcomponents/matching/base.py
+++ b/src/spikeinterface/sortingcomponents/matching/base.py
@@ -10,14 +10,15 @@
     ("segment_index", "int64"),
 ]
 
+
 class BaseTemplateMatching(PeakDetector):
     def __init__(self, recording, templates, return_output=True, parents=None):
         # TODO make a sharedmem of template here
         # TODO maybe check that channel_id are the same with recording
 
-        assert isinstance(templates, Templates), (
-            f"The templates supplied is of type {type(templates)} and must be a Templates"
-        )
+        assert isinstance(
+            templates, Templates
+        ), f"The templates supplied is of type {type(templates)} and must be a Templates"
         self.templates = templates
         PeakDetector.__init__(self, recording, return_output=return_output, parents=parents)
 
@@ -25,7 +26,7 @@ def get_dtype(self):
         return np.dtype(_base_matching_dtype)
 
     def get_trace_margin(self):
-        raise NotImplementedError  
+        raise NotImplementedError
 
     def compute(self, traces, start_frame, end_frame, segment_index, max_margin):
         spikes = self.compute_matching(traces, start_frame, end_frame, segment_index)
@@ -37,11 +38,11 @@ def compute(self, traces, start_frame, end_frame, segment_index, max_margin):
             spikes = spikes[keep]
 
         # node pipeline need to return a tuple
-        return (spikes, )
+        return (spikes,)
 
     def compute_matching(self, traces, start_frame, end_frame, segment_index):
         raise NotImplementedError
-    
+
     def get_extra_outputs(self):
         # can be overwritten if need to ouput some variables with a dict
-        return None
\ No newline at end of file
+        return None
diff --git a/src/spikeinterface/sortingcomponents/matching/circus.py b/src/spikeinterface/sortingcomponents/matching/circus.py
index 5bce943fc0..a3624f4296 100644
--- a/src/spikeinterface/sortingcomponents/matching/circus.py
+++ b/src/spikeinterface/sortingcomponents/matching/circus.py
@@ -88,6 +88,7 @@ def compute_overlaps(templates, num_samples, num_channels, sparsities):
 
     return new_overlaps
 
+
 class CircusOMPSVDPeeler(BaseTemplateMatching):
     """
     Orthogonal Matching Pursuit inspired from Spyking Circus sorter
@@ -121,17 +122,21 @@ class CircusOMPSVDPeeler(BaseTemplateMatching):
     """
 
     _more_output_keys = [
-                "norms",
-                "temporal",
-                "spatial",
-                "singular",
-                "units_overlaps",
-                "unit_overlaps_indices",
-                "normed_templates",
-                "overlaps",
-            ]
-
-    def __init__(self, recording, return_output=True, parents=None,
+        "norms",
+        "temporal",
+        "spatial",
+        "singular",
+        "units_overlaps",
+        "unit_overlaps_indices",
+        "normed_templates",
+        "overlaps",
+    ]
+
+    def __init__(
+        self,
+        recording,
+        return_output=True,
+        parents=None,
         templates=None,
         amplitudes=[0.6, np.inf],
         stop_criteria="max_failures",
@@ -142,7 +147,7 @@ def __init__(self, recording, return_output=True, parents=None,
         ignore_inds=[],
         vicinity=3,
         precomputed=None,
-        ):
+    ):
 
         BaseTemplateMatching.__init__(self, recording, templates, return_output=True, parents=None)
 
@@ -169,7 +174,6 @@ def __init__(self, recording, return_output=True, parents=None,
                 assert precomputed[key] is not None, "If templates are provided, %d should also be there" % key
                 setattr(self, key, precomputed[key])
 
-        
         self.ignore_inds = np.array(ignore_inds)
 
         self.unit_overlaps_tables = {}
@@ -182,7 +186,6 @@ def __init__(self, recording, return_output=True, parents=None,
         else:
             self.margin = 2 * self.num_samples
 
-
     def _prepare_templates(self):
 
         assert self.stop_criteria in ["max_failures", "omp_min_sps", "relative_error"]
@@ -256,11 +259,8 @@ def get_extra_outputs(self):
             output[key] = getattr(self, key)
         return output
 
-
-
-
     def get_trace_margin(self):
-        return self.margin    
+        return self.margin
 
     def compute_matching(self, traces, start_frame, end_frame, segment_index):
         import scipy.spatial
@@ -468,10 +468,8 @@ def compute_matching(self, traces, start_frame, end_frame, segment_index):
         if spikes.size > 0:
             order = np.argsort(spikes["sample_index"])
             spikes = spikes[order]
-        
-        return spikes
-
 
+        return spikes
 
 
 class CircusPeeler(BaseTemplateMatching):
@@ -519,19 +517,23 @@ class CircusPeeler(BaseTemplateMatching):
 
 
     """
-    def __init__(self, recording, return_output=True, parents=None,
-  
-            templates=None,
-            peak_sign="neg",
-            exclude_sweep_ms=0.1,
-            jitter_ms=0.1,
-            detect_threshold=5,
-            noise_levels=None,
-            random_chunk_kwargs={},
-            max_amplitude=1.5,
-            min_amplitude=0.5,
-            use_sparse_matrix_threshold=0.25,
-        ):
+
+    def __init__(
+        self,
+        recording,
+        return_output=True,
+        parents=None,
+        templates=None,
+        peak_sign="neg",
+        exclude_sweep_ms=0.1,
+        jitter_ms=0.1,
+        detect_threshold=5,
+        noise_levels=None,
+        random_chunk_kwargs={},
+        max_amplitude=1.5,
+        min_amplitude=0.5,
+        use_sparse_matrix_threshold=0.25,
+    ):
 
         BaseTemplateMatching.__init__(self, recording, templates, return_output=True, parents=None)
 
@@ -544,7 +546,9 @@ def __init__(self, recording, return_output=True, parents=None,
 
         assert HAVE_SKLEARN, "CircusPeeler needs sklearn to work"
 
-        assert (use_sparse_matrix_threshold >= 0) and (use_sparse_matrix_threshold <= 1), f"use_sparse_matrix_threshold should be in [0, 1]"
+        assert (use_sparse_matrix_threshold >= 0) and (
+            use_sparse_matrix_threshold <= 1
+        ), f"use_sparse_matrix_threshold should be in [0, 1]"
 
         self.num_channels = recording.get_num_channels()
         self.num_samples = templates.num_samples
@@ -580,8 +584,6 @@ def __init__(self, recording, return_output=True, parents=None,
         self.margin = max(self.nbefore, self.nafter) * 2
         self.peak_sign = peak_sign
 
-
-
     def _prepare_templates(self):
         import scipy.spatial
         import scipy
@@ -617,7 +619,6 @@ def _prepare_templates(self):
     def get_trace_margin(self):
         return self.margin
 
-
     def compute_matching(self, traces, start_frame, end_frame, segment_index):
 
         neighbor_window = self.num_samples - 1
@@ -702,4 +703,3 @@ def compute_matching(self, traces, start_frame, end_frame, segment_index):
         spikes = spikes[order]
 
         return spikes
-
diff --git a/src/spikeinterface/sortingcomponents/matching/main.py b/src/spikeinterface/sortingcomponents/matching/main.py
index 484993c657..f423d55e2a 100644
--- a/src/spikeinterface/sortingcomponents/matching/main.py
+++ b/src/spikeinterface/sortingcomponents/matching/main.py
@@ -10,7 +10,6 @@
 from spikeinterface.core.node_pipeline import run_node_pipeline
 
 
-
 def find_spikes_from_templates(
     recording, method="naive", method_kwargs={}, extra_outputs=False, verbose=False, **job_kwargs
 ) -> np.ndarray | tuple[np.ndarray, dict]:
diff --git a/src/spikeinterface/sortingcomponents/matching/naive.py b/src/spikeinterface/sortingcomponents/matching/naive.py
index 387fae65b0..26f093c187 100644
--- a/src/spikeinterface/sortingcomponents/matching/naive.py
+++ b/src/spikeinterface/sortingcomponents/matching/naive.py
@@ -8,19 +8,23 @@
 from spikeinterface.sortingcomponents.peak_detection import DetectPeakLocallyExclusive
 
 
-
 from .base import BaseTemplateMatching, _base_matching_dtype
 
+
 class NaiveMatching(BaseTemplateMatching):
-    def __init__(self, recording, return_output=True, parents=None,
+    def __init__(
+        self,
+        recording,
+        return_output=True,
+        parents=None,
         templates=None,
         peak_sign="neg",
         exclude_sweep_ms=0.1,
         detect_threshold=5,
         noise_levels=None,
-        radius_um=100.,
+        radius_um=100.0,
         random_chunk_kwargs={},
-        ):
+    ):
 
         BaseTemplateMatching.__init__(self, recording, templates, return_output=True, parents=None)
 
@@ -37,15 +41,13 @@ def __init__(self, recording, return_output=True, parents=None,
         self.nafter = self.templates.nafter
         self.margin = max(self.nbefore, self.nafter)
 
-
     def get_trace_margin(self):
         return self.margin
 
-
     def compute_matching(self, traces, start_frame, end_frame, segment_index):
 
         if self.margin > 0:
-            peak_traces = traces[self.margin:-self.margin, :]
+            peak_traces = traces[self.margin : -self.margin, :]
         else:
             peak_traces = traces
         peak_sample_ind, peak_chan_ind = DetectPeakLocallyExclusive.detect_peaks(
@@ -70,4 +72,3 @@ def compute_matching(self, traces, start_frame, end_frame, segment_index):
             spikes["amplitude"][i] = 0.0
 
         return spikes
-    
diff --git a/src/spikeinterface/sortingcomponents/matching/tdc.py b/src/spikeinterface/sortingcomponents/matching/tdc.py
index 8ec5fcb1d4..56457fe2fa 100644
--- a/src/spikeinterface/sortingcomponents/matching/tdc.py
+++ b/src/spikeinterface/sortingcomponents/matching/tdc.py
@@ -37,24 +37,29 @@ class TridesclousPeeler(BaseTemplateMatching):
     This method is quite fast but don't give exelent results to resolve
     spike collision when templates have high similarity.
     """
-    def __init__(self, recording, return_output=True, parents=None,
+
+    def __init__(
+        self,
+        recording,
+        return_output=True,
+        parents=None,
         templates=None,
         peak_sign="neg",
         peak_shift_ms=0.2,
         detect_threshold=5,
         noise_levels=None,
-        radius_um=100.,
+        radius_um=100.0,
         num_closest=5,
         sample_shift=3,
         ms_before=0.8,
         ms_after=1.2,
         num_peeler_loop=2,
         num_template_try=1,
-        ):
+    ):
 
         BaseTemplateMatching.__init__(self, recording, templates, return_output=True, parents=None)
 
-        # maybe in base? 
+        # maybe in base?
         self.templates_array = templates.get_dense_templates()
 
         unit_ids = templates.unit_ids
@@ -64,7 +69,7 @@ def __init__(self, recording, return_output=True, parents=None,
 
         self.nbefore = templates.nbefore
         self.nafter = templates.nafter
-        
+
         self.peak_sign = peak_sign
 
         nbefore_short = int(ms_before * sr / 1000.0)
@@ -103,6 +108,7 @@ def __init__(self, recording, return_output=True, parents=None,
 
         # distance between units
         import scipy
+
         unit_distances = scipy.spatial.distance.cdist(unit_locations, unit_locations, metric="euclidean")
 
         # seach for closet units and unitary discriminant vector
@@ -111,7 +117,7 @@ def __init__(self, recording, return_output=True, parents=None,
             order = np.argsort(unit_distances[unit_ind, :])
             closest_u = np.arange(unit_ids.size)[order].tolist()
             closest_u.remove(unit_ind)
-            closest_u = np.array(closest_u[: num_closest])
+            closest_u = np.array(closest_u[:num_closest])
 
             # compute unitary discriminent vector
             (chans,) = np.nonzero(self.template_sparsity[unit_ind, :])
@@ -298,10 +304,8 @@ def _find_spikes_one_level(self, traces, level=0):
 
             spikes["cluster_index"][i] = cluster_index
             spikes["amplitude"][i] = amplitude
-        
-        return spikes
-
 
+        return spikes
 
 
 if HAVE_NUMBA:
@@ -346,6 +350,3 @@ def numba_best_shift(traces, template, sample_index, nbefore, possible_shifts, d
             distances_shift[i] = sum_dist
 
         return distances_shift
-
-
-
diff --git a/src/spikeinterface/sortingcomponents/matching/wobble.py b/src/spikeinterface/sortingcomponents/matching/wobble.py
index 581eb78a77..d8766581be 100644
--- a/src/spikeinterface/sortingcomponents/matching/wobble.py
+++ b/src/spikeinterface/sortingcomponents/matching/wobble.py
@@ -337,10 +337,14 @@ class WobbleMatch(BaseTemplateMatching):
     #     "templates": None,
     # }
 
-    def __init__(self, recording, return_output=True, parents=None,
+    def __init__(
+        self,
+        recording,
+        return_output=True,
+        parents=None,
         templates=None,
         parameters={},
-        ):
+    ):
 
         BaseTemplateMatching.__init__(self, recording, templates, return_output=True, parents=None)
 
@@ -404,7 +408,12 @@ def compute_matching(self, traces, start_frame, end_frame, segment_index):
         for i in range(self.params.max_iter):
             # find peaks
             spike_train, scaling, distance_metric = self.find_peaks(
-                objective, objective_normalized, np.array(spike_trains), self.params, self.template_data, self.template_meta
+                objective,
+                objective_normalized,
+                np.array(spike_trains),
+                self.params,
+                self.template_data,
+                self.template_meta,
             )
             if len(spike_train) == 0:
                 break
@@ -416,7 +425,14 @@ def compute_matching(self, traces, start_frame, end_frame, segment_index):
 
             # 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,
+                scaling,
+                self.template_data,
+                objective,
+                objective_normalized,
+                self.params,
+                self.template_meta,
+                self.sparsity,
             )
 
         spike_train = np.array(spike_trains)
@@ -950,4 +966,3 @@ def compute_scale_amplitudes(
     scalings = np.clip(b / a, scale_min, scale_max)
     high_res_objective = (2 * scalings * b) - (np.square(scalings) * a) - (1 / amplitude_variance)
     return high_res_objective, scalings
-
diff --git a/src/spikeinterface/sortingcomponents/tests/test_template_matching.py b/src/spikeinterface/sortingcomponents/tests/test_template_matching.py
index 7fdd64bca5..cbf1d29932 100644
--- a/src/spikeinterface/sortingcomponents/tests/test_template_matching.py
+++ b/src/spikeinterface/sortingcomponents/tests/test_template_matching.py
@@ -41,11 +41,13 @@ def test_find_spikes_from_templates(method, sorting_analyzer):
     noise_levels = sorting_analyzer.get_extension("noise_levels").get_data()
 
     # sorting_analyzer
-    method_kwargs_all = {"templates": templates, }
+    method_kwargs_all = {
+        "templates": templates,
+    }
     method_kwargs = {}
     if method in ("naive", "tdc-peeler", "circus"):
         method_kwargs["noise_levels"] = noise_levels
-    
+
     # method_kwargs["wobble"] = {
     #     "templates": waveform_extractor.get_all_templates(),
     #     "nbefore": waveform_extractor.nbefore,
@@ -53,8 +55,9 @@ def test_find_spikes_from_templates(method, sorting_analyzer):
     # }
 
     method_kwargs.update(method_kwargs_all)
-    spikes, info = find_spikes_from_templates(recording, method=method, 
-                                              method_kwargs=method_kwargs, extra_outputs=True, **job_kwargs)
+    spikes, info = find_spikes_from_templates(
+        recording, method=method, method_kwargs=method_kwargs, extra_outputs=True, **job_kwargs
+    )
 
     # print(info)
 
@@ -77,7 +80,7 @@ def test_find_spikes_from_templates(method, sorting_analyzer):
     #     comp = si.compare_sorter_to_ground_truth(gt_sorting, sorting)
     #     si.plot_agreement_matrix(comp, ax=ax)
     #     ax.set_title(method)
-        # plt.show()
+    # plt.show()
 
 
 if __name__ == "__main__":

From f5bcb6a52391a412588024a8f2348702e68b2385 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Mon, 7 Oct 2024 19:10:43 +0200
Subject: [PATCH 086/344] debug wobble after refactoring

---
 .../sortingcomponents/matching/wobble.py             | 12 ++++++------
 .../sortingcomponents/tests/test_wobble.py           |  2 +-
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/matching/wobble.py b/src/spikeinterface/sortingcomponents/matching/wobble.py
index 581eb78a77..8b9279896a 100644
--- a/src/spikeinterface/sortingcomponents/matching/wobble.py
+++ b/src/spikeinterface/sortingcomponents/matching/wobble.py
@@ -200,7 +200,7 @@ def from_parameters_and_templates(cls, params, templates):
 
 # important : this is differents from the spikeinterface.core.Sparsity
 @dataclass
-class _Sparsity:
+class WobbleSparsity:
     """Variables that describe channel sparsity.
 
     Parameters
@@ -228,7 +228,7 @@ def from_parameters_and_templates(cls, params, templates):
 
         Returns
         -------
-        sparsity : _Sparsity
+        sparsity : WobbleSparsity
             Dataclass object for aggregating channel sparsity variables together.
         """
         visible_channels = np.ptp(templates, axis=1) > params.visibility_threshold
@@ -252,7 +252,7 @@ def from_templates(cls, params, templates):
 
         Returns
         -------
-        sparsity : _Sparsity
+        sparsity : WobbleSparsity
             Dataclass object for aggregating channel sparsity variables together.
         """
         visible_channels = templates.sparsity.mask
@@ -350,9 +350,9 @@ def __init__(self, recording, return_output=True, parents=None,
         params = WobbleParameters(**parameters)
         template_meta = TemplateMetadata.from_parameters_and_templates(params, templates_array)
         if not templates.are_templates_sparse():
-            sparsity = _Sparsity.from_parameters_and_templates(params, templates_array)
+            sparsity = WobbleSparsity.from_parameters_and_templates(params, templates_array)
         else:
-            sparsity = _Sparsity.from_templates(params, templates)
+            sparsity = WobbleSparsity.from_templates(params, templates)
 
         # Perform initial computations on templates necessary for computing the objective
         sparse_templates = np.where(sparsity.visible_channels[:, np.newaxis, :], templates_array, 0)
@@ -555,7 +555,7 @@ def subtract_spike_train(
             Dataclass object for aggregating the parameters together.
         template_meta : TemplateMetadata
             Dataclass object for aggregating template metadata together.
-        sparsity : _Sparsity
+        sparsity : WobbleSparsity
             Dataclass object for aggregating channel sparsity variables together.
 
         Returns
diff --git a/src/spikeinterface/sortingcomponents/tests/test_wobble.py b/src/spikeinterface/sortingcomponents/tests/test_wobble.py
index 5e6be02409..d6d1e1e0b9 100644
--- a/src/spikeinterface/sortingcomponents/tests/test_wobble.py
+++ b/src/spikeinterface/sortingcomponents/tests/test_wobble.py
@@ -143,7 +143,7 @@ def test_convolve_templates():
         )
         unit_overlap = unit_overlap > 0
         unit_overlap = np.repeat(unit_overlap, jitter_factor, axis=0)
-        sparsity = wobble.Sparsity(visible_channels, unit_overlap)
+        sparsity = wobble.WobbleSparsity(visible_channels, unit_overlap)
 
         # Act: run convolve_templates
         pairwise_convolution = wobble.convolve_templates(

From 8c3699e9ea5dcb7f16487011ba8da3cf3e555346 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 7 Oct 2024 18:18:34 +0000
Subject: [PATCH 087/344] [pre-commit.ci] pre-commit autoupdate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

updates:
- [github.com/pre-commit/pre-commit-hooks: v4.6.0 → v5.0.0](https://github.com/pre-commit/pre-commit-hooks/compare/v4.6.0...v5.0.0)
---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 4c4bd68be4..1e133694ba 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -1,6 +1,6 @@
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
     -   id: check-yaml
     -   id: end-of-file-fixer

From 4e38686836aa0a105cb01e8c9dcd25bf7f20a662 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Mon, 7 Oct 2024 20:51:52 +0200
Subject: [PATCH 088/344] feedback and clean

---
 src/spikeinterface/core/recording_tools.py | 75 ++++++----------------
 1 file changed, 20 insertions(+), 55 deletions(-)

diff --git a/src/spikeinterface/core/recording_tools.py b/src/spikeinterface/core/recording_tools.py
index 37fcd9714a..cde6f0ced5 100644
--- a/src/spikeinterface/core/recording_tools.py
+++ b/src/spikeinterface/core/recording_tools.py
@@ -529,18 +529,19 @@ def get_random_recording_slices(recording,
     ----------
     recording : BaseRecording
         The recording to get random chunks from
-    methid : "legacy"
-        The method used.
+    method : "legacy"
+        The method used to get random slices.
+          * "legacy" : the one used until version 0.101.0, there is no constrain on slices
+            and they can overlap.
     num_chunks_per_segment : int, default: 20
         Number of chunks per segment
     chunk_duration : str | float | None, default "500ms"
         The duration of each chunk in 's' or 'ms'
     chunk_size : int | None
-        Size of a chunk in number of frames
-    
+        Size of a chunk in number of frames. This is ued only if chunk_duration is None.
     concatenated : bool, default: True
         If True chunk are concatenated along time axis
-    seed : int, default: 0
+    seed : int, default: None
         Random seed
     margin_frames : int, default: 0
         Margin in number of frames to avoid edge effects
@@ -596,7 +597,8 @@ def get_random_data_chunks(
     recording,
     return_scaled=False,
     num_chunks_per_segment=20,
-    chunk_size=10000,
+    chunk_duration="500ms",
+    chunk_size=None,
     concatenated=True,
     seed=0,
     margin_frames=0,
@@ -604,8 +606,6 @@ def get_random_data_chunks(
     """
     Extract random chunks across segments
 
-    This is used for instance in get_noise_levels() to estimate noise on traces.
-
     Parameters
     ----------
     recording : BaseRecording
@@ -614,8 +614,10 @@ def get_random_data_chunks(
         If True, returned chunks are scaled to uV
     num_chunks_per_segment : int, default: 20
         Number of chunks per segment
-    chunk_size : int, default: 10000
-        Size of a chunk in number of frames
+    chunk_duration : str | float | None, default "500ms"
+        The duration of each chunk in 's' or 'ms'
+    chunk_size : int | None
+        Size of a chunk in number of frames. This is ued only if chunk_duration is None.
     concatenated : bool, default: True
         If True chunk are concatenated along time axis
     seed : int, default: 0
@@ -628,51 +630,19 @@ def get_random_data_chunks(
     chunk_list : np.array
         Array of concatenate chunks per segment
     """
-    # # check chunk size
-    # num_segments = recording.get_num_segments()
-    # for segment_index in range(num_segments):
-    #     chunk_size_limit = recording.get_num_frames(segment_index) - 2 * margin_frames
-    #     if chunk_size > chunk_size_limit:
-    #         chunk_size = chunk_size_limit - 1
-    #         warnings.warn(
-    #             f"chunk_size is greater than the number "
-    #             f"of samples for segment index {segment_index}. "
-    #             f"Using {chunk_size}."
-    #         )
-
-    # rng = np.random.default_rng(seed)
-    # chunk_list = []
-    # low = margin_frames
-    # size = num_chunks_per_segment
-    # for segment_index in range(num_segments):
-    #     num_frames = recording.get_num_frames(segment_index)
-    #     high = num_frames - chunk_size - margin_frames
-    #     random_starts = rng.integers(low=low, high=high, size=size)
-    #     segment_trace_chunk = [
-    #         recording.get_traces(
-    #             start_frame=start_frame,
-    #             end_frame=(start_frame + chunk_size),
-    #             segment_index=segment_index,
-    #             return_scaled=return_scaled,
-    #         )
-    #         for start_frame in random_starts
-    #     ]
-
-    #     chunk_list.extend(segment_trace_chunk)
-
     recording_slices = get_random_recording_slices(recording,
                                 method="legacy",
                                 num_chunks_per_segment=num_chunks_per_segment,
+                                chunk_duration=chunk_duration,
                                 chunk_size=chunk_size,
-                                # chunk_duration=chunk_duration,
                                 margin_frames=margin_frames,
                                 seed=seed)
 
     chunk_list = []
-    for segment_index, start_frame, stop_frame in recording_slices:
+    for segment_index, start_frame, end_frame in recording_slices:
         traces_chunk = recording.get_traces(
             start_frame=start_frame,
-            end_frame=(start_frame + chunk_size),
+            end_frame=end_frame,
             segment_index=segment_index,
             return_scaled=return_scaled,
         )
@@ -773,7 +743,11 @@ def get_noise_levels(
     You can use standard deviation with `method="std"`
 
     Internally it samples some chunk across segment.
-    And then, it use MAD estimator (more robust than STD)
+    And then, it use MAD estimator (more robust than STD) ot the STD on each chunk.
+    Finally the average on all MAD is performed.
+
+    The result is cached in a property of the recording.
+    Next call on the same recording will use the cache unless force_recompute=True.
 
     Parameters
     ----------
@@ -803,15 +777,6 @@ def get_noise_levels(
     if key in recording.get_property_keys() and not force_recompute:
         noise_levels = recording.get_property(key=key)
     else:
-        # random_chunks = get_random_data_chunks(recording, return_scaled=return_scaled, **random_chunk_kwargs)
-
-        # if method == "mad":
-        #     med = np.median(random_chunks, axis=0, keepdims=True)
-        #     # hard-coded so that core doesn't depend on scipy
-        #     noise_levels = np.median(np.abs(random_chunks - med), axis=0) / 0.6744897501960817
-        # elif method == "std":
-        #     noise_levels = np.std(random_chunks, axis=0)
-
         random_slices_kwargs, job_kwargs = split_job_kwargs(kwargs)
         recording_slices = get_random_recording_slices(recording,**random_slices_kwargs)
 

From 484a5f4626c1cd160f40d08cb8f6980ea6f6b8b3 Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Tue, 8 Oct 2024 10:38:45 +0200
Subject: [PATCH 089/344] WIP

---
 src/spikeinterface/curation/auto_merge.py | 151 +++++++++++-----------
 1 file changed, 77 insertions(+), 74 deletions(-)

diff --git a/src/spikeinterface/curation/auto_merge.py b/src/spikeinterface/curation/auto_merge.py
index 00c156094d..7a101ad609 100644
--- a/src/spikeinterface/curation/auto_merge.py
+++ b/src/spikeinterface/curation/auto_merge.py
@@ -35,26 +35,31 @@ def auto_merges(
     sorting_analyzer: SortingAnalyzer,
     preset: str | None = "similarity_correlograms",
     resolve_graph: bool = False,
-    num_spikes_kwargs={"min_spikes": 100},
-    snr_kwargs={"min_snr": 2},
-    remove_contaminated_kwargs={"contamination_thresh": 0.2, "refractory_period_ms": 1.0, "censored_period_ms": 0.3},
-    unit_locations_kwargs={"max_distance_um": 50},
-    correlogram_kwargs={
-        "corr_diff_thresh": 0.16,
-        "censor_correlograms_ms": 0.3,
-        "sigma_smooth_ms": 0.6,
-        "adaptative_window_thresh": 0.5,
-    },
-    template_similarity_kwargs={"template_diff_thresh": 0.25},
-    presence_distance_kwargs={"presence_distance_thresh": 100},
-    knn_kwargs={"k_nn": 10},
-    cross_contamination_kwargs={
-        "cc_thresh": 0.1,
-        "p_value": 0.2,
-        "refractory_period_ms": 1.0,
-        "censored_period_ms": 0.3,
-    },
-    quality_score_kwargs={"firing_contamination_balance": 2.5, "refractory_period_ms": 1.0, "censored_period_ms": 0.3},
+    steps_params: dict = {"num_spikes" : {"min_spikes": 100},
+                    "snr" : {"min_snr": 2},
+                    "remove_contaminated" : {"contamination_thresh": 0.2, 
+                                             "refractory_period_ms": 1.0, 
+                                             "censored_period_ms": 0.3},
+                    "unit_locations" : {"max_distance_um": 50},
+                    "correlogram" : {
+                            "corr_diff_thresh": 0.16,
+                            "censor_correlograms_ms": 0.3,
+                            "sigma_smooth_ms": 0.6,
+                            "adaptative_window_thresh": 0.5,
+                        },
+                    "template_similarity" : {"template_diff_thresh": 0.25},
+                    "presence_distance" : {"presence_distance_thresh": 100},
+                    "knn" : {"k_nn": 10},
+                    "cross_contamination" : {
+                        "cc_thresh": 0.1,
+                        "p_value": 0.2,
+                        "refractory_period_ms": 1.0,
+                        "censored_period_ms": 0.3,
+                    },
+                    "quality_score" : {"firing_contamination_balance": 2.5, 
+                                       "refractory_period_ms": 1.0, 
+                                       "censored_period_ms": 0.3},
+                },
     compute_needed_extensions: bool = True,
     extra_outputs: bool = False,
     steps: list[str] | None = None,
@@ -115,7 +120,8 @@ def auto_merges(
         Which steps to run, if no preset is used.
         Pontential steps : "num_spikes", "snr", "remove_contaminated", "unit_locations", "correlogram",
         "template_similarity", "presence_distance", "cross_contamination", "knn", "quality_score"
-        Please check steps explanations above!$
+        Please check steps explanations above!
+    steps_params : A dictionary whose keys are the steps, and keys are steps parameters.
     force_copy : boolean, default: True
         When new extensions are computed, the default is to make a copy of the analyzer, to avoid overwriting
         already computed extensions. False if you want to overwrite
@@ -140,11 +146,6 @@ def auto_merges(
     sorting = sorting_analyzer.sorting
     unit_ids = sorting.unit_ids
 
-    # to get fast computation we will not analyse pairs when:
-    #    * not enough spikes for one of theses
-    #    * auto correlogram is contaminated
-    #    * to far away one from each other
-
     all_steps = [
         "num_spikes",
         "snr",
@@ -227,11 +228,13 @@ def auto_merges(
     for step in steps:
 
         assert step in all_steps, f"{step} is not a valid step"
+        params = steps_params.get(step, {})
 
         # STEP : remove units with too few spikes
         if step == "num_spikes":
+            
             num_spikes = sorting.count_num_spikes_per_unit(outputs="array")
-            to_remove = num_spikes < num_spikes_kwargs["min_spikes"]
+            to_remove = num_spikes < params["min_spikes"]
             pair_mask[to_remove, :] = False
             pair_mask[:, to_remove] = False
             outs["num_spikes"] = to_remove
@@ -245,7 +248,7 @@ def auto_merges(
                 qm_ext = sorting_analyzer.get_extension("quality_metrics")
 
             snrs = qm_ext.get_data()["snr"].values
-            to_remove = snrs < snr_kwargs["min_snr"]
+            to_remove = snrs < params["min_snr"]
             pair_mask[to_remove, :] = False
             pair_mask[:, to_remove] = False
             outs["snr"] = to_remove
@@ -254,12 +257,12 @@ def auto_merges(
         elif step == "remove_contaminated":
             contaminations, nb_violations = compute_refrac_period_violations(
                 sorting_analyzer,
-                refractory_period_ms=remove_contaminated_kwargs["refractory_period_ms"],
-                censored_period_ms=remove_contaminated_kwargs["censored_period_ms"],
+                refractory_period_ms=params["refractory_period_ms"],
+                censored_period_ms=params["censored_period_ms"],
             )
             nb_violations = np.array(list(nb_violations.values()))
             contaminations = np.array(list(contaminations.values()))
-            to_remove = contaminations > remove_contaminated_kwargs["contamination_thresh"]
+            to_remove = contaminations > params["contamination_thresh"]
             pair_mask[to_remove, :] = False
             pair_mask[:, to_remove] = False
             outs["remove_contaminated"] = to_remove
@@ -270,15 +273,15 @@ def auto_merges(
             unit_locations = location_ext.get_data()[:, :2]
 
             unit_distances = scipy.spatial.distance.cdist(unit_locations, unit_locations, metric="euclidean")
-            pair_mask = pair_mask & (unit_distances <= unit_locations_kwargs["max_distance_um"])
+            pair_mask = pair_mask & (unit_distances <= params["max_distance_um"])
             outs["unit_distances"] = unit_distances
 
         # STEP : potential auto merge by correlogram
         elif step == "correlogram" in steps:
             correlograms_ext = sorting_analyzer.get_extension("correlograms")
             correlograms, bins = correlograms_ext.get_data()
-            censor_ms = correlogram_kwargs["censor_correlograms_ms"]
-            sigma_smooth_ms = correlogram_kwargs["sigma_smooth_ms"]
+            censor_ms = params["censor_correlograms_ms"]
+            sigma_smooth_ms = params["sigma_smooth_ms"]
             mask = (bins[:-1] >= -censor_ms) & (bins[:-1] < censor_ms)
             correlograms[:, :, mask] = 0
             correlograms_smoothed = smooth_correlogram(correlograms, bins, sigma_smooth_ms=sigma_smooth_ms)
@@ -286,7 +289,7 @@ def auto_merges(
             win_sizes = np.zeros(n, dtype=int)
             for unit_ind in range(n):
                 auto_corr = correlograms_smoothed[unit_ind, unit_ind, :]
-                thresh = np.max(auto_corr) * correlogram_kwargs["adaptative_window_thresh"]
+                thresh = np.max(auto_corr) * params["adaptative_window_thresh"]
                 win_size = get_unit_adaptive_window(auto_corr, thresh)
                 win_sizes[unit_ind] = win_size
             correlogram_diff = compute_correlogram_diff(
@@ -296,7 +299,7 @@ def auto_merges(
                 pair_mask=pair_mask,
             )
             # print(correlogram_diff)
-            pair_mask = pair_mask & (correlogram_diff < correlogram_kwargs["corr_diff_thresh"])
+            pair_mask = pair_mask & (correlogram_diff < params["corr_diff_thresh"])
             outs["correlograms"] = correlograms
             outs["bins"] = bins
             outs["correlograms_smoothed"] = correlograms_smoothed
@@ -308,16 +311,16 @@ def auto_merges(
             template_similarity_ext = sorting_analyzer.get_extension("template_similarity")
             templates_similarity = template_similarity_ext.get_data()
             templates_diff = 1 - templates_similarity
-            pair_mask = pair_mask & (templates_diff < template_similarity_kwargs["template_diff_thresh"])
+            pair_mask = pair_mask & (templates_diff < params["template_diff_thresh"])
             outs["templates_diff"] = templates_diff
 
         # STEP : check the vicinity of the spikes
         elif step == "knn" in steps:
-            pair_mask = get_pairs_via_nntree(sorting_analyzer, **knn_kwargs, pair_mask=pair_mask)
+            pair_mask = get_pairs_via_nntree(sorting_analyzer, **params, pair_mask=pair_mask)
 
         # STEP : check how the rates overlap in times
         elif step == "presence_distance" in steps:
-            presence_distance_kwargs = presence_distance_kwargs.copy()
+            presence_distance_kwargs = params.copy()
             presence_distance_thresh = presence_distance_kwargs.pop("presence_distance_thresh")
             num_samples = [
                 sorting_analyzer.get_num_samples(segment_index) for segment_index in range(sorting.get_num_segments())
@@ -331,13 +334,13 @@ def auto_merges(
         # STEP : check if the cross contamination is significant
         elif step == "cross_contamination" in steps:
             refractory = (
-                cross_contamination_kwargs["censored_period_ms"],
-                cross_contamination_kwargs["refractory_period_ms"],
+                params["censored_period_ms"],
+                params["refractory_period_ms"],
             )
             CC, p_values = compute_cross_contaminations(
-                sorting_analyzer, pair_mask, cross_contamination_kwargs["cc_thresh"], refractory, contaminations
+                sorting_analyzer, pair_mask, params["cc_thresh"], refractory, contaminations
             )
-            pair_mask = pair_mask & (p_values > cross_contamination_kwargs["p_value"])
+            pair_mask = pair_mask & (p_values > params["p_value"])
             outs["cross_contaminations"] = CC, p_values
 
         # STEP : validate the potential merges with CC increase the contamination quality metrics
@@ -346,9 +349,9 @@ def auto_merges(
                 sorting_analyzer,
                 pair_mask,
                 contaminations,
-                quality_score_kwargs["firing_contamination_balance"],
-                quality_score_kwargs["refractory_period_ms"],
-                quality_score_kwargs["censored_period_ms"],
+                params["firing_contamination_balance"],
+                params["refractory_period_ms"],
+                params["censored_period_ms"],
             )
             outs["pairs_decreased_score"] = pairs_decreased_score
 
@@ -505,34 +508,34 @@ def get_potential_auto_merge(
         sorting_analyzer,
         preset,
         resolve_graph,
-        num_spikes_kwargs={"min_spikes": min_spikes},
-        snr_kwargs={"min_snr": min_snr},
-        remove_contaminated_kwargs={
-            "contamination_thresh": contamination_thresh,
-            "refractory_period_ms": refractory_period_ms,
-            "censored_period_ms": censored_period_ms,
-        },
-        unit_locations_kwargs={"max_distance_um": max_distance_um},
-        correlogram_kwargs={
-            "corr_diff_thresh": corr_diff_thresh,
-            "censor_correlograms_ms": censor_correlograms_ms,
-            "sigma_smooth_ms": sigma_smooth_ms,
-            "adaptative_window_thresh": adaptative_window_thresh,
-        },
-        template_similarity_kwargs={"template_diff_thresh": template_diff_thresh},
-        presence_distance_kwargs={"presence_distance_thresh": presence_distance_thresh, **presence_distance_kwargs},
-        knn_kwargs={"k_nn": k_nn, **knn_kwargs},
-        cross_contamination_kwargs={
-            "cc_thresh": cc_thresh,
-            "p_value": p_value,
-            "refractory_period_ms": refractory_period_ms,
-            "censored_period_ms": censored_period_ms,
-        },
-        quality_score_kwargs={
-            "firing_contamination_balance": firing_contamination_balance,
-            "refractory_period_ms": refractory_period_ms,
-            "censored_period_ms": censored_period_ms,
-        },
+        step_params={"num_spikes" : {"min_spikes": min_spikes},
+                    "snr_kwargs" : {"min_snr": min_snr},
+                    "remove_contaminated_kwargs" : {
+                        "contamination_thresh": contamination_thresh,
+                        "refractory_period_ms": refractory_period_ms,
+                        "censored_period_ms": censored_period_ms,
+                    },
+                    "unit_locations" : {"max_distance_um": max_distance_um},
+                    "correlogram" : {
+                        "corr_diff_thresh": corr_diff_thresh,
+                        "censor_correlograms_ms": censor_correlograms_ms,
+                        "sigma_smooth_ms": sigma_smooth_ms,
+                        "adaptative_window_thresh": adaptative_window_thresh,
+                    },
+                    "template_similarity":  {"template_diff_thresh": template_diff_thresh},
+                    "presence_distance" : {"presence_distance_thresh": presence_distance_thresh, **presence_distance_kwargs},
+                    "knn" : {"k_nn": k_nn, **knn_kwargs},
+                    "cross_contamination" : {
+                        "cc_thresh": cc_thresh,
+                        "p_value": p_value,
+                        "refractory_period_ms": refractory_period_ms,
+                        "censored_period_ms": censored_period_ms,
+                    },
+                    "quality_score" : {
+                        "firing_contamination_balance": firing_contamination_balance,
+                        "refractory_period_ms": refractory_period_ms,
+                        "censored_period_ms": censored_period_ms,
+                    }},
         compute_needed_extensions=False,
         extra_outputs=extra_outputs,
         steps=steps,

From 35ad317e619be60abbdd40f1da41a167171be1c9 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Tue, 8 Oct 2024 08:41:42 +0000
Subject: [PATCH 090/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/curation/auto_merge.py | 107 +++++++++++-----------
 1 file changed, 53 insertions(+), 54 deletions(-)

diff --git a/src/spikeinterface/curation/auto_merge.py b/src/spikeinterface/curation/auto_merge.py
index 7a101ad609..db3300f0d2 100644
--- a/src/spikeinterface/curation/auto_merge.py
+++ b/src/spikeinterface/curation/auto_merge.py
@@ -35,31 +35,28 @@ def auto_merges(
     sorting_analyzer: SortingAnalyzer,
     preset: str | None = "similarity_correlograms",
     resolve_graph: bool = False,
-    steps_params: dict = {"num_spikes" : {"min_spikes": 100},
-                    "snr" : {"min_snr": 2},
-                    "remove_contaminated" : {"contamination_thresh": 0.2, 
-                                             "refractory_period_ms": 1.0, 
-                                             "censored_period_ms": 0.3},
-                    "unit_locations" : {"max_distance_um": 50},
-                    "correlogram" : {
-                            "corr_diff_thresh": 0.16,
-                            "censor_correlograms_ms": 0.3,
-                            "sigma_smooth_ms": 0.6,
-                            "adaptative_window_thresh": 0.5,
-                        },
-                    "template_similarity" : {"template_diff_thresh": 0.25},
-                    "presence_distance" : {"presence_distance_thresh": 100},
-                    "knn" : {"k_nn": 10},
-                    "cross_contamination" : {
-                        "cc_thresh": 0.1,
-                        "p_value": 0.2,
-                        "refractory_period_ms": 1.0,
-                        "censored_period_ms": 0.3,
-                    },
-                    "quality_score" : {"firing_contamination_balance": 2.5, 
-                                       "refractory_period_ms": 1.0, 
-                                       "censored_period_ms": 0.3},
-                },
+    steps_params: dict = {
+        "num_spikes": {"min_spikes": 100},
+        "snr": {"min_snr": 2},
+        "remove_contaminated": {"contamination_thresh": 0.2, "refractory_period_ms": 1.0, "censored_period_ms": 0.3},
+        "unit_locations": {"max_distance_um": 50},
+        "correlogram": {
+            "corr_diff_thresh": 0.16,
+            "censor_correlograms_ms": 0.3,
+            "sigma_smooth_ms": 0.6,
+            "adaptative_window_thresh": 0.5,
+        },
+        "template_similarity": {"template_diff_thresh": 0.25},
+        "presence_distance": {"presence_distance_thresh": 100},
+        "knn": {"k_nn": 10},
+        "cross_contamination": {
+            "cc_thresh": 0.1,
+            "p_value": 0.2,
+            "refractory_period_ms": 1.0,
+            "censored_period_ms": 0.3,
+        },
+        "quality_score": {"firing_contamination_balance": 2.5, "refractory_period_ms": 1.0, "censored_period_ms": 0.3},
+    },
     compute_needed_extensions: bool = True,
     extra_outputs: bool = False,
     steps: list[str] | None = None,
@@ -232,7 +229,7 @@ def auto_merges(
 
         # STEP : remove units with too few spikes
         if step == "num_spikes":
-            
+
             num_spikes = sorting.count_num_spikes_per_unit(outputs="array")
             to_remove = num_spikes < params["min_spikes"]
             pair_mask[to_remove, :] = False
@@ -508,34 +505,36 @@ def get_potential_auto_merge(
         sorting_analyzer,
         preset,
         resolve_graph,
-        step_params={"num_spikes" : {"min_spikes": min_spikes},
-                    "snr_kwargs" : {"min_snr": min_snr},
-                    "remove_contaminated_kwargs" : {
-                        "contamination_thresh": contamination_thresh,
-                        "refractory_period_ms": refractory_period_ms,
-                        "censored_period_ms": censored_period_ms,
-                    },
-                    "unit_locations" : {"max_distance_um": max_distance_um},
-                    "correlogram" : {
-                        "corr_diff_thresh": corr_diff_thresh,
-                        "censor_correlograms_ms": censor_correlograms_ms,
-                        "sigma_smooth_ms": sigma_smooth_ms,
-                        "adaptative_window_thresh": adaptative_window_thresh,
-                    },
-                    "template_similarity":  {"template_diff_thresh": template_diff_thresh},
-                    "presence_distance" : {"presence_distance_thresh": presence_distance_thresh, **presence_distance_kwargs},
-                    "knn" : {"k_nn": k_nn, **knn_kwargs},
-                    "cross_contamination" : {
-                        "cc_thresh": cc_thresh,
-                        "p_value": p_value,
-                        "refractory_period_ms": refractory_period_ms,
-                        "censored_period_ms": censored_period_ms,
-                    },
-                    "quality_score" : {
-                        "firing_contamination_balance": firing_contamination_balance,
-                        "refractory_period_ms": refractory_period_ms,
-                        "censored_period_ms": censored_period_ms,
-                    }},
+        step_params={
+            "num_spikes": {"min_spikes": min_spikes},
+            "snr_kwargs": {"min_snr": min_snr},
+            "remove_contaminated_kwargs": {
+                "contamination_thresh": contamination_thresh,
+                "refractory_period_ms": refractory_period_ms,
+                "censored_period_ms": censored_period_ms,
+            },
+            "unit_locations": {"max_distance_um": max_distance_um},
+            "correlogram": {
+                "corr_diff_thresh": corr_diff_thresh,
+                "censor_correlograms_ms": censor_correlograms_ms,
+                "sigma_smooth_ms": sigma_smooth_ms,
+                "adaptative_window_thresh": adaptative_window_thresh,
+            },
+            "template_similarity": {"template_diff_thresh": template_diff_thresh},
+            "presence_distance": {"presence_distance_thresh": presence_distance_thresh, **presence_distance_kwargs},
+            "knn": {"k_nn": k_nn, **knn_kwargs},
+            "cross_contamination": {
+                "cc_thresh": cc_thresh,
+                "p_value": p_value,
+                "refractory_period_ms": refractory_period_ms,
+                "censored_period_ms": censored_period_ms,
+            },
+            "quality_score": {
+                "firing_contamination_balance": firing_contamination_balance,
+                "refractory_period_ms": refractory_period_ms,
+                "censored_period_ms": censored_period_ms,
+            },
+        },
         compute_needed_extensions=False,
         extra_outputs=extra_outputs,
         steps=steps,

From 1ffe6ccf8898d237519c36a8ce439b6b9db896e7 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 9 Oct 2024 12:49:15 +0200
Subject: [PATCH 091/344] oups

---
 src/spikeinterface/benchmark/tests/test_benchmark_sorter.py | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/benchmark/tests/test_benchmark_sorter.py b/src/spikeinterface/benchmark/tests/test_benchmark_sorter.py
index 2564d58d52..db48d32fde 100644
--- a/src/spikeinterface/benchmark/tests/test_benchmark_sorter.py
+++ b/src/spikeinterface/benchmark/tests/test_benchmark_sorter.py
@@ -64,10 +64,10 @@ def test_SorterStudy(setup_module):
     print(study)
 
     # # this run the sorters
-    # study.run()
+    study.run()
 
     # # this run comparisons
-    # study.compute_results()
+    study.compute_results()
     print(study)
 
     # this is from the base class
@@ -84,5 +84,7 @@ def test_SorterStudy(setup_module):
 
 if __name__ == "__main__":
     study_folder = Path(__file__).resolve().parents[4] / "cache_folder" / "benchmarks" / "test_SorterStudy"
+    if study_folder.exists():
+        shutil.rmtree(study_folder)
     create_a_study(study_folder)
     test_SorterStudy(study_folder)

From 275e5017c978a7b5a5ffb29b914c8398658d1954 Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Wed, 9 Oct 2024 15:34:40 +0200
Subject: [PATCH 092/344] Sc2 fixes

* Fixes

* Patches

* Fixes for SC2 and for split clustering

* debugging clustering

* WIP

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

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

* WIP

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

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

* WIP

* WIP

* Default params

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

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

* WIP

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

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

* Adding gather_func to find_spikes

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

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

* Gathering mode more explicit for matching

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

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

* WIP

* WIP

* Fixes for SC2

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

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

* WIP

* Simplifications

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

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

* Naming for Sam

* Optimize circus matching engine

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

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

* Optimizations

* Remove the limit to chunk sizes in circus-omp-svd

* Naming

* Patch imports

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 .../sorters/internal/spyking_circus2.py       |  41 ++--
 .../sortingcomponents/clustering/circus.py    |  18 +-
 .../sortingcomponents/clustering/split.py     |  22 +-
 .../sortingcomponents/matching/circus.py      | 192 +++++++++---------
 .../sortingcomponents/peak_detection.py       |  13 +-
 .../sortingcomponents/peak_localization.py    |   2 +-
 6 files changed, 153 insertions(+), 135 deletions(-)

diff --git a/src/spikeinterface/sorters/internal/spyking_circus2.py b/src/spikeinterface/sorters/internal/spyking_circus2.py
index c3b3099535..211adba990 100644
--- a/src/spikeinterface/sorters/internal/spyking_circus2.py
+++ b/src/spikeinterface/sorters/internal/spyking_circus2.py
@@ -24,9 +24,10 @@ class Spykingcircus2Sorter(ComponentsBasedSorter):
     sorter_name = "spykingcircus2"
 
     _default_params = {
-        "general": {"ms_before": 2, "ms_after": 2, "radius_um": 100},
+        "general": {"ms_before": 2, "ms_after": 2, "radius_um": 75},
         "sparsity": {"method": "snr", "amplitude_mode": "peak_to_peak", "threshold": 0.25},
         "filtering": {"freq_min": 150, "freq_max": 7000, "ftype": "bessel", "filter_order": 2},
+        "whitening": {"mode": "local", "regularize": True},
         "detection": {"peak_sign": "neg", "detect_threshold": 4},
         "selection": {
             "method": "uniform",
@@ -36,7 +37,7 @@ class Spykingcircus2Sorter(ComponentsBasedSorter):
             "seed": 42,
         },
         "apply_motion_correction": True,
-        "motion_correction": {"preset": "nonrigid_fast_and_accurate"},
+        "motion_correction": {"preset": "dredge_fast"},
         "merging": {
             "similarity_kwargs": {"method": "cosine", "support": "union", "max_lag_ms": 0.2},
             "correlograms_kwargs": {},
@@ -46,7 +47,7 @@ class Spykingcircus2Sorter(ComponentsBasedSorter):
             },
         },
         "clustering": {"legacy": True},
-        "matching": {"method": "wobble"},
+        "matching": {"method": "circus-omp-svd"},
         "apply_preprocessing": True,
         "matched_filtering": True,
         "cache_preprocessing": {"mode": "memory", "memory_limit": 0.5, "delete_cache": True},
@@ -62,6 +63,7 @@ class Spykingcircus2Sorter(ComponentsBasedSorter):
                                         and also the radius_um used to be considered during clustering",
         "sparsity": "A dictionary to be passed to all the calls to sparsify the templates",
         "filtering": "A dictionary for the high_pass filter to be used during preprocessing",
+        "whitening": "A dictionary for the whitening option to be used during preprocessing",
         "detection": "A dictionary for the peak detection node (locally_exclusive)",
         "selection": "A dictionary for the peak selection node. Default is to use smart_sampling_amplitudes, with a minimum of 20000 peaks\
                                          and 5000 peaks per electrode on average.",
@@ -109,8 +111,7 @@ def _run_from_folder(cls, sorter_output_folder, params, verbose):
         from spikeinterface.sortingcomponents.tools import get_prototype_spike, check_probe_for_drift_correction
         from spikeinterface.sortingcomponents.tools import get_prototype_spike
 
-        job_kwargs = params["job_kwargs"]
-        job_kwargs = fix_job_kwargs(job_kwargs)
+        job_kwargs = fix_job_kwargs(params["job_kwargs"])
         job_kwargs.update({"progress_bar": verbose})
 
         recording = cls.load_recording_from_folder(sorter_output_folder.parent, with_warnings=False)
@@ -119,7 +120,7 @@ def _run_from_folder(cls, sorter_output_folder, params, verbose):
         num_channels = recording.get_num_channels()
         ms_before = params["general"].get("ms_before", 2)
         ms_after = params["general"].get("ms_after", 2)
-        radius_um = params["general"].get("radius_um", 100)
+        radius_um = params["general"].get("radius_um", 75)
         exclude_sweep_ms = params["detection"].get("exclude_sweep_ms", max(ms_before, ms_after) / 2)
 
         ## First, we are filtering the data
@@ -143,14 +144,19 @@ def _run_from_folder(cls, sorter_output_folder, params, verbose):
                     print("Motion correction activated (probe geometry compatible)")
                 motion_folder = sorter_output_folder / "motion"
                 params["motion_correction"].update({"folder": motion_folder})
-                recording_f = correct_motion(recording_f, **params["motion_correction"])
+                recording_f = correct_motion(recording_f, **params["motion_correction"], **job_kwargs)
         else:
             motion_folder = None
 
         ## We need to whiten before the template matching step, to boost the results
         # TODO add , regularize=True chen ready
-        recording_w = whiten(recording_f, mode="local", radius_um=radius_um, dtype="float32", regularize=True)
+        whitening_kwargs = params["whitening"].copy()
+        whitening_kwargs["dtype"] = "float32"
+        whitening_kwargs["radius_um"] = radius_um
+        if num_channels == 1:
+            whitening_kwargs["regularize"] = False
 
+        recording_w = whiten(recording_f, **whitening_kwargs)
         noise_levels = get_noise_levels(recording_w, return_scaled=False)
 
         if recording_w.check_serializability("json"):
@@ -172,20 +178,14 @@ def _run_from_folder(cls, sorter_output_folder, params, verbose):
         nbefore = int(ms_before * fs / 1000.0)
         nafter = int(ms_after * fs / 1000.0)
 
-        peaks = detect_peaks(recording_w, "locally_exclusive", **detection_params)
-
         if params["matched_filtering"]:
+            peaks = detect_peaks(recording_w, "locally_exclusive", **detection_params, skip_after_n_peaks=5000)
             prototype = get_prototype_spike(recording_w, peaks, ms_before, ms_after, **job_kwargs)
             detection_params["prototype"] = prototype
             detection_params["ms_before"] = ms_before
-
-            for value in ["chunk_size", "chunk_memory", "total_memory", "chunk_duration"]:
-                if value in detection_params:
-                    detection_params.pop(value)
-
-            detection_params["chunk_duration"] = "100ms"
-
             peaks = detect_peaks(recording_w, "matched_filtering", **detection_params)
+        else:
+            peaks = detect_peaks(recording_w, "locally_exclusive", **detection_params)
 
         if verbose:
             print("We found %d peaks in total" % len(peaks))
@@ -196,7 +196,7 @@ def _run_from_folder(cls, sorter_output_folder, params, verbose):
             ## We subselect a subset of all the peaks, by making the distributions os SNRs over all
             ## channels as flat as possible
             selection_params = params["selection"]
-            selection_params["n_peaks"] = params["selection"]["n_peaks_per_channel"] * num_channels
+            selection_params["n_peaks"] = min(len(peaks), selection_params["n_peaks_per_channel"] * num_channels)
             selection_params["n_peaks"] = max(selection_params["min_n_peaks"], selection_params["n_peaks"])
 
             selection_params.update({"noise_levels": noise_levels})
@@ -281,11 +281,6 @@ def _run_from_folder(cls, sorter_output_folder, params, verbose):
             matching_job_params = job_kwargs.copy()
 
             if matching_method is not None:
-                for value in ["chunk_size", "chunk_memory", "total_memory", "chunk_duration"]:
-                    if value in matching_job_params:
-                        matching_job_params[value] = None
-                matching_job_params["chunk_duration"] = "100ms"
-
                 spikes = find_spikes_from_templates(
                     recording_w, matching_method, method_kwargs=matching_params, **matching_job_params
                 )
diff --git a/src/spikeinterface/sortingcomponents/clustering/circus.py b/src/spikeinterface/sortingcomponents/clustering/circus.py
index b08ee4d9cb..b7e71d3b45 100644
--- a/src/spikeinterface/sortingcomponents/clustering/circus.py
+++ b/src/spikeinterface/sortingcomponents/clustering/circus.py
@@ -136,6 +136,7 @@ def main_function(cls, recording, peaks, params):
         pipeline_nodes = [node0, node1, node2]
 
         if len(params["recursive_kwargs"]) == 0:
+            from sklearn.decomposition import PCA
 
             all_pc_data = run_node_pipeline(
                 recording,
@@ -152,9 +153,9 @@ def main_function(cls, recording, peaks, params):
                 sub_data = sub_data.reshape(len(sub_data), -1)
 
                 if all_pc_data.shape[1] > params["n_svd"][1]:
-                    tsvd = TruncatedSVD(params["n_svd"][1])
+                    tsvd = PCA(params["n_svd"][1], whiten=True)
                 else:
-                    tsvd = TruncatedSVD(all_pc_data.shape[1])
+                    tsvd = PCA(all_pc_data.shape[1], whiten=True)
 
                 hdbscan_data = tsvd.fit_transform(sub_data)
                 try:
@@ -184,7 +185,7 @@ def main_function(cls, recording, peaks, params):
             )
 
             sparse_mask = node1.neighbours_mask
-            neighbours_mask = get_channel_distances(recording) < radius_um
+            neighbours_mask = get_channel_distances(recording) <= radius_um
 
             # np.save(features_folder / "sparse_mask.npy", sparse_mask)
             np.save(features_folder / "peaks.npy", peaks)
@@ -192,6 +193,8 @@ def main_function(cls, recording, peaks, params):
             original_labels = peaks["channel_index"]
             from spikeinterface.sortingcomponents.clustering.split import split_clusters
 
+            min_size = params["hdbscan_kwargs"].get("min_cluster_size", 50)
+
             peak_labels, _ = split_clusters(
                 original_labels,
                 recording,
@@ -202,7 +205,7 @@ def main_function(cls, recording, peaks, params):
                     feature_name="sparse_tsvd",
                     neighbours_mask=neighbours_mask,
                     waveforms_sparse_mask=sparse_mask,
-                    min_size_split=50,
+                    min_size_split=min_size,
                     clusterer_kwargs=d["hdbscan_kwargs"],
                     n_pca_features=params["n_svd"][1],
                     scale_n_pca_by_depth=True,
@@ -233,7 +236,7 @@ def main_function(cls, recording, peaks, params):
         if d["rank"] is not None:
             from spikeinterface.sortingcomponents.matching.circus import compress_templates
 
-            _, _, _, templates_array = compress_templates(templates_array, 5)
+            _, _, _, templates_array = compress_templates(templates_array, d["rank"])
 
         templates = Templates(
             templates_array=templates_array,
@@ -258,13 +261,8 @@ def main_function(cls, recording, peaks, params):
             print("We found %d raw clusters, starting to clean with matching..." % (len(templates.unit_ids)))
 
         cleaning_matching_params = params["job_kwargs"].copy()
-        for value in ["chunk_size", "chunk_memory", "total_memory", "chunk_duration"]:
-            if value in cleaning_matching_params:
-                cleaning_matching_params.pop(value)
-        cleaning_matching_params["chunk_duration"] = "100ms"
         cleaning_matching_params["n_jobs"] = 1
         cleaning_matching_params["progress_bar"] = False
-
         cleaning_params = params["cleaning_kwargs"].copy()
 
         labels, peak_labels = remove_duplicates_via_matching(
diff --git a/src/spikeinterface/sortingcomponents/clustering/split.py b/src/spikeinterface/sortingcomponents/clustering/split.py
index 5934bdfbbb..15917934a8 100644
--- a/src/spikeinterface/sortingcomponents/clustering/split.py
+++ b/src/spikeinterface/sortingcomponents/clustering/split.py
@@ -24,7 +24,7 @@ def split_clusters(
     peak_labels,
     recording,
     features_dict_or_folder,
-    method="hdbscan_on_local_pca",
+    method="local_feature_clustering",
     method_kwargs={},
     recursive=False,
     recursive_depth=None,
@@ -81,7 +81,6 @@ def split_clusters(
     ) as pool:
         labels_set = np.setdiff1d(peak_labels, [-1])
         current_max_label = np.max(labels_set) + 1
-
         jobs = []
         for label in labels_set:
             peak_indices = np.flatnonzero(peak_labels == label)
@@ -95,15 +94,14 @@ def split_clusters(
 
         for res in iterator:
             is_split, local_labels, peak_indices = res.result()
+            # print(is_split, local_labels, peak_indices)
             if not is_split:
                 continue
 
             mask = local_labels >= 0
             peak_labels[peak_indices[mask]] = local_labels[mask] + current_max_label
             peak_labels[peak_indices[~mask]] = local_labels[~mask]
-
             split_count[peak_indices] += 1
-
             current_max_label += np.max(local_labels[mask]) + 1
 
             if recursive:
@@ -120,6 +118,7 @@ def split_clusters(
                     for label in new_labels_set:
                         peak_indices = np.flatnonzero(peak_labels == label)
                         if peak_indices.size > 0:
+                            # print('Relaunched', label, len(peak_indices), recursion_level)
                             jobs.append(pool.submit(split_function_wrapper, peak_indices, recursion_level))
                             if progress_bar:
                                 iterator.total += 1
@@ -187,7 +186,7 @@ def split(
         min_size_split=25,
         n_pca_features=2,
         scale_n_pca_by_depth=False,
-        minimum_common_channels=2,
+        minimum_overlap_ratio=0.25,
     ):
         local_labels = np.zeros(peak_indices.size, dtype=np.int64)
 
@@ -199,19 +198,22 @@ def split(
         # target channel subset is done intersect local channels + neighbours
         local_chans = np.unique(peaks["channel_index"][peak_indices])
 
-        target_channels = np.flatnonzero(np.all(neighbours_mask[local_chans, :], axis=0))
+        target_intersection_channels = np.flatnonzero(np.all(neighbours_mask[local_chans, :], axis=0))
+        target_union_channels = np.flatnonzero(np.any(neighbours_mask[local_chans, :], axis=0))
+        num_intersection = len(target_intersection_channels)
+        num_union = len(target_union_channels)
 
         # TODO fix this a better way, this when cluster have too few overlapping channels
-        if target_channels.size < minimum_common_channels:
+        if (num_intersection / num_union) < minimum_overlap_ratio:
             return False, None
 
         aligned_wfs, dont_have_channels = aggregate_sparse_features(
-            peaks, peak_indices, sparse_features, waveforms_sparse_mask, target_channels
+            peaks, peak_indices, sparse_features, waveforms_sparse_mask, target_intersection_channels
         )
 
         local_labels[dont_have_channels] = -2
         kept = np.flatnonzero(~dont_have_channels)
-
+        # print(recursion_level, kept.size, min_size_split)
         if kept.size < min_size_split:
             return False, None
 
@@ -222,6 +224,8 @@ def split(
         if flatten_features.shape[1] > n_pca_features:
             from sklearn.decomposition import PCA
 
+            # from sklearn.decomposition import TruncatedSVD
+
             if scale_n_pca_by_depth:
                 # tsvd = TruncatedSVD(n_pca_features * recursion_level)
                 tsvd = PCA(n_pca_features * recursion_level, whiten=True)
diff --git a/src/spikeinterface/sortingcomponents/matching/circus.py b/src/spikeinterface/sortingcomponents/matching/circus.py
index a3624f4296..d1b2139c5b 100644
--- a/src/spikeinterface/sortingcomponents/matching/circus.py
+++ b/src/spikeinterface/sortingcomponents/matching/circus.py
@@ -9,6 +9,7 @@
 from spikeinterface.sortingcomponents.peak_detection import DetectPeakByChannel
 from spikeinterface.core.template import Templates
 
+
 spike_dtype = [
     ("sample_index", "int64"),
     ("channel_index", "int64"),
@@ -140,12 +141,12 @@ def __init__(
         templates=None,
         amplitudes=[0.6, np.inf],
         stop_criteria="max_failures",
-        max_failures=10,
+        max_failures=5,
         omp_min_sps=0.1,
         relative_error=5e-5,
         rank=5,
         ignore_inds=[],
-        vicinity=3,
+        vicinity=2,
         precomputed=None,
     ):
 
@@ -181,16 +182,16 @@ def __init__(
             self.unit_overlaps_tables[i] = np.zeros(self.num_templates, dtype=int)
             self.unit_overlaps_tables[i][self.unit_overlaps_indices[i]] = np.arange(len(self.unit_overlaps_indices[i]))
 
-        if self.vicinity > 0:
-            self.margin = self.vicinity
-        else:
-            self.margin = 2 * self.num_samples
+        self.margin = 2 * self.num_samples
 
     def _prepare_templates(self):
 
         assert self.stop_criteria in ["max_failures", "omp_min_sps", "relative_error"]
 
-        sparsity = self.templates.sparsity.mask
+        if self.templates.sparsity is None:
+            sparsity = np.ones((self.num_templates, self.num_channels), dtype=bool)
+        else:
+            sparsity = self.templates.sparsity.mask
 
         units_overlaps = np.sum(np.logical_and(sparsity[:, np.newaxis, :], sparsity[np.newaxis, :, :]), axis=2)
         self.units_overlaps = units_overlaps > 0
@@ -265,6 +266,7 @@ def get_trace_margin(self):
     def compute_matching(self, traces, start_frame, end_frame, segment_index):
         import scipy.spatial
         import scipy
+        from scipy import ndimage
 
         (potrs,) = scipy.linalg.get_lapack_funcs(("potrs",), dtype=np.float32)
 
@@ -316,8 +318,6 @@ def compute_matching(self, traces, start_frame, end_frame, segment_index):
 
         full_sps = scalar_products.copy()
 
-        neighbors = {}
-
         all_amplitudes = np.zeros(0, dtype=np.float32)
         is_in_vicinity = np.zeros(0, dtype=np.int32)
 
@@ -336,100 +336,113 @@ def compute_matching(self, traces, start_frame, end_frame, segment_index):
         do_loop = True
 
         while do_loop:
-            best_amplitude_ind = scalar_products.argmax()
-            best_cluster_ind, peak_index = np.unravel_index(best_amplitude_ind, scalar_products.shape)
 
-            if num_selection > 0:
-                delta_t = selection[1] - peak_index
-                idx = np.where((delta_t < num_samples) & (delta_t > -num_samples))[0]
-                myline = neighbor_window + delta_t[idx]
-                myindices = selection[0, idx]
+            best_cluster_inds = np.argmax(scalar_products, axis=0, keepdims=True)
+            products = np.take_along_axis(scalar_products, best_cluster_inds, axis=0)
 
-                local_overlaps = overlaps_array[best_cluster_ind]
-                overlapping_templates = self.unit_overlaps_indices[best_cluster_ind]
-                table = self.unit_overlaps_tables[best_cluster_ind]
+            result = ndimage.maximum_filter(products[0], size=self.vicinity, mode="constant", cval=0)
+            cond_1 = products[0] / self.norms[best_cluster_inds[0]] > 0.25
+            cond_2 = np.abs(products[0] - result) < 1e-9
+            peak_indices = np.flatnonzero(cond_1 * cond_2)
 
-                if num_selection == M.shape[0]:
-                    Z = np.zeros((2 * num_selection, 2 * num_selection), dtype=np.float32)
-                    Z[:num_selection, :num_selection] = M
-                    M = Z
+            if len(peak_indices) == 0:
+                break
 
-                mask = np.isin(myindices, overlapping_templates)
-                a, b = myindices[mask], myline[mask]
-                M[num_selection, idx[mask]] = local_overlaps[table[a], b]
+            for peak_index in peak_indices:
 
-                if self.vicinity == 0:
-                    scipy.linalg.solve_triangular(
-                        M[:num_selection, :num_selection],
-                        M[num_selection, :num_selection],
-                        trans=0,
-                        lower=1,
-                        overwrite_b=True,
-                        check_finite=False,
-                    )
-
-                    v = nrm2(M[num_selection, :num_selection]) ** 2
-                    Lkk = 1 - v
-                    if Lkk <= omp_tol:  # selected atoms are dependent
-                        break
-                    M[num_selection, num_selection] = np.sqrt(Lkk)
-                else:
-                    is_in_vicinity = np.where(np.abs(delta_t) < self.vicinity)[0]
+                best_cluster_ind = best_cluster_inds[0, peak_index]
+
+                if num_selection > 0:
+                    delta_t = selection[1] - peak_index
+                    idx = np.flatnonzero((delta_t < num_samples) & (delta_t > -num_samples))
+                    myline = neighbor_window + delta_t[idx]
+                    myindices = selection[0, idx]
+
+                    local_overlaps = overlaps_array[best_cluster_ind]
+                    overlapping_templates = self.unit_overlaps_indices[best_cluster_ind]
+                    table = self.unit_overlaps_tables[best_cluster_ind]
 
-                    if len(is_in_vicinity) > 0:
-                        L = M[is_in_vicinity, :][:, is_in_vicinity]
+                    if num_selection == M.shape[0]:
+                        Z = np.zeros((2 * num_selection, 2 * num_selection), dtype=np.float32)
+                        Z[:num_selection, :num_selection] = M
+                        M = Z
 
-                        M[num_selection, is_in_vicinity] = scipy.linalg.solve_triangular(
-                            L, M[num_selection, is_in_vicinity], trans=0, lower=1, overwrite_b=True, check_finite=False
+                    mask = np.isin(myindices, overlapping_templates)
+                    a, b = myindices[mask], myline[mask]
+                    M[num_selection, idx[mask]] = local_overlaps[table[a], b]
+
+                    if self.vicinity == 0:
+                        scipy.linalg.solve_triangular(
+                            M[:num_selection, :num_selection],
+                            M[num_selection, :num_selection],
+                            trans=0,
+                            lower=1,
+                            overwrite_b=True,
+                            check_finite=False,
                         )
 
-                        v = nrm2(M[num_selection, is_in_vicinity]) ** 2
+                        v = nrm2(M[num_selection, :num_selection]) ** 2
                         Lkk = 1 - v
                         if Lkk <= omp_tol:  # selected atoms are dependent
                             break
                         M[num_selection, num_selection] = np.sqrt(Lkk)
                     else:
-                        M[num_selection, num_selection] = 1.0
-            else:
-                M[0, 0] = 1
-
-            all_selections[:, num_selection] = [best_cluster_ind, peak_index]
-            num_selection += 1
-
-            selection = all_selections[:, :num_selection]
-            res_sps = full_sps[selection[0], selection[1]]
-
-            if self.vicinity == 0:
-                all_amplitudes, _ = potrs(M[:num_selection, :num_selection], res_sps, lower=True, overwrite_b=False)
-                all_amplitudes /= self.norms[selection[0]]
-            else:
-                is_in_vicinity = np.append(is_in_vicinity, num_selection - 1)
-                all_amplitudes = np.append(all_amplitudes, np.float32(1))
-                L = M[is_in_vicinity, :][:, is_in_vicinity]
-                all_amplitudes[is_in_vicinity], _ = potrs(L, res_sps[is_in_vicinity], lower=True, overwrite_b=False)
-                all_amplitudes[is_in_vicinity] /= self.norms[selection[0][is_in_vicinity]]
-
-            diff_amplitudes = all_amplitudes - final_amplitudes[selection[0], selection[1]]
-            modified = np.where(np.abs(diff_amplitudes) > omp_tol)[0]
-            final_amplitudes[selection[0], selection[1]] = all_amplitudes
-
-            for i in modified:
-                tmp_best, tmp_peak = selection[:, i]
-                diff_amp = diff_amplitudes[i] * self.norms[tmp_best]
-
-                local_overlaps = overlaps_array[tmp_best]
-                overlapping_templates = self.units_overlaps[tmp_best]
+                        is_in_vicinity = np.flatnonzero(np.abs(delta_t) < self.vicinity)
+
+                        if len(is_in_vicinity) > 0:
+                            L = M[is_in_vicinity, :][:, is_in_vicinity]
+
+                            M[num_selection, is_in_vicinity] = scipy.linalg.solve_triangular(
+                                L,
+                                M[num_selection, is_in_vicinity],
+                                trans=0,
+                                lower=1,
+                                overwrite_b=True,
+                                check_finite=False,
+                            )
+
+                            v = nrm2(M[num_selection, is_in_vicinity]) ** 2
+                            Lkk = 1 - v
+                            if Lkk <= omp_tol:  # selected atoms are dependent
+                                break
+                            M[num_selection, num_selection] = np.sqrt(Lkk)
+                        else:
+                            M[num_selection, num_selection] = 1.0
+                else:
+                    M[0, 0] = 1
 
-                if not tmp_peak in neighbors.keys():
-                    idx = [max(0, tmp_peak - neighbor_window), min(num_peaks, tmp_peak + num_samples)]
-                    tdx = [neighbor_window + idx[0] - tmp_peak, num_samples + idx[1] - tmp_peak - 1]
-                    neighbors[tmp_peak] = {"idx": idx, "tdx": tdx}
+                all_selections[:, num_selection] = [best_cluster_ind, peak_index]
+                num_selection += 1
 
-                idx = neighbors[tmp_peak]["idx"]
-                tdx = neighbors[tmp_peak]["tdx"]
+                selection = all_selections[:, :num_selection]
+                res_sps = full_sps[selection[0], selection[1]]
 
-                to_add = diff_amp * local_overlaps[:, tdx[0] : tdx[1]]
-                scalar_products[overlapping_templates, idx[0] : idx[1]] -= to_add
+                if self.vicinity == 0:
+                    new_amplitudes, _ = potrs(M[:num_selection, :num_selection], res_sps, lower=True, overwrite_b=False)
+                    sub_selection = selection
+                    new_amplitudes /= self.norms[sub_selection[0]]
+                else:
+                    is_in_vicinity = np.append(is_in_vicinity, num_selection - 1)
+                    all_amplitudes = np.append(all_amplitudes, np.float32(1))
+                    L = M[is_in_vicinity, :][:, is_in_vicinity]
+                    new_amplitudes, _ = potrs(L, res_sps[is_in_vicinity], lower=True, overwrite_b=False)
+                    sub_selection = selection[:, is_in_vicinity]
+                    new_amplitudes /= self.norms[sub_selection[0]]
+
+                diff_amplitudes = new_amplitudes - final_amplitudes[sub_selection[0], sub_selection[1]]
+                modified = np.flatnonzero(np.abs(diff_amplitudes) > omp_tol)
+                final_amplitudes[sub_selection[0], sub_selection[1]] = new_amplitudes
+
+                for i in modified:
+                    tmp_best, tmp_peak = sub_selection[:, i]
+                    diff_amp = diff_amplitudes[i] * self.norms[tmp_best]
+                    local_overlaps = overlaps_array[tmp_best]
+                    overlapping_templates = self.units_overlaps[tmp_best]
+                    tmp = tmp_peak - neighbor_window
+                    idx = [max(0, tmp), min(num_peaks, tmp_peak + num_samples)]
+                    tdx = [idx[0] - tmp, idx[1] - tmp]
+                    to_add = diff_amp * local_overlaps[:, tdx[0] : tdx[1]]
+                    scalar_products[overlapping_templates, idx[0] : idx[1]] -= to_add
 
             # We stop when updates do not modify the chosen spikes anymore
             if self.stop_criteria == "omp_min_sps":
@@ -462,12 +475,9 @@ def compute_matching(self, traces, start_frame, end_frame, segment_index):
         spikes["cluster_index"][:num_spikes] = valid_indices[0]
         spikes["amplitude"][:num_spikes] = final_amplitudes[valid_indices[0], valid_indices[1]]
 
-        print("yep0", spikes.size, num_spikes, spikes.shape, spikes.dtype)
         spikes = spikes[:num_spikes]
-        print("yep1", spikes.size, spikes.shape, spikes.dtype)
-        if spikes.size > 0:
-            order = np.argsort(spikes["sample_index"])
-            spikes = spikes[order]
+        order = np.argsort(spikes["sample_index"])
+        spikes = spikes[order]
 
         return spikes
 
diff --git a/src/spikeinterface/sortingcomponents/peak_detection.py b/src/spikeinterface/sortingcomponents/peak_detection.py
index ad8897df91..d608c5d105 100644
--- a/src/spikeinterface/sortingcomponents/peak_detection.py
+++ b/src/spikeinterface/sortingcomponents/peak_detection.py
@@ -50,7 +50,14 @@
 
 
 def detect_peaks(
-    recording, method="locally_exclusive", pipeline_nodes=None, gather_mode="memory", folder=None, names=None, **kwargs
+    recording,
+    method="locally_exclusive",
+    pipeline_nodes=None,
+    gather_mode="memory",
+    folder=None,
+    names=None,
+    skip_after_n_peaks=None,
+    **kwargs,
 ):
     """Peak detection based on threshold crossing in term of k x MAD.
 
@@ -73,6 +80,9 @@ def detect_peaks(
         If gather_mode is "npy", the folder where the files are created.
     names : list
         List of strings with file stems associated with returns.
+    skip_after_n_peaks : None | int
+        Skip the computation after n_peaks.
+        This is not an exact because internally this skip is done per worker in average.
 
     {method_doc}
     {job_doc}
@@ -124,6 +134,7 @@ def detect_peaks(
         squeeze_output=squeeze_output,
         folder=folder,
         names=names,
+        skip_after_n_peaks=skip_after_n_peaks,
     )
     return outs
 
diff --git a/src/spikeinterface/sortingcomponents/peak_localization.py b/src/spikeinterface/sortingcomponents/peak_localization.py
index ddc8add995..08bcabf5e5 100644
--- a/src/spikeinterface/sortingcomponents/peak_localization.py
+++ b/src/spikeinterface/sortingcomponents/peak_localization.py
@@ -135,7 +135,7 @@ def __init__(self, recording, return_output=True, parents=None, radius_um=75.0):
         self.radius_um = radius_um
         self.contact_locations = recording.get_channel_locations()
         self.channel_distance = get_channel_distances(recording)
-        self.neighbours_mask = self.channel_distance < radius_um
+        self.neighbours_mask = self.channel_distance <= radius_um
         self._kwargs["radius_um"] = radius_um
 
     def get_dtype(self):

From bbf7daf6fb34c831dafc6111e9f51221b028b396 Mon Sep 17 00:00:00 2001
From: Zach McKenzie <92116279+zm711@users.noreply.github.com>
Date: Wed, 9 Oct 2024 17:40:29 -0400
Subject: [PATCH 093/344] Add neuronexus allego recording Extractor (#3235)

* add neuronexus allego

* add tests

* fix neuronexus name

* Heberto feedback

* Fix capitalization

* oops

* add assert messaging

* Update src/spikeinterface/extractors/neoextractors/neuronexus.py

Co-authored-by: Zach McKenzie <92116279+zm711@users.noreply.github.com>

---------

Co-authored-by: Heberto Mayorquin <h.mayorquin@gmail.com>
---
 .../extractors/neoextractors/__init__.py      |  2 +
 .../extractors/neoextractors/neuronexus.py    | 66 +++++++++++++++++++
 .../extractors/tests/common_tests.py          |  7 +-
 .../extractors/tests/test_neoextractors.py    |  8 +++
 4 files changed, 81 insertions(+), 2 deletions(-)
 create mode 100644 src/spikeinterface/extractors/neoextractors/neuronexus.py

diff --git a/src/spikeinterface/extractors/neoextractors/__init__.py b/src/spikeinterface/extractors/neoextractors/__init__.py
index bf52de7c1d..03d517b46e 100644
--- a/src/spikeinterface/extractors/neoextractors/__init__.py
+++ b/src/spikeinterface/extractors/neoextractors/__init__.py
@@ -9,6 +9,7 @@
 from .mearec import MEArecRecordingExtractor, MEArecSortingExtractor, read_mearec
 from .mcsraw import MCSRawRecordingExtractor, read_mcsraw
 from .neuralynx import NeuralynxRecordingExtractor, NeuralynxSortingExtractor, read_neuralynx, read_neuralynx_sorting
+from .neuronexus import NeuroNexusRecordingExtractor, read_neuronexus
 from .neuroscope import (
     NeuroScopeRecordingExtractor,
     NeuroScopeSortingExtractor,
@@ -54,6 +55,7 @@
     MCSRawRecordingExtractor,
     NeuralynxRecordingExtractor,
     NeuroScopeRecordingExtractor,
+    NeuroNexusRecordingExtractor,
     NixRecordingExtractor,
     OpenEphysBinaryRecordingExtractor,
     OpenEphysLegacyRecordingExtractor,
diff --git a/src/spikeinterface/extractors/neoextractors/neuronexus.py b/src/spikeinterface/extractors/neoextractors/neuronexus.py
new file mode 100644
index 0000000000..dca482b28a
--- /dev/null
+++ b/src/spikeinterface/extractors/neoextractors/neuronexus.py
@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from spikeinterface.core.core_tools import define_function_from_class
+
+from .neobaseextractor import NeoBaseRecordingExtractor, NeoBaseSortingExtractor
+
+
+class NeuroNexusRecordingExtractor(NeoBaseRecordingExtractor):
+    """
+    Class for reading data from NeuroNexus Allego.
+
+    Based on :py:class:`neo.rawio.NeuronexusRawIO`
+
+    Parameters
+    ----------
+    file_path : str | Path
+        The file path to the metadata .xdat.json file of an Allego session
+    stream_id : str | None, default: None
+        If there are several streams, specify the stream id you want to load.
+    stream_name : str | None, default: None
+        If there are several streams, specify the stream name you want to load.
+    all_annotations : bool, default: False
+        Load exhaustively all annotations from neo.
+    use_names_as_ids : bool, default: False
+        Determines the format of the channel IDs used by the extractor. If set to True, the channel IDs will be the
+        names from NeoRawIO. If set to False, the channel IDs will be the ids provided by NeoRawIO.
+
+        In Neuronexus the ids provided by NeoRawIO are the hardware channel ids stored as `ntv_chan_name` within
+        the metada and the names are the `chan_names`
+
+
+    """
+
+    NeoRawIOClass = "NeuroNexusRawIO"
+
+    def __init__(
+        self,
+        file_path: str | Path,
+        stream_id: str | None = None,
+        stream_name: str | None = None,
+        all_annotations: bool = False,
+        use_names_as_ids: bool = False,
+    ):
+        neo_kwargs = self.map_to_neo_kwargs(file_path)
+        NeoBaseRecordingExtractor.__init__(
+            self,
+            stream_id=stream_id,
+            stream_name=stream_name,
+            all_annotations=all_annotations,
+            use_names_as_ids=use_names_as_ids,
+            **neo_kwargs,
+        )
+
+        self._kwargs.update(dict(file_path=str(Path(file_path).resolve())))
+
+    @classmethod
+    def map_to_neo_kwargs(cls, file_path):
+
+        neo_kwargs = {"filename": str(file_path)}
+
+        return neo_kwargs
+
+
+read_neuronexus = define_function_from_class(source_class=NeuroNexusRecordingExtractor, name="read_neuronexus")
diff --git a/src/spikeinterface/extractors/tests/common_tests.py b/src/spikeinterface/extractors/tests/common_tests.py
index 5432efa9f3..61cfc2a153 100644
--- a/src/spikeinterface/extractors/tests/common_tests.py
+++ b/src/spikeinterface/extractors/tests/common_tests.py
@@ -52,8 +52,11 @@ def test_open(self):
                 num_samples = rec.get_num_samples(segment_index=segment_index)
 
                 full_traces = rec.get_traces(segment_index=segment_index)
-                assert full_traces.shape == (num_samples, num_chans)
-                assert full_traces.dtype == dtype
+                assert full_traces.shape == (
+                    num_samples,
+                    num_chans,
+                ), f"{full_traces.shape} != {(num_samples, num_chans)}"
+                assert full_traces.dtype == dtype, f"{full_traces.dtype} != {dtype=}"
 
                 traces_sample_first = rec.get_traces(segment_index=segment_index, start_frame=0, end_frame=1)
                 assert traces_sample_first.shape == (1, num_chans)
diff --git a/src/spikeinterface/extractors/tests/test_neoextractors.py b/src/spikeinterface/extractors/tests/test_neoextractors.py
index 3f73161218..fcdd766f4f 100644
--- a/src/spikeinterface/extractors/tests/test_neoextractors.py
+++ b/src/spikeinterface/extractors/tests/test_neoextractors.py
@@ -181,6 +181,14 @@ class NeuroScopeSortingTest(SortingCommonTestSuite, unittest.TestCase):
     ]
 
 
+class NeuroNexusRecordingTest(RecordingCommonTestSuite, unittest.TestCase):
+    ExtractorClass = NeuroNexusRecordingExtractor
+    downloads = ["neuronexus"]
+    entities = [
+        ("neuronexus/allego_1/allego_2__uid0701-13-04-49.xdat.json", {"stream_id": "0"}),
+    ]
+
+
 class PlexonRecordingTest(RecordingCommonTestSuite, unittest.TestCase):
     ExtractorClass = PlexonRecordingExtractor
     downloads = ["plexon"]

From 0ae32e729acb0be01d1cee28453e3ad3503877fb Mon Sep 17 00:00:00 2001
From: Garcia Samuel <sam.garcia.die@gmail.com>
Date: Fri, 11 Oct 2024 11:32:27 +0200
Subject: [PATCH 094/344] Tdc peeler (#3466)

Improving the Peeler
---
 .../benchmark/benchmark_matching.py           |  73 +-
 .../benchmark/benchmark_plot_tools.py         |  64 +-
 .../sortingcomponents/matching/tdc.py         | 686 +++++++++++++-----
 .../sortingcomponents/matching/wobble.py      |   2 +-
 .../tests/test_template_matching.py           |  40 +-
 5 files changed, 608 insertions(+), 257 deletions(-)

diff --git a/src/spikeinterface/benchmark/benchmark_matching.py b/src/spikeinterface/benchmark/benchmark_matching.py
index c53567f460..3799fa19b3 100644
--- a/src/spikeinterface/benchmark/benchmark_matching.py
+++ b/src/spikeinterface/benchmark/benchmark_matching.py
@@ -33,7 +33,7 @@ def run(self, **job_kwargs):
         sorting["unit_index"] = spikes["cluster_index"]
         sorting["segment_index"] = spikes["segment_index"]
         sorting = NumpySorting(sorting, self.recording.sampling_frequency, unit_ids)
-        self.result = {"sorting": sorting}
+        self.result = {"sorting": sorting, "spikes": spikes}
         self.result["templates"] = self.templates
 
     def compute_result(self, with_collision=False, **result_params):
@@ -45,6 +45,7 @@ def compute_result(self, with_collision=False, **result_params):
 
     _run_key_saved = [
         ("sorting", "sorting"),
+        ("spikes", "npy"),
         ("templates", "zarr_templates"),
     ]
     _result_key_saved = [("gt_collision", "pickle"), ("gt_comparison", "pickle")]
@@ -71,6 +72,11 @@ def plot_performances_vs_snr(self, **kwargs):
 
         return plot_performances_vs_snr(self, **kwargs)
 
+    def plot_performances_comparison(self, **kwargs):
+        from .benchmark_plot_tools import plot_performances_comparison
+
+        return plot_performances_comparison(self, **kwargs)
+
     def plot_collisions(self, case_keys=None, figsize=None):
         if case_keys is None:
             case_keys = list(self.cases.keys())
@@ -90,70 +96,6 @@ def plot_collisions(self, case_keys=None, figsize=None):
 
         return fig
 
-    def plot_comparison_matching(
-        self,
-        case_keys=None,
-        performance_names=["accuracy", "recall", "precision"],
-        colors=["g", "b", "r"],
-        ylim=(-0.1, 1.1),
-        figsize=None,
-    ):
-
-        if case_keys is None:
-            case_keys = list(self.cases.keys())
-
-        num_methods = len(case_keys)
-        import pylab as plt
-
-        fig, axs = plt.subplots(ncols=num_methods, nrows=num_methods, figsize=(10, 10))
-        for i, key1 in enumerate(case_keys):
-            for j, key2 in enumerate(case_keys):
-                if len(axs.shape) > 1:
-                    ax = axs[i, j]
-                else:
-                    ax = axs[j]
-                comp1 = self.get_result(key1)["gt_comparison"]
-                comp2 = self.get_result(key2)["gt_comparison"]
-                if i <= j:
-                    for performance, color in zip(performance_names, colors):
-                        perf1 = comp1.get_performance()[performance]
-                        perf2 = comp2.get_performance()[performance]
-                        ax.plot(perf2, perf1, ".", label=performance, color=color)
-
-                    ax.plot([0, 1], [0, 1], "k--", alpha=0.5)
-                    ax.set_ylim(ylim)
-                    ax.set_xlim(ylim)
-                    ax.spines[["right", "top"]].set_visible(False)
-                    ax.set_aspect("equal")
-
-                    label1 = self.cases[key1]["label"]
-                    label2 = self.cases[key2]["label"]
-                    if j == i:
-                        ax.set_ylabel(f"{label1}")
-                    else:
-                        ax.set_yticks([])
-                    if i == j:
-                        ax.set_xlabel(f"{label2}")
-                    else:
-                        ax.set_xticks([])
-                    if i == num_methods - 1 and j == num_methods - 1:
-                        patches = []
-                        import matplotlib.patches as mpatches
-
-                        for color, name in zip(colors, performance_names):
-                            patches.append(mpatches.Patch(color=color, label=name))
-                        ax.legend(handles=patches, bbox_to_anchor=(1.05, 1), loc="upper left", borderaxespad=0.0)
-                else:
-                    ax.spines["bottom"].set_visible(False)
-                    ax.spines["left"].set_visible(False)
-                    ax.spines["top"].set_visible(False)
-                    ax.spines["right"].set_visible(False)
-                    ax.set_xticks([])
-                    ax.set_yticks([])
-        plt.tight_layout(h_pad=0, w_pad=0)
-
-        return fig
-
     def get_count_units(self, case_keys=None, well_detected_score=None, redundant_score=None, overmerged_score=None):
         import pandas as pd
 
@@ -196,6 +138,7 @@ def plot_unit_counts(self, case_keys=None, figsize=None):
         plot_study_unit_counts(self, case_keys, figsize=figsize)
 
     def plot_unit_losses(self, before, after, metric=["precision"], figsize=None):
+        import matplotlib.pyplot as plt
 
         fig, axs = plt.subplots(ncols=1, nrows=len(metric), figsize=figsize, squeeze=False)
 
diff --git a/src/spikeinterface/benchmark/benchmark_plot_tools.py b/src/spikeinterface/benchmark/benchmark_plot_tools.py
index a6e9b6dacc..e15636ebaf 100644
--- a/src/spikeinterface/benchmark/benchmark_plot_tools.py
+++ b/src/spikeinterface/benchmark/benchmark_plot_tools.py
@@ -235,9 +235,71 @@ def plot_performances_vs_snr(study, case_keys=None, figsize=None, metrics=["accu
             ax.scatter(x, y, marker=".", label=label)
             ax.set_title(k)
 
-        ax.set_ylim(0, 1.05)
+        ax.set_ylim(-0.05, 1.05)
 
         if count == 2:
             ax.legend()
 
     return fig
+
+
+def plot_performances_comparison(
+    study,
+    case_keys=None,
+    figsize=None,
+    metrics=["accuracy", "recall", "precision"],
+    colors=["g", "b", "r"],
+    ylim=(-0.1, 1.1),
+):
+    import matplotlib.pyplot as plt
+
+    if case_keys is None:
+        case_keys = list(study.cases.keys())
+
+    num_methods = len(case_keys)
+    assert num_methods >= 2, "plot_performances_comparison need at least 2 cases!"
+
+    fig, axs = plt.subplots(ncols=num_methods - 1, nrows=num_methods - 1, figsize=(10, 10), squeeze=False)
+    for i, key1 in enumerate(case_keys):
+        for j, key2 in enumerate(case_keys):
+
+            if i < j:
+                ax = axs[i, j - 1]
+
+                comp1 = study.get_result(key1)["gt_comparison"]
+                comp2 = study.get_result(key2)["gt_comparison"]
+
+                for performance, color in zip(metrics, colors):
+                    perf1 = comp1.get_performance()[performance]
+                    perf2 = comp2.get_performance()[performance]
+                    ax.scatter(perf2, perf1, marker=".", label=performance, color=color)
+
+                ax.plot([0, 1], [0, 1], "k--", alpha=0.5)
+                ax.set_ylim(ylim)
+                ax.set_xlim(ylim)
+                ax.spines[["right", "top"]].set_visible(False)
+                ax.set_aspect("equal")
+
+                label1 = study.cases[key1]["label"]
+                label2 = study.cases[key2]["label"]
+
+                if i == j - 1:
+                    ax.set_xlabel(label2)
+                    ax.set_ylabel(label1)
+
+            else:
+                if j >= 1 and i < num_methods - 1:
+                    ax = axs[i, j - 1]
+                    ax.spines[["right", "top", "left", "bottom"]].set_visible(False)
+                    ax.set_xticks([])
+                    ax.set_yticks([])
+
+    ax = axs[num_methods - 2, 0]
+    patches = []
+    from matplotlib.patches import Patch
+
+    for color, name in zip(colors, metrics):
+        patches.append(Patch(color=color, label=name))
+    ax.legend(handles=patches)
+    fig.tight_layout()
+    return fig
diff --git a/src/spikeinterface/sortingcomponents/matching/tdc.py b/src/spikeinterface/sortingcomponents/matching/tdc.py
index 56457fe2fa..125baa3bda 100644
--- a/src/spikeinterface/sortingcomponents/matching/tdc.py
+++ b/src/spikeinterface/sortingcomponents/matching/tdc.py
@@ -2,15 +2,11 @@
 
 import numpy as np
 from spikeinterface.core import (
-    get_noise_levels,
     get_channel_distances,
-    compute_sparsity,
     get_template_extremum_channel,
 )
 
-from spikeinterface.sortingcomponents.peak_detection import DetectPeakLocallyExclusive
-from spikeinterface.core.template import Templates
-
+from spikeinterface.sortingcomponents.peak_detection import DetectPeakLocallyExclusive, DetectPeakMatchedFiltering
 from .base import BaseTemplateMatching, _base_matching_dtype
 
 
@@ -25,7 +21,7 @@
 
 class TridesclousPeeler(BaseTemplateMatching):
     """
-    Template-matching ported from Tridesclous sorter.
+    Template-matching used by Tridesclous sorter.
 
     The idea of this peeler is pretty simple.
     1. Find peaks
@@ -34,8 +30,10 @@ class TridesclousPeeler(BaseTemplateMatching):
     4. remove it from traces.
     5. in the residual find peaks again
 
-    This method is quite fast but don't give exelent results to resolve
-    spike collision when templates have high similarity.
+    Contrary tp circus_peeler or wobble, this template matching is working directly one the waveforms.
+    There is no SVD decomposition
+
+
     """
 
     def __init__(
@@ -45,26 +43,29 @@ def __init__(
         parents=None,
         templates=None,
         peak_sign="neg",
+        exclude_sweep_ms=0.5,
         peak_shift_ms=0.2,
         detect_threshold=5,
         noise_levels=None,
-        radius_um=100.0,
-        num_closest=5,
-        sample_shift=3,
-        ms_before=0.8,
-        ms_after=1.2,
-        num_peeler_loop=2,
-        num_template_try=1,
+        use_fine_detector=True,
+        # TODO optimize theses radius
+        detection_radius_um=80.0,
+        cluster_radius_um=150.0,
+        amplitude_fitting_radius_um=150.0,
+        sample_shift=2,
+        ms_before=0.5,
+        ms_after=0.8,
+        max_peeler_loop=2,
+        amplitude_limits=(0.7, 1.4),
     ):
 
         BaseTemplateMatching.__init__(self, recording, templates, return_output=True, parents=None)
 
-        # maybe in base?
-        self.templates_array = templates.get_dense_templates()
-
         unit_ids = templates.unit_ids
         channel_ids = recording.channel_ids
 
+        num_templates = unit_ids.size
+
         sr = recording.sampling_frequency
 
         self.nbefore = templates.nbefore
@@ -82,8 +83,9 @@ def __init__(
         s1 = -(templates.nafter - nafter_short)
         if s1 == 0:
             s1 = None
+
         # TODO check with out copy
-        self.templates_short = self.templates_array[:, slice(s0, s1), :].copy()
+        self.sparse_templates_array_short = templates.templates_array[:, slice(s0, s1), :].copy()
 
         self.peak_shift = int(peak_shift_ms / 1000 * sr)
 
@@ -92,12 +94,12 @@ def __init__(
         self.abs_thresholds = noise_levels * detect_threshold
 
         channel_distance = get_channel_distances(recording)
-        self.neighbours_mask = channel_distance < radius_um
+        self.neighbours_mask = channel_distance <= detection_radius_um
 
         if templates.sparsity is not None:
-            self.template_sparsity = templates.sparsity.mask
+            self.sparsity_mask = templates.sparsity.mask
         else:
-            self.template_sparsity = np.ones((unit_ids.size, channel_ids.size), dtype=bool)
+            self.sparsity_mask = np.ones((unit_ids.size, channel_ids.size), dtype=bool)
 
         extremum_chan = get_template_extremum_channel(templates, peak_sign=peak_sign, outputs="index")
         # as numpy vector
@@ -109,72 +111,108 @@ def __init__(
         # distance between units
         import scipy
 
-        unit_distances = scipy.spatial.distance.cdist(unit_locations, unit_locations, metric="euclidean")
-
-        # seach for closet units and unitary discriminant vector
-        closest_units = []
-        for unit_ind, unit_id in enumerate(unit_ids):
-            order = np.argsort(unit_distances[unit_ind, :])
-            closest_u = np.arange(unit_ids.size)[order].tolist()
-            closest_u.remove(unit_ind)
-            closest_u = np.array(closest_u[:num_closest])
-
-            # compute unitary discriminent vector
-            (chans,) = np.nonzero(self.template_sparsity[unit_ind, :])
-            template_sparse = self.templates_array[unit_ind, :, :][:, chans]
-            closest_vec = []
-            # against N closets
-            for u in closest_u:
-                vec = self.templates_array[u, :, :][:, chans] - template_sparse
-                vec /= np.sum(vec**2)
-                closest_vec.append((u, vec))
-            # against noise
-            closest_vec.append((None, -template_sparse / np.sum(template_sparse**2)))
-
-            closest_units.append(closest_vec)
-
-        self.closest_units = closest_units
-
-        # distance channel from unit
-        import scipy
-
-        distances = scipy.spatial.distance.cdist(channel_locations, unit_locations, metric="euclidean")
-        near_cluster_mask = distances < radius_um
-
         # nearby cluster for each channel
+        distances = scipy.spatial.distance.cdist(channel_locations, unit_locations, metric="euclidean")
+        near_cluster_mask = distances <= cluster_radius_um
         self.possible_clusters_by_channel = []
         for channel_index in range(distances.shape[0]):
             (cluster_inds,) = np.nonzero(near_cluster_mask[channel_index, :])
             self.possible_clusters_by_channel.append(cluster_inds)
 
+        # precompute template norms ons sparse channels
+        self.template_norms = np.zeros(num_templates, dtype="float32")
+        for i in range(unit_ids.size):
+            chan_mask = self.sparsity_mask[i, :]
+            n = np.sum(chan_mask)
+            template = templates.templates_array[i, :, :n]
+            self.template_norms[i] = np.sum(template**2)
+
+        #
+        distances = scipy.spatial.distance.cdist(channel_locations, channel_locations, metric="euclidean")
+        self.near_chan_mask = distances <= amplitude_fitting_radius_um
+
         self.possible_shifts = np.arange(-sample_shift, sample_shift + 1, dtype="int64")
 
-        self.num_peeler_loop = num_peeler_loop
-        self.num_template_try = num_template_try
+        self.max_peeler_loop = max_peeler_loop
+        self.amplitude_limits = amplitude_limits
+
+        self.fast_spike_detector = DetectPeakLocallyExclusive(
+            recording=recording,
+            peak_sign=peak_sign,
+            detect_threshold=detect_threshold,
+            exclude_sweep_ms=exclude_sweep_ms,
+            radius_um=detection_radius_um,
+            noise_levels=noise_levels,
+        )
 
-        self.margin = max(self.nbefore, self.nafter) * 2
+        ##get prototype from best channel of each template
+        prototype = np.zeros(self.nbefore + self.nafter, dtype="float32")
+        for i in range(num_templates):
+            template = templates.templates_array[i, :, :]
+            chan_ind = np.argmax(np.abs(template[self.nbefore, :]))
+            if template[self.nbefore, chan_ind] != 0:
+                prototype += template[:, chan_ind] / np.abs(template[self.nbefore, chan_ind])
+        prototype /= np.abs(prototype[self.nbefore])
+
+        # import matplotlib.pyplot as plt
+        # fig,ax = plt.subplots()
+        # ax.plot(prototype)
+        # plt.show()
+
+        self.use_fine_detector = use_fine_detector
+        if self.use_fine_detector:
+            self.fine_spike_detector = DetectPeakMatchedFiltering(
+                recording=recording,
+                prototype=prototype,
+                ms_before=templates.nbefore / sr * 1000.0,
+                peak_sign="neg",
+                detect_threshold=detect_threshold,
+                exclude_sweep_ms=exclude_sweep_ms,
+                radius_um=detection_radius_um,
+                weight_method=dict(
+                    z_list_um=np.array([50.0]),
+                    sigma_3d=2.5,
+                    mode="exponential_3d",
+                ),
+                noise_levels=None,
+            )
+
+        self.detector_margin0 = self.fast_spike_detector.get_trace_margin()
+        self.detector_margin1 = self.fine_spike_detector.get_trace_margin() if use_fine_detector else 0
+        self.peeler_margin = max(self.nbefore, self.nafter) * 2
+        self.margin = max(self.peeler_margin, self.detector_margin0, self.detector_margin1)
 
     def get_trace_margin(self):
         return self.margin
 
     def compute_matching(self, traces, start_frame, end_frame, segment_index):
-        traces = traces.copy()
+
+        # TODO check if this is usefull
+        residuals = traces.copy()
 
         all_spikes = []
         level = 0
+        spikes_prev_loop = np.zeros(0, dtype=_base_matching_dtype)
+        use_fine_detector_level = False
         while True:
-            # spikes = _tdc_find_spikes(traces, d, level=level)
-            spikes = self._find_spikes_one_level(traces, level=level)
-            keep = spikes["cluster_index"] >= 0
-
-            if not np.any(keep):
-                break
-            all_spikes.append(spikes[keep])
+            # print('level', level)
+            spikes = self._find_spikes_one_level(residuals, spikes_prev_loop, use_fine_detector_level, level)
+            if spikes.size > 0:
+                all_spikes.append(spikes)
 
             level += 1
 
-            if level == self.num_peeler_loop:
-                break
+            # TODO concatenate all spikes for this instead of prev loop
+            spikes_prev_loop = spikes
+
+            if (spikes.size == 0) or (level == self.max_peeler_loop):
+                if self.use_fine_detector and not use_fine_detector_level:
+                    # extra loop with fine detector
+                    use_fine_detector_level = True
+                    level = self.max_peeler_loop - 1
+                    continue
+                else:
+                    break
 
         if len(all_spikes) > 0:
             all_spikes = np.concatenate(all_spikes)
@@ -185,13 +223,34 @@ def compute_matching(self, traces, start_frame, end_frame, segment_index):
 
         return all_spikes
 
-    def _find_spikes_one_level(self, traces, level=0):
+    def _find_spikes_one_level(self, traces, spikes_prev_loop, use_fine_detector, level):
 
-        peak_traces = traces[self.margin // 2 : -self.margin // 2, :]
-        peak_sample_ind, peak_chan_ind = DetectPeakLocallyExclusive.detect_peaks(
-            peak_traces, self.peak_sign, self.abs_thresholds, self.peak_shift, self.neighbours_mask
-        )
-        peak_sample_ind += self.margin // 2
+        # print(use_fine_detector, level)
+
+        # TODO change the threhold dynaically depending the level
+        # peak_traces = traces[self.detector_margin : -self.detector_margin, :]
+
+        # peak_sample_ind, peak_chan_ind = DetectPeakLocallyExclusive.detect_peaks(
+        #     peak_traces, self.peak_sign, self.abs_thresholds, self.peak_shift, self.neighbours_mask
+        # )
+
+        if use_fine_detector:
+            peak_detector = self.fine_spike_detector
+        else:
+            peak_detector = self.fast_spike_detector
+
+        detector_margin = peak_detector.get_trace_margin()
+        if self.peeler_margin > detector_margin:
+            margin_shift = self.peeler_margin - detector_margin
+            sl = slice(margin_shift, -margin_shift)
+        else:
+            sl = slice(None)
+            margin_shift = 0
+        peak_traces = traces[sl, :]
+        (peaks,) = peak_detector.compute(peak_traces, None, None, 0, self.margin)
+        peak_sample_ind = peaks["sample_index"]
+        peak_chan_ind = peaks["channel_index"]
+        peak_sample_ind += margin_shift
 
         peak_amplitude = traces[peak_sample_ind, peak_chan_ind]
         order = np.argsort(np.abs(peak_amplitude))[::-1]
@@ -200,153 +259,438 @@ def _find_spikes_one_level(self, traces, level=0):
 
         spikes = np.zeros(peak_sample_ind.size, dtype=_base_matching_dtype)
         spikes["sample_index"] = peak_sample_ind
-        spikes["channel_index"] = peak_chan_ind  # TODO need to put the channel from template
+        spikes["channel_index"] = peak_chan_ind
 
-        possible_shifts = self.possible_shifts
-        distances_shift = np.zeros(possible_shifts.size)
+        distances_shift = np.zeros(self.possible_shifts.size)
 
-        for i in range(peak_sample_ind.size):
+        delta_sample = max(self.nbefore, self.nafter)  #  TODO check this maybe add margin
+        # neighbors_spikes_inds = get_neighbors_spikes(spikes["sample_index"], spikes["channel_index"], delta_sample, self.near_chan_mask)
+
+        # neighbors in actual and previous level
+        neighbors_spikes_inds = get_neighbors_spikes(
+            np.concatenate([spikes["sample_index"], spikes_prev_loop["sample_index"]]),
+            np.concatenate([spikes["channel_index"], spikes_prev_loop["channel_index"]]),
+            delta_sample,
+            self.near_chan_mask,
+        )
+
+        for i in range(spikes.size):
             sample_index = peak_sample_ind[i]
 
             chan_ind = peak_chan_ind[i]
             possible_clusters = self.possible_clusters_by_channel[chan_ind]
 
             if possible_clusters.size > 0:
-                # ~ s0 = sample_index - d['nbefore']
-                # ~ s1 = sample_index + d['nafter']
+                cluster_index = get_most_probable_cluster(
+                    traces,
+                    self.sparse_templates_array_short,
+                    possible_clusters,
+                    sample_index,
+                    chan_ind,
+                    self.nbefore_short,
+                    self.nafter_short,
+                    self.sparsity_mask,
+                )
+
+                # import matplotlib.pyplot as plt
+                # fig, ax = plt.subplots()
+                # chans = np.any(self.sparsity_mask[possible_clusters, :], axis=0)
+                # wf = traces[sample_index - self.nbefore : sample_index + self.nafter][:, chans]
+                # ax.plot(wf.T.flatten(), color='k')
+                # dense_templates_array = self.templates.get_dense_templates()
+                # for c_ind in possible_clusters:
+                #     template = dense_templates_array[c_ind, :, :][:, chans]
+                #     ax.plot(template.T.flatten())
+                #     if c_ind == cluster_index:
+                #         ax.plot(template.T.flatten(), color='m', ls='--')
+                #     ax.set_title(f"use_fine_detector{use_fine_detector} level{level}")
+                # plt.show()
+
+                chan_sparsity_mask = self.sparsity_mask[cluster_index, :]
+
+                # find best shift
+                numba_best_shift_sparse(
+                    traces,
+                    self.sparse_templates_array_short[cluster_index, :, :],
+                    sample_index,
+                    self.nbefore_short,
+                    self.possible_shifts,
+                    distances_shift,
+                    chan_sparsity_mask,
+                )
+
+                ind_shift = np.argmin(distances_shift)
+                shift = self.possible_shifts[ind_shift]
+
+                # TODO DEBUG shift later
+                spikes["sample_index"][i] += shift
+
+                spikes["cluster_index"][i] = cluster_index
+
+                # check that the the same cluster is not already detected at same place
+                # this can happen for small template the substract forvever the traces
+                outer_neighbors_inds = [ind for ind in neighbors_spikes_inds[i] if ind > i and ind >= spikes.size]
+                is_valid = True
+                for b in outer_neighbors_inds:
+                    b = b - spikes.size
+                    if (spikes[i]["sample_index"] == spikes_prev_loop[b]["sample_index"]) and (
+                        spikes[i]["cluster_index"] == spikes_prev_loop[b]["cluster_index"]
+                    ):
+                        is_valid = False
+
+                if is_valid:
+                    # temporary assign a cluster to neighbors if not done yet
+                    inner_neighbors_inds = [ind for ind in neighbors_spikes_inds[i] if (ind > i and ind < spikes.size)]
+                    for b in inner_neighbors_inds:
+                        spikes["cluster_index"][b] = get_most_probable_cluster(
+                            traces,
+                            self.sparse_templates_array_short,
+                            possible_clusters,
+                            spikes["sample_index"][b],
+                            spikes["channel_index"][b],
+                            self.nbefore_short,
+                            self.nafter_short,
+                            self.sparsity_mask,
+                        )
+
+                    amp = fit_one_amplitude_with_neighbors(
+                        spikes[i],
+                        spikes[inner_neighbors_inds],
+                        traces,
+                        self.sparsity_mask,
+                        self.templates.templates_array,
+                        self.template_norms,
+                        self.nbefore,
+                        self.nafter,
+                    )
 
-                # ~ wf = traces[s0:s1, :]
+                    low_lim, up_lim = self.amplitude_limits
+                    if low_lim <= amp <= up_lim:
+                        spikes["amplitude"][i] = amp
+                        wanted_channel_mask = np.ones(traces.shape[1], dtype=bool)  # TODO move this before the loop
+                        construct_prediction_sparse(
+                            spikes[i : i + 1],
+                            traces,
+                            self.templates.templates_array,
+                            self.sparsity_mask,
+                            wanted_channel_mask,
+                            self.nbefore,
+                            additive=False,
+                        )
+                    elif low_lim > amp:
+                        # print("bad amp", amp)
+                        spikes["cluster_index"][i] = -1
+
+                        # import matplotlib.pyplot as plt
+                        # fig, ax = plt.subplots()
+                        # sample_ind = spikes["sample_index"][i]
+                        # print(chan_sparsity_mask)
+                        # wf = traces[sample_ind - self.nbefore : sample_ind + self.nafter][:, chan_sparsity_mask]
+                        # dense_templates_array = self.templates.get_dense_templates()
+                        # template = dense_templates_array[cluster_index, :, :][:, chan_sparsity_mask]
+                        # ax.plot(wf.T.flatten())
+                        # ax.plot(template.T.flatten())
+                        # ax.plot(template.T.flatten() * amp)
+                        # ax.set_title(f"amp{amp} use_fine_detector{use_fine_detector} level{level}")
+                        # plt.show()
+                    else:
+                        # amp > up_lim
+                        # TODO should try other cluster for the fit!!
+                        # spikes["cluster_index"][i] = -1
+
+                        # force amplitude to be one and need a fiting at next level
+                        spikes["amplitude"][i] = 1
+
+                        # print(amp)
+                        # import matplotlib.pyplot as plt
+                        # fig, ax = plt.subplots()
+                        # sample_ind = spikes["sample_index"][i]
+                        # wf = traces[sample_ind - self.nbefore : sample_ind + self.nafter][:, chan_sparsity_mask]
+                        # dense_templates_array = self.templates.get_dense_templates()
+                        # template = dense_templates_array[cluster_index, :, :][:, chan_sparsity_mask]
+                        # ax.plot(wf.T.flatten())
+                        # ax.plot(template.T.flatten())
+                        # ax.plot(template.T.flatten() * amp)
+                        # ax.set_title(f"amp{amp} use_fine_detector{use_fine_detector} level{level}")
+                        # plt.show()
+
+                        # import matplotlib.pyplot as plt
+                        # fig, ax = plt.subplots()
+                        # chans = np.any(self.sparsity_mask[possible_clusters, :], axis=0)
+                        # wf = traces[sample_index - self.nbefore : sample_index + self.nafter][:, chans]
+                        # ax.plot(wf.T.flatten(), color='k')
+                        # dense_templates_array = self.templates.get_dense_templates()
+                        # for c_ind in possible_clusters:
+                        #     template = dense_templates_array[c_ind, :, :][:, chans]
+                        #     ax.plot(template.T.flatten())
+                        #     if c_ind == cluster_index:
+                        #         ax.plot(template.T.flatten(), color='m', ls='--')
+                        #     ax.set_title(f"use_fine_detector{use_fine_detector} level{level}")
+                        # plt.show()
 
-                s0 = sample_index - self.nbefore_short
-                s1 = sample_index + self.nafter_short
-                wf_short = traces[s0:s1, :]
+                else:
+                    # not valid because already detected
+                    spikes["cluster_index"][i] = -1
 
-                ## pure numpy with cluster spasity
-                # distances = np.sum(np.sum((templates[possible_clusters, :, :] - wf[None, : , :])**2, axis=1), axis=1)
+            else:
+                # no possible cluster in neighborhood for this channel
+                spikes["cluster_index"][i] = -1
 
-                ## pure numpy with cluster+channel spasity
-                # union_channels, = np.nonzero(np.any(d['template_sparsity'][possible_clusters, :], axis=0))
-                # distances = np.sum(np.sum((templates[possible_clusters][:, :, union_channels] - wf[: , union_channels][None, : :])**2, axis=1), axis=1)
+        # delta_sample = self.nbefore + self.nafter
+        # # TODO benchmark this and make this faster
+        # neighbors_spikes_inds = get_neighbors_spikes(spikes["sample_index"], spikes["channel_index"], delta_sample, self.near_chan_mask)
+        # for i in range(spikes.size):
+        #     amp = fit_one_amplitude_with_neighbors(spikes[i], spikes[neighbors_spikes_inds[i]],  traces,
+        #                                      self.sparsity_mask, self.templates.templates_array, self.nbefore, self.nafter)
+        #     spikes["amplitude"][i] = amp
 
-                ## numba with cluster+channel spasity
-                union_channels = np.any(self.template_sparsity[possible_clusters, :], axis=0)
-                # distances = numba_sparse_dist(wf, templates, union_channels, possible_clusters)
-                distances = numba_sparse_dist(wf_short, self.templates_short, union_channels, possible_clusters)
+        keep = spikes["cluster_index"] >= 0
+        spikes = spikes[keep]
 
-                # DEBUG
-                # ~ ind = np.argmin(distances)
-                # ~ cluster_index = possible_clusters[ind]
+        # keep = (spikes["amplitude"] >= 0.7) & (spikes["amplitude"] <= 1.4)
+        # spikes = spikes[keep]
 
-                for ind in np.argsort(distances)[: self.num_template_try]:
-                    cluster_index = possible_clusters[ind]
+        # sparse_templates_array = self.templates.templates_array
+        # wanted_channel_mask = np.ones(traces.shape[1], dtype=bool)
+        # assert np.sum(wanted_channel_mask) == traces.shape[1] # TODO remove this DEBUG later
+        # construct_prediction_sparse(spikes, traces, sparse_templates_array, self.sparsity_mask, wanted_channel_mask, self.nbefore, additive=False)
 
-                    chan_sparsity = self.template_sparsity[cluster_index, :]
-                    template_sparse = self.templates_array[cluster_index, :, :][:, chan_sparsity]
+        return spikes
 
-                    # find best shift
 
-                    ## pure numpy version
-                    # for s, shift in enumerate(possible_shifts):
-                    #     wf_shift = traces[s0 + shift: s1 + shift, chan_sparsity]
-                    #     distances_shift[s] = np.sum((template_sparse - wf_shift)**2)
-                    # ind_shift = np.argmin(distances_shift)
-                    # shift = possible_shifts[ind_shift]
+def get_most_probable_cluster(
+    traces,
+    sparse_templates_array,
+    possible_clusters,
+    sample_index,
+    chan_ind,
+    nbefore_short,
+    nafter_short,
+    template_sparsity_mask,
+):
+    s0 = sample_index - nbefore_short
+    s1 = sample_index + nafter_short
+    wf_short = traces[s0:s1, :]
 
-                    ## numba version
-                    numba_best_shift(
-                        traces,
-                        self.templates_array[cluster_index, :, :],
-                        sample_index,
-                        self.nbefore,
-                        possible_shifts,
-                        distances_shift,
-                        chan_sparsity,
-                    )
-                    ind_shift = np.argmin(distances_shift)
-                    shift = possible_shifts[ind_shift]
-
-                    sample_index = sample_index + shift
-                    s0 = sample_index - self.nbefore
-                    s1 = sample_index + self.nafter
-                    wf_sparse = traces[s0:s1, chan_sparsity]
-
-                    # accept or not
-
-                    centered = wf_sparse - template_sparse
-                    accepted = True
-                    for other_ind, other_vector in self.closest_units[cluster_index]:
-                        v = np.sum(centered * other_vector)
-                        if np.abs(v) > 0.5:
-                            accepted = False
-                            break
-
-                    if accepted:
-                        # ~ if ind != np.argsort(distances)[0]:
-                        # ~ print('not first one', np.argsort(distances), ind)
-                        break
-
-                if accepted:
-                    amplitude = 1.0
-
-                    # remove template
-                    template = self.templates_array[cluster_index, :, :]
-                    s0 = sample_index - self.nbefore
-                    s1 = sample_index + self.nafter
-                    traces[s0:s1, :] -= template * amplitude
+    ## numba with cluster+channel spasity
+    union_channels = np.any(template_sparsity_mask[possible_clusters, :], axis=0)
+    distances = numba_sparse_distance(
+        wf_short, sparse_templates_array, template_sparsity_mask, union_channels, possible_clusters
+    )
 
-                else:
-                    cluster_index = -1
-                    amplitude = 0.0
+    ind = np.argmin(distances)
+    cluster_index = possible_clusters[ind]
 
-            else:
-                cluster_index = -1
-                amplitude = 0.0
+    return cluster_index
 
-            spikes["cluster_index"][i] = cluster_index
-            spikes["amplitude"][i] = amplitude
 
-        return spikes
+def get_neighbors_spikes(sample_inds, chan_inds, delta_sample, near_chan_mask):
+
+    neighbors_spikes_inds = []
+    for i in range(sample_inds.size):
+
+        inds = np.flatnonzero(np.abs(sample_inds - sample_inds[i]) < delta_sample)
+        neighb = []
+        for ind in inds:
+            if near_chan_mask[chan_inds[i], chan_inds[ind]] and i != ind:
+                neighb.append(ind)
+        neighbors_spikes_inds.append(neighb)
+
+    return neighbors_spikes_inds
+
+
+def fit_one_amplitude_with_neighbors(
+    spike, neighbors_spikes, traces, template_sparsity_mask, sparse_templates_array, template_norms, nbefore, nafter
+):
+    """
+    Fit amplitude one spike of one spike with/without neighbors
+
+    """
+
+    import scipy.linalg
+
+    cluster_index = spike["cluster_index"]
+    sample_index = spike["sample_index"]
+    chan_sparsity_mask = template_sparsity_mask[cluster_index, :]
+    num_chans = np.sum(chan_sparsity_mask)
+    if num_chans == 0:
+        # protect against empty template because too sparse
+        return 0.0
+    start, stop = sample_index - nbefore, sample_index + nafter
+    if neighbors_spikes is None or (neighbors_spikes.size == 0):
+        template = sparse_templates_array[cluster_index, :, :num_chans]
+        wf = traces[start:stop, :][:, chan_sparsity_mask]
+        # TODO precompute template norms
+        amplitude = np.sum(template.flatten() * wf.flatten()) / template_norms[cluster_index]
+    else:
+
+        lim0 = min(start, np.min(neighbors_spikes["sample_index"]) - nbefore)
+        lim1 = max(stop, np.max(neighbors_spikes["sample_index"]) + nafter)
+
+        local_traces = traces[lim0:lim1, :][:, chan_sparsity_mask]
+        mask_not_fitted = (neighbors_spikes["amplitude"] == 0.0) & (neighbors_spikes["cluster_index"] >= 0)
+        local_spike = spike.copy()
+        local_spike["sample_index"] -= lim0
+        local_spike["amplitude"] = 1.0
+
+        local_neighbors_spikes = neighbors_spikes.copy()
+        local_neighbors_spikes["sample_index"] -= lim0
+        local_neighbors_spikes["amplitude"][:] = 1.0
+
+        num_spikes_to_fit = 1 + np.sum(mask_not_fitted)
+        x = np.zeros((lim1 - lim0, num_chans, num_spikes_to_fit), dtype="float32")
+        wanted_channel_mask = chan_sparsity_mask
+        construct_prediction_sparse(
+            np.array([local_spike]),
+            x[:, :, 0],
+            sparse_templates_array,
+            template_sparsity_mask,
+            chan_sparsity_mask,
+            nbefore,
+            True,
+        )
+
+        j = 1
+        for i in range(neighbors_spikes.size):
+            if mask_not_fitted[i]:
+                # add to one regressor
+                construct_prediction_sparse(
+                    local_neighbors_spikes[i : i + 1],
+                    x[:, :, j],
+                    sparse_templates_array,
+                    template_sparsity_mask,
+                    chan_sparsity_mask,
+                    nbefore,
+                    True,
+                )
+                j += 1
+            elif local_neighbors_spikes[neighbors_spikes[i]]["sample_index"] >= 0:
+                # remove from traces
+                construct_prediction_sparse(
+                    local_neighbors_spikes[i : i + 1],
+                    local_traces,
+                    sparse_templates_array,
+                    template_sparsity_mask,
+                    chan_sparsity_mask,
+                    nbefore,
+                    False,
+                )
+            # else:
+            #     pass
+
+        x = x.reshape(-1, num_spikes_to_fit)
+        y = local_traces.flatten()
+
+        res = scipy.linalg.lstsq(x, y, cond=None, lapack_driver="gelsd")
+        amplitudes = res[0]
+        amplitude = amplitudes[0]
+
+        # import matplotlib.pyplot as plt
+        # x_plot = x.reshape((lim1 - lim0, num_chans, num_spikes_to_fit)).swapaxes(0, 1).reshape(-1, num_spikes_to_fit)
+        # pred = x @ amplitudes
+        # pred_plot = pred.reshape(-1, num_chans).T.flatten()
+        # y_plot = y.reshape(-1, num_chans).T.flatten()
+        # fig, ax = plt.subplots()
+        # ax.plot(x_plot, color='b')
+        # print(x_plot.shape, y_plot.shape)
+        # ax.plot(y_plot, color='g')
+        # ax.plot(pred_plot , color='r')
+        # ax.set_title(f"{amplitudes}")
+        # # ax.set_title(f"{amplitudes} {amp_dot}")
+        # plt.show()
+
+    return amplitude
 
 
 if HAVE_NUMBA:
 
     @jit(nopython=True)
-    def numba_sparse_dist(wf, templates, union_channels, possible_clusters):
+    def construct_prediction_sparse(
+        spikes, traces, sparse_templates_array, template_sparsity_mask, wanted_channel_mask, nbefore, additive
+    ):
+        #  must have np.sum(wanted_channel_mask) == traces.shape[0]
+        total_chans = wanted_channel_mask.shape[0]
+        for spike in spikes:
+            ind0 = spike["sample_index"] - nbefore
+            ind1 = ind0 + sparse_templates_array.shape[1]
+            cluster_index = spike["cluster_index"]
+            amplitude = spike["amplitude"]
+            chan_in_template = 0
+            chan_in_trace = 0
+            for chan in range(total_chans):
+                if wanted_channel_mask[chan]:
+                    if template_sparsity_mask[cluster_index, chan]:
+                        if additive:
+                            traces[ind0:ind1, chan_in_trace] += (
+                                sparse_templates_array[cluster_index, :, chan_in_template] * amplitude
+                            )
+                        else:
+                            traces[ind0:ind1, chan_in_trace] -= (
+                                sparse_templates_array[cluster_index, :, chan_in_template] * amplitude
+                            )
+                        chan_in_template += 1
+                    chan_in_trace += 1
+                else:
+                    if template_sparsity_mask[cluster_index, chan]:
+                        chan_in_template += 1
+
+    @jit(nopython=True)
+    def numba_sparse_distance(
+        wf, sparse_templates_array, template_sparsity_mask, wanted_channel_mask, possible_clusters
+    ):
         """
         numba implementation that compute distance from template with sparsity
-        handle by two separate vectors
+
+        wf is dense
+        sparse_templates_array is sparse with the template_sparsity_mask
         """
-        total_cluster, width, num_chan = templates.shape
+        width, total_chans = wf.shape
         num_cluster = possible_clusters.shape[0]
         distances = np.zeros((num_cluster,), dtype=np.float32)
         for i in prange(num_cluster):
             cluster_index = possible_clusters[i]
             sum_dist = 0.0
-            for chan_ind in range(num_chan):
-                if union_channels[chan_ind]:
-                    for s in range(width):
-                        v = wf[s, chan_ind]
-                        t = templates[cluster_index, s, chan_ind]
-                        sum_dist += (v - t) ** 2
+            chan_in_template = 0
+            for chan in range(total_chans):
+                if wanted_channel_mask[chan]:
+                    if template_sparsity_mask[cluster_index, chan]:
+                        for s in range(width):
+                            v = wf[s, chan]
+                            t = sparse_templates_array[cluster_index, s, chan_in_template]
+                            sum_dist += (v - t) ** 2
+                        chan_in_template += 1
+                    else:
+                        for s in range(width):
+                            v = wf[s, chan]
+                            t = 0
+                            sum_dist += (v - t) ** 2
+                else:
+                    if template_sparsity_mask[cluster_index, chan]:
+                        chan_in_template += 1
             distances[i] = sum_dist
         return distances
 
     @jit(nopython=True)
-    def numba_best_shift(traces, template, sample_index, nbefore, possible_shifts, distances_shift, chan_sparsity):
+    def numba_best_shift_sparse(
+        traces, sparse_template, sample_index, nbefore, possible_shifts, distances_shift, chan_sparsity
+    ):
         """
         numba implementation to compute several sample shift before template substraction
         """
-        width, num_chan = template.shape
+        width = sparse_template.shape[0]
+        total_chans = traces.shape[1]
         n_shift = possible_shifts.size
         for i in range(n_shift):
             shift = possible_shifts[i]
             sum_dist = 0.0
-            for chan_ind in range(num_chan):
-                if chan_sparsity[chan_ind]:
+            chan_in_template = 0
+            for chan in range(total_chans):
+                if chan_sparsity[chan]:
                     for s in range(width):
-                        v = traces[sample_index - nbefore + s + shift, chan_ind]
-                        t = template[s, chan_ind]
+                        v = traces[sample_index - nbefore + s + shift, chan]
+                        t = sparse_template[s, chan_in_template]
                         sum_dist += (v - t) ** 2
+                    chan_in_template += 1
             distances_shift[i] = sum_dist
 
         return distances_shift
diff --git a/src/spikeinterface/sortingcomponents/matching/wobble.py b/src/spikeinterface/sortingcomponents/matching/wobble.py
index 2531a922da..3099448b11 100644
--- a/src/spikeinterface/sortingcomponents/matching/wobble.py
+++ b/src/spikeinterface/sortingcomponents/matching/wobble.py
@@ -348,7 +348,7 @@ def __init__(
 
         BaseTemplateMatching.__init__(self, recording, templates, return_output=True, parents=None)
 
-        templates_array = templates.get_dense_templates().astype(np.float32, casting="safe")
+        templates_array = templates.get_dense_templates().astype(np.float32)
 
         # Aggregate useful parameters/variables for handy access in downstream functions
         params = WobbleParameters(**parameters)
diff --git a/src/spikeinterface/sortingcomponents/tests/test_template_matching.py b/src/spikeinterface/sortingcomponents/tests/test_template_matching.py
index cbf1d29932..7cd899a3bb 100644
--- a/src/spikeinterface/sortingcomponents/tests/test_template_matching.py
+++ b/src/spikeinterface/sortingcomponents/tests/test_template_matching.py
@@ -9,8 +9,8 @@
 from spikeinterface.sortingcomponents.tests.common import make_dataset
 
 
-job_kwargs = dict(n_jobs=-1, chunk_duration="500ms", progress_bar=True)
-# job_kwargs = dict(n_jobs=1, chunk_duration="500ms", progress_bar=True)
+# job_kwargs = dict(n_jobs=-1, chunk_duration="500ms", progress_bar=True)
+job_kwargs = dict(n_jobs=1, chunk_duration="500ms", progress_bar=True)
 
 
 def get_sorting_analyzer():
@@ -45,7 +45,7 @@ def test_find_spikes_from_templates(method, sorting_analyzer):
         "templates": templates,
     }
     method_kwargs = {}
-    if method in ("naive", "tdc-peeler", "circus"):
+    if method in ("naive", "tdc-peeler", "circus", "tdc-peeler2"):
         method_kwargs["noise_levels"] = noise_levels
 
     # method_kwargs["wobble"] = {
@@ -61,26 +61,28 @@ def test_find_spikes_from_templates(method, sorting_analyzer):
 
     # print(info)
 
-    # DEBUG = True
+    DEBUG = True
 
-    # if DEBUG:
-    #     import matplotlib.pyplot as plt
-    #     import spikeinterface.full as si
+    if DEBUG:
+        import matplotlib.pyplot as plt
+        import spikeinterface.full as si
 
-    #     sorting_analyzer.compute("waveforms")
-    #     sorting_analyzer.compute("templates")
+        sorting_analyzer.compute("waveforms")
+        sorting_analyzer.compute("templates")
 
-    #     gt_sorting = sorting_analyzer.sorting
+        gt_sorting = sorting_analyzer.sorting
 
-    #     sorting = NumpySorting.from_times_labels(spikes["sample_index"], spikes["cluster_index"], recording.sampling_frequency)
+        sorting = NumpySorting.from_times_labels(
+            spikes["sample_index"], spikes["cluster_index"], recording.sampling_frequency
+        )
 
-    #     ##metrics = si.compute_quality_metrics(sorting_analyzer, metric_names=["snr"])
+        ##metrics = si.compute_quality_metrics(sorting_analyzer, metric_names=["snr"])
 
-    #     fig, ax = plt.subplots()
-    #     comp = si.compare_sorter_to_ground_truth(gt_sorting, sorting)
-    #     si.plot_agreement_matrix(comp, ax=ax)
-    #     ax.set_title(method)
-    # plt.show()
+        # fig, ax = plt.subplots()
+        # comp = si.compare_sorter_to_ground_truth(gt_sorting, sorting)
+        # si.plot_agreement_matrix(comp, ax=ax)
+        # ax.set_title(method)
+        # plt.show()
 
 
 if __name__ == "__main__":
@@ -88,6 +90,6 @@ def test_find_spikes_from_templates(method, sorting_analyzer):
     # method = "naive"
     # method = "tdc-peeler"
     # method =  "circus"
-    method = "circus-omp-svd"
-    # method = "wobble"
+    # method = "circus-omp-svd"
+    method = "wobble"
     test_find_spikes_from_templates(method, sorting_analyzer)

From 957861fd43861a124880c41c5cbcc8921db30889 Mon Sep 17 00:00:00 2001
From: Sebastien <pierre.yger@gmail.com>
Date: Mon, 14 Oct 2024 17:19:07 +0200
Subject: [PATCH 095/344] Sparsify the weights

---
 src/spikeinterface/sortingcomponents/peak_detection.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/peak_detection.py b/src/spikeinterface/sortingcomponents/peak_detection.py
index d608c5d105..51b3e4dc77 100644
--- a/src/spikeinterface/sortingcomponents/peak_detection.py
+++ b/src/spikeinterface/sortingcomponents/peak_detection.py
@@ -631,7 +631,7 @@ def __init__(
         weight_method={},
     ):
         PeakDetector.__init__(self, recording, return_output=True)
-
+        import scipy
         if not HAVE_NUMBA:
             raise ModuleNotFoundError('matched_filtering" needs numba which is not installed')
 
@@ -664,7 +664,7 @@ def __init__(
             self.num_templates *= 2
 
         self.weights = self.weights.reshape(self.num_templates * self.num_z_factors, -1)
-
+        self.weights = scipy.sparse.csr_matrix(self.weights)
         random_data = get_random_data_chunks(recording, return_scaled=False, **random_chunk_kwargs)
         conv_random_data = self.get_convolved_traces(random_data)
         medians = np.median(conv_random_data, axis=1)
@@ -737,7 +737,7 @@ def get_convolved_traces(self, traces):
         import scipy.signal
 
         tmp = scipy.signal.oaconvolve(self.prototype[None, :], traces.T, axes=1, mode="valid")
-        scalar_products = np.dot(self.weights, tmp)
+        scalar_products = self.weights.dot(tmp)
         return scalar_products
 
 

From 5568e1a3cd98f6f9c77953c294fdd558c4457e6c Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 14 Oct 2024 15:23:19 +0000
Subject: [PATCH 096/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/sortingcomponents/peak_detection.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/spikeinterface/sortingcomponents/peak_detection.py b/src/spikeinterface/sortingcomponents/peak_detection.py
index 51b3e4dc77..2961f11981 100644
--- a/src/spikeinterface/sortingcomponents/peak_detection.py
+++ b/src/spikeinterface/sortingcomponents/peak_detection.py
@@ -632,6 +632,7 @@ def __init__(
     ):
         PeakDetector.__init__(self, recording, return_output=True)
         import scipy
+
         if not HAVE_NUMBA:
             raise ModuleNotFoundError('matched_filtering" needs numba which is not installed')
 

From ba847a8720c54558f94d918ee2e6a8797713729d Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 14 Oct 2024 17:52:59 +0000
Subject: [PATCH 097/344] [pre-commit.ci] pre-commit autoupdate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

updates:
- [github.com/psf/black: 24.8.0 → 24.10.0](https://github.com/psf/black/compare/24.8.0...24.10.0)
---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 1e133694ba..4c36d6fb86 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -6,7 +6,7 @@ repos:
     -   id: end-of-file-fixer
     -   id: trailing-whitespace
 -   repo: https://github.com/psf/black
-    rev: 24.8.0
+    rev: 24.10.0
     hooks:
     -   id: black
         files: ^src/

From 14278161efe44c5955dc2072a5354de73dcf6bb3 Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Mon, 14 Oct 2024 23:36:43 +0200
Subject: [PATCH 098/344] Imports

---
 src/spikeinterface/sortingcomponents/peak_detection.py | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/peak_detection.py b/src/spikeinterface/sortingcomponents/peak_detection.py
index 2961f11981..d2d1afaafb 100644
--- a/src/spikeinterface/sortingcomponents/peak_detection.py
+++ b/src/spikeinterface/sortingcomponents/peak_detection.py
@@ -631,7 +631,7 @@ def __init__(
         weight_method={},
     ):
         PeakDetector.__init__(self, recording, return_output=True)
-        import scipy
+        from scipy.sparse import csr_matrix
 
         if not HAVE_NUMBA:
             raise ModuleNotFoundError('matched_filtering" needs numba which is not installed')
@@ -665,7 +665,7 @@ def __init__(
             self.num_templates *= 2
 
         self.weights = self.weights.reshape(self.num_templates * self.num_z_factors, -1)
-        self.weights = scipy.sparse.csr_matrix(self.weights)
+        self.weights = csr_matrix(self.weights)
         random_data = get_random_data_chunks(recording, return_scaled=False, **random_chunk_kwargs)
         conv_random_data = self.get_convolved_traces(random_data)
         medians = np.median(conv_random_data, axis=1)
@@ -735,9 +735,8 @@ def compute(self, traces, start_frame, end_frame, segment_index, max_margin):
         return (local_peaks,)
 
     def get_convolved_traces(self, traces):
-        import scipy.signal
-
-        tmp = scipy.signal.oaconvolve(self.prototype[None, :], traces.T, axes=1, mode="valid")
+        from scipy.signal import oaconvolve
+        tmp = oaconvolve(self.prototype[None, :], traces.T, axes=1, mode="valid")
         scalar_products = self.weights.dot(tmp)
         return scalar_products
 

From b9f2cc803b295097a6cf4ae95eee5f82d5be222f Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 14 Oct 2024 21:37:04 +0000
Subject: [PATCH 099/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/sortingcomponents/peak_detection.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/spikeinterface/sortingcomponents/peak_detection.py b/src/spikeinterface/sortingcomponents/peak_detection.py
index d2d1afaafb..134481289e 100644
--- a/src/spikeinterface/sortingcomponents/peak_detection.py
+++ b/src/spikeinterface/sortingcomponents/peak_detection.py
@@ -736,6 +736,7 @@ def compute(self, traces, start_frame, end_frame, segment_index, max_margin):
 
     def get_convolved_traces(self, traces):
         from scipy.signal import oaconvolve
+
         tmp = oaconvolve(self.prototype[None, :], traces.T, axes=1, mode="valid")
         scalar_products = self.weights.dot(tmp)
         return scalar_products

From 3e608c60b96a33f7cccdabb1adcf0a92ab3ada78 Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Tue, 15 Oct 2024 12:15:37 +0200
Subject: [PATCH 100/344] Torch support for matching engines circus and OMP

* Fixes

* Patches

* Fixes for SC2 and for split clustering

* debugging clustering

* WIP

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

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

* WIP

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

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

* Torch for convolutions

* Forcing data structures to be float32

* Device and wobble

* WIP

* Speeding up wobble

* WIP

* WIP

* Troch

* WIP torch

* WIP

* WIP

* Addition of a detection node for coherence

* Doc

* WIP

* Default params

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

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

* WIP

* Handling context with torch on the fly

* Dealing with torch

* Adding support for torch in matching engines

* Automatic handling of torch

* Default back

* WIP

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

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

* Adding gather_func to find_spikes

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

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

* Gathering mode more explicit for matching

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

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

* WIP

* WIP

* Fixes for SC2

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

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

* WIP

* Simplifications

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

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

* Naming for Sam

* Optimize circus matching engine

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

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

* Optimizations

* Remove the limit to chunk sizes in circus-omp-svd

* WIP

* Wobble also

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

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

* Wobble also

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

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

* WIP

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

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

* Oups

* WIP

* WIP

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

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

* Fixes

* Backward compatibility*

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

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

* Naming

* Cleaning

* Bringing back context for peak detectors

* Update src/spikeinterface/benchmark/benchmark_matching.py

* Update src/spikeinterface/sortingcomponents/matching/circus.py

* WIP

* Patch imports

* WIP

* WIP

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

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

* Fixing tests

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

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

* WIP

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

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

* KSPeeler

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

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

* Moving KS in a new PR

* Moving KS in a new PR

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

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

* Allow spawn and cuda for circus

* Add push_to_torch to allow pickling of objects

* Default

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

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

* Cleaning docs

* WIP

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Garcia Samuel <sam.garcia.die@gmail.com>
---
 .../benchmark/benchmark_matching.py           |   1 +
 .../sorters/internal/spyking_circus2.py       |   8 +-
 .../sortingcomponents/clustering/circus.py    |   6 +-
 .../sortingcomponents/matching/circus.py      | 134 ++++++++++++------
 .../sortingcomponents/matching/wobble.py      | 111 +++++++++++----
 .../sortingcomponents/peak_detection.py       |  11 +-
 .../sortingcomponents/tests/test_wobble.py    |  53 +++++--
 7 files changed, 235 insertions(+), 89 deletions(-)

diff --git a/src/spikeinterface/benchmark/benchmark_matching.py b/src/spikeinterface/benchmark/benchmark_matching.py
index 3799fa19b3..1934b65ef4 100644
--- a/src/spikeinterface/benchmark/benchmark_matching.py
+++ b/src/spikeinterface/benchmark/benchmark_matching.py
@@ -80,6 +80,7 @@ def plot_performances_comparison(self, **kwargs):
     def plot_collisions(self, case_keys=None, figsize=None):
         if case_keys is None:
             case_keys = list(self.cases.keys())
+        import matplotlib.pyplot as plt
 
         fig, axs = plt.subplots(ncols=len(case_keys), nrows=1, figsize=figsize, squeeze=False)
 
diff --git a/src/spikeinterface/sorters/internal/spyking_circus2.py b/src/spikeinterface/sorters/internal/spyking_circus2.py
index 211adba990..eed693b343 100644
--- a/src/spikeinterface/sorters/internal/spyking_circus2.py
+++ b/src/spikeinterface/sorters/internal/spyking_circus2.py
@@ -27,7 +27,7 @@ class Spykingcircus2Sorter(ComponentsBasedSorter):
         "general": {"ms_before": 2, "ms_after": 2, "radius_um": 75},
         "sparsity": {"method": "snr", "amplitude_mode": "peak_to_peak", "threshold": 0.25},
         "filtering": {"freq_min": 150, "freq_max": 7000, "ftype": "bessel", "filter_order": 2},
-        "whitening": {"mode": "local", "regularize": True},
+        "whitening": {"mode": "local", "regularize": False},
         "detection": {"peak_sign": "neg", "detect_threshold": 4},
         "selection": {
             "method": "uniform",
@@ -100,6 +100,12 @@ def _run_from_folder(cls, sorter_output_folder, params, verbose):
         except:
             HAVE_HDBSCAN = False
 
+        try:
+            import torch
+        except ImportError:
+            HAVE_TORCH = False
+            print("spykingcircus2 could benefit from using torch. Consider installing it")
+
         assert HAVE_HDBSCAN, "spykingcircus2 needs hdbscan to be installed"
 
         # this is importanted only on demand because numba import are too heavy
diff --git a/src/spikeinterface/sortingcomponents/clustering/circus.py b/src/spikeinterface/sortingcomponents/clustering/circus.py
index b7e71d3b45..99c59f493e 100644
--- a/src/spikeinterface/sortingcomponents/clustering/circus.py
+++ b/src/spikeinterface/sortingcomponents/clustering/circus.py
@@ -92,7 +92,7 @@ def main_function(cls, recording, peaks, params):
         # SVD for time compression
         few_peaks = select_peaks(peaks, recording=recording, method="uniform", n_peaks=10000, margin=(nbefore, nafter))
         few_wfs = extract_waveform_at_max_channel(
-            recording, few_peaks, ms_before=ms_before, ms_after=ms_after, **params["job_kwargs"]
+            recording, few_peaks, ms_before=ms_before, ms_after=ms_after, **job_kwargs
         )
 
         wfs = few_wfs[:, :, 0]
@@ -141,7 +141,7 @@ def main_function(cls, recording, peaks, params):
             all_pc_data = run_node_pipeline(
                 recording,
                 pipeline_nodes,
-                params["job_kwargs"],
+                job_kwargs,
                 job_name="extracting features",
             )
 
@@ -176,7 +176,7 @@ def main_function(cls, recording, peaks, params):
             _ = run_node_pipeline(
                 recording,
                 pipeline_nodes,
-                params["job_kwargs"],
+                job_kwargs,
                 job_name="extracting features",
                 gather_mode="npy",
                 gather_kwargs=dict(exist_ok=True),
diff --git a/src/spikeinterface/sortingcomponents/matching/circus.py b/src/spikeinterface/sortingcomponents/matching/circus.py
index d1b2139c5b..3b97f2dc6a 100644
--- a/src/spikeinterface/sortingcomponents/matching/circus.py
+++ b/src/spikeinterface/sortingcomponents/matching/circus.py
@@ -18,6 +18,15 @@
     ("segment_index", "int64"),
 ]
 
+try:
+    import torch
+    import torch.nn.functional as F
+
+    HAVE_TORCH = True
+    from torch.nn.functional import conv1d
+except ImportError:
+    HAVE_TORCH = False
+
 from .base import BaseTemplateMatching
 
 
@@ -43,9 +52,9 @@ def compress_templates(
 
     temporal, singular, spatial = np.linalg.svd(templates_array, full_matrices=False)
     # Keep only the strongest components
-    temporal = temporal[:, :, :approx_rank]
-    singular = singular[:, :approx_rank]
-    spatial = spatial[:, :approx_rank, :]
+    temporal = temporal[:, :, :approx_rank].astype(np.float32)
+    singular = singular[:, :approx_rank].astype(np.float32)
+    spatial = spatial[:, :approx_rank, :].astype(np.float32)
 
     if return_new_templates:
         templates_array = np.matmul(temporal * singular[:, np.newaxis, :], spatial)
@@ -107,18 +116,22 @@ class CircusOMPSVDPeeler(BaseTemplateMatching):
 
     Parameters
     ----------
-    amplitude: tuple
+    amplitude : tuple
         (Minimal, Maximal) amplitudes allowed for every template
-    max_failures: int
+    max_failures : int
         Stopping criteria of the OMP algorithm, as number of retry while updating amplitudes
-    sparse_kwargs: dict
+    sparse_kwargs : dict
         Parameters to extract a sparsity mask from the waveform_extractor, if not
         already sparse.
-    rank: int, default: 5
+    rank : int, default: 5
         Number of components used internally by the SVD
-    vicinity: int
+    vicinity : int
         Size of the area surrounding a spike to perform modification (expressed in terms
         of template temporal width)
+    engine : string in ["numpy", "torch", "auto"]. Default "auto"
+        The engine to use for the convolutions
+    torch_device : string in ["cpu", "cuda", None]. Default "cpu"
+        Controls torch device if the torch engine is selected
     -----
     """
 
@@ -148,6 +161,8 @@ def __init__(
         ignore_inds=[],
         vicinity=2,
         precomputed=None,
+        engine="numpy",
+        torch_device="cpu",
     ):
 
         BaseTemplateMatching.__init__(self, recording, templates, return_output=True, parents=None)
@@ -158,6 +173,19 @@ def __init__(
         self.nafter = templates.nafter
         self.sampling_frequency = recording.get_sampling_frequency()
         self.vicinity = vicinity * self.num_samples
+        assert engine in ["numpy", "torch", "auto"], "engine should be numpy, torch or auto"
+        if engine == "auto":
+            if HAVE_TORCH:
+                self.engine = "torch"
+            else:
+                self.engine = "numpy"
+        else:
+            if engine == "torch":
+                assert HAVE_TORCH, "please install torch to use the torch engine"
+            self.engine = engine
+
+        assert torch_device in ["cuda", "cpu", None]
+        self.torch_device = torch_device
 
         self.amplitudes = amplitudes
         self.stop_criteria = stop_criteria
@@ -183,6 +211,7 @@ def __init__(
             self.unit_overlaps_tables[i][self.unit_overlaps_indices[i]] = np.arange(len(self.unit_overlaps_indices[i]))
 
         self.margin = 2 * self.num_samples
+        self.is_pushed = False
 
     def _prepare_templates(self):
 
@@ -254,6 +283,14 @@ def _prepare_templates(self):
         self.temporal = np.moveaxis(self.temporal, [0, 1, 2], [1, 2, 0])
         self.singular = self.singular.T[:, :, np.newaxis]
 
+    def _push_to_torch(self):
+        if self.engine == "torch":
+            self.spatial = torch.as_tensor(self.spatial, device=self.torch_device)
+            self.singular = torch.as_tensor(self.singular, device=self.torch_device)
+            self.temporal = torch.as_tensor(self.temporal.copy(), device=self.torch_device).swapaxes(0, 1)
+            self.temporal = torch.flip(self.temporal, (2,))
+        self.is_pushed = True
+
     def get_extra_outputs(self):
         output = {}
         for key in self._more_output_keys:
@@ -268,15 +305,15 @@ def compute_matching(self, traces, start_frame, end_frame, segment_index):
         import scipy
         from scipy import ndimage
 
-        (potrs,) = scipy.linalg.get_lapack_funcs(("potrs",), dtype=np.float32)
+        if not self.is_pushed:
+            self._push_to_torch()
 
+        (potrs,) = scipy.linalg.get_lapack_funcs(("potrs",), dtype=np.float32)
         (nrm2,) = scipy.linalg.get_blas_funcs(("nrm2",), dtype=np.float32)
 
-        overlaps_array = self.overlaps
-
         omp_tol = np.finfo(np.float32).eps
-        num_samples = self.nafter + self.nbefore
-        neighbor_window = num_samples - 1
+        neighbor_window = self.num_samples - 1
+
         if isinstance(self.amplitudes, list):
             min_amplitude, max_amplitude = self.amplitudes
         else:
@@ -284,27 +321,36 @@ def compute_matching(self, traces, start_frame, end_frame, segment_index):
             min_amplitude = min_amplitude[:, np.newaxis]
             max_amplitude = max_amplitude[:, np.newaxis]
 
-        num_timesteps = len(traces)
+        if self.engine == "torch":
+            blank = np.zeros((neighbor_window, self.num_channels), dtype=np.float32)
+            traces = np.vstack((blank, traces, blank))
+            num_timesteps = traces.shape[0]
+            torch_traces = torch.as_tensor(traces.T[np.newaxis, :, :], device=self.torch_device)
+            num_templates, num_channels = self.temporal.shape[0], self.temporal.shape[1]
+            spatially_filtered_data = torch.matmul(self.spatial, torch_traces)
+            scaled_filtered_data = (spatially_filtered_data * self.singular).swapaxes(0, 1)
+            scaled_filtered_data_ = scaled_filtered_data.reshape(1, num_templates * num_channels, num_timesteps)
+            scalar_products = conv1d(scaled_filtered_data_, self.temporal, groups=num_templates, padding="valid")
+            scalar_products = scalar_products.cpu().numpy()[0, :, self.num_samples - 1 : -neighbor_window]
+        else:
+            num_timesteps = traces.shape[0]
+            num_peaks = num_timesteps - neighbor_window
+            conv_shape = (self.num_templates, num_peaks)
+            scalar_products = np.zeros(conv_shape, dtype=np.float32)
+            # Filter using overlap-and-add convolution
+            spatially_filtered_data = np.matmul(self.spatial, traces.T[np.newaxis, :, :])
+            scaled_filtered_data = spatially_filtered_data * self.singular
+            from scipy import signal
 
-        num_peaks = num_timesteps - num_samples + 1
-        conv_shape = (self.num_templates, num_peaks)
-        scalar_products = np.zeros(conv_shape, dtype=np.float32)
+            objective_by_rank = signal.oaconvolve(scaled_filtered_data, self.temporal, axes=2, mode="valid")
+            scalar_products += np.sum(objective_by_rank, axis=0)
+
+        num_peaks = scalar_products.shape[1]
 
         # Filter using overlap-and-add convolution
         if len(self.ignore_inds) > 0:
-            not_ignored = ~np.isin(np.arange(self.num_templates), self.ignore_inds)
-            spatially_filtered_data = np.matmul(self.spatial[:, not_ignored, :], traces.T[np.newaxis, :, :])
-            scaled_filtered_data = spatially_filtered_data * self.singular[:, not_ignored, :]
-            objective_by_rank = scipy.signal.oaconvolve(
-                scaled_filtered_data, self.temporal[:, not_ignored, :], axes=2, mode="valid"
-            )
-            scalar_products[not_ignored] += np.sum(objective_by_rank, axis=0)
             scalar_products[self.ignore_inds] = -np.inf
-        else:
-            spatially_filtered_data = np.matmul(self.spatial, traces.T[np.newaxis, :, :])
-            scaled_filtered_data = spatially_filtered_data * self.singular
-            objective_by_rank = scipy.signal.oaconvolve(scaled_filtered_data, self.temporal, axes=2, mode="valid")
-            scalar_products += np.sum(objective_by_rank, axis=0)
+            not_ignored = ~np.isin(np.arange(self.num_templates), self.ignore_inds)
 
         num_spikes = 0
 
@@ -322,7 +368,7 @@ def compute_matching(self, traces, start_frame, end_frame, segment_index):
         is_in_vicinity = np.zeros(0, dtype=np.int32)
 
         if self.stop_criteria == "omp_min_sps":
-            stop_criteria = self.omp_min_sps * np.maximum(self.norms, np.sqrt(self.num_channels * num_samples))
+            stop_criteria = self.omp_min_sps * np.maximum(self.norms, np.sqrt(self.num_channels * self.num_samples))
         elif self.stop_criteria == "max_failures":
             num_valids = 0
             nb_failures = self.max_failures
@@ -354,11 +400,11 @@ def compute_matching(self, traces, start_frame, end_frame, segment_index):
 
                 if num_selection > 0:
                     delta_t = selection[1] - peak_index
-                    idx = np.flatnonzero((delta_t < num_samples) & (delta_t > -num_samples))
+                    idx = np.flatnonzero((delta_t < self.num_samples) & (delta_t > -self.num_samples))
                     myline = neighbor_window + delta_t[idx]
                     myindices = selection[0, idx]
 
-                    local_overlaps = overlaps_array[best_cluster_ind]
+                    local_overlaps = self.overlaps[best_cluster_ind]
                     overlapping_templates = self.unit_overlaps_indices[best_cluster_ind]
                     table = self.unit_overlaps_tables[best_cluster_ind]
 
@@ -436,10 +482,10 @@ def compute_matching(self, traces, start_frame, end_frame, segment_index):
                 for i in modified:
                     tmp_best, tmp_peak = sub_selection[:, i]
                     diff_amp = diff_amplitudes[i] * self.norms[tmp_best]
-                    local_overlaps = overlaps_array[tmp_best]
+                    local_overlaps = self.overlaps[tmp_best]
                     overlapping_templates = self.units_overlaps[tmp_best]
                     tmp = tmp_peak - neighbor_window
-                    idx = [max(0, tmp), min(num_peaks, tmp_peak + num_samples)]
+                    idx = [max(0, tmp), min(num_peaks, tmp_peak + self.num_samples)]
                     tdx = [idx[0] - tmp, idx[1] - tmp]
                     to_add = diff_amp * local_overlaps[:, tdx[0] : tdx[1]]
                     scalar_products[overlapping_templates, idx[0] : idx[1]] -= to_add
@@ -500,27 +546,27 @@ class CircusPeeler(BaseTemplateMatching):
 
     Parameters
     ----------
-    peak_sign: str
+    peak_sign : str
         Sign of the peak (neg, pos, or both)
-    exclude_sweep_ms: float
+    exclude_sweep_ms : float
         The number of samples before/after to classify a peak (should be low)
-    jitter: int
+    jitter : int
         The number of samples considered before/after every peak to search for
         matches
-    detect_threshold: int
+    detect_threshold : int
         The detection threshold
-    noise_levels: array
+    noise_levels : array
         The noise levels, for every channels
-    random_chunk_kwargs: dict
+    random_chunk_kwargs : dict
         Parameters for computing noise levels, if not provided (sub optimal)
-    max_amplitude: float
+    max_amplitude : float
         Maximal amplitude allowed for every template
-    min_amplitude: float
+    min_amplitude : float
         Minimal amplitude allowed for every template
-    use_sparse_matrix_threshold: float
+    use_sparse_matrix_threshold : float
         If density of the templates is below a given threshold, sparse matrix
         are used (memory efficient)
-    sparse_kwargs: dict
+    sparse_kwargs : dict
         Parameters to extract a sparsity mask from the waveform_extractor, if not
         already sparse.
     -----
diff --git a/src/spikeinterface/sortingcomponents/matching/wobble.py b/src/spikeinterface/sortingcomponents/matching/wobble.py
index 3099448b11..59e171fe52 100644
--- a/src/spikeinterface/sortingcomponents/matching/wobble.py
+++ b/src/spikeinterface/sortingcomponents/matching/wobble.py
@@ -8,6 +8,15 @@
 from .base import BaseTemplateMatching, _base_matching_dtype
 from spikeinterface.core.template import Templates
 
+try:
+    import torch
+    import torch.nn.functional as F
+
+    HAVE_TORCH = True
+    from torch.nn.functional import conv1d
+except ImportError:
+    HAVE_TORCH = False
+
 
 @dataclass
 class WobbleParameters:
@@ -41,6 +50,10 @@ class WobbleParameters:
         Maximum value for ampltiude scaling of templates.
     scale_amplitudes : bool
         If True, scale amplitudes of templates to match spikes.
+    engine : string in ["numpy", "torch", "auto"]. Default "auto"
+        The engine to use for the convolutions
+    torch_device : string in ["cpu", "cuda", None]. Default "cpu"
+        Controls torch device if the torch engine is selected
 
     Notes
     -----
@@ -62,6 +75,8 @@ class WobbleParameters:
     scale_min: float = 0
     scale_max: float = np.inf
     scale_amplitudes: bool = False
+    engine: str = "numpy"
+    torch_device: str = "cpu"
 
     def __post_init__(self):
         assert self.amplitude_variance >= 0, "amplitude_variance must be a non-negative scalar"
@@ -344,6 +359,8 @@ def __init__(
         parents=None,
         templates=None,
         parameters={},
+        engine="numpy",
+        torch_device="cpu",
     ):
 
         BaseTemplateMatching.__init__(self, recording, templates, return_output=True, parents=None)
@@ -352,6 +369,21 @@ def __init__(
 
         # Aggregate useful parameters/variables for handy access in downstream functions
         params = WobbleParameters(**parameters)
+
+        assert engine in ["numpy", "torch", "auto"], "engine should be numpy, torch or auto"
+        if engine == "auto":
+            if HAVE_TORCH:
+                self.engine = "torch"
+            else:
+                self.engine = "numpy"
+        else:
+            if engine == "torch":
+                assert HAVE_TORCH, "please install torch to use the torch engine"
+            self.engine = engine
+
+        assert torch_device in ["cuda", "cpu", None]
+        self.torch_device = torch_device
+
         template_meta = TemplateMetadata.from_parameters_and_templates(params, templates_array)
         if not templates.are_templates_sparse():
             sparsity = WobbleSparsity.from_parameters_and_templates(params, templates_array)
@@ -366,13 +398,21 @@ def __init__(
         pairwise_convolution = convolve_templates(
             compressed_templates, params.jitter_factor, params.approx_rank, template_meta.jittered_indices, sparsity
         )
+
         norm_squared = compute_template_norm(sparsity.visible_channels, templates_array)
+
+        spatial = np.moveaxis(spatial, [0, 1, 2], [1, 0, 2])
+        temporal = np.moveaxis(temporal, [0, 1, 2], [1, 2, 0])
+        singular = singular.T[:, :, np.newaxis]
+
+        compressed_templates = (temporal, singular, spatial, temporal_jittered)
         template_data = TemplateData(
             compressed_templates=compressed_templates,
             pairwise_convolution=pairwise_convolution,
             norm_squared=norm_squared,
         )
 
+        self.is_pushed = False
         self.params = params
         self.template_meta = template_meta
         self.sparsity = sparsity
@@ -384,11 +424,24 @@ def __init__(
         # self.margin = int(buffer_ms*1e-3 * recording.sampling_frequency)
         self.margin = 300  # To ensure equivalence with spike-psvae version of the algorithm
 
+    def _push_to_torch(self):
+        if self.engine == "torch":
+            temporal, singular, spatial, temporal_jittered = self.template_data.compressed_templates
+            spatial = torch.as_tensor(spatial, device=self.torch_device)
+            singular = torch.as_tensor(singular, device=self.torch_device)
+            temporal = torch.as_tensor(temporal.copy(), device=self.torch_device).swapaxes(0, 1)
+            temporal = torch.flip(temporal, (2,))
+            self.template_data.compressed_templates = (temporal, singular, spatial, temporal_jittered)
+        self.is_pushed = True
+
     def get_trace_margin(self):
         return self.margin
 
     def compute_matching(self, traces, start_frame, end_frame, segment_index):
 
+        if not self.is_pushed:
+            self._push_to_torch()
+
         # Unpack method_kwargs
         # nbefore, nafter = method_kwargs["nbefore"], method_kwargs["nafter"]
         # template_meta = method_kwargs["template_meta"]
@@ -400,7 +453,9 @@ def compute_matching(self, traces, start_frame, end_frame, segment_index):
         assert traces.dtype == np.float32, "traces must be specified as np.float32"
 
         # Compute objective
-        objective = compute_objective(traces, self.template_data, self.params.approx_rank)
+        objective = compute_objective(
+            traces, self.template_data, self.params.approx_rank, self.engine, self.torch_device
+        )
         objective_normalized = 2 * objective - self.template_data.norm_squared[:, np.newaxis]
 
         # Compute spike train
@@ -786,10 +841,11 @@ def compress_templates(templates, approx_rank) -> tuple[np.ndarray, np.ndarray,
     temporal, singular, spatial = np.linalg.svd(templates, full_matrices=False)
 
     # Keep only the strongest components
-    temporal = temporal[:, :, :approx_rank]
+    temporal = temporal[:, :, :approx_rank].astype(np.float32)
     temporal = np.flip(temporal, axis=1)
-    singular = singular[:, :approx_rank]
-    spatial = spatial[:, :approx_rank, :]
+    singular = singular[:, :approx_rank].astype(np.float32)
+    spatial = spatial[:, :approx_rank, :].astype(np.float32)
+
     return temporal, singular, spatial
 
 
@@ -827,7 +883,6 @@ def upsample_and_jitter(temporal, jitter_factor, num_samples):
 
     shape_temporal_jittered = (-1, num_samples, approx_rank)
     temporal_jittered = np.reshape(temporal_jittered[:, shifted_index, :], shape_temporal_jittered)
-
     temporal_jittered = np.flip(temporal_jittered, axis=1)
     return temporal_jittered
 
@@ -889,7 +944,7 @@ def convolve_templates(compressed_templates, jitter_factor, approx_rank, jittere
     return pairwise_convolution
 
 
-def compute_objective(traces, template_data, approx_rank) -> np.ndarray:
+def compute_objective(traces, template_data, approx_rank, engine="numpy", torch_device=None) -> np.ndarray:
     """Compute objective by convolving templates with voltage traces.
 
     Parameters
@@ -898,31 +953,39 @@ def compute_objective(traces, template_data, approx_rank) -> np.ndarray:
         Voltage traces for a chunk of the recording.
     template_data : TemplateData
         Dataclass object for aggregating template data together.
-    approx_rank : int
-        Rank of the compressed template matrices.
 
     Returns
     -------
     objective : ndarray (template_meta.num_templates, traces.shape[0]+template_meta.num_samples-1)
             Template matching objective for each template.
     """
-    temporal, singular, spatial, temporal_jittered = template_data.compressed_templates
-    num_templates = temporal.shape[0]
-    num_samples = temporal.shape[1]
-    objective_len = get_convolution_len(traces.shape[0], num_samples)
-    conv_shape = (num_templates, objective_len)
-    objective = np.zeros(conv_shape, dtype=np.float32)
-    spatial_filters = np.moveaxis(spatial[:, :approx_rank, :], [0, 1, 2], [1, 0, 2])
-    temporal_filters = np.moveaxis(temporal[:, :, :approx_rank], [0, 1, 2], [1, 2, 0])
-    singular_filters = singular.T[:, :, np.newaxis]
-
-    # Filter using overlap-and-add convolution
-    spatially_filtered_data = np.matmul(spatial_filters, traces.T[np.newaxis, :, :])
-    scaled_filtered_data = spatially_filtered_data * singular_filters
-    from scipy import signal
+    temporal, singular, spatial, _ = template_data.compressed_templates
+    if engine == "torch":
+        nt = temporal.shape[2] - 1
+        num_channels = traces.shape[1]
+        blank = np.zeros((nt, num_channels), dtype=np.float32)
+        traces = np.vstack((blank, traces, blank))
+        torch_traces = torch.as_tensor(traces.T[None, :, :], device=torch_device)
+        num_templates, num_channels = temporal.shape[0], temporal.shape[1]
+        num_timesteps = torch_traces.shape[2]
+        spatially_filtered_data = torch.matmul(spatial, torch_traces)
+        scaled_filtered_data = (spatially_filtered_data * singular).swapaxes(0, 1)
+        scaled_filtered_data_ = scaled_filtered_data.reshape(1, num_templates * num_channels, num_timesteps)
+        objective = conv1d(scaled_filtered_data_, temporal, groups=num_templates, padding="valid")
+        objective = objective.cpu().numpy()[0, :, :]
+    elif engine == "numpy":
+        num_channels, num_templates = temporal.shape[0], temporal.shape[1]
+        num_timesteps = temporal.shape[2]
+        objective_len = get_convolution_len(traces.shape[0], num_timesteps)
+        conv_shape = (num_templates, objective_len)
+        objective = np.zeros(conv_shape, dtype=np.float32)
+        # Filter using overlap-and-add convolution
+        spatially_filtered_data = np.matmul(spatial, traces.T[np.newaxis, :, :])
+        scaled_filtered_data = spatially_filtered_data * singular
+        from scipy import signal
 
-    objective_by_rank = signal.oaconvolve(scaled_filtered_data, temporal_filters, axes=2, mode="full")
-    objective += np.sum(objective_by_rank, axis=0)
+        objective_by_rank = signal.oaconvolve(scaled_filtered_data, temporal, axes=2, mode="full")
+        objective += np.sum(objective_by_rank, axis=0)
     return objective
 
 
diff --git a/src/spikeinterface/sortingcomponents/peak_detection.py b/src/spikeinterface/sortingcomponents/peak_detection.py
index 134481289e..5b1d33b334 100644
--- a/src/spikeinterface/sortingcomponents/peak_detection.py
+++ b/src/spikeinterface/sortingcomponents/peak_detection.py
@@ -603,13 +603,13 @@ class DetectPeakMatchedFiltering(PeakDetector):
     params_doc = (
         DetectPeakByChannel.params_doc
         + """
-    radius_um: float
+    radius_um : float
         The radius to use to select neighbour channels for locally exclusive detection.
-    prototype: array
+    prototype : array
         The canonical waveform of action potentials
-    rank : int (default 1)
-        The rank for SVD convolution of spatiotemporal templates with the traces
-    weight_method: dict
+    ms_before : float
+        The time in ms before the maximial value of the absolute prototype
+    weight_method : dict
         Parameter that should be provided to the get_convolution_weights() function
         in order to know how to estimate the positions. One argument is mode that could
         be either gaussian_2d (KS like) or exponential_3d (default)
@@ -625,7 +625,6 @@ def __init__(
         detect_threshold=5,
         exclude_sweep_ms=0.1,
         radius_um=50,
-        rank=1,
         noise_levels=None,
         random_chunk_kwargs={"num_chunks_per_segment": 5},
         weight_method={},
diff --git a/src/spikeinterface/sortingcomponents/tests/test_wobble.py b/src/spikeinterface/sortingcomponents/tests/test_wobble.py
index d6d1e1e0b9..0d46b790ad 100644
--- a/src/spikeinterface/sortingcomponents/tests/test_wobble.py
+++ b/src/spikeinterface/sortingcomponents/tests/test_wobble.py
@@ -44,7 +44,7 @@ def test_compress_templates():
         elif test_case == "num_channels == num_samples":
             num_channels = rng.integers(1, 100)
             num_samples = num_channels
-        templates = rng.random((num_templates, num_samples, num_channels))
+        templates = rng.random((num_templates, num_samples, num_channels), dtype=np.float32)
         full_rank = np.minimum(num_samples, num_channels)
         approx_rank = rng.integers(1, full_rank)
 
@@ -66,15 +66,31 @@ def test_compress_templates():
         assert np.all(singular_full >= 0)
         # check that svd matrices are orthonormal if applicable
         if num_channels > num_samples:
-            assert np.allclose(np.matmul(temporal_full, temporal_full.transpose(0, 2, 1)), np.eye(num_samples))
+            assert np.allclose(
+                np.matmul(temporal_full, temporal_full.transpose(0, 2, 1)),
+                np.eye(num_samples, dtype=np.float32),
+                atol=1e-3,
+            )
         elif num_samples > num_channels:
-            assert np.allclose(np.matmul(spatial_full, spatial_full.transpose(0, 2, 1)), np.eye(num_channels))
+            assert np.allclose(
+                np.matmul(spatial_full, spatial_full.transpose(0, 2, 1)),
+                np.eye(num_channels, dtype=np.float32),
+                atol=1e-3,
+            )
         elif num_channels == num_samples:
-            assert np.allclose(np.matmul(temporal_full, temporal_full.transpose(0, 2, 1)), np.eye(num_samples))
-            assert np.allclose(np.matmul(spatial_full, spatial_full.transpose(0, 2, 1)), np.eye(num_channels))
+            assert np.allclose(
+                np.matmul(temporal_full, temporal_full.transpose(0, 2, 1)),
+                np.eye(num_samples, dtype=np.float32),
+                atol=1e-3,
+            )
+            assert np.allclose(
+                np.matmul(spatial_full, spatial_full.transpose(0, 2, 1)),
+                np.eye(num_channels, dtype=np.float32),
+                atol=1e-3,
+            )
             # check that the full rank svd matrices reconstruct the original templates
             reconstructed_templates = np.matmul(temporal_full * singular_full[:, np.newaxis, :], spatial_full)
-            assert np.allclose(reconstructed_templates, templates)
+            assert np.allclose(reconstructed_templates, templates, atol=1e-3)
 
 
 def test_upsample_and_jitter():
@@ -211,18 +227,33 @@ def test_compute_objective():
     approx_rank = rng.integers(1, num_samples)
     num_channels = rng.integers(1, 100)
     chunk_len = rng.integers(num_samples * 2, num_samples * 10)
-    traces = rng.random((chunk_len, num_channels))
+    traces = rng.random((chunk_len, num_channels), dtype=np.float32)
     temporal = rng.random((num_templates, num_samples, approx_rank))
     singular = rng.random((num_templates, approx_rank))
     spatial = rng.random((num_templates, approx_rank, num_channels))
-    compressed_templates = (temporal, singular, spatial, temporal)
+
+    spatial_transformed = np.moveaxis(spatial, [0, 1, 2], [1, 0, 2])
+    temporal_transformed = np.moveaxis(temporal, [0, 1, 2], [1, 2, 0])
+    singular_transformed = singular.T[:, :, np.newaxis]
+
+    compressed_templates_transformed = (
+        temporal_transformed,
+        singular_transformed,
+        spatial_transformed,
+        temporal_transformed,
+    )
     norm_squared = np.random.rand(num_templates)
+
+    template_data_transformed = wobble.TemplateData(
+        compressed_templates=compressed_templates_transformed, pairwise_convolution=[], norm_squared=norm_squared
+    )
+    # Act: run compute_objective
+    objective = wobble.compute_objective(traces, template_data_transformed, approx_rank, engine="numpy")
+
+    compressed_templates = (temporal, singular, spatial, temporal)
     template_data = wobble.TemplateData(
         compressed_templates=compressed_templates, pairwise_convolution=[], norm_squared=norm_squared
     )
-
-    # Act: run compute_objective
-    objective = wobble.compute_objective(traces, template_data, approx_rank)
     expected_objective = compute_objective_loopy(traces, template_data, approx_rank)
 
     # Assert: check shape and equivalence to expected_objective

From 49c7a92a57af5a65f7367b375567afaed6abda56 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Tue, 15 Oct 2024 13:46:36 +0200
Subject: [PATCH 101/344] Use existing sparsity for unit location + add
 location with max channel

---
 .../postprocessing/localization_tools.py      | 67 +++++++++++++++++--
 .../tests/test_unit_locations.py              |  1 +
 2 files changed, 64 insertions(+), 4 deletions(-)

diff --git a/src/spikeinterface/postprocessing/localization_tools.py b/src/spikeinterface/postprocessing/localization_tools.py
index e6278fc59f..59ca8cf7db 100644
--- a/src/spikeinterface/postprocessing/localization_tools.py
+++ b/src/spikeinterface/postprocessing/localization_tools.py
@@ -76,8 +76,12 @@ def compute_monopolar_triangulation(
     assert feature in ["ptp", "energy", "peak_voltage"], f"{feature} is not a valid feature"
 
     contact_locations = sorting_analyzer_or_templates.get_channel_locations()
+    
+    if sorting_analyzer_or_templates.sparsity is None:
+        sparsity = compute_sparsity(sorting_analyzer_or_templates, method="radius", radius_um=radius_um)
+    else:
+        sparsity = sorting_analyzer_or_templates.sparsity
 
-    sparsity = compute_sparsity(sorting_analyzer_or_templates, method="radius", radius_um=radius_um)
     templates = get_dense_templates_array(
         sorting_analyzer_or_templates, return_scaled=get_return_scaled(sorting_analyzer_or_templates)
     )
@@ -157,9 +161,13 @@ def compute_center_of_mass(
 
     assert feature in ["ptp", "mean", "energy", "peak_voltage"], f"{feature} is not a valid feature"
 
-    sparsity = compute_sparsity(
-        sorting_analyzer_or_templates, peak_sign=peak_sign, method="radius", radius_um=radius_um
-    )
+    if sorting_analyzer_or_templates.sparsity is None:
+        sparsity = compute_sparsity(
+            sorting_analyzer_or_templates, peak_sign=peak_sign, method="radius", radius_um=radius_um
+        )
+    else:
+        sparsity = sorting_analyzer_or_templates.sparsity
+    
     templates = get_dense_templates_array(
         sorting_analyzer_or_templates, return_scaled=get_return_scaled(sorting_analyzer_or_templates)
     )
@@ -650,8 +658,59 @@ def get_convolution_weights(
     enforce_decrease_shells = numba.jit(enforce_decrease_shells_data, nopython=True)
 
 
+
+def compute_location_max_channel(
+    templates_or_sorting_analyzer: SortingAnalyzer | Templates,
+    unit_ids=None,
+    peak_sign: "neg" | "pos" | "both" = "neg",
+    mode: "extremum" | "at_index" | "peak_to_peak" = "extremum",
+) -> np.ndarray:
+    """
+    Localize a unit using max channel.
+
+    This use inetrnally get_template_extremum_channel()
+
+
+    Parameters
+    ----------
+    templates_or_sorting_analyzer : SortingAnalyzer | Templates
+        A SortingAnalyzer or Templates object
+    unit_ids: str | int | None
+        A list of unit_id to restrict the computation
+    peak_sign :  "neg" | "pos" | "both"
+        Sign of the template to find extremum channels
+    mode : "extremum" | "at_index" | "peak_to_peak", default: "at_index"
+        Where the amplitude is computed
+        * "extremum" : take the peak value (max or min depending on `peak_sign`)
+        * "at_index" : take value at `nbefore` index
+        * "peak_to_peak" : take the peak-to-peak amplitude
+
+            Returns
+    -------
+    unit_location: np.ndarray
+        2d
+    """
+    extremum_channels_index = get_template_extremum_channel(
+        templates_or_sorting_analyzer,
+        peak_sign=peak_sign,
+        mode=mode,
+        outputs="index"
+    )
+    contact_locations = templates_or_sorting_analyzer.get_channel_locations()
+    if unit_ids is None:
+        unit_ids = templates_or_sorting_analyzer.unit_ids
+    else:
+        unit_ids = np.asarray(unit_ids)
+    unit_location = np.zeros((unit_ids.size, 2), dtype="float32")
+    for i, unit_id in enumerate(unit_ids):
+        unit_location[i, :] = contact_locations[extremum_channels_index[unit_id]]
+
+    return unit_location
+
+
 _unit_location_methods = {
     "center_of_mass": compute_center_of_mass,
     "grid_convolution": compute_grid_convolution,
     "monopolar_triangulation": compute_monopolar_triangulation,
+    "max_channel": compute_location_max_channel,
 }
diff --git a/src/spikeinterface/postprocessing/tests/test_unit_locations.py b/src/spikeinterface/postprocessing/tests/test_unit_locations.py
index c40a917a2b..545edb3497 100644
--- a/src/spikeinterface/postprocessing/tests/test_unit_locations.py
+++ b/src/spikeinterface/postprocessing/tests/test_unit_locations.py
@@ -13,6 +13,7 @@ class TestUnitLocationsExtension(AnalyzerExtensionCommonTestSuite):
             dict(method="grid_convolution", radius_um=150, weight_method={"mode": "gaussian_2d"}),
             dict(method="monopolar_triangulation", radius_um=150),
             dict(method="monopolar_triangulation", radius_um=150, optimizer="minimize_with_log_penality"),
+            dict(method="max_channel"),
         ],
     )
     def test_extension(self, params):

From 9cf9377a30b1733223037c58bb05709f0e76d5c8 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Tue, 15 Oct 2024 11:50:21 +0000
Subject: [PATCH 102/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 .../postprocessing/localization_tools.py               | 10 +++-------
 1 file changed, 3 insertions(+), 7 deletions(-)

diff --git a/src/spikeinterface/postprocessing/localization_tools.py b/src/spikeinterface/postprocessing/localization_tools.py
index 59ca8cf7db..4bf39e00e8 100644
--- a/src/spikeinterface/postprocessing/localization_tools.py
+++ b/src/spikeinterface/postprocessing/localization_tools.py
@@ -76,7 +76,7 @@ def compute_monopolar_triangulation(
     assert feature in ["ptp", "energy", "peak_voltage"], f"{feature} is not a valid feature"
 
     contact_locations = sorting_analyzer_or_templates.get_channel_locations()
-    
+
     if sorting_analyzer_or_templates.sparsity is None:
         sparsity = compute_sparsity(sorting_analyzer_or_templates, method="radius", radius_um=radius_um)
     else:
@@ -167,7 +167,7 @@ def compute_center_of_mass(
         )
     else:
         sparsity = sorting_analyzer_or_templates.sparsity
-    
+
     templates = get_dense_templates_array(
         sorting_analyzer_or_templates, return_scaled=get_return_scaled(sorting_analyzer_or_templates)
     )
@@ -658,7 +658,6 @@ def get_convolution_weights(
     enforce_decrease_shells = numba.jit(enforce_decrease_shells_data, nopython=True)
 
 
-
 def compute_location_max_channel(
     templates_or_sorting_analyzer: SortingAnalyzer | Templates,
     unit_ids=None,
@@ -691,10 +690,7 @@ def compute_location_max_channel(
         2d
     """
     extremum_channels_index = get_template_extremum_channel(
-        templates_or_sorting_analyzer,
-        peak_sign=peak_sign,
-        mode=mode,
-        outputs="index"
+        templates_or_sorting_analyzer, peak_sign=peak_sign, mode=mode, outputs="index"
     )
     contact_locations = templates_or_sorting_analyzer.get_channel_locations()
     if unit_ids is None:

From 3bf9b4884de04c89ffd0e89c647a9c151c27ed96 Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Tue, 15 Oct 2024 14:54:30 +0200
Subject: [PATCH 103/344] Fixing tests

---
 src/spikeinterface/curation/auto_merge.py | 46 ++++++++++++-----------
 1 file changed, 24 insertions(+), 22 deletions(-)

diff --git a/src/spikeinterface/curation/auto_merge.py b/src/spikeinterface/curation/auto_merge.py
index db3300f0d2..7a8404d076 100644
--- a/src/spikeinterface/curation/auto_merge.py
+++ b/src/spikeinterface/curation/auto_merge.py
@@ -38,7 +38,9 @@ def auto_merges(
     steps_params: dict = {
         "num_spikes": {"min_spikes": 100},
         "snr": {"min_snr": 2},
-        "remove_contaminated": {"contamination_thresh": 0.2, "refractory_period_ms": 1.0, "censored_period_ms": 0.3},
+        "remove_contaminated": {"contamination_thresh": 0.2, 
+                                "refractory_period_ms": 1.0, 
+                                "censored_period_ms": 0.3},
         "unit_locations": {"max_distance_um": 50},
         "correlogram": {
             "corr_diff_thresh": 0.16,
@@ -55,7 +57,9 @@ def auto_merges(
             "refractory_period_ms": 1.0,
             "censored_period_ms": 0.3,
         },
-        "quality_score": {"firing_contamination_balance": 2.5, "refractory_period_ms": 1.0, "censored_period_ms": 0.3},
+        "quality_score": {"firing_contamination_balance": 2.5, 
+                          "refractory_period_ms": 1.0, 
+                          "censored_period_ms": 0.3},
     },
     compute_needed_extensions: bool = True,
     extra_outputs: bool = False,
@@ -203,21 +207,6 @@ def auto_merges(
         # To avoid erasing the extensions of the user
         sorting_analyzer = sorting_analyzer.copy()
 
-    for step in steps:
-        if step in _required_extensions:
-            for ext in _required_extensions[step]:
-                if compute_needed_extensions:
-                    if step in _templates_needed:
-                        template_ext = sorting_analyzer.get_extension("templates")
-                        if template_ext is None:
-                            sorting_analyzer.compute(["random_spikes", "templates"], **job_kwargs)
-                    params = eval(f"{step}_kwargs")
-                    params = params.get(ext, dict())
-                    sorting_analyzer.compute(ext, **params, **job_kwargs)
-                else:
-                    if not sorting_analyzer.has_extension(ext):
-                        raise ValueError(f"{step} requires {ext} extension")
-
     n = unit_ids.size
     pair_mask = np.triu(np.arange(n)) > 0
     outs = dict()
@@ -225,7 +214,20 @@ def auto_merges(
     for step in steps:
 
         assert step in all_steps, f"{step} is not a valid step"
-        params = steps_params.get(step, {})
+
+        if step in _required_extensions:
+            for ext in _required_extensions[step]:
+                if compute_needed_extensions and step in _templates_needed:
+                    template_ext = sorting_analyzer.get_extension("templates")
+                    if template_ext is None:
+                        sorting_analyzer.compute(["random_spikes", "templates"], **job_kwargs)
+                    print(f"Extension {ext} is computed with default params")
+                    sorting_analyzer.compute(ext, **job_kwargs)
+                elif not compute_needed_extensions and not sorting_analyzer.has_extension(ext):
+                    raise ValueError(f"{step} requires {ext} extension")
+
+
+        params = steps_params.get(step, dict())
 
         # STEP : remove units with too few spikes
         if step == "num_spikes":
@@ -240,7 +242,7 @@ def auto_merges(
         elif step == "snr":
             qm_ext = sorting_analyzer.get_extension("quality_metrics")
             if qm_ext is None:
-                sorting_analyzer.compute(["noise_levels"], **job_kwargs)
+                sorting_analyzer.compute("noise_levels", **job_kwargs)
                 sorting_analyzer.compute("quality_metrics", metric_names=["snr"], **job_kwargs)
                 qm_ext = sorting_analyzer.get_extension("quality_metrics")
 
@@ -505,10 +507,10 @@ def get_potential_auto_merge(
         sorting_analyzer,
         preset,
         resolve_graph,
-        step_params={
+        steps_params={
             "num_spikes": {"min_spikes": min_spikes},
-            "snr_kwargs": {"min_snr": min_snr},
-            "remove_contaminated_kwargs": {
+            "snr": {"min_snr": min_snr},
+            "remove_contaminated": {
                 "contamination_thresh": contamination_thresh,
                 "refractory_period_ms": refractory_period_ms,
                 "censored_period_ms": censored_period_ms,

From 3df19c2e11117e9b69be4416bdb1123637ce63e8 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Tue, 15 Oct 2024 12:55:03 +0000
Subject: [PATCH 104/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/curation/auto_merge.py | 9 ++-------
 1 file changed, 2 insertions(+), 7 deletions(-)

diff --git a/src/spikeinterface/curation/auto_merge.py b/src/spikeinterface/curation/auto_merge.py
index 7a8404d076..d38b717bc8 100644
--- a/src/spikeinterface/curation/auto_merge.py
+++ b/src/spikeinterface/curation/auto_merge.py
@@ -38,9 +38,7 @@ def auto_merges(
     steps_params: dict = {
         "num_spikes": {"min_spikes": 100},
         "snr": {"min_snr": 2},
-        "remove_contaminated": {"contamination_thresh": 0.2, 
-                                "refractory_period_ms": 1.0, 
-                                "censored_period_ms": 0.3},
+        "remove_contaminated": {"contamination_thresh": 0.2, "refractory_period_ms": 1.0, "censored_period_ms": 0.3},
         "unit_locations": {"max_distance_um": 50},
         "correlogram": {
             "corr_diff_thresh": 0.16,
@@ -57,9 +55,7 @@ def auto_merges(
             "refractory_period_ms": 1.0,
             "censored_period_ms": 0.3,
         },
-        "quality_score": {"firing_contamination_balance": 2.5, 
-                          "refractory_period_ms": 1.0, 
-                          "censored_period_ms": 0.3},
+        "quality_score": {"firing_contamination_balance": 2.5, "refractory_period_ms": 1.0, "censored_period_ms": 0.3},
     },
     compute_needed_extensions: bool = True,
     extra_outputs: bool = False,
@@ -226,7 +222,6 @@ def auto_merges(
                 elif not compute_needed_extensions and not sorting_analyzer.has_extension(ext):
                     raise ValueError(f"{step} requires {ext} extension")
 
-
         params = steps_params.get(step, dict())
 
         # STEP : remove units with too few spikes

From 51edfece2f8ef041774bd2b27582021431e0f93d Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Tue, 15 Oct 2024 15:00:18 +0200
Subject: [PATCH 105/344] Fixing tests

---
 src/spikeinterface/curation/auto_merge.py | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/src/spikeinterface/curation/auto_merge.py b/src/spikeinterface/curation/auto_merge.py
index 7a8404d076..4966db4247 100644
--- a/src/spikeinterface/curation/auto_merge.py
+++ b/src/spikeinterface/curation/auto_merge.py
@@ -23,12 +23,12 @@
 _required_extensions = {
     "unit_locations": ["unit_locations"],
     "correlogram": ["correlograms"],
-    "min_snr": ["noise_levels", "templates"],
+    "snr": ["noise_levels", "templates"],
     "template_similarity": ["template_similarity"],
     "knn": ["spike_locations", "spike_amplitudes"],
 }
 
-_templates_needed = ["unit_locations", "min_snr", "template_similarity", "spike_locations", "spike_amplitudes"]
+_templates_needed = ["unit_locations", "snr", "template_similarity", "knn", "spike_amplitudes"]
 
 
 def auto_merges(
@@ -242,7 +242,6 @@ def auto_merges(
         elif step == "snr":
             qm_ext = sorting_analyzer.get_extension("quality_metrics")
             if qm_ext is None:
-                sorting_analyzer.compute("noise_levels", **job_kwargs)
                 sorting_analyzer.compute("quality_metrics", metric_names=["snr"], **job_kwargs)
                 qm_ext = sorting_analyzer.get_extension("quality_metrics")
 
@@ -537,7 +536,7 @@ def get_potential_auto_merge(
                 "censored_period_ms": censored_period_ms,
             },
         },
-        compute_needed_extensions=False,
+        compute_needed_extensions=True,
         extra_outputs=extra_outputs,
         steps=steps,
     )

From e2fb8cc6985ab51c4d599122ab9643071bd950b9 Mon Sep 17 00:00:00 2001
From: Heberto Mayorquin <h.mayorquin@gmail.com>
Date: Tue, 15 Oct 2024 14:31:25 -0600
Subject: [PATCH 106/344] cap python

---
 pyproject.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pyproject.toml b/pyproject.toml
index a43ab63c8e..e535747428 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -7,7 +7,7 @@ authors = [
 ]
 description = "Python toolkit for analysis, visualization, and comparison of spike sorting output"
 readme = "README.md"
-requires-python = ">=3.9,<4.0"
+requires-python = ">=3.9,<3.14"  # Only numpy 2.0 supported on python 3.12 for windows. We need to wait for fix on neo
 classifiers = [
     "Programming Language :: Python :: 3 :: Only",
     "License :: OSI Approved :: MIT License",

From 5347cba25a67566f0adc46b3dee8e24bfd1a545a Mon Sep 17 00:00:00 2001
From: Heberto Mayorquin <h.mayorquin@gmail.com>
Date: Tue, 15 Oct 2024 14:55:52 -0600
Subject: [PATCH 107/344] Update pyproject.toml

Co-authored-by: Zach McKenzie <92116279+zm711@users.noreply.github.com>
---
 pyproject.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pyproject.toml b/pyproject.toml
index e535747428..403988c980 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -7,7 +7,7 @@ authors = [
 ]
 description = "Python toolkit for analysis, visualization, and comparison of spike sorting output"
 readme = "README.md"
-requires-python = ">=3.9,<3.14"  # Only numpy 2.0 supported on python 3.12 for windows. We need to wait for fix on neo
+requires-python = ">=3.9,<3.13"  # Only numpy 2.0 supported on python 3.13 for windows. We need to wait for fix on neo
 classifiers = [
     "Programming Language :: Python :: 3 :: Only",
     "License :: OSI Approved :: MIT License",

From 146d34a58f29165307bd5e00af7e6c4fbb8d2306 Mon Sep 17 00:00:00 2001
From: zm711 <92116279+zm711@users.noreply.github.com>
Date: Tue, 15 Oct 2024 17:16:02 -0400
Subject: [PATCH 108/344] remove writing text_file

---
 src/spikeinterface/sorters/basesorter.py | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/src/spikeinterface/sorters/basesorter.py b/src/spikeinterface/sorters/basesorter.py
index 3502d27548..28948f81cc 100644
--- a/src/spikeinterface/sorters/basesorter.py
+++ b/src/spikeinterface/sorters/basesorter.py
@@ -145,9 +145,8 @@ def initialize_folder(cls, recording, output_folder, verbose, remove_existing_fo
         elif recording.check_serializability("pickle"):
             recording.dump(output_folder / "spikeinterface_recording.pickle", relative_to=output_folder)
         else:
-            # TODO: deprecate and finally remove this after 0.100
-            d = {"warning": "The recording is not serializable to json"}
-            rec_file.write_text(json.dumps(d, indent=4), encoding="utf8")
+            raise RuntimeError("This recording is not serializable and so can not be sorted. Consider `recording.save()` to save a "
+                               "compatible binary file.")
 
         return output_folder
 

From 5e832c9523a218a032c75d774c71c9188a8114ae Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Tue, 15 Oct 2024 21:19:30 +0000
Subject: [PATCH 109/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/sorters/basesorter.py | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/sorters/basesorter.py b/src/spikeinterface/sorters/basesorter.py
index 28948f81cc..c59fa29c05 100644
--- a/src/spikeinterface/sorters/basesorter.py
+++ b/src/spikeinterface/sorters/basesorter.py
@@ -145,8 +145,10 @@ def initialize_folder(cls, recording, output_folder, verbose, remove_existing_fo
         elif recording.check_serializability("pickle"):
             recording.dump(output_folder / "spikeinterface_recording.pickle", relative_to=output_folder)
         else:
-            raise RuntimeError("This recording is not serializable and so can not be sorted. Consider `recording.save()` to save a "
-                               "compatible binary file.")
+            raise RuntimeError(
+                "This recording is not serializable and so can not be sorted. Consider `recording.save()` to save a "
+                "compatible binary file."
+            )
 
         return output_folder
 

From c26b7199e086c9a3e48c99aa0495f540206e44a4 Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Wed, 16 Oct 2024 14:27:14 +0200
Subject: [PATCH 110/344] Default params

---
 src/spikeinterface/curation/auto_merge.py | 19 ++++++++++++-------
 1 file changed, 12 insertions(+), 7 deletions(-)

diff --git a/src/spikeinterface/curation/auto_merge.py b/src/spikeinterface/curation/auto_merge.py
index 03c8c131a9..39a155ec09 100644
--- a/src/spikeinterface/curation/auto_merge.py
+++ b/src/spikeinterface/curation/auto_merge.py
@@ -31,11 +31,7 @@
 _templates_needed = ["unit_locations", "snr", "template_similarity", "knn", "spike_amplitudes"]
 
 
-def auto_merges(
-    sorting_analyzer: SortingAnalyzer,
-    preset: str | None = "similarity_correlograms",
-    resolve_graph: bool = False,
-    steps_params: dict = {
+_default_step_params = {
         "num_spikes": {"min_spikes": 100},
         "snr": {"min_snr": 2},
         "remove_contaminated": {"contamination_thresh": 0.2, "refractory_period_ms": 1.0, "censored_period_ms": 0.3},
@@ -56,7 +52,14 @@ def auto_merges(
             "censored_period_ms": 0.3,
         },
         "quality_score": {"firing_contamination_balance": 2.5, "refractory_period_ms": 1.0, "censored_period_ms": 0.3},
-    },
+    }
+
+
+def auto_merges(
+    sorting_analyzer: SortingAnalyzer,
+    preset: str | None = "similarity_correlograms",
+    resolve_graph: bool = False,
+    steps_params: dict = None,
     compute_needed_extensions: bool = True,
     extra_outputs: bool = False,
     steps: list[str] | None = None,
@@ -222,7 +225,9 @@ def auto_merges(
                 elif not compute_needed_extensions and not sorting_analyzer.has_extension(ext):
                     raise ValueError(f"{step} requires {ext} extension")
 
-        params = steps_params.get(step, dict())
+        params = _default_step_params.get(step).copy()
+        if step in steps_params:
+            params.update(steps_params[step])
 
         # STEP : remove units with too few spikes
         if step == "num_spikes":

From 9692fb0fbaf294c323edc4bbaeb66d3347e2145c Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Wed, 16 Oct 2024 12:31:36 +0000
Subject: [PATCH 111/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/curation/auto_merge.py | 42 +++++++++++------------
 1 file changed, 21 insertions(+), 21 deletions(-)

diff --git a/src/spikeinterface/curation/auto_merge.py b/src/spikeinterface/curation/auto_merge.py
index 39a155ec09..e337b3d99d 100644
--- a/src/spikeinterface/curation/auto_merge.py
+++ b/src/spikeinterface/curation/auto_merge.py
@@ -32,27 +32,27 @@
 
 
 _default_step_params = {
-        "num_spikes": {"min_spikes": 100},
-        "snr": {"min_snr": 2},
-        "remove_contaminated": {"contamination_thresh": 0.2, "refractory_period_ms": 1.0, "censored_period_ms": 0.3},
-        "unit_locations": {"max_distance_um": 50},
-        "correlogram": {
-            "corr_diff_thresh": 0.16,
-            "censor_correlograms_ms": 0.3,
-            "sigma_smooth_ms": 0.6,
-            "adaptative_window_thresh": 0.5,
-        },
-        "template_similarity": {"template_diff_thresh": 0.25},
-        "presence_distance": {"presence_distance_thresh": 100},
-        "knn": {"k_nn": 10},
-        "cross_contamination": {
-            "cc_thresh": 0.1,
-            "p_value": 0.2,
-            "refractory_period_ms": 1.0,
-            "censored_period_ms": 0.3,
-        },
-        "quality_score": {"firing_contamination_balance": 2.5, "refractory_period_ms": 1.0, "censored_period_ms": 0.3},
-    }
+    "num_spikes": {"min_spikes": 100},
+    "snr": {"min_snr": 2},
+    "remove_contaminated": {"contamination_thresh": 0.2, "refractory_period_ms": 1.0, "censored_period_ms": 0.3},
+    "unit_locations": {"max_distance_um": 50},
+    "correlogram": {
+        "corr_diff_thresh": 0.16,
+        "censor_correlograms_ms": 0.3,
+        "sigma_smooth_ms": 0.6,
+        "adaptative_window_thresh": 0.5,
+    },
+    "template_similarity": {"template_diff_thresh": 0.25},
+    "presence_distance": {"presence_distance_thresh": 100},
+    "knn": {"k_nn": 10},
+    "cross_contamination": {
+        "cc_thresh": 0.1,
+        "p_value": 0.2,
+        "refractory_period_ms": 1.0,
+        "censored_period_ms": 0.3,
+    },
+    "quality_score": {"firing_contamination_balance": 2.5, "refractory_period_ms": 1.0, "censored_period_ms": 0.3},
+}
 
 
 def auto_merges(

From 3c277b3445dc05760d617c249fbc58a43b2d7ace Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Wed, 16 Oct 2024 14:35:24 +0200
Subject: [PATCH 112/344] Precomputing extensions

---
 src/spikeinterface/curation/auto_merge.py | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/src/spikeinterface/curation/auto_merge.py b/src/spikeinterface/curation/auto_merge.py
index 39a155ec09..fcf5fd8fd9 100644
--- a/src/spikeinterface/curation/auto_merge.py
+++ b/src/spikeinterface/curation/auto_merge.py
@@ -216,12 +216,15 @@ def auto_merges(
 
         if step in _required_extensions:
             for ext in _required_extensions[step]:
-                if compute_needed_extensions and step in _templates_needed:
-                    template_ext = sorting_analyzer.get_extension("templates")
-                    if template_ext is None:
-                        sorting_analyzer.compute(["random_spikes", "templates"], **job_kwargs)
-                    print(f"Extension {ext} is computed with default params")
-                    sorting_analyzer.compute(ext, **job_kwargs)
+                if compute_needed_extensions:
+                    if step in _templates_needed:
+                        template_ext = sorting_analyzer.get_extension("templates")
+                        if template_ext is None:
+                            sorting_analyzer.compute(["random_spikes", "templates"], **job_kwargs)
+                    res_ext = sorting_analyzer.get_extension(step)
+                    if res_ext is None:
+                        print(f"Extension {ext} is computed with default params. Precompute it with custom params if needed")
+                        sorting_analyzer.compute(ext, **job_kwargs)
                 elif not compute_needed_extensions and not sorting_analyzer.has_extension(ext):
                     raise ValueError(f"{step} requires {ext} extension")
 

From a3d1c2c4f49025e01bf17b13b76b931cd071e938 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Wed, 16 Oct 2024 12:35:58 +0000
Subject: [PATCH 113/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/curation/auto_merge.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/spikeinterface/curation/auto_merge.py b/src/spikeinterface/curation/auto_merge.py
index ffc4fea78b..86f47af0eb 100644
--- a/src/spikeinterface/curation/auto_merge.py
+++ b/src/spikeinterface/curation/auto_merge.py
@@ -223,7 +223,9 @@ def auto_merges(
                             sorting_analyzer.compute(["random_spikes", "templates"], **job_kwargs)
                     res_ext = sorting_analyzer.get_extension(step)
                     if res_ext is None:
-                        print(f"Extension {ext} is computed with default params. Precompute it with custom params if needed")
+                        print(
+                            f"Extension {ext} is computed with default params. Precompute it with custom params if needed"
+                        )
                         sorting_analyzer.compute(ext, **job_kwargs)
                 elif not compute_needed_extensions and not sorting_analyzer.has_extension(ext):
                     raise ValueError(f"{step} requires {ext} extension")

From d8ee9da3dbc5599dc2876b47933aab8b352fab71 Mon Sep 17 00:00:00 2001
From: rainsong <57996958+522848942@users.noreply.github.com>
Date: Mon, 21 Oct 2024 00:06:19 +0800
Subject: [PATCH 114/344] Update core.rst

doc error
---
 doc/modules/core.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/modules/core.rst b/doc/modules/core.rst
index 8aa1815a55..5df9a7e6b1 100644
--- a/doc/modules/core.rst
+++ b/doc/modules/core.rst
@@ -385,7 +385,7 @@ and merging unit groups.
 
     sorting_analyzer_select = sorting_analyzer.select_units(unit_ids=[0, 1, 2, 3])
     sorting_analyzer_remove = sorting_analyzer.remove_units(remove_unit_ids=[0])
-    sorting_analyzer_merge = sorting_analyzer.merge_units([0, 1], [2, 3])
+    sorting_analyzer_merge = sorting_analyzer.merge_units([[0, 1], [2, 3]])
 
 All computed extensions will be automatically propagated or merged when curating. Please refer to the
 :ref:`modules/curation:Curation module` documentation for more information.

From b62e02ba244c40f9eb86e2206bc844e2be339a2d Mon Sep 17 00:00:00 2001
From: chrishalcrow <57948917+chrishalcrow@users.noreply.github.com>
Date: Mon, 21 Oct 2024 10:39:37 +0100
Subject: [PATCH 115/344] export_report without waveforms

---
 src/spikeinterface/widgets/unit_summary.py | 44 +++++++++++++---------
 1 file changed, 26 insertions(+), 18 deletions(-)

diff --git a/src/spikeinterface/widgets/unit_summary.py b/src/spikeinterface/widgets/unit_summary.py
index 755e60ccbf..8aea6fd690 100644
--- a/src/spikeinterface/widgets/unit_summary.py
+++ b/src/spikeinterface/widgets/unit_summary.py
@@ -107,15 +107,18 @@ def plot_matplotlib(self, data_plot, **backend_kwargs):
         # and use custum grid spec
         fig = self.figure
         nrows = 2
-        ncols = 3
+        ncols = 2
         if sorting_analyzer.has_extension("correlograms") or sorting_analyzer.has_extension("spike_amplitudes"):
             ncols += 1
+        if sorting_analyzer.has_extension("waveforms"):
+            ncols += 1
         if sorting_analyzer.has_extension("spike_amplitudes"):
             nrows += 1
         gs = fig.add_gridspec(nrows, ncols)
+        col_counter = 0
 
         if sorting_analyzer.has_extension("unit_locations"):
-            ax1 = fig.add_subplot(gs[:2, 0])
+            ax1 = fig.add_subplot(gs[:2, col_counter])
             # UnitLocationsPlotter().do_plot(dp.plot_data_unit_locations, ax=ax1)
             w = UnitLocationsWidget(
                 sorting_analyzer,
@@ -126,6 +129,7 @@ def plot_matplotlib(self, data_plot, **backend_kwargs):
                 ax=ax1,
                 **unitlocationswidget_kwargs,
             )
+            col_counter = col_counter + 1
 
             unit_locations = sorting_analyzer.get_extension("unit_locations").get_data(outputs="by_unit")
             unit_location = unit_locations[unit_id]
@@ -136,12 +140,13 @@ def plot_matplotlib(self, data_plot, **backend_kwargs):
             ax1.set_xlabel(None)
             ax1.set_ylabel(None)
 
-        ax2 = fig.add_subplot(gs[:2, 1])
+        ax2 = fig.add_subplot(gs[:2, col_counter])
         w = UnitWaveformsWidget(
             sorting_analyzer,
             unit_ids=[unit_id],
             unit_colors=unit_colors,
             plot_templates=True,
+            plot_waveforms=sorting_analyzer.has_extension("waveforms"),
             same_axis=True,
             plot_legend=False,
             sparsity=sparsity,
@@ -149,24 +154,27 @@ def plot_matplotlib(self, data_plot, **backend_kwargs):
             ax=ax2,
             **unitwaveformswidget_kwargs,
         )
+        col_counter = col_counter + 1
 
         ax2.set_title(None)
 
-        ax3 = fig.add_subplot(gs[:2, 2])
-        UnitWaveformDensityMapWidget(
-            sorting_analyzer,
-            unit_ids=[unit_id],
-            unit_colors=unit_colors,
-            use_max_channel=True,
-            same_axis=False,
-            backend="matplotlib",
-            ax=ax3,
-            **unitwaveformdensitymapwidget_kwargs,
-        )
-        ax3.set_ylabel(None)
+        if sorting_analyzer.has_extension("waveforms"):
+            ax3 = fig.add_subplot(gs[:2, col_counter])
+            UnitWaveformDensityMapWidget(
+                sorting_analyzer,
+                unit_ids=[unit_id],
+                unit_colors=unit_colors,
+                use_max_channel=True,
+                same_axis=False,
+                backend="matplotlib",
+                ax=ax3,
+                **unitwaveformdensitymapwidget_kwargs,
+            )
+            ax3.set_ylabel(None)
+            col_counter = col_counter + 1
 
         if sorting_analyzer.has_extension("correlograms"):
-            ax4 = fig.add_subplot(gs[:2, 3])
+            ax4 = fig.add_subplot(gs[:2, col_counter])
             AutoCorrelogramsWidget(
                 sorting_analyzer,
                 unit_ids=[unit_id],
@@ -180,8 +188,8 @@ def plot_matplotlib(self, data_plot, **backend_kwargs):
             ax4.set_yticks([])
 
         if sorting_analyzer.has_extension("spike_amplitudes"):
-            ax5 = fig.add_subplot(gs[2, :3])
-            ax6 = fig.add_subplot(gs[2, 3])
+            ax5 = fig.add_subplot(gs[2, :col_counter])
+            ax6 = fig.add_subplot(gs[2, col_counter])
             axes = np.array([ax5, ax6])
             AmplitudesWidget(
                 sorting_analyzer,

From 0e5f50fdfb6b6ae35a9b06d814e811ac9bf833ee Mon Sep 17 00:00:00 2001
From: Garcia Samuel <sam.garcia.die@gmail.com>
Date: Mon, 21 Oct 2024 13:54:42 +0200
Subject: [PATCH 116/344] merci zach

Co-authored-by: Zach McKenzie <92116279+zm711@users.noreply.github.com>
---
 src/spikeinterface/postprocessing/localization_tools.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/postprocessing/localization_tools.py b/src/spikeinterface/postprocessing/localization_tools.py
index 4bf39e00e8..a17abea1eb 100644
--- a/src/spikeinterface/postprocessing/localization_tools.py
+++ b/src/spikeinterface/postprocessing/localization_tools.py
@@ -667,14 +667,14 @@ def compute_location_max_channel(
     """
     Localize a unit using max channel.
 
-    This use inetrnally get_template_extremum_channel()
+    This uses interrnally `get_template_extremum_channel()`
 
 
     Parameters
     ----------
     templates_or_sorting_analyzer : SortingAnalyzer | Templates
         A SortingAnalyzer or Templates object
-    unit_ids: str | int | None
+    unit_ids: list[str] | list[int] | None
         A list of unit_id to restrict the computation
     peak_sign :  "neg" | "pos" | "both"
         Sign of the template to find extremum channels

From 1411c6fdf9d89c68a205c1512b1dce9ce2a29c62 Mon Sep 17 00:00:00 2001
From: OlivierPeron <79974181+OlivierPeron@users.noreply.github.com>
Date: Mon, 21 Oct 2024 15:59:20 +0200
Subject: [PATCH 117/344] Loading templates

Loading templates whatever the operator
---
 src/spikeinterface/core/template_tools.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/spikeinterface/core/template_tools.py b/src/spikeinterface/core/template_tools.py
index 934b18ed49..769610ad2b 100644
--- a/src/spikeinterface/core/template_tools.py
+++ b/src/spikeinterface/core/template_tools.py
@@ -31,7 +31,8 @@ def get_dense_templates_array(one_object: Templates | SortingAnalyzer, return_sc
             )
         ext = one_object.get_extension("templates")
         if ext is not None:
-            templates_array = ext.data["average"]
+            templates_array = ext.data.get("average") or ext.data.get("median")
+            assert templates_array is not None, "Average or median templates have not been computed."
         else:
             raise ValueError("SortingAnalyzer need extension 'templates' to be computed to retrieve templates")
     else:

From 72357a68a25acc58c6634300d574e056a1e46857 Mon Sep 17 00:00:00 2001
From: OlivierPeron <79974181+OlivierPeron@users.noreply.github.com>
Date: Mon, 21 Oct 2024 16:22:52 +0200
Subject: [PATCH 118/344] Update src/spikeinterface/core/template_tools.py

Co-authored-by: Alessio Buccino <alejoe9187@gmail.com>
---
 src/spikeinterface/core/template_tools.py | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/core/template_tools.py b/src/spikeinterface/core/template_tools.py
index 769610ad2b..3c8663df70 100644
--- a/src/spikeinterface/core/template_tools.py
+++ b/src/spikeinterface/core/template_tools.py
@@ -31,8 +31,12 @@ def get_dense_templates_array(one_object: Templates | SortingAnalyzer, return_sc
             )
         ext = one_object.get_extension("templates")
         if ext is not None:
-            templates_array = ext.data.get("average") or ext.data.get("median")
-            assert templates_array is not None, "Average or median templates have not been computed."
+            if "average" in ext.data:
+                templates_array = ext.data.get("average")
+            elif "median" in ext.data:
+                templates_array = ext.data.get("median")
+            else:
+                raise ValueError("Average or median templates have not been computed.")
         else:
             raise ValueError("SortingAnalyzer need extension 'templates' to be computed to retrieve templates")
     else:

From ebc6164064c72490cc1b9f539b1b2eb5f0eae9ea Mon Sep 17 00:00:00 2001
From: Heberto Mayorquin <h.mayorquin@gmail.com>
Date: Mon, 21 Oct 2024 09:12:37 -0600
Subject: [PATCH 119/344] Update pyproject.toml

Co-authored-by: Zach McKenzie <92116279+zm711@users.noreply.github.com>
---
 pyproject.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pyproject.toml b/pyproject.toml
index 403988c980..fc09ad9198 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -7,7 +7,7 @@ authors = [
 ]
 description = "Python toolkit for analysis, visualization, and comparison of spike sorting output"
 readme = "README.md"
-requires-python = ">=3.9,<3.13"  # Only numpy 2.0 supported on python 3.13 for windows. We need to wait for fix on neo
+requires-python = ">=3.9,<3.13"  # Only numpy 2.1 supported on python 3.13 for windows. We need to wait for fix on neo
 classifiers = [
     "Programming Language :: Python :: 3 :: Only",
     "License :: OSI Approved :: MIT License",

From f4dd922447eac6d422e43093a5b93a8877df34be Mon Sep 17 00:00:00 2001
From: Zach McKenzie <92116279+zm711@users.noreply.github.com>
Date: Mon, 21 Oct 2024 12:44:26 -0400
Subject: [PATCH 120/344] better error message (#3479)

---
 src/spikeinterface/core/baserecordingsnippets.py | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/core/baserecordingsnippets.py b/src/spikeinterface/core/baserecordingsnippets.py
index 310533c96b..2ec3664a45 100644
--- a/src/spikeinterface/core/baserecordingsnippets.py
+++ b/src/spikeinterface/core/baserecordingsnippets.py
@@ -172,8 +172,10 @@ def _set_probes(self, probe_or_probegroup, group_mode="by_probe", in_place=False
         number_of_device_channel_indices = np.max(list(device_channel_indices) + [0])
         if number_of_device_channel_indices >= self.get_num_channels():
             error_msg = (
-                f"The given Probe have 'device_channel_indices' that do not match channel count \n"
-                f"{number_of_device_channel_indices} vs {self.get_num_channels()} \n"
+                f"The given Probe either has 'device_channel_indices' that does not match channel count \n"
+                f"{len(device_channel_indices)} vs {self.get_num_channels()} \n"
+                f"or it's max index {number_of_device_channel_indices} is the same as the number of channels {self.get_num_channels()} \n"
+                f"If using all channels remember that python is 0-indexed so max device_channel_index should be {self.get_num_channels() - 1} \n"
                 f"device_channel_indices are the following: {device_channel_indices} \n"
                 f"recording channels are the following: {self.get_channel_ids()} \n"
             )

From 0be00cf32fad46b1a55d7018ea051014644568ab Mon Sep 17 00:00:00 2001
From: Garcia Samuel <sam.garcia.die@gmail.com>
Date: Mon, 21 Oct 2024 18:47:14 +0200
Subject: [PATCH 121/344] Update
 src/spikeinterface/postprocessing/localization_tools.py

Co-authored-by: Alessio Buccino <alejoe9187@gmail.com>
---
 src/spikeinterface/postprocessing/localization_tools.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/postprocessing/localization_tools.py b/src/spikeinterface/postprocessing/localization_tools.py
index a17abea1eb..3372a34c98 100644
--- a/src/spikeinterface/postprocessing/localization_tools.py
+++ b/src/spikeinterface/postprocessing/localization_tools.py
@@ -667,7 +667,7 @@ def compute_location_max_channel(
     """
     Localize a unit using max channel.
 
-    This uses interrnally `get_template_extremum_channel()`
+    This uses internally `get_template_extremum_channel()`
 
 
     Parameters

From 0002edcbe99764fcf65edae405a2be59647691f1 Mon Sep 17 00:00:00 2001
From: Garcia Samuel <sam.garcia.die@gmail.com>
Date: Mon, 21 Oct 2024 18:47:23 +0200
Subject: [PATCH 122/344] Update
 src/spikeinterface/postprocessing/localization_tools.py

Co-authored-by: Alessio Buccino <alejoe9187@gmail.com>
---
 src/spikeinterface/postprocessing/localization_tools.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/postprocessing/localization_tools.py b/src/spikeinterface/postprocessing/localization_tools.py
index 3372a34c98..67d469f85c 100644
--- a/src/spikeinterface/postprocessing/localization_tools.py
+++ b/src/spikeinterface/postprocessing/localization_tools.py
@@ -686,7 +686,7 @@ def compute_location_max_channel(
 
             Returns
     -------
-    unit_location: np.ndarray
+    unit_locations: np.ndarray
         2d
     """
     extremum_channels_index = get_template_extremum_channel(

From b4e681d8524d119a86ba21fd9a19c5e6716c1ca0 Mon Sep 17 00:00:00 2001
From: Garcia Samuel <sam.garcia.die@gmail.com>
Date: Mon, 21 Oct 2024 18:47:33 +0200
Subject: [PATCH 123/344] Update
 src/spikeinterface/postprocessing/localization_tools.py

Co-authored-by: Alessio Buccino <alejoe9187@gmail.com>
---
 src/spikeinterface/postprocessing/localization_tools.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/spikeinterface/postprocessing/localization_tools.py b/src/spikeinterface/postprocessing/localization_tools.py
index 67d469f85c..a073b6c518 100644
--- a/src/spikeinterface/postprocessing/localization_tools.py
+++ b/src/spikeinterface/postprocessing/localization_tools.py
@@ -697,11 +697,11 @@ def compute_location_max_channel(
         unit_ids = templates_or_sorting_analyzer.unit_ids
     else:
         unit_ids = np.asarray(unit_ids)
-    unit_location = np.zeros((unit_ids.size, 2), dtype="float32")
+    unit_locations = np.zeros((unit_ids.size, 2), dtype="float32")
     for i, unit_id in enumerate(unit_ids):
-        unit_location[i, :] = contact_locations[extremum_channels_index[unit_id]]
+        unit_locations[i, :] = contact_locations[extremum_channels_index[unit_id]]
 
-    return unit_location
+    return unit_locations
 
 
 _unit_location_methods = {

From 55b50abdebf5f1e0aa0c00307d706588b1d9038d Mon Sep 17 00:00:00 2001
From: Garcia Samuel <sam.garcia.die@gmail.com>
Date: Mon, 21 Oct 2024 18:47:54 +0200
Subject: [PATCH 124/344] Update
 src/spikeinterface/postprocessing/localization_tools.py

Co-authored-by: Alessio Buccino <alejoe9187@gmail.com>
---
 src/spikeinterface/postprocessing/localization_tools.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/postprocessing/localization_tools.py b/src/spikeinterface/postprocessing/localization_tools.py
index a073b6c518..837b983059 100644
--- a/src/spikeinterface/postprocessing/localization_tools.py
+++ b/src/spikeinterface/postprocessing/localization_tools.py
@@ -684,7 +684,7 @@ def compute_location_max_channel(
         * "at_index" : take value at `nbefore` index
         * "peak_to_peak" : take the peak-to-peak amplitude
 
-            Returns
+    Returns
     -------
     unit_locations: np.ndarray
         2d

From c2f980c6bb40df45d411904dd5f58288fa7b8ad3 Mon Sep 17 00:00:00 2001
From: zm711 <92116279+zm711@users.noreply.github.com>
Date: Mon, 21 Oct 2024 14:28:20 -0400
Subject: [PATCH 125/344] typos

---
 doc/modules/curation.rst | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/doc/modules/curation.rst b/doc/modules/curation.rst
index d115b33e4a..d24fc810b0 100644
--- a/doc/modules/curation.rst
+++ b/doc/modules/curation.rst
@@ -88,7 +88,7 @@ The ``censored_period_ms`` parameter is the time window in milliseconds to consi
 The :py:func:`~spikeinterface.curation.remove_redundand_units` function removes
 redundant units from the sorting output. Redundant units are units that share over
 a certain percentage of spikes, by default 80%.
-The function can acto both on a ``BaseSorting`` or a ``SortingAnalyzer`` object.
+The function can act both on a ``BaseSorting`` or a ``SortingAnalyzer`` object.
 
 .. code-block:: python
 
@@ -102,13 +102,16 @@ The function can acto both on a ``BaseSorting`` or a ``SortingAnalyzer`` object.
     )
 
     # remove redundant units from SortingAnalyzer object
-    clean_sorting_analyzer = remove_redundant_units(
+    # note this returns a cleaned sorting
+    clean_sorting = remove_redundant_units(
         sorting_analyzer,
         duplicate_threshold=0.9,
         remove_strategy="min_shift"
     )
+    # in order to have a sorter with only the non-redundant units do:
+    clean_sorting_analyzer = sorting_analyzer.select_units(clean_sorting.unit_ids)
 
-We recommend usinf the ``SortingAnalyzer`` approach, since the ``min_shift`` strategy keeps
+We recommend using the ``SortingAnalyzer`` approach, since the ``min_shift`` strategy keeps
 the unit (among the redundant ones), with a better template alignment.
 
 

From 61ce0007476b9a1e80d69bdbbc42e70d8bcce626 Mon Sep 17 00:00:00 2001
From: zm711 <92116279+zm711@users.noreply.github.com>
Date: Mon, 21 Oct 2024 14:32:37 -0400
Subject: [PATCH 126/344] better comment

---
 doc/modules/curation.rst | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/doc/modules/curation.rst b/doc/modules/curation.rst
index d24fc810b0..37de992806 100644
--- a/doc/modules/curation.rst
+++ b/doc/modules/curation.rst
@@ -108,7 +108,9 @@ The function can act both on a ``BaseSorting`` or a ``SortingAnalyzer`` object.
         duplicate_threshold=0.9,
         remove_strategy="min_shift"
     )
-    # in order to have a sorter with only the non-redundant units do:
+    # in order to have a SortingAnalyer with only the non-redundant units one must
+    # select the designed units remembering to give format and folder if one wants
+    # a persistent SortingAnalyzer.
     clean_sorting_analyzer = sorting_analyzer.select_units(clean_sorting.unit_ids)
 
 We recommend using the ``SortingAnalyzer`` approach, since the ``min_shift`` strategy keeps

From 6527c9038c53e68c9355f32bd032ecc6824e59ca Mon Sep 17 00:00:00 2001
From: zm711 <92116279+zm711@users.noreply.github.com>
Date: Tue, 22 Oct 2024 15:36:44 -0400
Subject: [PATCH 127/344] fix dtype of quality metrics after merging

---
 .../quality_metric_calculator.py              |  6 ++++
 .../tests/test_quality_metric_calculator.py   | 28 +++++++++++++++++++
 2 files changed, 34 insertions(+)

diff --git a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
index b6a50d60f5..c16241710a 100644
--- a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
+++ b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
@@ -125,7 +125,13 @@ def _merge_extension_data(
         all_unit_ids = new_sorting_analyzer.unit_ids
         not_new_ids = all_unit_ids[~np.isin(all_unit_ids, new_unit_ids)]
 
+        # this creates a new metrics dictionary, but the dtype for everything will be
+        # object
         metrics = pd.DataFrame(index=all_unit_ids, columns=old_metrics.columns)
+        # we can iterate through the columns and convert them back to numbers with
+        # pandas.to_numeric. coerce allows us to keep the nan values.
+        for column in metrics.columns:
+            metrics[column] = pd.to_numeric(metrics[column], errors="coerce")
 
         metrics.loc[not_new_ids, :] = old_metrics.loc[not_new_ids, :]
         metrics.loc[new_unit_ids, :] = self._compute_metrics(
diff --git a/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py b/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py
index a6415c58e8..a34324da7e 100644
--- a/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py
+++ b/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py
@@ -48,6 +48,34 @@ def test_compute_quality_metrics(sorting_analyzer_simple):
     assert "isolation_distance" in metrics.columns
 
 
+def test_merging_quality_metrics(sorting_analyzer_simple):
+
+    sorting_analyzer = sorting_analyzer_simple
+
+    metrics = compute_quality_metrics(
+        sorting_analyzer,
+        metric_names=None,
+        qm_params=dict(isi_violation=dict(isi_threshold_ms=2)),
+        skip_pc_metrics=False,
+        seed=2205,
+    )
+
+    # sorting_analyzer_simple has ten units
+    new_sorting_analyzer = sorting_analyzer.merge([0, 1])
+
+    new_metrics = new_sorting_analyzer.get_extension("quality_metrics").get_data()
+
+    # we should copy over the metrics after merge
+    for column in metrics.columns:
+        assert column in new_metrics.columns
+
+    # 10 units vs 9 units
+    assert len(metrics.index) > len(new_metrics.index)
+
+    # dtype should be fine after merge
+    assert metrics["snr"].dtype == new_metrics["snr"].dtype
+
+
 def test_compute_quality_metrics_recordingless(sorting_analyzer_simple):
 
     sorting_analyzer = sorting_analyzer_simple

From 1e596f87be8e56a3abe1d6071b93adc6bbb50c07 Mon Sep 17 00:00:00 2001
From: zm711 <92116279+zm711@users.noreply.github.com>
Date: Tue, 22 Oct 2024 16:00:04 -0400
Subject: [PATCH 128/344] fix test

---
 .../qualitymetrics/tests/test_quality_metric_calculator.py  | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py b/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py
index a34324da7e..f4d37aafee 100644
--- a/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py
+++ b/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py
@@ -61,7 +61,7 @@ def test_merging_quality_metrics(sorting_analyzer_simple):
     )
 
     # sorting_analyzer_simple has ten units
-    new_sorting_analyzer = sorting_analyzer.merge([0, 1])
+    new_sorting_analyzer = sorting_analyzer.merge_units([[0, 1]])
 
     new_metrics = new_sorting_analyzer.get_extension("quality_metrics").get_data()
 
@@ -72,8 +72,8 @@ def test_merging_quality_metrics(sorting_analyzer_simple):
     # 10 units vs 9 units
     assert len(metrics.index) > len(new_metrics.index)
 
-    # dtype should be fine after merge
-    assert metrics["snr"].dtype == new_metrics["snr"].dtype
+    # dtype should be fine after merge but is cast from Float64->float64
+    assert np.float64 == new_metrics["snr"].dtype
 
 
 def test_compute_quality_metrics_recordingless(sorting_analyzer_simple):

From 1ce2f8dc411acadf7bdf6bdd537f616d448a536c Mon Sep 17 00:00:00 2001
From: Garcia Samuel <sam.garcia.die@gmail.com>
Date: Wed, 23 Oct 2024 14:58:41 +0200
Subject: [PATCH 129/344] merci alessio

Co-authored-by: Alessio Buccino <alejoe9187@gmail.com>
---
 src/spikeinterface/core/recording_tools.py | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/spikeinterface/core/recording_tools.py b/src/spikeinterface/core/recording_tools.py
index 01f541ddac..790511ad88 100644
--- a/src/spikeinterface/core/recording_tools.py
+++ b/src/spikeinterface/core/recording_tools.py
@@ -744,11 +744,11 @@ def get_noise_levels(
     You can use standard deviation with `method="std"`
 
     Internally it samples some chunk across segment.
-    And then, it use MAD estimator (more robust than STD) ot the STD on each chunk.
-    Finally the average on all MAD is performed.
+    And then, it uses the MAD estimator (more robust than STD) or the STD on each chunk.
+    Finally the average of all MAD/STD values is performed.
 
-    The result is cached in a property of the recording.
-    Next call on the same recording will use the cache unless force_recompute=True.
+    The result is cached in a property of the recording, so that the next call on the same
+    recording will use the cached result unless `force_recompute=True`.
 
     Parameters
     ----------

From b5bd2fb1f4459689e05893a0524a8dab3543b5e8 Mon Sep 17 00:00:00 2001
From: zm711 <92116279+zm711@users.noreply.github.com>
Date: Wed, 23 Oct 2024 09:21:01 -0400
Subject: [PATCH 130/344] add error messaging around use of get data in
 templates

---
 .../core/analyzer_extension_core.py             | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/core/analyzer_extension_core.py b/src/spikeinterface/core/analyzer_extension_core.py
index bc5de63d07..e0b267ae72 100644
--- a/src/spikeinterface/core/analyzer_extension_core.py
+++ b/src/spikeinterface/core/analyzer_extension_core.py
@@ -380,7 +380,12 @@ def _set_params(self, ms_before: float = 1.0, ms_after: float = 2.0, operators=N
         assert isinstance(operators, list)
         for operator in operators:
             if isinstance(operator, str):
-                assert operator in ("average", "std", "median", "mad")
+                if operator not in ("average", "std", "median", "mad"):
+                    error_msg = (
+                        f"You have entered an operator {operator} in your `operators` argument which is "
+                        f"not supported. Please use any of ['average', 'std', 'median', 'mad'] instead."
+                    )
+                    raise ValueError(error_msg)
             else:
                 assert isinstance(operator, (list, tuple))
                 assert len(operator) == 2
@@ -549,9 +554,17 @@ def _get_data(self, operator="average", percentile=None, outputs="numpy"):
         if operator != "percentile":
             key = operator
         else:
-            assert percentile is not None, "You must provide percentile=..."
+            assert percentile is not None, "You must provide percentile=... if `operator=percentile`"
             key = f"percentile_{percentile}"
 
+        if key not in self.data.keys():
+            error_msg = (
+                f"You have entered `operator={key}`, but the only operators calculated are "
+                f"{list(self.data.keys())}. Please use one of these as your `operator` in the "
+                f"`get_data` function."
+            )
+            raise ValueError(error_msg)
+
         templates_array = self.data[key]
 
         if outputs == "numpy":

From 22d19d52217594a129fc474bde119a2370e8d0e4 Mon Sep 17 00:00:00 2001
From: zm711 <92116279+zm711@users.noreply.github.com>
Date: Wed, 23 Oct 2024 09:36:17 -0400
Subject: [PATCH 131/344] more docs stuff

---
 .../core/analyzer_extension_core.py           | 62 ++++++++++---------
 1 file changed, 34 insertions(+), 28 deletions(-)

diff --git a/src/spikeinterface/core/analyzer_extension_core.py b/src/spikeinterface/core/analyzer_extension_core.py
index e0b267ae72..7d644c9c00 100644
--- a/src/spikeinterface/core/analyzer_extension_core.py
+++ b/src/spikeinterface/core/analyzer_extension_core.py
@@ -22,21 +22,23 @@
 
 class ComputeRandomSpikes(AnalyzerExtension):
     """
-    AnalyzerExtension that select some random spikes.
+    AnalyzerExtension that select somes random spikes.
+    This is allows for a subsampling of spikes for further calculations and is important
+    for managing that amount of memory and speed of computation in the analyzer.
 
     This will be used by the `waveforms`/`templates` extensions.
 
-    This internally use `random_spikes_selection()` parameters are the same.
+    This internally use `random_spikes_selection()` parameters.
 
     Parameters
     ----------
-    method: "uniform" | "all", default: "uniform"
+    method : "uniform" | "all", default: "uniform"
         The method to select the spikes
-    max_spikes_per_unit: int, default: 500
+    max_spikes_per_unit : int, default: 500
         The maximum number of spikes per unit, ignored if method="all"
-    margin_size: int, default: None
+    margin_size : int, default: None
         A margin on each border of segments to avoid border spikes, ignored if method="all"
-    seed: int or None, default: None
+    seed : int or None, default: None
         A seed for the random generator, ignored if method="all"
 
     Returns
@@ -104,7 +106,7 @@ def get_random_spikes(self):
         return self._some_spikes
 
     def get_selected_indices_in_spike_train(self, unit_id, segment_index):
-        # usefull for Waveforms extractor backwars compatibility
+        # useful for Waveforms extractor backwars compatibility
         # In Waveforms extractor "selected_spikes" was a dict (key: unit_id) of list (segment_index) of indices of spikes in spiketrain
         sorting = self.sorting_analyzer.sorting
         random_spikes_indices = self.data["random_spikes_indices"]
@@ -133,16 +135,16 @@ class ComputeWaveforms(AnalyzerExtension):
 
     Parameters
     ----------
-    ms_before: float, default: 1.0
+    ms_before : float, default: 1.0
         The number of ms to extract before the spike events
-    ms_after: float, default: 2.0
+    ms_after : float, default: 2.0
         The number of ms to extract after the spike events
-    dtype: None | dtype, default: None
+    dtype : None | dtype, default: None
         The dtype of the waveforms. If None, the dtype of the recording is used.
 
     Returns
     -------
-    waveforms: np.ndarray
+    waveforms : np.ndarray
         Array with computed waveforms with shape (num_random_spikes, num_samples, num_channels)
     """
 
@@ -410,9 +412,13 @@ def _run(self, verbose=False, **job_kwargs):
             self._compute_and_append_from_waveforms(self.params["operators"])
 
         else:
-            for operator in self.params["operators"]:
-                if operator not in ("average", "std"):
-                    raise ValueError(f"Computing templates with operators {operator} needs the 'waveforms' extension")
+            bad_operator_list = [
+                operator for operator in self.params["operators"] if operator not in ("average", "std")
+            ]
+            if len(bad_operator_list) > 0:
+                raise ValueError(
+                    f"Computing templates with operators {bad_operator_list} requires the 'waveforms' extension"
+                )
 
             recording = self.sorting_analyzer.recording
             sorting = self.sorting_analyzer.sorting
@@ -446,7 +452,7 @@ def _run(self, verbose=False, **job_kwargs):
 
     def _compute_and_append_from_waveforms(self, operators):
         if not self.sorting_analyzer.has_extension("waveforms"):
-            raise ValueError(f"Computing templates with operators {operators} needs the 'waveforms' extension")
+            raise ValueError(f"Computing templates with operators {operators} requires the 'waveforms' extension")
 
         unit_ids = self.sorting_analyzer.unit_ids
         channel_ids = self.sorting_analyzer.channel_ids
@@ -471,7 +477,7 @@ def _compute_and_append_from_waveforms(self, operators):
 
         assert self.sorting_analyzer.has_extension(
             "random_spikes"
-        ), "compute templates requires the random_spikes extension. You can run sorting_analyzer.get_random_spikes()"
+        ), "compute 'templates' requires the random_spikes extension. You can run sorting_analyzer.compute('random_spikes')"
         some_spikes = self.sorting_analyzer.get_extension("random_spikes").get_random_spikes()
         for unit_index, unit_id in enumerate(unit_ids):
             spike_mask = some_spikes["unit_index"] == unit_index
@@ -579,7 +585,7 @@ def _get_data(self, operator="average", percentile=None, outputs="numpy"):
                 probe=self.sorting_analyzer.get_probe(),
             )
         else:
-            raise ValueError("outputs must be numpy or Templates")
+            raise ValueError("outputs must be `numpy` or `Templates`")
 
     def get_templates(self, unit_ids=None, operator="average", percentile=None, save=True, outputs="numpy"):
         """
@@ -589,26 +595,26 @@ def get_templates(self, unit_ids=None, operator="average", percentile=None, save
 
         Parameters
         ----------
-        unit_ids: list or None
+        unit_ids : list or None
             Unit ids to retrieve waveforms for
-        operator: "average" | "median" | "std" | "percentile", default: "average"
+        operator : "average" | "median" | "std" | "percentile", default: "average"
             The operator to compute the templates
-        percentile: float, default: None
+        percentile : float, default: None
             Percentile to use for operator="percentile"
-        save: bool, default True
+        save : bool, default: True
             In case, the operator is not computed yet it can be saved to folder or zarr
-        outputs: "numpy" | "Templates"
+        outputs : "numpy" | "Templates", default: "numpy"
             Whether to return a numpy array or a Templates object
 
         Returns
         -------
-        templates: np.array
+        templates : np.array | Templates
             The returned templates (num_units, num_samples, num_channels)
         """
         if operator != "percentile":
             key = operator
         else:
-            assert percentile is not None, "You must provide percentile=..."
+            assert percentile is not None, "You must provide percentile=... if `operator='percentile'`"
             key = f"pencentile_{percentile}"
 
         if key in self.data:
@@ -645,7 +651,7 @@ def get_templates(self, unit_ids=None, operator="average", percentile=None, save
                 is_scaled=self.sorting_analyzer.return_scaled,
             )
         else:
-            raise ValueError("outputs must be numpy or Templates")
+            raise ValueError("`outputs` must be 'numpy' or 'Templates'")
 
     def get_unit_template(self, unit_id, operator="average"):
         """
@@ -655,7 +661,7 @@ def get_unit_template(self, unit_id, operator="average"):
         ----------
         unit_id: str | int
             Unit id to retrieve waveforms for
-        operator: str
+        operator: str, default: "average"
              The operator to compute the templates
 
         Returns
@@ -713,13 +719,13 @@ def _set_params(self, num_chunks_per_segment=20, chunk_size=10000, seed=None):
         return params
 
     def _select_extension_data(self, unit_ids):
-        # this do not depend on units
+        # this does not depend on units
         return self.data
 
     def _merge_extension_data(
         self, merge_unit_groups, new_unit_ids, new_sorting_analyzer, keep_mask=None, verbose=False, **job_kwargs
     ):
-        # this do not depend on units
+        # this does not depend on units
         return self.data.copy()
 
     def _run(self, verbose=False):

From b1f11fbdcf3a9e94e77030f7da83368ed9ccea73 Mon Sep 17 00:00:00 2001
From: Zach McKenzie <92116279+zm711@users.noreply.github.com>
Date: Wed, 23 Oct 2024 09:38:03 -0400
Subject: [PATCH 132/344] fix typo

---
 src/spikeinterface/core/analyzer_extension_core.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/core/analyzer_extension_core.py b/src/spikeinterface/core/analyzer_extension_core.py
index 7d644c9c00..2d9924554c 100644
--- a/src/spikeinterface/core/analyzer_extension_core.py
+++ b/src/spikeinterface/core/analyzer_extension_core.py
@@ -23,7 +23,7 @@
 class ComputeRandomSpikes(AnalyzerExtension):
     """
     AnalyzerExtension that select somes random spikes.
-    This is allows for a subsampling of spikes for further calculations and is important
+    This allows for a subsampling of spikes for further calculations and is important
     for managing that amount of memory and speed of computation in the analyzer.
 
     This will be used by the `waveforms`/`templates` extensions.

From eb6219999ce1d8d1c898575ec9a71045c6a8bcb1 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 23 Oct 2024 15:50:51 +0200
Subject: [PATCH 133/344] wip

---
 src/spikeinterface/core/recording_tools.py    | 27 +++++++------------
 .../preprocessing/silence_periods.py          |  4 ++-
 .../preprocessing/tests/test_silence.py       |  5 +++-
 .../preprocessing/tests/test_whiten.py        |  7 +++--
 4 files changed, 22 insertions(+), 21 deletions(-)

diff --git a/src/spikeinterface/core/recording_tools.py b/src/spikeinterface/core/recording_tools.py
index 790511ad88..a4feff4d14 100644
--- a/src/spikeinterface/core/recording_tools.py
+++ b/src/spikeinterface/core/recording_tools.py
@@ -601,11 +601,16 @@ def get_random_data_chunks(
     recording,
     return_scaled=False,
     concatenated=True,
-    random_slices_kwargs={},
-    **kwargs,
+    **random_slices_kwargs
 ):
     """
-    Extract random chunks across segments
+    Extract random chunks across segments.
+    
+    Internally, it uses `get_random_recording_slices()` and retrieves the traces chunk as a list
+    or a concatenated unique array.
+
+    Please read `get_random_recording_slices()` for more details on parameters.
+
 
     Parameters
     ----------
@@ -617,7 +622,7 @@ def get_random_data_chunks(
         Number of chunks per segment
     concatenated : bool, default: True
         If True chunk are concatenated along time axis
-    random_slices_kwargs : dict
+    **random_slices_kwargs : dict
         Options transmited to  get_random_recording_slices(), please read documentation from this
         function for more details.
 
@@ -626,18 +631,6 @@ def get_random_data_chunks(
     chunk_list : np.array
         Array of concatenate chunks per segment
     """
-    if len(kwargs) > 0:
-        # This is to keep backward compatibility 
-        # lets keep for a while and remove this maybe in 0.103.0
-        msg = (
-            "get_random_data_chunks(recording, num_chunks_per_segment=20) is deprecated\n"
-            "Now, you need to use get_random_data_chunks(recording, random_slices_kwargs=dict(num_chunks_per_segment=20))\n"
-            "Please read get_random_recording_slices() documentation for more options."
-        )
-        assert len(random_slices_kwargs) ==0, msg
-        warnings.warn(msg)
-        random_slices_kwargs = kwargs
-
     recording_slices = get_random_recording_slices(recording, **random_slices_kwargs)
 
     chunk_list = []
@@ -797,7 +790,7 @@ def get_noise_levels(
             if "chunk_size" in job_kwargs:
                 random_slices_kwargs["chunk_size"] = job_kwargs["chunk_size"]
 
-        recording_slices = get_random_recording_slices(recording, **random_slices_kwargs)
+        recording_slices = get_random_recording_slices(recording, random_slices_kwargs)
 
         noise_levels_chunks = []
         def append_noise_chunk(res):
diff --git a/src/spikeinterface/preprocessing/silence_periods.py b/src/spikeinterface/preprocessing/silence_periods.py
index 8f38f01469..3129acd3f3 100644
--- a/src/spikeinterface/preprocessing/silence_periods.py
+++ b/src/spikeinterface/preprocessing/silence_periods.py
@@ -71,8 +71,10 @@ def __init__(self, recording, list_periods, mode="zeros", noise_levels=None, see
 
         if mode in ["noise"]:
             if noise_levels is None:
+                random_chunk_kwargs = random_chunk_kwargs.copy()
+                random_chunk_kwargs["seed"] = seed
                 noise_levels = get_noise_levels(
-                    recording, return_scaled=False, concatenated=True, seed=seed, **random_chunk_kwargs
+                    recording, return_scaled=False, random_slices_kwargs=random_chunk_kwargs
                 )
             noise_generator = NoiseGeneratorRecording(
                 num_channels=recording.get_num_channels(),
diff --git a/src/spikeinterface/preprocessing/tests/test_silence.py b/src/spikeinterface/preprocessing/tests/test_silence.py
index 6c2e8ec8b5..6405b6b0c4 100644
--- a/src/spikeinterface/preprocessing/tests/test_silence.py
+++ b/src/spikeinterface/preprocessing/tests/test_silence.py
@@ -9,6 +9,8 @@
 
 import numpy as np
 
+from pathlib import Path
+
 
 def test_silence(create_cache_folder):
 
@@ -46,4 +48,5 @@ def test_silence(create_cache_folder):
 
 
 if __name__ == "__main__":
-    test_silence()
+    cache_folder = Path(__file__).resolve().parents[4] / "cache_folder" 
+    test_silence(cache_folder)
diff --git a/src/spikeinterface/preprocessing/tests/test_whiten.py b/src/spikeinterface/preprocessing/tests/test_whiten.py
index 04b731de4f..3444323488 100644
--- a/src/spikeinterface/preprocessing/tests/test_whiten.py
+++ b/src/spikeinterface/preprocessing/tests/test_whiten.py
@@ -5,13 +5,15 @@
 
 from spikeinterface.preprocessing import whiten, scale, compute_whitening_matrix
 
+from pathlib import Path
+
 
 def test_whiten(create_cache_folder):
     cache_folder = create_cache_folder
     rec = generate_recording(num_channels=4, seed=2205)
 
     print(rec.get_channel_locations())
-    random_chunk_kwargs = {}
+    random_chunk_kwargs = {"seed": 2205}
     W1, M = compute_whitening_matrix(rec, "global", random_chunk_kwargs, apply_mean=False, radius_um=None)
     # print(W)
     # print(M)
@@ -47,4 +49,5 @@ def test_whiten(create_cache_folder):
 
 
 if __name__ == "__main__":
-    test_whiten()
+    cache_folder = Path(__file__).resolve().parents[4] / "cache_folder" 
+    test_whiten(cache_folder)

From 68b4b200907be01e63149dd673b49f1f02f9b821 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 23 Oct 2024 17:14:06 +0200
Subject: [PATCH 134/344] small updates on auto merge + renaming

---
 src/spikeinterface/curation/__init__.py       |   2 +-
 src/spikeinterface/curation/auto_merge.py     | 197 ++++++++++--------
 .../curation/tests/test_auto_merge.py         |  49 +++--
 3 files changed, 137 insertions(+), 111 deletions(-)

diff --git a/src/spikeinterface/curation/__init__.py b/src/spikeinterface/curation/__init__.py
index 657b936fb9..579e47a553 100644
--- a/src/spikeinterface/curation/__init__.py
+++ b/src/spikeinterface/curation/__init__.py
@@ -3,7 +3,7 @@
 from .remove_redundant import remove_redundant_units, find_redundant_units
 from .remove_duplicated_spikes import remove_duplicated_spikes
 from .remove_excess_spikes import remove_excess_spikes
-from .auto_merge import get_potential_auto_merge
+from .auto_merge import compute_merge_unit_groups, auto_merge, get_potential_auto_merge
 
 
 # manual sorting,
diff --git a/src/spikeinterface/curation/auto_merge.py b/src/spikeinterface/curation/auto_merge.py
index 86f47af0eb..16147a6225 100644
--- a/src/spikeinterface/curation/auto_merge.py
+++ b/src/spikeinterface/curation/auto_merge.py
@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import warnings
+
 from typing import Tuple
 import numpy as np
 import math
@@ -17,19 +19,50 @@
 from .mergeunitssorting import MergeUnitsSorting
 from .curation_tools import resolve_merging_graph
 
-
-_possible_presets = ["similarity_correlograms", "x_contaminations", "temporal_splits", "feature_neighbors"]
+_compute_merge_persets = {
+    "similarity_correlograms":[
+        "num_spikes",
+        "remove_contaminated",
+        "unit_locations",
+        "template_similarity",
+        "correlogram",
+        "quality_score",
+    ],
+    "temporal_splits":[
+        "num_spikes",
+        "remove_contaminated",
+        "unit_locations",
+        "template_similarity",
+        "presence_distance",
+        "quality_score",
+    ],
+    "x_contaminations":[
+        "num_spikes",
+        "remove_contaminated",
+        "unit_locations",
+        "template_similarity",
+        "cross_contamination",
+        "quality_score",
+    ],
+    "feature_neighbors":[
+        "num_spikes",
+        "snr",
+        "remove_contaminated",
+        "unit_locations",
+        "knn",
+        "quality_score",
+    ]
+}
 
 _required_extensions = {
-    "unit_locations": ["unit_locations"],
+    "unit_locations": ["templates", "unit_locations"],
     "correlogram": ["correlograms"],
-    "snr": ["noise_levels", "templates"],
-    "template_similarity": ["template_similarity"],
-    "knn": ["spike_locations", "spike_amplitudes"],
+    "snr": ["templates","noise_levels", "templates"],
+    "template_similarity": ["templates", "template_similarity"],
+    "knn": ["templates", "spike_locations", "spike_amplitudes"],
+    "spike_amplitudes" : ["templates"],
 }
 
-_templates_needed = ["unit_locations", "snr", "template_similarity", "knn", "spike_amplitudes"]
-
 
 _default_step_params = {
     "num_spikes": {"min_spikes": 100},
@@ -55,17 +88,18 @@
 }
 
 
-def auto_merges(
+
+def compute_merge_unit_groups(
     sorting_analyzer: SortingAnalyzer,
     preset: str | None = "similarity_correlograms",
-    resolve_graph: bool = False,
+    resolve_graph: bool = True,
     steps_params: dict = None,
     compute_needed_extensions: bool = True,
     extra_outputs: bool = False,
     steps: list[str] | None = None,
     force_copy: bool = True,
     **job_kwargs,
-) -> list[tuple[int | str, int | str]] | Tuple[tuple[int | str, int | str], dict]:
+) -> list[tuple[int | str, int | str]] | Tuple[list[tuple[int | str, int | str]], dict]:
     """
     Algorithm to find and check potential merges between units.
 
@@ -110,7 +144,7 @@ def auto_merges(
           | It uses the following steps: "num_spikes", "snr", "remove_contaminated", "unit_locations",
           | "knn", "quality_score"
         If `preset` is None, you can specify the steps manually with the `steps` parameter.
-    resolve_graph : bool, default: False
+    resolve_graph : bool, default: True
         If True, the function resolves the potential unit pairs to be merged into multiple-unit merges.
     compute_needed_extensions : bool, default : True
         Should we force the computation of needed extensions?
@@ -128,9 +162,10 @@ def auto_merges(
 
     Returns
     -------
-    potential_merges:
-        A list of tuples of 2 elements (if `resolve_graph`if false) or 2+ elements (if `resolve_graph` is true).
-        List of pairs that could be merged.
+    merge_unit_groups:
+        List of groups that need to be merge.
+        When `resolve_graph` is true (default) a list of tuples of 2+ elements
+        If `resolve_graph` is false then a list of tuple of 2 elements is returned instead.
     outs:
         Returned only when extra_outputs=True
         A dictionary that contains data for debugging and plotting.
@@ -146,62 +181,17 @@ def auto_merges(
     sorting = sorting_analyzer.sorting
     unit_ids = sorting.unit_ids
 
-    all_steps = [
-        "num_spikes",
-        "snr",
-        "remove_contaminated",
-        "unit_locations",
-        "correlogram",
-        "template_similarity",
-        "presence_distance",
-        "knn",
-        "cross_contamination",
-        "quality_score",
-    ]
 
-    if preset is not None and preset not in _possible_presets:
-        raise ValueError(f"preset must be one of {_possible_presets}")
-
-    if steps is None:
-        if preset is None:
-            if steps is None:
-                raise ValueError("You need to specify a preset or steps for the auto-merge function")
-        elif preset == "similarity_correlograms":
-            steps = [
-                "num_spikes",
-                "remove_contaminated",
-                "unit_locations",
-                "template_similarity",
-                "correlogram",
-                "quality_score",
-            ]
-        elif preset == "temporal_splits":
-            steps = [
-                "num_spikes",
-                "remove_contaminated",
-                "unit_locations",
-                "template_similarity",
-                "presence_distance",
-                "quality_score",
-            ]
-        elif preset == "x_contaminations":
-            steps = [
-                "num_spikes",
-                "remove_contaminated",
-                "unit_locations",
-                "template_similarity",
-                "cross_contamination",
-                "quality_score",
-            ]
-        elif preset == "feature_neighbors":
-            steps = [
-                "num_spikes",
-                "snr",
-                "remove_contaminated",
-                "unit_locations",
-                "knn",
-                "quality_score",
-            ]
+    if preset is None and steps is None:
+        raise ValueError("You need to specify a preset or steps for the auto-merge function")
+    elif steps is not None:
+        # steps has presendance on presets
+        pass
+    elif preset is not None:
+        if preset not in _compute_merge_persets:
+            raise ValueError(f"preset must be one of {list(_compute_merge_persets.keys())}")
+        steps = _compute_merge_persets[preset]
+
     if force_copy and compute_needed_extensions:
         # To avoid erasing the extensions of the user
         sorting_analyzer = sorting_analyzer.copy()
@@ -212,26 +202,23 @@ def auto_merges(
 
     for step in steps:
 
-        assert step in all_steps, f"{step} is not a valid step"
+        assert step in _default_step_params, f"{step} is not a valid step"
 
         if step in _required_extensions:
             for ext in _required_extensions[step]:
-                if compute_needed_extensions:
-                    if step in _templates_needed:
-                        template_ext = sorting_analyzer.get_extension("templates")
-                        if template_ext is None:
-                            sorting_analyzer.compute(["random_spikes", "templates"], **job_kwargs)
-                    res_ext = sorting_analyzer.get_extension(step)
-                    if res_ext is None:
-                        print(
-                            f"Extension {ext} is computed with default params. Precompute it with custom params if needed"
-                        )
-                        sorting_analyzer.compute(ext, **job_kwargs)
-                elif not compute_needed_extensions and not sorting_analyzer.has_extension(ext):
+                if sorting_analyzer.has_extension(ext):
+                    continue
+                if not compute_needed_extensions:
                     raise ValueError(f"{step} requires {ext} extension")
+                
+                # special case for templates
+                if ext == "templates" and not sorting_analyzer.has_extension("random_spikes"):
+                    sorting_analyzer.compute(["random_spikes", "templates"], **job_kwargs)
+                else:
+                    sorting_analyzer.compute(ext, **job_kwargs)
 
         params = _default_step_params.get(step).copy()
-        if step in steps_params:
+        if steps_params is not None and step in steps_params:
             params.update(steps_params[step])
 
         # STEP : remove units with too few spikes
@@ -360,15 +347,38 @@ def auto_merges(
 
     # FINAL STEP : create the final list from pair_mask boolean matrix
     ind1, ind2 = np.nonzero(pair_mask)
-    potential_merges = list(zip(unit_ids[ind1], unit_ids[ind2]))
+    merge_unit_groups = list(zip(unit_ids[ind1], unit_ids[ind2]))
 
     if resolve_graph:
-        potential_merges = resolve_merging_graph(sorting, potential_merges)
+        merge_unit_groups = resolve_merging_graph(sorting, merge_unit_groups)
 
     if extra_outputs:
-        return potential_merges, outs
+        return merge_unit_groups, outs
     else:
-        return potential_merges
+        return merge_unit_groups
+
+def auto_merge(
+        sorting_analyzer: SortingAnalyzer,
+        compute_merge_kwargs:dict = {},
+        apply_merge_kwargs: dict = {},
+        **job_kwargs
+        ) -> SortingAnalyzer:
+    """
+    Compute merge unit groups and apply it on a SortingAnalyzer.
+    Internally uses `compute_merge_unit_groups()`
+    """
+    merge_unit_groups = compute_merge_unit_groups(
+        sorting_analyzer,
+        extra_outputs=False,
+        **compute_merge_kwargs,
+        **job_kwargs
+    )
+
+    merged_analyzer = sorting_analyzer.merge_units(
+        merge_unit_groups, **apply_merge_kwargs, **job_kwargs
+    )
+    return merged_analyzer
+
 
 
 def get_potential_auto_merge(
@@ -397,6 +407,9 @@ def get_potential_auto_merge(
     steps: list[str] | None = None,
 ) -> list[tuple[int | str, int | str]] | Tuple[tuple[int | str, int | str], dict]:
     """
+    This function is deprecated. Use compute_merge_unit_groups() instead.
+    This will be removed in 0.103.0
+
     Algorithm to find and check potential merges between units.
 
     The merges are proposed based on a series of steps with different criteria:
@@ -505,9 +518,15 @@ def get_potential_auto_merge(
     done by Aurelien Wyngaard and Victor Llobet.
     https://github.com/BarbourLab/lussac/blob/v1.0.0/postprocessing/merge_units.py
     """
+    warnings.warn(
+            "get_potential_auto_merge() is deprecated. Use compute_merge_unit_groups() instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
     presence_distance_kwargs = presence_distance_kwargs or dict()
     knn_kwargs = knn_kwargs or dict()
-    return auto_merges(
+    return compute_merge_unit_groups(
         sorting_analyzer,
         preset,
         resolve_graph,
diff --git a/src/spikeinterface/curation/tests/test_auto_merge.py b/src/spikeinterface/curation/tests/test_auto_merge.py
index 33fd06d27a..ebd7bf1504 100644
--- a/src/spikeinterface/curation/tests/test_auto_merge.py
+++ b/src/spikeinterface/curation/tests/test_auto_merge.py
@@ -3,16 +3,16 @@
 
 from spikeinterface.core import create_sorting_analyzer
 from spikeinterface.core.generate import inject_some_split_units
-from spikeinterface.curation import get_potential_auto_merge
+from spikeinterface.curation import compute_merge_unit_groups, auto_merge
 
 
 from spikeinterface.curation.tests.common import make_sorting_analyzer, sorting_analyzer_for_curation
 
 
 @pytest.mark.parametrize(
-    "preset", ["x_contaminations", "feature_neighbors", "temporal_splits", "similarity_correlograms"]
+    "preset", ["x_contaminations", "feature_neighbors", "temporal_splits", "similarity_correlograms", None]
 )
-def test_get_auto_merge_list(sorting_analyzer_for_curation, preset):
+def test_compute_merge_unit_groups(sorting_analyzer_for_curation, preset):
 
     print(sorting_analyzer_for_curation)
     sorting = sorting_analyzer_for_curation.sorting
@@ -47,32 +47,37 @@ def test_get_auto_merge_list(sorting_analyzer_for_curation, preset):
     )
 
     if preset is not None:
-        potential_merges, outs = get_potential_auto_merge(
+        # do not resolve graph for checking true pairs
+        merge_unit_groups, outs = compute_merge_unit_groups(
             sorting_analyzer,
             preset=preset,
-            min_spikes=1000,
-            max_distance_um=150.0,
-            contamination_thresh=0.2,
-            corr_diff_thresh=0.16,
-            template_diff_thresh=0.25,
-            censored_period_ms=0.0,
-            refractory_period_ms=4.0,
-            sigma_smooth_ms=0.6,
-            adaptative_window_thresh=0.5,
-            firing_contamination_balance=1.5,
+            resolve_graph=False,
+            # min_spikes=1000,
+            # max_distance_um=150.0,
+            # contamination_thresh=0.2,
+            # corr_diff_thresh=0.16,
+            # template_diff_thresh=0.25,
+            # censored_period_ms=0.0,
+            # refractory_period_ms=4.0,
+            # sigma_smooth_ms=0.6,
+            # adaptative_window_thresh=0.5,
+            # firing_contamination_balance=1.5,
             extra_outputs=True,
+            **job_kwargs
         )
         if preset == "x_contaminations":
-            assert len(potential_merges) == num_unit_splited
+            assert len(merge_unit_groups) == num_unit_splited
             for true_pair in other_ids.values():
                 true_pair = tuple(true_pair)
-                assert true_pair in potential_merges
+                assert true_pair in merge_unit_groups
     else:
         # when preset is None you have to specify the steps
         with pytest.raises(ValueError):
-            potential_merges = get_potential_auto_merge(sorting_analyzer, preset=preset)
-        potential_merges = get_potential_auto_merge(
-            sorting_analyzer, preset=preset, steps=["min_spikes", "min_snr", "remove_contaminated", "unit_positions"]
+            merge_unit_groups = compute_merge_unit_groups(sorting_analyzer, preset=preset)
+        merge_unit_groups = compute_merge_unit_groups(
+            sorting_analyzer, preset=preset,
+            steps=["num_spikes", "snr", "remove_contaminated", "unit_locations"],
+            **job_kwargs
         )
 
     # DEBUG
@@ -93,7 +98,7 @@ def test_get_auto_merge_list(sorting_analyzer_for_curation, preset):
 
     # m = correlograms.shape[2] // 2
 
-    # for unit_id1, unit_id2 in potential_merges[:5]:
+    # for unit_id1, unit_id2 in merge_unit_groups[:5]:
     #     unit_ind1 = sorting_with_split.id_to_index(unit_id1)
     #     unit_ind2 = sorting_with_split.id_to_index(unit_id2)
 
@@ -129,4 +134,6 @@ def test_get_auto_merge_list(sorting_analyzer_for_curation, preset):
 
 if __name__ == "__main__":
     sorting_analyzer = make_sorting_analyzer(sparse=True)
-    test_get_auto_merge_list(sorting_analyzer)
+    # preset = "x_contaminations"
+    preset = None
+    test_compute_merge_unit_groups(sorting_analyzer, preset=preset)

From 4476d4ccc6bde244561936b8ed22c9b7a0032113 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Wed, 23 Oct 2024 15:15:47 +0000
Subject: [PATCH 135/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/curation/auto_merge.py     | 44 +++++++------------
 .../curation/tests/test_auto_merge.py         |  7 +--
 2 files changed, 21 insertions(+), 30 deletions(-)

diff --git a/src/spikeinterface/curation/auto_merge.py b/src/spikeinterface/curation/auto_merge.py
index 16147a6225..ec5e8be20c 100644
--- a/src/spikeinterface/curation/auto_merge.py
+++ b/src/spikeinterface/curation/auto_merge.py
@@ -20,7 +20,7 @@
 from .curation_tools import resolve_merging_graph
 
 _compute_merge_persets = {
-    "similarity_correlograms":[
+    "similarity_correlograms": [
         "num_spikes",
         "remove_contaminated",
         "unit_locations",
@@ -28,7 +28,7 @@
         "correlogram",
         "quality_score",
     ],
-    "temporal_splits":[
+    "temporal_splits": [
         "num_spikes",
         "remove_contaminated",
         "unit_locations",
@@ -36,7 +36,7 @@
         "presence_distance",
         "quality_score",
     ],
-    "x_contaminations":[
+    "x_contaminations": [
         "num_spikes",
         "remove_contaminated",
         "unit_locations",
@@ -44,23 +44,23 @@
         "cross_contamination",
         "quality_score",
     ],
-    "feature_neighbors":[
+    "feature_neighbors": [
         "num_spikes",
         "snr",
         "remove_contaminated",
         "unit_locations",
         "knn",
         "quality_score",
-    ]
+    ],
 }
 
 _required_extensions = {
     "unit_locations": ["templates", "unit_locations"],
     "correlogram": ["correlograms"],
-    "snr": ["templates","noise_levels", "templates"],
+    "snr": ["templates", "noise_levels", "templates"],
     "template_similarity": ["templates", "template_similarity"],
     "knn": ["templates", "spike_locations", "spike_amplitudes"],
-    "spike_amplitudes" : ["templates"],
+    "spike_amplitudes": ["templates"],
 }
 
 
@@ -88,7 +88,6 @@
 }
 
 
-
 def compute_merge_unit_groups(
     sorting_analyzer: SortingAnalyzer,
     preset: str | None = "similarity_correlograms",
@@ -181,7 +180,6 @@ def compute_merge_unit_groups(
     sorting = sorting_analyzer.sorting
     unit_ids = sorting.unit_ids
 
-
     if preset is None and steps is None:
         raise ValueError("You need to specify a preset or steps for the auto-merge function")
     elif steps is not None:
@@ -210,7 +208,7 @@ def compute_merge_unit_groups(
                     continue
                 if not compute_needed_extensions:
                     raise ValueError(f"{step} requires {ext} extension")
-                
+
                 # special case for templates
                 if ext == "templates" and not sorting_analyzer.has_extension("random_spikes"):
                     sorting_analyzer.compute(["random_spikes", "templates"], **job_kwargs)
@@ -357,30 +355,22 @@ def compute_merge_unit_groups(
     else:
         return merge_unit_groups
 
+
 def auto_merge(
-        sorting_analyzer: SortingAnalyzer,
-        compute_merge_kwargs:dict = {},
-        apply_merge_kwargs: dict = {},
-        **job_kwargs
-        ) -> SortingAnalyzer:
+    sorting_analyzer: SortingAnalyzer, compute_merge_kwargs: dict = {}, apply_merge_kwargs: dict = {}, **job_kwargs
+) -> SortingAnalyzer:
     """
     Compute merge unit groups and apply it on a SortingAnalyzer.
     Internally uses `compute_merge_unit_groups()`
     """
     merge_unit_groups = compute_merge_unit_groups(
-        sorting_analyzer,
-        extra_outputs=False,
-        **compute_merge_kwargs,
-        **job_kwargs
+        sorting_analyzer, extra_outputs=False, **compute_merge_kwargs, **job_kwargs
     )
 
-    merged_analyzer = sorting_analyzer.merge_units(
-        merge_unit_groups, **apply_merge_kwargs, **job_kwargs
-    )
+    merged_analyzer = sorting_analyzer.merge_units(merge_unit_groups, **apply_merge_kwargs, **job_kwargs)
     return merged_analyzer
 
 
-
 def get_potential_auto_merge(
     sorting_analyzer: SortingAnalyzer,
     preset: str | None = "similarity_correlograms",
@@ -519,10 +509,10 @@ def get_potential_auto_merge(
     https://github.com/BarbourLab/lussac/blob/v1.0.0/postprocessing/merge_units.py
     """
     warnings.warn(
-            "get_potential_auto_merge() is deprecated. Use compute_merge_unit_groups() instead",
-            DeprecationWarning,
-            stacklevel=2,
-        )
+        "get_potential_auto_merge() is deprecated. Use compute_merge_unit_groups() instead",
+        DeprecationWarning,
+        stacklevel=2,
+    )
 
     presence_distance_kwargs = presence_distance_kwargs or dict()
     knn_kwargs = knn_kwargs or dict()
diff --git a/src/spikeinterface/curation/tests/test_auto_merge.py b/src/spikeinterface/curation/tests/test_auto_merge.py
index ebd7bf1504..4c05f41a4c 100644
--- a/src/spikeinterface/curation/tests/test_auto_merge.py
+++ b/src/spikeinterface/curation/tests/test_auto_merge.py
@@ -63,7 +63,7 @@ def test_compute_merge_unit_groups(sorting_analyzer_for_curation, preset):
             # adaptative_window_thresh=0.5,
             # firing_contamination_balance=1.5,
             extra_outputs=True,
-            **job_kwargs
+            **job_kwargs,
         )
         if preset == "x_contaminations":
             assert len(merge_unit_groups) == num_unit_splited
@@ -75,9 +75,10 @@ def test_compute_merge_unit_groups(sorting_analyzer_for_curation, preset):
         with pytest.raises(ValueError):
             merge_unit_groups = compute_merge_unit_groups(sorting_analyzer, preset=preset)
         merge_unit_groups = compute_merge_unit_groups(
-            sorting_analyzer, preset=preset,
+            sorting_analyzer,
+            preset=preset,
             steps=["num_spikes", "snr", "remove_contaminated", "unit_locations"],
-            **job_kwargs
+            **job_kwargs,
         )
 
     # DEBUG

From 6ee7299c7f7a0b14fbc49f12abf46907b418a072 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 23 Oct 2024 17:40:57 +0200
Subject: [PATCH 136/344] more updates

---
 src/spikeinterface/core/recording_tools.py            | 10 ++++++----
 src/spikeinterface/core/tests/test_recording_tools.py |  2 +-
 src/spikeinterface/preprocessing/silence_periods.py   |  6 +++---
 3 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/src/spikeinterface/core/recording_tools.py b/src/spikeinterface/core/recording_tools.py
index a4feff4d14..1f46de7d29 100644
--- a/src/spikeinterface/core/recording_tools.py
+++ b/src/spikeinterface/core/recording_tools.py
@@ -628,7 +628,7 @@ def get_random_data_chunks(
 
     Returns
     -------
-    chunk_list : np.array
+    chunk_list : np.array | list of np.array
         Array of concatenate chunks per segment
     """
     recording_slices = get_random_recording_slices(recording, **random_slices_kwargs)
@@ -757,8 +757,9 @@ def get_noise_levels(
     random_slices_kwargs : dict
         Options transmited to  get_random_recording_slices(), please read documentation from this
         function for more details.
-    **job_kwargs: 
-        Job kwargs for parallel computing.
+
+    {}
+    
     Returns
     -------
     noise_levels : array
@@ -790,7 +791,7 @@ def get_noise_levels(
             if "chunk_size" in job_kwargs:
                 random_slices_kwargs["chunk_size"] = job_kwargs["chunk_size"]
 
-        recording_slices = get_random_recording_slices(recording, random_slices_kwargs)
+        recording_slices = get_random_recording_slices(recording, **random_slices_kwargs)
 
         noise_levels_chunks = []
         def append_noise_chunk(res):
@@ -812,6 +813,7 @@ def append_noise_chunk(res):
 
     return noise_levels
 
+get_noise_levels.__doc__ = get_noise_levels.__doc__.format(_shared_job_kwargs_doc)
 
 
 def get_chunk_with_margin(
diff --git a/src/spikeinterface/core/tests/test_recording_tools.py b/src/spikeinterface/core/tests/test_recording_tools.py
index 07515ef3f0..1fa9ffe124 100644
--- a/src/spikeinterface/core/tests/test_recording_tools.py
+++ b/src/spikeinterface/core/tests/test_recording_tools.py
@@ -182,7 +182,7 @@ def test_get_random_recording_slices():
 
 def test_get_random_data_chunks():
     rec = generate_recording(num_channels=1, sampling_frequency=1000.0, durations=[10.0, 20.0])
-    chunks = get_random_data_chunks(rec, random_slices_kwargs=dict(num_chunks_per_segment=50, chunk_size=500, seed=0))
+    chunks = get_random_data_chunks(rec, num_chunks_per_segment=50, chunk_size=500, seed=0)
     assert chunks.shape == (50000, 1)
 
 
diff --git a/src/spikeinterface/preprocessing/silence_periods.py b/src/spikeinterface/preprocessing/silence_periods.py
index 3129acd3f3..85169011d8 100644
--- a/src/spikeinterface/preprocessing/silence_periods.py
+++ b/src/spikeinterface/preprocessing/silence_periods.py
@@ -71,10 +71,10 @@ def __init__(self, recording, list_periods, mode="zeros", noise_levels=None, see
 
         if mode in ["noise"]:
             if noise_levels is None:
-                random_chunk_kwargs = random_chunk_kwargs.copy()
-                random_chunk_kwargs["seed"] = seed
+                random_slices_kwargs = random_chunk_kwargs.copy()
+                random_slices_kwargs["seed"] = seed
                 noise_levels = get_noise_levels(
-                    recording, return_scaled=False, random_slices_kwargs=random_chunk_kwargs
+                    recording, return_scaled=False, random_slices_kwargs=random_slices_kwargs
                 )
             noise_generator = NoiseGeneratorRecording(
                 num_channels=recording.get_num_channels(),

From 7517d06cb99d398eaecd48e3c50e063a8796bf7f Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Thu, 24 Oct 2024 10:09:47 +0200
Subject: [PATCH 137/344] fix scaling seed

---
 src/spikeinterface/preprocessing/tests/test_scaling.py | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/preprocessing/tests/test_scaling.py b/src/spikeinterface/preprocessing/tests/test_scaling.py
index 321d7c9df2..e32d96901e 100644
--- a/src/spikeinterface/preprocessing/tests/test_scaling.py
+++ b/src/spikeinterface/preprocessing/tests/test_scaling.py
@@ -55,11 +55,11 @@ def test_scaling_in_preprocessing_chain():
     recording.set_channel_gains(gains)
     recording.set_channel_offsets(offsets)
 
-    centered_recording = CenterRecording(scale_to_uV(recording=recording))
+    centered_recording = CenterRecording(scale_to_uV(recording=recording), seed=2205)
     traces_scaled_with_argument = centered_recording.get_traces(return_scaled=True)
 
     # Chain preprocessors
-    centered_recording_scaled = CenterRecording(scale_to_uV(recording=recording))
+    centered_recording_scaled = CenterRecording(scale_to_uV(recording=recording), seed=2205)
     traces_scaled_with_preprocessor = centered_recording_scaled.get_traces()
 
     np.testing.assert_allclose(traces_scaled_with_argument, traces_scaled_with_preprocessor)
@@ -68,3 +68,8 @@ def test_scaling_in_preprocessing_chain():
     traces_scaled_with_preprocessor_and_argument = centered_recording_scaled.get_traces(return_scaled=True)
 
     np.testing.assert_allclose(traces_scaled_with_preprocessor, traces_scaled_with_preprocessor_and_argument)
+
+
+if __name__ == "__main__":
+    test_scale_to_uV()
+    test_scaling_in_preprocessing_chain()

From bac57fe00450a6fe758a67092c0ff0d8f17ebfb5 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Thu, 24 Oct 2024 08:39:08 +0000
Subject: [PATCH 138/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 .../core/analyzer_extension_core.py           |  1 -
 src/spikeinterface/core/job_tools.py          |  3 +-
 src/spikeinterface/core/recording_tools.py    | 51 ++++++++++---------
 .../tests/test_analyzer_extension_core.py     |  2 +-
 .../core/tests/test_recording_tools.py        | 35 ++++++++-----
 .../preprocessing/tests/test_silence.py       |  2 +-
 .../preprocessing/tests/test_whiten.py        |  2 +-
 7 files changed, 54 insertions(+), 42 deletions(-)

diff --git a/src/spikeinterface/core/analyzer_extension_core.py b/src/spikeinterface/core/analyzer_extension_core.py
index 38d7ab247c..1d3501c4d0 100644
--- a/src/spikeinterface/core/analyzer_extension_core.py
+++ b/src/spikeinterface/core/analyzer_extension_core.py
@@ -693,7 +693,6 @@ class ComputeNoiseLevels(AnalyzerExtension):
     need_job_kwargs = False
     need_backward_compatibility_on_load = True
 
-
     def __init__(self, sorting_analyzer):
         AnalyzerExtension.__init__(self, sorting_analyzer)
 
diff --git a/src/spikeinterface/core/job_tools.py b/src/spikeinterface/core/job_tools.py
index 8f5df37695..27f05bb36b 100644
--- a/src/spikeinterface/core/job_tools.py
+++ b/src/spikeinterface/core/job_tools.py
@@ -184,6 +184,7 @@ def ensure_n_jobs(recording, n_jobs=1):
 
     return n_jobs
 
+
 def chunk_duration_to_chunk_size(chunk_duration, recording):
     if isinstance(chunk_duration, float):
         chunk_size = int(chunk_duration * recording.get_sampling_frequency())
@@ -196,7 +197,7 @@ def chunk_duration_to_chunk_size(chunk_duration, recording):
             raise ValueError("chunk_duration must ends with s or ms")
         chunk_size = int(chunk_duration * recording.get_sampling_frequency())
     else:
-        raise ValueError("chunk_duration must be str or float")    
+        raise ValueError("chunk_duration must be str or float")
     return chunk_size
 
 
diff --git a/src/spikeinterface/core/recording_tools.py b/src/spikeinterface/core/recording_tools.py
index 1f46de7d29..2ab74ce51e 100644
--- a/src/spikeinterface/core/recording_tools.py
+++ b/src/spikeinterface/core/recording_tools.py
@@ -514,15 +514,15 @@ def determine_cast_unsigned(recording, dtype):
     return cast_unsigned
 
 
-
-
-def get_random_recording_slices(recording,
-                                method="full_random",
-                                num_chunks_per_segment=20,
-                                chunk_duration="500ms",
-                                chunk_size=None,
-                                margin_frames=0,
-                                seed=None):
+def get_random_recording_slices(
+    recording,
+    method="full_random",
+    num_chunks_per_segment=20,
+    chunk_duration="500ms",
+    chunk_size=None,
+    margin_frames=0,
+    seed=None,
+):
     """
     Get random slice of a recording across segments.
 
@@ -593,19 +593,14 @@ def get_random_recording_slices(recording,
             ]
     else:
         raise ValueError(f"get_random_recording_slices : wrong method {method}")
-    
+
     return recording_slices
 
 
-def get_random_data_chunks(
-    recording,
-    return_scaled=False,
-    concatenated=True,
-    **random_slices_kwargs
-):
+def get_random_data_chunks(recording, return_scaled=False, concatenated=True, **random_slices_kwargs):
     """
     Extract random chunks across segments.
-    
+
     Internally, it uses `get_random_recording_slices()` and retrieves the traces chunk as a list
     or a concatenated unique array.
 
@@ -698,7 +693,7 @@ def get_closest_channels(recording, channel_ids=None, num_channels=None):
 
 def _noise_level_chunk(segment_index, start_frame, end_frame, worker_ctx):
     recording = worker_ctx["recording"]
-    
+
     one_chunk = recording.get_traces(
         start_frame=start_frame,
         end_frame=end_frame,
@@ -706,7 +701,6 @@ def _noise_level_chunk(segment_index, start_frame, end_frame, worker_ctx):
         return_scaled=worker_ctx["return_scaled"],
     )
 
-
     if worker_ctx["method"] == "mad":
         med = np.median(one_chunk, axis=0, keepdims=True)
         # hard-coded so that core doesn't depend on scipy
@@ -724,12 +718,13 @@ def _noise_level_chunk_init(recording, return_scaled, method):
     worker_ctx["method"] = method
     return worker_ctx
 
+
 def get_noise_levels(
     recording: "BaseRecording",
     return_scaled: bool = True,
     method: Literal["mad", "std"] = "mad",
     force_recompute: bool = False,
-    random_slices_kwargs : dict = {},
+    random_slices_kwargs: dict = {},
     **kwargs,
 ) -> np.ndarray:
     """
@@ -759,7 +754,7 @@ def get_noise_levels(
         function for more details.
 
     {}
-    
+
     Returns
     -------
     noise_levels : array
@@ -774,7 +769,7 @@ def get_noise_levels(
     if key in recording.get_property_keys() and not force_recompute:
         noise_levels = recording.get_property(key=key)
     else:
-        # This is to keep backward compatibility 
+        # This is to keep backward compatibility
         # lets keep for a while and remove this maybe in 0.103.0
         # chunk_size used to be in the signature and now is ambiguous
         random_slices_kwargs_, job_kwargs = split_job_kwargs(kwargs)
@@ -794,6 +789,7 @@ def get_noise_levels(
         recording_slices = get_random_recording_slices(recording, **random_slices_kwargs)
 
         noise_levels_chunks = []
+
         def append_noise_chunk(res):
             noise_levels_chunks.append(res)
 
@@ -801,8 +797,14 @@ def append_noise_chunk(res):
         init_func = _noise_level_chunk_init
         init_args = (recording, return_scaled, method)
         executor = ChunkRecordingExecutor(
-            recording, func, init_func, init_args, job_name="noise_level", verbose=False,
-            gather_func=append_noise_chunk, **job_kwargs
+            recording,
+            func,
+            init_func,
+            init_args,
+            job_name="noise_level",
+            verbose=False,
+            gather_func=append_noise_chunk,
+            **job_kwargs,
         )
         executor.run(all_chunks=recording_slices)
         noise_levels_chunks = np.stack(noise_levels_chunks)
@@ -813,6 +815,7 @@ def append_noise_chunk(res):
 
     return noise_levels
 
+
 get_noise_levels.__doc__ = get_noise_levels.__doc__.format(_shared_job_kwargs_doc)
 
 
diff --git a/src/spikeinterface/core/tests/test_analyzer_extension_core.py b/src/spikeinterface/core/tests/test_analyzer_extension_core.py
index b04155261b..6f5bef3c6c 100644
--- a/src/spikeinterface/core/tests/test_analyzer_extension_core.py
+++ b/src/spikeinterface/core/tests/test_analyzer_extension_core.py
@@ -259,7 +259,7 @@ def test_compute_several(create_cache_folder):
     # test_ComputeWaveforms(format="binary_folder", sparse=False, create_cache_folder=cache_folder)
     # test_ComputeWaveforms(format="zarr", sparse=True, create_cache_folder=cache_folder)
     # test_ComputeWaveforms(format="zarr", sparse=False, create_cache_folder=cache_folder)
-    #test_ComputeRandomSpikes(format="memory", sparse=True, create_cache_folder=cache_folder)
+    # test_ComputeRandomSpikes(format="memory", sparse=True, create_cache_folder=cache_folder)
     test_ComputeRandomSpikes(format="binary_folder", sparse=False, create_cache_folder=cache_folder)
     test_ComputeTemplates(format="memory", sparse=True, create_cache_folder=cache_folder)
     test_ComputeNoiseLevels(format="memory", sparse=False, create_cache_folder=cache_folder)
diff --git a/src/spikeinterface/core/tests/test_recording_tools.py b/src/spikeinterface/core/tests/test_recording_tools.py
index 1fa9ffe124..dad5273f12 100644
--- a/src/spikeinterface/core/tests/test_recording_tools.py
+++ b/src/spikeinterface/core/tests/test_recording_tools.py
@@ -167,19 +167,18 @@ def test_write_memory_recording():
     for shm in shms:
         shm.unlink()
 
+
 def test_get_random_recording_slices():
     rec = generate_recording(num_channels=1, sampling_frequency=1000.0, durations=[10.0, 20.0])
-    rec_slices = get_random_recording_slices(rec,
-                                method="full_random",
-                                num_chunks_per_segment=20,
-                                chunk_duration="500ms",
-                                margin_frames=0,
-                                seed=0)
+    rec_slices = get_random_recording_slices(
+        rec, method="full_random", num_chunks_per_segment=20, chunk_duration="500ms", margin_frames=0, seed=0
+    )
     assert len(rec_slices) == 40
     for seg_ind, start, stop in rec_slices:
         assert stop - start == 500
         assert seg_ind in (0, 1)
 
+
 def test_get_random_data_chunks():
     rec = generate_recording(num_channels=1, sampling_frequency=1000.0, durations=[10.0, 20.0])
     chunks = get_random_data_chunks(rec, num_chunks_per_segment=50, chunk_size=500, seed=0)
@@ -216,7 +215,9 @@ def test_get_noise_levels():
 
     assert np.all(noise_levels_1 == noise_levels_2)
     assert np.allclose(get_noise_levels(recording, return_scaled=False, **job_kwargs), [std, std], rtol=1e-2, atol=1e-3)
-    assert np.allclose(get_noise_levels(recording, method="std", return_scaled=False, **job_kwargs), [std, std], rtol=1e-2, atol=1e-3)
+    assert np.allclose(
+        get_noise_levels(recording, method="std", return_scaled=False, **job_kwargs), [std, std], rtol=1e-2, atol=1e-3
+    )
 
 
 def test_get_noise_levels_output():
@@ -230,13 +231,21 @@ def test_get_noise_levels_output():
     traces = rng.normal(loc=10.0, scale=std, size=(num_samples, num_channels))
     recording = NumpyRecording(traces_list=traces, sampling_frequency=sampling_frequency)
 
-    std_estimated_with_mad = get_noise_levels(recording, method="mad", return_scaled=False,
-                                              random_slices_kwargs=dict(num_chunks_per_segment=40, chunk_size=1_000, seed=seed))
+    std_estimated_with_mad = get_noise_levels(
+        recording,
+        method="mad",
+        return_scaled=False,
+        random_slices_kwargs=dict(num_chunks_per_segment=40, chunk_size=1_000, seed=seed),
+    )
     print(std_estimated_with_mad)
     assert np.allclose(std_estimated_with_mad, [std, std], rtol=1e-2, atol=1e-3)
 
-    std_estimated_with_std = get_noise_levels(recording, method="std", return_scaled=False,
-                                              random_slices_kwargs=dict(num_chunks_per_segment=40, chunk_size=1_000, seed=seed))
+    std_estimated_with_std = get_noise_levels(
+        recording,
+        method="std",
+        return_scaled=False,
+        random_slices_kwargs=dict(num_chunks_per_segment=40, chunk_size=1_000, seed=seed),
+    )
     assert np.allclose(std_estimated_with_std, [std, std], rtol=1e-2, atol=1e-3)
 
 
@@ -358,8 +367,8 @@ def test_do_recording_attributes_match():
     # test_write_memory_recording()
 
     test_get_random_recording_slices()
-    # test_get_random_data_chunks()
+    # test_get_random_data_chunks()
     # test_get_closest_channels()
     # test_get_noise_levels()
-    # test_get_noise_levels_output()
+    # test_get_noise_levels_output()
     # test_order_channels_by_depth()
diff --git a/src/spikeinterface/preprocessing/tests/test_silence.py b/src/spikeinterface/preprocessing/tests/test_silence.py
index 6405b6b0c4..20d4f6dfc7 100644
--- a/src/spikeinterface/preprocessing/tests/test_silence.py
+++ b/src/spikeinterface/preprocessing/tests/test_silence.py
@@ -48,5 +48,5 @@ def test_silence(create_cache_folder):
 
 
 if __name__ == "__main__":
-    cache_folder = Path(__file__).resolve().parents[4] / "cache_folder" 
+    cache_folder = Path(__file__).resolve().parents[4] / "cache_folder"
     test_silence(cache_folder)
diff --git a/src/spikeinterface/preprocessing/tests/test_whiten.py b/src/spikeinterface/preprocessing/tests/test_whiten.py
index 3444323488..b40627d836 100644
--- a/src/spikeinterface/preprocessing/tests/test_whiten.py
+++ b/src/spikeinterface/preprocessing/tests/test_whiten.py
@@ -49,5 +49,5 @@ def test_whiten(create_cache_folder):
 
 
 if __name__ == "__main__":
-    cache_folder = Path(__file__).resolve().parents[4] / "cache_folder" 
+    cache_folder = Path(__file__).resolve().parents[4] / "cache_folder"
     test_whiten(cache_folder)

From f66ae7fc9c6cf66c5ca35d11dddedfbb2180080d Mon Sep 17 00:00:00 2001
From: JoeZiminski <joseph.j.ziminski@gmail.com>
Date: Fri, 25 Oct 2024 08:28:41 +0100
Subject: [PATCH 139/344] Compute covariance matrix in float64.

---
 src/spikeinterface/preprocessing/whiten.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/spikeinterface/preprocessing/whiten.py b/src/spikeinterface/preprocessing/whiten.py
index 195969ff79..91c74c423f 100644
--- a/src/spikeinterface/preprocessing/whiten.py
+++ b/src/spikeinterface/preprocessing/whiten.py
@@ -124,7 +124,7 @@ def __init__(self, parent_recording_segment, W, M, dtype, int_scale):
     def get_traces(self, start_frame, end_frame, channel_indices):
         traces = self.parent_recording_segment.get_traces(start_frame, end_frame, slice(None))
         traces_dtype = traces.dtype
-        # if uint --> force int
+        # if uint --> force float
         if traces_dtype.kind == "u":
             traces = traces.astype("float32")
 
@@ -185,6 +185,7 @@ def compute_whitening_matrix(
 
     """
     random_data = get_random_data_chunks(recording, concatenated=True, return_scaled=False, **random_chunk_kwargs)
+    random_data = random_data.astype(np.float64)
 
     regularize_kwargs = regularize_kwargs if regularize_kwargs is not None else {"method": "GraphicalLassoCV"}
 

From b5c260aed812d6fb6202ffdf13d35e28d79ff4e9 Mon Sep 17 00:00:00 2001
From: JoeZiminski <joseph.j.ziminski@gmail.com>
Date: Fri, 25 Oct 2024 09:16:26 +0100
Subject: [PATCH 140/344] Update docstring.

---
 src/spikeinterface/preprocessing/whiten.py | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/spikeinterface/preprocessing/whiten.py b/src/spikeinterface/preprocessing/whiten.py
index 91c74c423f..1c81f2ae42 100644
--- a/src/spikeinterface/preprocessing/whiten.py
+++ b/src/spikeinterface/preprocessing/whiten.py
@@ -19,6 +19,8 @@ class WhitenRecording(BasePreprocessor):
     recording : RecordingExtractor
         The recording extractor to be whitened.
     dtype : None or dtype, default: None
+        Datatype of the output recording (covariance matrix estimation
+        and whitening are performed in float64.
         If None the the parent dtype is kept.
         For integer dtype a int_scale must be also given.
     mode : "global" | "local", default: "global"
@@ -74,7 +76,8 @@ def __init__(
         dtype_ = fix_dtype(recording, dtype)
 
         if dtype_.kind == "i":
-            assert int_scale is not None, "For recording with dtype=int you must set dtype=float32 OR set a int_scale"
+            assert int_scale is not None, ("For recording with dtype=int you must set the output dtype to float "
+                                           " OR set a int_scale")
 
         if W is not None:
             W = np.asarray(W)

From 18cfb2b385d9cf5e18d622097a41631d94a0e9a8 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Fri, 25 Oct 2024 08:18:56 +0000
Subject: [PATCH 141/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/preprocessing/whiten.py | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/preprocessing/whiten.py b/src/spikeinterface/preprocessing/whiten.py
index 1c81f2ae42..4e3135c3e9 100644
--- a/src/spikeinterface/preprocessing/whiten.py
+++ b/src/spikeinterface/preprocessing/whiten.py
@@ -76,8 +76,9 @@ def __init__(
         dtype_ = fix_dtype(recording, dtype)
 
         if dtype_.kind == "i":
-            assert int_scale is not None, ("For recording with dtype=int you must set the output dtype to float "
-                                           " OR set a int_scale")
+            assert int_scale is not None, (
+                "For recording with dtype=int you must set the output dtype to float " " OR set a int_scale"
+            )
 
         if W is not None:
             W = np.asarray(W)

From 98e5db95aa36a415d520cfe758113fc7c5db9bac Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Fri, 25 Oct 2024 10:42:58 +0200
Subject: [PATCH 142/344] recording_slices in run_node_pipeline()

---
 src/spikeinterface/core/job_tools.py          | 22 +++++++++---------
 src/spikeinterface/core/node_pipeline.py      |  7 +++++-
 src/spikeinterface/core/recording_tools.py    |  2 +-
 .../core/tests/test_node_pipeline.py          | 23 +++++++++++++++----
 .../sortingcomponents/peak_detection.py       |  6 +++++
 5 files changed, 42 insertions(+), 18 deletions(-)

diff --git a/src/spikeinterface/core/job_tools.py b/src/spikeinterface/core/job_tools.py
index 27f05bb36b..7a6172369b 100644
--- a/src/spikeinterface/core/job_tools.py
+++ b/src/spikeinterface/core/job_tools.py
@@ -149,12 +149,12 @@ def divide_segment_into_chunks(num_frames, chunk_size):
 
 
 def divide_recording_into_chunks(recording, chunk_size):
-    all_chunks = []
+    recording_slices = []
     for segment_index in range(recording.get_num_segments()):
         num_frames = recording.get_num_samples(segment_index)
         chunks = divide_segment_into_chunks(num_frames, chunk_size)
-        all_chunks.extend([(segment_index, frame_start, frame_stop) for frame_start, frame_stop in chunks])
-    return all_chunks
+        recording_slices.extend([(segment_index, frame_start, frame_stop) for frame_start, frame_stop in chunks])
+    return recording_slices
 
 
 def ensure_n_jobs(recording, n_jobs=1):
@@ -387,13 +387,13 @@ def __init__(
                 f"chunk_duration={chunk_duration_str}",
             )
 
-    def run(self, all_chunks=None):
+    def run(self, recording_slices=None):
         """
         Runs the defined jobs.
         """
 
-        if all_chunks is None:
-            all_chunks = divide_recording_into_chunks(self.recording, self.chunk_size)
+        if recording_slices is None:
+            recording_slices = divide_recording_into_chunks(self.recording, self.chunk_size)
 
         if self.handle_returns:
             returns = []
@@ -402,17 +402,17 @@ def run(self, all_chunks=None):
 
         if self.n_jobs == 1:
             if self.progress_bar:
-                all_chunks = tqdm(all_chunks, ascii=True, desc=self.job_name)
+                recording_slices = tqdm(recording_slices, ascii=True, desc=self.job_name)
 
             worker_ctx = self.init_func(*self.init_args)
-            for segment_index, frame_start, frame_stop in all_chunks:
+            for segment_index, frame_start, frame_stop in recording_slices:
                 res = self.func(segment_index, frame_start, frame_stop, worker_ctx)
                 if self.handle_returns:
                     returns.append(res)
                 if self.gather_func is not None:
                     self.gather_func(res)
         else:
-            n_jobs = min(self.n_jobs, len(all_chunks))
+            n_jobs = min(self.n_jobs, len(recording_slices))
 
             # parallel
             with ProcessPoolExecutor(
@@ -421,10 +421,10 @@ def run(self, all_chunks=None):
                 mp_context=mp.get_context(self.mp_context),
                 initargs=(self.func, self.init_func, self.init_args, self.max_threads_per_process),
             ) as executor:
-                results = executor.map(function_wrapper, all_chunks)
+                results = executor.map(function_wrapper, recording_slices)
 
                 if self.progress_bar:
-                    results = tqdm(results, desc=self.job_name, total=len(all_chunks))
+                    results = tqdm(results, desc=self.job_name, total=len(recording_slices))
 
                 for res in results:
                     if self.handle_returns:
diff --git a/src/spikeinterface/core/node_pipeline.py b/src/spikeinterface/core/node_pipeline.py
index d90a20902d..8ca4ba7f3a 100644
--- a/src/spikeinterface/core/node_pipeline.py
+++ b/src/spikeinterface/core/node_pipeline.py
@@ -489,6 +489,7 @@ def run_node_pipeline(
     names=None,
     verbose=False,
     skip_after_n_peaks=None,
+    recording_slices=None,
 ):
     """
     Machinery to compute in parallel operations on peaks and traces.
@@ -540,6 +541,10 @@ def run_node_pipeline(
     skip_after_n_peaks : None | int
         Skip the computation after n_peaks.
         This is not an exact because internally this skip is done per worker in average.
+    recording_slices : None | list[tuple]
+        Optionaly give a list of slices to run the pipeline only on some chunks of the recording.
+        It must be a list of (segment_index, frame_start, frame_stop).
+        If None (default), the entire recording is computed.
 
     Returns
     -------
@@ -578,7 +583,7 @@ def run_node_pipeline(
         **job_kwargs,
     )
 
-    processor.run()
+    processor.run(recording_slices=recording_slices)
 
     outs = gather_func.finalize_buffers(squeeze_output=squeeze_output)
     return outs
diff --git a/src/spikeinterface/core/recording_tools.py b/src/spikeinterface/core/recording_tools.py
index 2ab74ce51e..4aabbfd587 100644
--- a/src/spikeinterface/core/recording_tools.py
+++ b/src/spikeinterface/core/recording_tools.py
@@ -806,7 +806,7 @@ def append_noise_chunk(res):
             gather_func=append_noise_chunk,
             **job_kwargs,
         )
-        executor.run(all_chunks=recording_slices)
+        executor.run(recording_slices=recording_slices)
         noise_levels_chunks = np.stack(noise_levels_chunks)
         noise_levels = np.mean(noise_levels_chunks, axis=0)
 
diff --git a/src/spikeinterface/core/tests/test_node_pipeline.py b/src/spikeinterface/core/tests/test_node_pipeline.py
index deef2291c6..400a71c424 100644
--- a/src/spikeinterface/core/tests/test_node_pipeline.py
+++ b/src/spikeinterface/core/tests/test_node_pipeline.py
@@ -4,7 +4,7 @@
 import shutil
 
 from spikeinterface import create_sorting_analyzer, get_template_extremum_channel, generate_ground_truth_recording
-
+from spikeinterface.core.job_tools import divide_recording_into_chunks
 
 # from spikeinterface.sortingcomponents.peak_detection import detect_peaks
 from spikeinterface.core.node_pipeline import (
@@ -191,8 +191,8 @@ def test_run_node_pipeline(cache_folder_creation):
             unpickled_node = pickle.loads(pickled_node)
 
 
-def test_skip_after_n_peaks():
-    recording, sorting = generate_ground_truth_recording(num_channels=10, num_units=10, durations=[10.0])
+def test_skip_after_n_peaks_and_recording_slices():
+    recording, sorting = generate_ground_truth_recording(num_channels=10, num_units=10, durations=[10.0], seed=2205)
 
     # job_kwargs = dict(chunk_duration="0.5s", n_jobs=2, progress_bar=False)
     job_kwargs = dict(chunk_duration="0.5s", n_jobs=1, progress_bar=False)
@@ -211,18 +211,31 @@ def test_skip_after_n_peaks():
     node1 = AmplitudeExtractionNode(recording, parents=[node0], param0=6.6, return_output=True)
     nodes = [node0, node1]
 
+    # skip
     skip_after_n_peaks = 30
     some_amplitudes = run_node_pipeline(
         recording, nodes, job_kwargs, gather_mode="memory", skip_after_n_peaks=skip_after_n_peaks
     )
-
     assert some_amplitudes.size >= skip_after_n_peaks
     assert some_amplitudes.size < spikes.size
 
+    # slices : 1 every 4
+    recording_slices = divide_recording_into_chunks(recording, 10_000)
+    recording_slices = recording_slices[::4]
+    some_amplitudes = run_node_pipeline(
+        recording, nodes, job_kwargs, gather_mode="memory", recording_slices=recording_slices
+    )
+    tolerance = 1.2
+    assert some_amplitudes.size < (spikes.size // 4) * tolerance
+
+
+    
+
+
 
 # the following is for testing locally with python or ipython. It is not used in ci or with pytest.
 if __name__ == "__main__":
     # folder = Path("./cache_folder/core")
     # test_run_node_pipeline(folder)
 
-    test_skip_after_n_peaks()
+    test_skip_after_n_peaks_and_recording_slices()
diff --git a/src/spikeinterface/sortingcomponents/peak_detection.py b/src/spikeinterface/sortingcomponents/peak_detection.py
index 5b1d33b334..233b16dcf7 100644
--- a/src/spikeinterface/sortingcomponents/peak_detection.py
+++ b/src/spikeinterface/sortingcomponents/peak_detection.py
@@ -57,6 +57,7 @@ def detect_peaks(
     folder=None,
     names=None,
     skip_after_n_peaks=None,
+    recording_slices=None,
     **kwargs,
 ):
     """Peak detection based on threshold crossing in term of k x MAD.
@@ -83,6 +84,10 @@ def detect_peaks(
     skip_after_n_peaks : None | int
         Skip the computation after n_peaks.
         This is not an exact because internally this skip is done per worker in average.
+    recording_slices : None | list[tuple]
+        Optionaly give a list of slices to run the pipeline only on some chunks of the recording.
+        It must be a list of (segment_index, frame_start, frame_stop).
+        If None (default), the entire recording is computed.
 
     {method_doc}
     {job_doc}
@@ -135,6 +140,7 @@ def detect_peaks(
         folder=folder,
         names=names,
         skip_after_n_peaks=skip_after_n_peaks,
+        recording_slices=recording_slices,
     )
     return outs
 

From aaa689fa9174e8576550528224431b9ea3e32759 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Fri, 25 Oct 2024 08:47:02 +0000
Subject: [PATCH 143/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/core/tests/test_node_pipeline.py | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/src/spikeinterface/core/tests/test_node_pipeline.py b/src/spikeinterface/core/tests/test_node_pipeline.py
index 400a71c424..028eaecf12 100644
--- a/src/spikeinterface/core/tests/test_node_pipeline.py
+++ b/src/spikeinterface/core/tests/test_node_pipeline.py
@@ -229,10 +229,6 @@ def test_skip_after_n_peaks_and_recording_slices():
     assert some_amplitudes.size < (spikes.size // 4) * tolerance
 
 
-    
-
-
-
 # the following is for testing locally with python or ipython. It is not used in ci or with pytest.
 if __name__ == "__main__":
     # folder = Path("./cache_folder/core")

From 3406f85ba35209dd557ca9c0b0c15c5c84219e7a Mon Sep 17 00:00:00 2001
From: Zach McKenzie <92116279+zm711@users.noreply.github.com>
Date: Fri, 25 Oct 2024 06:39:35 -0400
Subject: [PATCH 144/344] Joe's comments

Co-authored-by: Joe Ziminski <55797454+JoeZiminski@users.noreply.github.com>
---
 src/spikeinterface/core/analyzer_extension_core.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/core/analyzer_extension_core.py b/src/spikeinterface/core/analyzer_extension_core.py
index 2d9924554c..55e0e34dcc 100644
--- a/src/spikeinterface/core/analyzer_extension_core.py
+++ b/src/spikeinterface/core/analyzer_extension_core.py
@@ -28,7 +28,7 @@ class ComputeRandomSpikes(AnalyzerExtension):
 
     This will be used by the `waveforms`/`templates` extensions.
 
-    This internally use `random_spikes_selection()` parameters.
+    This internally uses `random_spikes_selection()` parameters.
 
     Parameters
     ----------
@@ -106,7 +106,7 @@ def get_random_spikes(self):
         return self._some_spikes
 
     def get_selected_indices_in_spike_train(self, unit_id, segment_index):
-        # useful for Waveforms extractor backwars compatibility
+        # useful for WaveformExtractor backwards compatibility
         # In Waveforms extractor "selected_spikes" was a dict (key: unit_id) of list (segment_index) of indices of spikes in spiketrain
         sorting = self.sorting_analyzer.sorting
         random_spikes_indices = self.data["random_spikes_indices"]

From f0f7f6c7165b76f07706254597c5e0730691789a Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Mon, 28 Oct 2024 10:16:27 +0100
Subject: [PATCH 145/344] Update src/spikeinterface/curation/auto_merge.py

Co-authored-by: Alessio Buccino <alejoe9187@gmail.com>
---
 src/spikeinterface/curation/auto_merge.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/spikeinterface/curation/auto_merge.py b/src/spikeinterface/curation/auto_merge.py
index ec5e8be20c..73b69426f1 100644
--- a/src/spikeinterface/curation/auto_merge.py
+++ b/src/spikeinterface/curation/auto_merge.py
@@ -154,7 +154,8 @@ def compute_merge_unit_groups(
         Pontential steps : "num_spikes", "snr", "remove_contaminated", "unit_locations", "correlogram",
         "template_similarity", "presence_distance", "cross_contamination", "knn", "quality_score"
         Please check steps explanations above!
-    steps_params : A dictionary whose keys are the steps, and keys are steps parameters.
+    steps_params : dict
+        A dictionary whose keys are the steps, and keys are steps parameters.
     force_copy : boolean, default: True
         When new extensions are computed, the default is to make a copy of the analyzer, to avoid overwriting
         already computed extensions. False if you want to overwrite

From 0dd48c424e437e9729af16f44101e881ba1d968e Mon Sep 17 00:00:00 2001
From: Sebastien <pierre.yger@gmail.com>
Date: Mon, 28 Oct 2024 10:27:17 +0100
Subject: [PATCH 146/344] Typos and signatures

---
 src/spikeinterface/curation/auto_merge.py | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/src/spikeinterface/curation/auto_merge.py b/src/spikeinterface/curation/auto_merge.py
index 73b69426f1..6680a70af4 100644
--- a/src/spikeinterface/curation/auto_merge.py
+++ b/src/spikeinterface/curation/auto_merge.py
@@ -19,7 +19,7 @@
 from .mergeunitssorting import MergeUnitsSorting
 from .curation_tools import resolve_merging_graph
 
-_compute_merge_persets = {
+_compute_merge_presets = {
     "similarity_correlograms": [
         "num_spikes",
         "remove_contaminated",
@@ -146,7 +146,7 @@ def compute_merge_unit_groups(
     resolve_graph : bool, default: True
         If True, the function resolves the potential unit pairs to be merged into multiple-unit merges.
     compute_needed_extensions : bool, default : True
-        Should we force the computation of needed extensions?
+        Should we force the computation of needed extensions, if not already computed?
     extra_outputs : bool, default: False
         If True, an additional dictionary (`outs`) with processed data is returned.
     steps : None or list of str, default: None
@@ -172,9 +172,11 @@ def compute_merge_unit_groups(
 
     References
     ----------
-    This function is inspired and built upon similar functions from Lussac [Llobet]_,
+    This function used to be inspired and built upon similar functions from Lussac [Llobet]_,
     done by Aurelien Wyngaard and Victor Llobet.
     https://github.com/BarbourLab/lussac/blob/v1.0.0/postprocessing/merge_units.py
+
+    However, it has been greatly consolidated and refined depending on the presets.
     """
     import scipy
 
@@ -187,11 +189,11 @@ def compute_merge_unit_groups(
         # steps has presendance on presets
         pass
     elif preset is not None:
-        if preset not in _compute_merge_persets:
-            raise ValueError(f"preset must be one of {list(_compute_merge_persets.keys())}")
-        steps = _compute_merge_persets[preset]
+        if preset not in _compute_merge_presets:
+            raise ValueError(f"preset must be one of {list(_compute_merge_presets.keys())}")
+        steps = _compute_merge_presets[preset]
 
-    if force_copy and compute_needed_extensions:
+    if force_copy:
         # To avoid erasing the extensions of the user
         sorting_analyzer = sorting_analyzer.copy()
 
@@ -357,7 +359,7 @@ def compute_merge_unit_groups(
         return merge_unit_groups
 
 
-def auto_merge(
+def auto_merge_units(
     sorting_analyzer: SortingAnalyzer, compute_merge_kwargs: dict = {}, apply_merge_kwargs: dict = {}, **job_kwargs
 ) -> SortingAnalyzer:
     """

From a0587f6e04a210fe6bbde62e8b759176c69a47c3 Mon Sep 17 00:00:00 2001
From: Sebastien <pierre.yger@gmail.com>
Date: Mon, 28 Oct 2024 10:30:35 +0100
Subject: [PATCH 147/344] Cleaning requiered extensions

---
 src/spikeinterface/curation/auto_merge.py | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/src/spikeinterface/curation/auto_merge.py b/src/spikeinterface/curation/auto_merge.py
index 6680a70af4..52dffc0378 100644
--- a/src/spikeinterface/curation/auto_merge.py
+++ b/src/spikeinterface/curation/auto_merge.py
@@ -57,10 +57,9 @@
 _required_extensions = {
     "unit_locations": ["templates", "unit_locations"],
     "correlogram": ["correlograms"],
-    "snr": ["templates", "noise_levels", "templates"],
+    "snr": ["templates", "noise_levels"],
     "template_similarity": ["templates", "template_similarity"],
-    "knn": ["templates", "spike_locations", "spike_amplitudes"],
-    "spike_amplitudes": ["templates"],
+    "knn": ["templates", "spike_locations", "spike_amplitudes"]
 }
 
 

From f22a4cc95a690ee5c0d89608a79c93d9207ca2be Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 28 Oct 2024 09:31:21 +0000
Subject: [PATCH 148/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/curation/auto_merge.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/curation/auto_merge.py b/src/spikeinterface/curation/auto_merge.py
index 52dffc0378..dfcd7bbb17 100644
--- a/src/spikeinterface/curation/auto_merge.py
+++ b/src/spikeinterface/curation/auto_merge.py
@@ -59,7 +59,7 @@
     "correlogram": ["correlograms"],
     "snr": ["templates", "noise_levels"],
     "template_similarity": ["templates", "template_similarity"],
-    "knn": ["templates", "spike_locations", "spike_amplitudes"]
+    "knn": ["templates", "spike_locations", "spike_amplitudes"],
 }
 
 

From 516acc9dda2c55bd5014f3ac4cee4350d3940607 Mon Sep 17 00:00:00 2001
From: Sebastien <pierre.yger@gmail.com>
Date: Mon, 28 Oct 2024 12:14:46 +0100
Subject: [PATCH 149/344] Names

---
 src/spikeinterface/curation/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/curation/__init__.py b/src/spikeinterface/curation/__init__.py
index 579e47a553..0302ffe5b7 100644
--- a/src/spikeinterface/curation/__init__.py
+++ b/src/spikeinterface/curation/__init__.py
@@ -3,7 +3,7 @@
 from .remove_redundant import remove_redundant_units, find_redundant_units
 from .remove_duplicated_spikes import remove_duplicated_spikes
 from .remove_excess_spikes import remove_excess_spikes
-from .auto_merge import compute_merge_unit_groups, auto_merge, get_potential_auto_merge
+from .auto_merge import compute_merge_unit_groups, auto_merge_units, get_potential_auto_merge
 
 
 # manual sorting,

From f55a9405040310064f716015f8d9b0c976b97923 Mon Sep 17 00:00:00 2001
From: JoeZiminski <joseph.j.ziminski@gmail.com>
Date: Mon, 28 Oct 2024 14:28:05 +0000
Subject: [PATCH 150/344] Add 'shift start time' function.

---
 src/spikeinterface/core/baserecording.py | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/src/spikeinterface/core/baserecording.py b/src/spikeinterface/core/baserecording.py
index 5e2e9e4014..b8a0420794 100644
--- a/src/spikeinterface/core/baserecording.py
+++ b/src/spikeinterface/core/baserecording.py
@@ -509,6 +509,26 @@ def reset_times(self):
             rs.t_start = None
             rs.sampling_frequency = self.sampling_frequency
 
+    def shift_start_time(self, shift, segment_index=None):
+        """
+        Shift the starting time of the times.
+
+        shift : int | float
+            The shift to apply to the first time point. If positive,
+            the current start time will be increased by `shift`. If
+            negative, the start time will be decreased.
+
+        segment_index : int | None
+            The segment on which to shift the times.
+        """
+        segment_index = self._check_segment_index(segment_index)
+        rs = self._recording_segments[segment_index]
+
+        if self.has_time_vector():
+            rs.time_vector += shift
+        else:
+            rs.t_start += shift
+
     def sample_index_to_time(self, sample_ind, segment_index=None):
         """
         Transform sample index into time in seconds

From d17181f3bd68f602780ad99e1b618aa3f793b8ad Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Tue, 29 Oct 2024 13:08:56 +0100
Subject: [PATCH 151/344] Update src/spikeinterface/preprocessing/whiten.py

---
 src/spikeinterface/preprocessing/whiten.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/preprocessing/whiten.py b/src/spikeinterface/preprocessing/whiten.py
index 4e3135c3e9..505e8a330a 100644
--- a/src/spikeinterface/preprocessing/whiten.py
+++ b/src/spikeinterface/preprocessing/whiten.py
@@ -20,7 +20,7 @@ class WhitenRecording(BasePreprocessor):
         The recording extractor to be whitened.
     dtype : None or dtype, default: None
         Datatype of the output recording (covariance matrix estimation
-        and whitening are performed in float64.
+        and whitening are performed in float64).
         If None the the parent dtype is kept.
         For integer dtype a int_scale must be also given.
     mode : "global" | "local", default: "global"

From 7c953c2b1347dfbbb4058f5a9b7462f90d22c1dd Mon Sep 17 00:00:00 2001
From: chrishalcrow <57948917+chrishalcrow@users.noreply.github.com>
Date: Tue, 29 Oct 2024 12:19:26 +0000
Subject: [PATCH 152/344] Respond to Joe; add template_similarity check

---
 src/spikeinterface/exporters/report.py     |  8 +--
 src/spikeinterface/widgets/unit_summary.py | 82 +++++++++++-----------
 2 files changed, 45 insertions(+), 45 deletions(-)

diff --git a/src/spikeinterface/exporters/report.py b/src/spikeinterface/exporters/report.py
index 3a4be9213a..484da83342 100644
--- a/src/spikeinterface/exporters/report.py
+++ b/src/spikeinterface/exporters/report.py
@@ -20,10 +20,10 @@ def export_report(
     **job_kwargs,
 ):
     """
-    Exports a SI spike sorting report. The report includes summary figures of the spike sorting output
-    (e.g. amplitude distributions, unit localization and depth VS amplitude) as well as unit-specific reports,
-    that include waveforms, templates, template maps, ISI distributions, and more.
-
+    Exports a SI spike sorting report. The report includes summary figures of the spike sorting output.
+    What is plotted depends on what has been calculated. Unit locations and unit waveforms are always included.
+    Unit waveform densities, correlograms and spike amplitudes are plotted if `waveforms`, `correlograms`
+    and 'template_similarity', and `spike_amplitudes` have been computed for the given `sorting_analyzer`.
 
     Parameters
     ----------
diff --git a/src/spikeinterface/widgets/unit_summary.py b/src/spikeinterface/widgets/unit_summary.py
index 8aea6fd690..d8cbeb7bb3 100644
--- a/src/spikeinterface/widgets/unit_summary.py
+++ b/src/spikeinterface/widgets/unit_summary.py
@@ -108,7 +108,7 @@ def plot_matplotlib(self, data_plot, **backend_kwargs):
         fig = self.figure
         nrows = 2
         ncols = 2
-        if sorting_analyzer.has_extension("correlograms") or sorting_analyzer.has_extension("spike_amplitudes"):
+        if sorting_analyzer.has_extension("correlograms") and sorting_analyzer.has_extension("template_similarity"):
             ncols += 1
         if sorting_analyzer.has_extension("waveforms"):
             ncols += 1
@@ -117,31 +117,30 @@ def plot_matplotlib(self, data_plot, **backend_kwargs):
         gs = fig.add_gridspec(nrows, ncols)
         col_counter = 0
 
-        if sorting_analyzer.has_extension("unit_locations"):
-            ax1 = fig.add_subplot(gs[:2, col_counter])
-            # UnitLocationsPlotter().do_plot(dp.plot_data_unit_locations, ax=ax1)
-            w = UnitLocationsWidget(
-                sorting_analyzer,
-                unit_ids=[unit_id],
-                unit_colors=unit_colors,
-                plot_legend=False,
-                backend="matplotlib",
-                ax=ax1,
-                **unitlocationswidget_kwargs,
-            )
-            col_counter = col_counter + 1
-
-            unit_locations = sorting_analyzer.get_extension("unit_locations").get_data(outputs="by_unit")
-            unit_location = unit_locations[unit_id]
-            x, y = unit_location[0], unit_location[1]
-            ax1.set_xlim(x - 80, x + 80)
-            ax1.set_ylim(y - 250, y + 250)
-            ax1.set_xticks([])
-            ax1.set_xlabel(None)
-            ax1.set_ylabel(None)
-
-        ax2 = fig.add_subplot(gs[:2, col_counter])
-        w = UnitWaveformsWidget(
+        # Unit locations and unit waveform plots are always generated
+        ax_unit_locations = fig.add_subplot(gs[:2, col_counter])
+        _ = UnitLocationsWidget(
+            sorting_analyzer,
+            unit_ids=[unit_id],
+            unit_colors=unit_colors,
+            plot_legend=False,
+            backend="matplotlib",
+            ax=ax_unit_locations,
+            **unitlocationswidget_kwargs,
+        )
+        col_counter += 1
+
+        unit_locations = sorting_analyzer.get_extension("unit_locations").get_data(outputs="by_unit")
+        unit_location = unit_locations[unit_id]
+        x, y = unit_location[0], unit_location[1]
+        ax_unit_locations.set_xlim(x - 80, x + 80)
+        ax_unit_locations.set_ylim(y - 250, y + 250)
+        ax_unit_locations.set_xticks([])
+        ax_unit_locations.set_xlabel(None)
+        ax_unit_locations.set_ylabel(None)
+
+        ax_unit_waveforms = fig.add_subplot(gs[:2, col_counter])
+        _ = UnitWaveformsWidget(
             sorting_analyzer,
             unit_ids=[unit_id],
             unit_colors=unit_colors,
@@ -151,15 +150,15 @@ def plot_matplotlib(self, data_plot, **backend_kwargs):
             plot_legend=False,
             sparsity=sparsity,
             backend="matplotlib",
-            ax=ax2,
+            ax=ax_unit_waveforms,
             **unitwaveformswidget_kwargs,
         )
-        col_counter = col_counter + 1
+        col_counter += 1
 
-        ax2.set_title(None)
+        ax_unit_waveforms.set_title(None)
 
         if sorting_analyzer.has_extension("waveforms"):
-            ax3 = fig.add_subplot(gs[:2, col_counter])
+            ax_waveform_density = fig.add_subplot(gs[:2, col_counter])
             UnitWaveformDensityMapWidget(
                 sorting_analyzer,
                 unit_ids=[unit_id],
@@ -167,30 +166,31 @@ def plot_matplotlib(self, data_plot, **backend_kwargs):
                 use_max_channel=True,
                 same_axis=False,
                 backend="matplotlib",
-                ax=ax3,
+                ax=ax_waveform_density,
                 **unitwaveformdensitymapwidget_kwargs,
             )
-            ax3.set_ylabel(None)
-            col_counter = col_counter + 1
+            col_counter += 1
+            ax_waveform_density.set_ylabel(None)
 
-        if sorting_analyzer.has_extension("correlograms"):
-            ax4 = fig.add_subplot(gs[:2, col_counter])
+        if sorting_analyzer.has_extension("correlograms") and sorting_analyzer.has_extension("template_similarity"):
+            ax_correlograms = fig.add_subplot(gs[:2, col_counter])
             AutoCorrelogramsWidget(
                 sorting_analyzer,
                 unit_ids=[unit_id],
                 unit_colors=unit_colors,
                 backend="matplotlib",
-                ax=ax4,
+                ax=ax_correlograms,
                 **autocorrelogramswidget_kwargs,
             )
+            col_counter += 1
 
-            ax4.set_title(None)
-            ax4.set_yticks([])
+            ax_correlograms.set_title(None)
+            ax_correlograms.set_yticks([])
 
         if sorting_analyzer.has_extension("spike_amplitudes"):
-            ax5 = fig.add_subplot(gs[2, :col_counter])
-            ax6 = fig.add_subplot(gs[2, col_counter])
-            axes = np.array([ax5, ax6])
+            ax_spike_amps = fig.add_subplot(gs[2, : col_counter - 1])
+            ax_amps_distribution = fig.add_subplot(gs[2, col_counter - 1])
+            axes = np.array([ax_spike_amps, ax_amps_distribution])
             AmplitudesWidget(
                 sorting_analyzer,
                 unit_ids=[unit_id],

From 78738ef679ebf8de5c4a16769aa879e51f68cf29 Mon Sep 17 00:00:00 2001
From: Sebastien <pierre.yger@gmail.com>
Date: Tue, 29 Oct 2024 14:41:51 +0100
Subject: [PATCH 153/344] WIP

---
 src/spikeinterface/curation/auto_merge.py | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/src/spikeinterface/curation/auto_merge.py b/src/spikeinterface/curation/auto_merge.py
index dfcd7bbb17..f7110f131d 100644
--- a/src/spikeinterface/curation/auto_merge.py
+++ b/src/spikeinterface/curation/auto_merge.py
@@ -258,7 +258,7 @@ def compute_merge_unit_groups(
             outs["remove_contaminated"] = to_remove
 
         # STEP : unit positions are estimated roughly with channel
-        elif step == "unit_locations" in steps:
+        elif step == "unit_locations":
             location_ext = sorting_analyzer.get_extension("unit_locations")
             unit_locations = location_ext.get_data()[:, :2]
 
@@ -267,7 +267,7 @@ def compute_merge_unit_groups(
             outs["unit_distances"] = unit_distances
 
         # STEP : potential auto merge by correlogram
-        elif step == "correlogram" in steps:
+        elif step == "correlogram":
             correlograms_ext = sorting_analyzer.get_extension("correlograms")
             correlograms, bins = correlograms_ext.get_data()
             censor_ms = params["censor_correlograms_ms"]
@@ -297,7 +297,7 @@ def compute_merge_unit_groups(
             outs["win_sizes"] = win_sizes
 
         # STEP : check if potential merge with CC also have template similarity
-        elif step == "template_similarity" in steps:
+        elif step == "template_similarity":
             template_similarity_ext = sorting_analyzer.get_extension("template_similarity")
             templates_similarity = template_similarity_ext.get_data()
             templates_diff = 1 - templates_similarity
@@ -305,11 +305,11 @@ def compute_merge_unit_groups(
             outs["templates_diff"] = templates_diff
 
         # STEP : check the vicinity of the spikes
-        elif step == "knn" in steps:
+        elif step == "knn":
             pair_mask = get_pairs_via_nntree(sorting_analyzer, **params, pair_mask=pair_mask)
 
         # STEP : check how the rates overlap in times
-        elif step == "presence_distance" in steps:
+        elif step == "presence_distance":
             presence_distance_kwargs = params.copy()
             presence_distance_thresh = presence_distance_kwargs.pop("presence_distance_thresh")
             num_samples = [
@@ -322,7 +322,7 @@ def compute_merge_unit_groups(
             outs["presence_distances"] = presence_distances
 
         # STEP : check if the cross contamination is significant
-        elif step == "cross_contamination" in steps:
+        elif step == "cross_contamination":
             refractory = (
                 params["censored_period_ms"],
                 params["refractory_period_ms"],
@@ -334,7 +334,7 @@ def compute_merge_unit_groups(
             outs["cross_contaminations"] = CC, p_values
 
         # STEP : validate the potential merges with CC increase the contamination quality metrics
-        elif step == "quality_score" in steps:
+        elif step == "quality_score":
             pair_mask, pairs_decreased_score = check_improve_contaminations_score(
                 sorting_analyzer,
                 pair_mask,

From 71e38e023ab660b28957c44d518477bfabf1782b Mon Sep 17 00:00:00 2001
From: Sebastien <pierre.yger@gmail.com>
Date: Tue, 29 Oct 2024 15:17:13 +0100
Subject: [PATCH 154/344] Mix up with default params. Bringing back order

---
 src/spikeinterface/curation/auto_merge.py | 24 +++++++++++++----------
 1 file changed, 14 insertions(+), 10 deletions(-)

diff --git a/src/spikeinterface/curation/auto_merge.py b/src/spikeinterface/curation/auto_merge.py
index f7110f131d..12f7f9eac3 100644
--- a/src/spikeinterface/curation/auto_merge.py
+++ b/src/spikeinterface/curation/auto_merge.py
@@ -66,11 +66,13 @@
 _default_step_params = {
     "num_spikes": {"min_spikes": 100},
     "snr": {"min_snr": 2},
-    "remove_contaminated": {"contamination_thresh": 0.2, "refractory_period_ms": 1.0, "censored_period_ms": 0.3},
-    "unit_locations": {"max_distance_um": 50},
+    "remove_contaminated": {"contamination_thresh": 0.2, 
+                            "refractory_period_ms": 1.0, 
+                            "censored_period_ms": 0.3},
+    "unit_locations": {"max_distance_um": 150},
     "correlogram": {
         "corr_diff_thresh": 0.16,
-        "censor_correlograms_ms": 0.3,
+        "censor_correlograms_ms": 0.15,
         "sigma_smooth_ms": 0.6,
         "adaptative_window_thresh": 0.5,
     },
@@ -83,7 +85,9 @@
         "refractory_period_ms": 1.0,
         "censored_period_ms": 0.3,
     },
-    "quality_score": {"firing_contamination_balance": 2.5, "refractory_period_ms": 1.0, "censored_period_ms": 0.3},
+    "quality_score": {"firing_contamination_balance": 1.5, 
+                      "refractory_period_ms": 1.0, 
+                      "censored_period_ms": 0.3},
 }
 
 
@@ -391,7 +395,7 @@ def get_potential_auto_merge(
     sigma_smooth_ms: float = 0.6,
     adaptative_window_thresh: float = 0.5,
     censor_correlograms_ms: float = 0.15,
-    firing_contamination_balance: float = 2.5,
+    firing_contamination_balance: float = 1.5,
     k_nn: int = 10,
     knn_kwargs: dict | None = None,
     presence_distance_kwargs: dict | None = None,
@@ -479,7 +483,7 @@ def get_potential_auto_merge(
         Parameter to detect the window size in correlogram estimation.
     censor_correlograms_ms : float, default: 0.15
         The period to censor on the auto and cross-correlograms.
-    firing_contamination_balance : float, default: 2.5
+    firing_contamination_balance : float, default: 1.5
         Parameter to control the balance between firing rate and contamination in computing unit "quality score".
     k_nn : int, default 5
         The number of neighbors to consider for every spike in the recording.
@@ -843,10 +847,10 @@ def check_improve_contaminations_score(
         f_new = compute_firing_rates(sorting_analyzer_new)[unit_id1]
 
         # old and new scores
-        k = firing_contamination_balance
-        score_1 = f_1 * (1 - (k + 1) * c_1)
-        score_2 = f_2 * (1 - (k + 1) * c_2)
-        score_new = f_new * (1 - (k + 1) * c_new)
+        k = 1 + firing_contamination_balance
+        score_1 = f_1 * (1 - k * c_1)
+        score_2 = f_2 * (1 - k * c_2)
+        score_new = f_new * (1 - k * c_new)
 
         if score_new < score_1 or score_new < score_2:
             # the score is not improved

From 10d455cdf6db3038b59f484d7bc12d107cf8c578 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Tue, 29 Oct 2024 14:18:35 +0000
Subject: [PATCH 155/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/curation/auto_merge.py | 8 ++------
 1 file changed, 2 insertions(+), 6 deletions(-)

diff --git a/src/spikeinterface/curation/auto_merge.py b/src/spikeinterface/curation/auto_merge.py
index 12f7f9eac3..085467fe9f 100644
--- a/src/spikeinterface/curation/auto_merge.py
+++ b/src/spikeinterface/curation/auto_merge.py
@@ -66,9 +66,7 @@
 _default_step_params = {
     "num_spikes": {"min_spikes": 100},
     "snr": {"min_snr": 2},
-    "remove_contaminated": {"contamination_thresh": 0.2, 
-                            "refractory_period_ms": 1.0, 
-                            "censored_period_ms": 0.3},
+    "remove_contaminated": {"contamination_thresh": 0.2, "refractory_period_ms": 1.0, "censored_period_ms": 0.3},
     "unit_locations": {"max_distance_um": 150},
     "correlogram": {
         "corr_diff_thresh": 0.16,
@@ -85,9 +83,7 @@
         "refractory_period_ms": 1.0,
         "censored_period_ms": 0.3,
     },
-    "quality_score": {"firing_contamination_balance": 1.5, 
-                      "refractory_period_ms": 1.0, 
-                      "censored_period_ms": 0.3},
+    "quality_score": {"firing_contamination_balance": 1.5, "refractory_period_ms": 1.0, "censored_period_ms": 0.3},
 }
 
 

From 988723df9212bda349adc40aaa631ddb68f44123 Mon Sep 17 00:00:00 2001
From: Sebastien <pierre.yger@gmail.com>
Date: Tue, 29 Oct 2024 15:50:24 +0100
Subject: [PATCH 156/344] Triangular sup excluding self pairs

---
 src/spikeinterface/curation/auto_merge.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/curation/auto_merge.py b/src/spikeinterface/curation/auto_merge.py
index 085467fe9f..994cc25d26 100644
--- a/src/spikeinterface/curation/auto_merge.py
+++ b/src/spikeinterface/curation/auto_merge.py
@@ -197,7 +197,7 @@ def compute_merge_unit_groups(
         sorting_analyzer = sorting_analyzer.copy()
 
     n = unit_ids.size
-    pair_mask = np.triu(np.arange(n)) > 0
+    pair_mask = np.triu(np.arange(n), 1) > 0
     outs = dict()
 
     for step in steps:

From 95120e1391a041924879ab4236b1e431f892c020 Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Tue, 29 Oct 2024 16:17:21 +0100
Subject: [PATCH 157/344] Update src/spikeinterface/curation/auto_merge.py

Co-authored-by: Alessio Buccino <alejoe9187@gmail.com>
---
 src/spikeinterface/curation/auto_merge.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/curation/auto_merge.py b/src/spikeinterface/curation/auto_merge.py
index 994cc25d26..8ac1ef0f95 100644
--- a/src/spikeinterface/curation/auto_merge.py
+++ b/src/spikeinterface/curation/auto_merge.py
@@ -185,7 +185,7 @@ def compute_merge_unit_groups(
     if preset is None and steps is None:
         raise ValueError("You need to specify a preset or steps for the auto-merge function")
     elif steps is not None:
-        # steps has presendance on presets
+        # steps has precedence on presets
         pass
     elif preset is not None:
         if preset not in _compute_merge_presets:

From 21408543fc5589a06977997fb93567287b8cbbda Mon Sep 17 00:00:00 2001
From: Sebastien <pierre.yger@gmail.com>
Date: Wed, 30 Oct 2024 10:52:50 +0100
Subject: [PATCH 158/344] Docs

---
 src/spikeinterface/curation/auto_merge.py | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/src/spikeinterface/curation/auto_merge.py b/src/spikeinterface/curation/auto_merge.py
index 8ac1ef0f95..af4407b10e 100644
--- a/src/spikeinterface/curation/auto_merge.py
+++ b/src/spikeinterface/curation/auto_merge.py
@@ -121,6 +121,9 @@ def compute_merge_unit_groups(
 
         Q = f(1 - (k + 1)C)
 
+    IMPORTANT: internally, all computations are relying on extensions of the analyzer, that are computed
+    with default parameters if not present (i.e. correlograms, template_similarity, ...) If you want to 
+    have a finer control on these values, please precompute the extensions before applying the auto_merge  
 
     Parameters
     ----------
@@ -424,6 +427,9 @@ def get_potential_auto_merge(
 
         Q = f(1 - (k + 1)C)
 
+    IMPORTANT: internally, all computations are relying on extensions of the analyzer, that are computed
+    with default parameters if not present (i.e. correlograms, template_similarity, ...) If you want to 
+    have a finer control on these values, please precompute the extensions before applying the auto_merge     
 
     Parameters
     ----------

From df3d2dffda836b90a75ac8a68deb859a3b824b24 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Wed, 30 Oct 2024 09:54:41 +0000
Subject: [PATCH 159/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/curation/auto_merge.py | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/spikeinterface/curation/auto_merge.py b/src/spikeinterface/curation/auto_merge.py
index af4407b10e..eeeb5b2098 100644
--- a/src/spikeinterface/curation/auto_merge.py
+++ b/src/spikeinterface/curation/auto_merge.py
@@ -122,8 +122,8 @@ def compute_merge_unit_groups(
         Q = f(1 - (k + 1)C)
 
     IMPORTANT: internally, all computations are relying on extensions of the analyzer, that are computed
-    with default parameters if not present (i.e. correlograms, template_similarity, ...) If you want to 
-    have a finer control on these values, please precompute the extensions before applying the auto_merge  
+    with default parameters if not present (i.e. correlograms, template_similarity, ...) If you want to
+    have a finer control on these values, please precompute the extensions before applying the auto_merge
 
     Parameters
     ----------
@@ -428,8 +428,8 @@ def get_potential_auto_merge(
         Q = f(1 - (k + 1)C)
 
     IMPORTANT: internally, all computations are relying on extensions of the analyzer, that are computed
-    with default parameters if not present (i.e. correlograms, template_similarity, ...) If you want to 
-    have a finer control on these values, please precompute the extensions before applying the auto_merge     
+    with default parameters if not present (i.e. correlograms, template_similarity, ...) If you want to
+    have a finer control on these values, please precompute the extensions before applying the auto_merge
 
     Parameters
     ----------

From 22b90945c82e55c15e06c9c92ebd6b752889906a Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 30 Oct 2024 16:56:22 +0100
Subject: [PATCH 160/344] avoid copy when not necessary

---
 src/spikeinterface/curation/auto_merge.py | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

diff --git a/src/spikeinterface/curation/auto_merge.py b/src/spikeinterface/curation/auto_merge.py
index eeeb5b2098..4f4cff144e 100644
--- a/src/spikeinterface/curation/auto_merge.py
+++ b/src/spikeinterface/curation/auto_merge.py
@@ -195,7 +195,19 @@ def compute_merge_unit_groups(
             raise ValueError(f"preset must be one of {list(_compute_merge_presets.keys())}")
         steps = _compute_merge_presets[preset]
 
-    if force_copy:
+    # check at least one extension is needed
+    at_least_one_extension_to_compute = False
+    for step in steps:
+        assert step in _default_step_params, f"{step} is not a valid step"
+        if step in _required_extensions:
+            for ext in _required_extensions[step]:
+                if sorting_analyzer.has_extension(ext):
+                    continue
+                if not compute_needed_extensions:
+                    raise ValueError(f"{step} requires {ext} extension")
+                at_least_one_extension_to_compute = True
+
+    if force_copy and at_least_one_extension_to_compute:
         # To avoid erasing the extensions of the user
         sorting_analyzer = sorting_analyzer.copy()
 
@@ -205,14 +217,10 @@ def compute_merge_unit_groups(
 
     for step in steps:
 
-        assert step in _default_step_params, f"{step} is not a valid step"
-
         if step in _required_extensions:
             for ext in _required_extensions[step]:
                 if sorting_analyzer.has_extension(ext):
                     continue
-                if not compute_needed_extensions:
-                    raise ValueError(f"{step} requires {ext} extension")
 
                 # special case for templates
                 if ext == "templates" and not sorting_analyzer.has_extension("random_spikes"):

From 12538cc646f47b162b73190326d5b541121b2c1a Mon Sep 17 00:00:00 2001
From: JoeZiminski <joseph.j.ziminski@gmail.com>
Date: Thu, 31 Oct 2024 17:49:29 +0000
Subject: [PATCH 161/344] Revert to float32.

---
 src/spikeinterface/preprocessing/whiten.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/preprocessing/whiten.py b/src/spikeinterface/preprocessing/whiten.py
index 505e8a330a..b9c106a5a2 100644
--- a/src/spikeinterface/preprocessing/whiten.py
+++ b/src/spikeinterface/preprocessing/whiten.py
@@ -20,7 +20,7 @@ class WhitenRecording(BasePreprocessor):
         The recording extractor to be whitened.
     dtype : None or dtype, default: None
         Datatype of the output recording (covariance matrix estimation
-        and whitening are performed in float64).
+        and whitening are performed in float32).
         If None the the parent dtype is kept.
         For integer dtype a int_scale must be also given.
     mode : "global" | "local", default: "global"
@@ -189,7 +189,7 @@ def compute_whitening_matrix(
 
     """
     random_data = get_random_data_chunks(recording, concatenated=True, return_scaled=False, **random_chunk_kwargs)
-    random_data = random_data.astype(np.float64)
+    random_data = random_data.astype(np.float32)
 
     regularize_kwargs = regularize_kwargs if regularize_kwargs is not None else {"method": "GraphicalLassoCV"}
 

From 035d61c38dbdb453a6461de424028d1466367bda Mon Sep 17 00:00:00 2001
From: Joe Ziminski <55797454+JoeZiminski@users.noreply.github.com>
Date: Thu, 31 Oct 2024 18:02:03 +0000
Subject: [PATCH 162/344] Fix string format error.

---
 src/spikeinterface/preprocessing/whiten.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/preprocessing/whiten.py b/src/spikeinterface/preprocessing/whiten.py
index b9c106a5a2..fa33975a68 100644
--- a/src/spikeinterface/preprocessing/whiten.py
+++ b/src/spikeinterface/preprocessing/whiten.py
@@ -77,7 +77,7 @@ def __init__(
 
         if dtype_.kind == "i":
             assert int_scale is not None, (
-                "For recording with dtype=int you must set the output dtype to float " " OR set a int_scale"
+                "For recording with dtype=int you must set the output dtype to float OR set a int_scale"
             )
 
         if W is not None:

From 7b8d0a2c1c3e006d8a9a46257e0f06e034aa0a76 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Thu, 31 Oct 2024 18:02:31 +0000
Subject: [PATCH 163/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/preprocessing/whiten.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/spikeinterface/preprocessing/whiten.py b/src/spikeinterface/preprocessing/whiten.py
index fa33975a68..57400c1199 100644
--- a/src/spikeinterface/preprocessing/whiten.py
+++ b/src/spikeinterface/preprocessing/whiten.py
@@ -76,9 +76,9 @@ def __init__(
         dtype_ = fix_dtype(recording, dtype)
 
         if dtype_.kind == "i":
-            assert int_scale is not None, (
-                "For recording with dtype=int you must set the output dtype to float OR set a int_scale"
-            )
+            assert (
+                int_scale is not None
+            ), "For recording with dtype=int you must set the output dtype to float OR set a int_scale"
 
         if W is not None:
             W = np.asarray(W)

From f34da1aff682828dfba78cd17034c0fc2cb40fda Mon Sep 17 00:00:00 2001
From: JoeZiminski <Joseph.j.ziminski@gmail.com>
Date: Fri, 1 Nov 2024 14:03:13 +0000
Subject: [PATCH 164/344] Make new index page with hover CSS.

---
 doc/_static/css/custom.css     |  20 +++
 doc/conf.py                    |   6 +-
 doc/index.rst                  |   1 +
 doc/tutorials_custom_index.rst | 254 +++++++++++++++++++++++++++++++++
 4 files changed, 279 insertions(+), 2 deletions(-)
 create mode 100644 doc/_static/css/custom.css
 create mode 100644 doc/tutorials_custom_index.rst

diff --git a/doc/_static/css/custom.css b/doc/_static/css/custom.css
new file mode 100644
index 0000000000..0c51da539e
--- /dev/null
+++ b/doc/_static/css/custom.css
@@ -0,0 +1,20 @@
+/* Center and make the title bold */
+.gallery-card .grid-item-card-title {
+    text-align: center;
+    font-weight: bold;
+}
+
+/* Default style for hover content (hidden) */
+.gallery-card .hover-content {
+    display: none;
+    text-align: center;
+}
+
+/* Show the hover content when hovering over the card */
+.gallery-card:hover .default-title {
+    display: none;
+}
+
+.gallery-card:hover .hover-content {
+    display: block;
+}
diff --git a/doc/conf.py b/doc/conf.py
index e3d58ca8f2..db16269991 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -109,8 +109,10 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ['_static']
-
+html_static_path = ['_static']
+html_css_files = [
+    'css/custom.css',
+]
 html_favicon = "images/favicon-32x32.png"
 
 
diff --git a/doc/index.rst b/doc/index.rst
index ed443e4200..57a0c95443 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -51,6 +51,7 @@ SpikeInterface is made of several modules to deal with different aspects of the
 
     overview
     get_started/index
+    tutorials_custom_index
     tutorials/index
     how_to/index
     modules/index
diff --git a/doc/tutorials_custom_index.rst b/doc/tutorials_custom_index.rst
new file mode 100644
index 0000000000..46a7bea630
--- /dev/null
+++ b/doc/tutorials_custom_index.rst
@@ -0,0 +1,254 @@
+.. This page provides a custom index to the 'Tutorials' page, rather than the default sphinx-gallery
+.. generated page. The benefits of this are flexibility in design and inclusion of non-sphinx files in the index.
+..
+.. To update this index with a new documentation page
+.. 1) Copy the grid-item-card and associated ".. raw:: html" section.
+.. 2) change :link: to a link to your page. If this is an `.rst` file, point to the rst file directly.
+..    If it is a sphinx-gallery generated file, format the path as separated by underscore and prefix `sphx_glr`,
+..    pointing to the .py file. e.g. `tutorials/my/page.py` -> `sphx_glr_tutorials_my_page.py
+.. 3) Change :img-top: to point to the thumbnail image of your choosing. You can point to images generated
+..    in the sphinx gallery page if you wish.
+.. 4) In the `html` section, change the `default-title` to your pages title and `hover-content` to the subtitle.
+
+:orphan:
+
+TutorialsNew
+============
+
+Longer form tutorials about using SpikeInterface. Many of these are downloadable as notebooks or Python scripts so that you can "code along" with the tutorials.
+
+If you're new to SpikeInterface, we recommend trying out the :ref:`get_started/quickstart:Quickstart tutorial` first.
+
+Updating from legacy
+--------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   tutorials/waveform_extractor_to_sorting_analyzer
+
+Core tutorials
+--------------
+
+These tutorials focus on the :py:mod:`spikeinterface.core` module.
+
+.. grid:: 1 2 2 3
+   :gutter: 2
+
+   .. grid-item-card::
+      :link-type: ref
+      :link: sphx_glr_tutorials_core_plot_1_recording_extractor.py
+      :img-top: /tutorials/core/images/thumb/sphx_glr_plot_1_recording_extractor_thumb.png
+      :img-alt: Recording objects
+      :class-card: gallery-card
+
+      .. raw:: html
+
+         <div class="grid-item-card-title default-title">Recording objects</div>
+         <div class="hover-content">Manage loaded recordings in SpikeInterface</div>
+
+   .. grid-item-card::
+      :link-type: ref
+      :link: sphx_glr_tutorials_core_plot_2_sorting_extractor.py
+      :img-top: /tutorials/core/images/thumb/sphx_glr_plot_2_sorting_extractor_thumb.png
+      :img-alt: Sorting objects
+      :class-card: gallery-card
+
+      .. raw:: html
+
+         <div class="grid-item-card-title default-title">Sorting objects</div>
+         <div class="hover-content">Explore sorting extractor features</div>
+
+   .. grid-item-card::
+      :link-type: ref
+      :link: sphx_glr_tutorials_core_plot_3_handle_probe_info.py
+      :img-top: /tutorials/core/images/thumb/sphx_glr_plot_3_handle_probe_info_thumb.png
+      :img-alt: Handling probe information
+      :class-card: gallery-card
+
+      .. raw:: html
+
+         <div class="grid-item-card-title default-title">Handling probe information</div>
+         <div class="hover-content">Handle and visualize probe information</div>
+
+   .. grid-item-card::
+      :link-type: ref
+      :link: sphx_glr_tutorials_core_plot_4_sorting_analyzer.py
+      :img-top: /tutorials/core/images/thumb/sphx_glr_plot_4_sorting_analyzer_thumb.png
+      :img-alt: SortingAnalyzer
+      :class-card: gallery-card
+
+      .. raw:: html
+
+         <div class="grid-item-card-title default-title">SortingAnalyzer</div>
+         <div class="hover-content">Analyze sorting results with ease</div>
+
+   .. grid-item-card::
+      :link-type: ref
+      :link: sphx_glr_tutorials_core_plot_5_append_concatenate_segments.py
+      :img-top: /tutorials/core/images/thumb/sphx_glr_plot_5_append_concatenate_segments_thumb.png
+      :img-alt: Append/Concatenate segments
+      :class-card: gallery-card
+
+      .. raw:: html
+
+         <div class="grid-item-card-title default-title">Append and/or concatenate segments</div>
+         <div class="hover-content">Combine segments efficiently</div>
+
+   .. grid-item-card::
+      :link-type: ref
+      :link: sphx_glr_tutorials_core_plot_6_handle_times.py
+      :img-top: /tutorials/core/images/thumb/sphx_glr_plot_6_handle_times_thumb.png
+      :img-alt: Handle time information
+      :class-card: gallery-card
+
+      .. raw:: html
+
+         <div class="grid-item-card-title default-title">Handle time information</div>
+         <div class="hover-content">Manage and analyze time information</div>
+
+Extractors tutorials
+--------------------
+
+The :py:mod:`spikeinterface.extractors` module is designed to load and save recorded and sorted data, and to handle probe information.
+
+.. grid:: 1 2 2 3
+   :gutter: 2
+
+   .. grid-item-card::
+      :link-type: ref
+      :link: sphx_glr_tutorials_extractors_plot_1_read_various_formats.py
+      :img-top: /tutorials/extractors/images/thumb/sphx_glr_plot_1_read_various_formats_thumb.png
+      :img-alt: Read various formats
+      :class-card: gallery-card
+
+      .. raw:: html
+
+         <div class="grid-item-card-title default-title">Read various formats</div>
+         <div class="hover-content">Read different recording formats efficiently</div>
+
+   .. grid-item-card::
+      :link-type: ref
+      :link: sphx_glr_tutorials_extractors_plot_2_working_with_unscaled_traces.py
+      :img-top: /tutorials/extractors/images/thumb/sphx_glr_plot_2_working_with_unscaled_traces_thumb.png
+      :img-alt: Unscaled traces
+      :class-card: gallery-card
+
+      .. raw:: html
+
+         <div class="grid-item-card-title default-title">Working with unscaled traces</div>
+         <div class="hover-content">Learn about managing unscaled traces</div>
+
+Quality metrics tutorial
+------------------------
+
+The :code:`spikeinterface.qualitymetrics` module allows users to compute various quality metrics to assess the goodness of a spike sorting output.
+
+.. grid:: 1 2 2 3
+   :gutter: 2
+
+   .. grid-item-card::
+      :link-type: ref
+      :link: sphx_glr_tutorials_qualitymetrics_plot_3_quality_mertics.py
+      :img-top: /tutorials/qualitymetrics/images/thumb/sphx_glr_plot_3_quality_mertics_thumb.png
+      :img-alt: Quality Metrics
+      :class-card: gallery-card
+
+      .. raw:: html
+
+         <div class="grid-item-card-title default-title">Quality Metrics</div>
+         <div class="hover-content">Evaluate sorting quality using metrics</div>
+
+   .. grid-item-card::
+      :link-type: ref
+      :link: sphx_glr_tutorials_qualitymetrics_plot_4_curation.py
+      :img-top: /tutorials/qualitymetrics/images/thumb/sphx_glr_plot_4_curation_thumb.png
+      :img-alt: Curation Tutorial
+      :class-card: gallery-card
+
+      .. raw:: html
+
+         <div class="grid-item-card-title default-title">Curation Tutorial</div>
+         <div class="hover-content">Learn how to curate spike sorting data</div>
+
+Comparison tutorial
+-------------------
+
+The :code:`spikeinterface.comparison` module allows you to compare sorter outputs or benchmark against ground truth.
+
+.. grid:: 1 2 2 3
+   :gutter: 2
+
+   .. grid-item-card::
+      :link-type: ref
+      :link: sphx_glr_tutorials_comparison_plot_5_comparison_sorter_weaknesses.py
+      :img-top: /tutorials/comparison/images/thumb/sphx_glr_plot_5_comparison_sorter_weaknesses_thumb.png
+      :img-alt: Sorter Comparison
+      :class-card: gallery-card
+
+      .. raw:: html
+
+         <div class="grid-item-card-title default-title">Sorter Comparison</div>
+         <div class="hover-content">Compare sorter outputs and assess weaknesses</div>
+
+Widgets tutorials
+-----------------
+
+The :code:`widgets` module contains several plotting routines (widgets) for visualizing recordings, sorting data, probe layout, and more.
+
+.. grid:: 1 2 2 3
+   :gutter: 2
+
+   .. grid-item-card::
+      :link-type: ref
+      :link: sphx_glr_tutorials_widgets_plot_1_rec_gallery.py
+      :img-top: /tutorials/widgets/images/thumb/sphx_glr_plot_1_rec_gallery_thumb.png
+      :img-alt: Recording Widgets
+      :class-card: gallery-card
+
+      .. raw:: html
+
+         <div class="grid-item-card-title default-title">RecordingExtractor Widgets</div>
+         <div class="hover-content">Visualize recordings with widgets</div>
+
+   .. grid-item-card::
+      :link-type: ref
+      :link: sphx_glr_tutorials_widgets_plot_2_sort_gallery.py
+      :img-top: /tutorials/widgets/images/thumb/sphx_glr_plot_2_sort_gallery_thumb.png
+      :img-alt: Sorting Widgets
+      :class-card: gallery-card
+
+      .. raw:: html
+
+         <div class="grid-item-card-title default-title">SortingExtractor Widgets</div>
+         <div class="hover-content">Explore sorting data using widgets</div>
+
+   .. grid-item-card::
+      :link-type: ref
+      :link: sphx_glr_tutorials_widgets_plot_3_waveforms_gallery.py
+      :img-top: /tutorials/widgets/images/thumb/sphx_glr_plot_3_waveforms_gallery_thumb.png
+      :img-alt: Waveforms Widgets
+      :class-card: gallery-card
+
+      .. raw:: html
+
+         <div class="grid-item-card-title default-title">Waveforms Widgets</div>
+         <div class="hover-content">Display waveforms using SpikeInterface</div>
+
+   .. grid-item-card::
+      :link-type: ref
+      :link: sphx_glr_tutorials_widgets_plot_4_peaks_gallery.py
+      :img-top: /tutorials/widgets/images/thumb/sphx_glr_plot_4_peaks_gallery_thumb.png
+      :img-alt: Peaks Widgets
+      :class-card: gallery-card
+
+      .. raw:: html
+
+         <div class="grid-item-card-title default-title">Peaks Widgets</div>
+         <div class="hover-content">Visualize detected peaks</div>
+
+Download All Examples
+---------------------
+
+- :download:`Download all examples in Python source code </tutorials/tutorials_python.zip>`
+- :download:`Download all examples in Jupyter notebooks </tutorials/tutorials_jupyter.zip>`

From 7aa93490cca20916338629518800a1cbf976b8ff Mon Sep 17 00:00:00 2001
From: JoeZiminski <Joseph.j.ziminski@gmail.com>
Date: Fri, 1 Nov 2024 14:53:22 +0000
Subject: [PATCH 165/344] Remove CSS and update development docs.

---
 doc/_static/css/custom.css      |  20 -----
 doc/conf.py                     |   6 +-
 doc/development/development.rst |  19 +++++
 doc/index.rst                   |   1 -
 doc/tutorials_custom_index.rst  | 128 +++++++++-----------------------
 5 files changed, 56 insertions(+), 118 deletions(-)
 delete mode 100644 doc/_static/css/custom.css

diff --git a/doc/_static/css/custom.css b/doc/_static/css/custom.css
deleted file mode 100644
index 0c51da539e..0000000000
--- a/doc/_static/css/custom.css
+++ /dev/null
@@ -1,20 +0,0 @@
-/* Center and make the title bold */
-.gallery-card .grid-item-card-title {
-    text-align: center;
-    font-weight: bold;
-}
-
-/* Default style for hover content (hidden) */
-.gallery-card .hover-content {
-    display: none;
-    text-align: center;
-}
-
-/* Show the hover content when hovering over the card */
-.gallery-card:hover .default-title {
-    display: none;
-}
-
-.gallery-card:hover .hover-content {
-    display: block;
-}
diff --git a/doc/conf.py b/doc/conf.py
index db16269991..e3d58ca8f2 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -109,10 +109,8 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
-html_css_files = [
-    'css/custom.css',
-]
+# html_static_path = ['_static']
+
 html_favicon = "images/favicon-32x32.png"
 
 
diff --git a/doc/development/development.rst b/doc/development/development.rst
index a91818a271..1638c41243 100644
--- a/doc/development/development.rst
+++ b/doc/development/development.rst
@@ -213,6 +213,25 @@ We use Sphinx to build the documentation. To build the documentation locally, yo
 
 This will build the documentation in the :code:`doc/_build/html` folder. You can open the :code:`index.html` file in your browser to see the documentation.
 
+Adding new documentation
+------------------------
+
+Documentation can be added as a
+`sphinx-gallery <https://sphinx-gallery.github.io/stable/index.html>`_
+python file ('tutorials')
+or a
+`sphinx rst <https://sphinx-tutorial.readthedocs.io/step-1/>`_
+file (all other sections).
+
+To add a new tutorial, add your ``.py`` file to ``spikeinterface/examples``.
+Then, update the ``spikeinterface/doc/tutorials_custom_index.rst`` file
+to make a new card linking to the page and an optional image. See
+``tutorials_custom_index.rst`` header for more information.
+
+For other sections, write your documentation in ``.rst`` format and add
+the page to the appropriate ``index.rst`` file found in the relevant
+folder (e.g. ``how_to/index.rst``).
+
 How to run code coverage locally
 --------------------------------
 To run code coverage locally, you can use the following command:
diff --git a/doc/index.rst b/doc/index.rst
index 57a0c95443..e6d8aa3fea 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -52,7 +52,6 @@ SpikeInterface is made of several modules to deal with different aspects of the
     overview
     get_started/index
     tutorials_custom_index
-    tutorials/index
     how_to/index
     modules/index
     api
diff --git a/doc/tutorials_custom_index.rst b/doc/tutorials_custom_index.rst
index 46a7bea630..4c7625d811 100644
--- a/doc/tutorials_custom_index.rst
+++ b/doc/tutorials_custom_index.rst
@@ -12,12 +12,14 @@
 
 :orphan:
 
-TutorialsNew
+Tutorials
 ============
 
-Longer form tutorials about using SpikeInterface. Many of these are downloadable as notebooks or Python scripts so that you can "code along" with the tutorials.
+Longer form tutorials about using SpikeInterface. Many of these are downloadable
+as notebooks or Python scripts so that you can "code along" with the tutorials.
 
-If you're new to SpikeInterface, we recommend trying out the :ref:`get_started/quickstart:Quickstart tutorial` first.
+If you're new to SpikeInterface, we recommend trying out the
+:ref:`get_started/quickstart:Quickstart tutorial` first.
 
 Updating from legacy
 --------------------
@@ -35,77 +37,53 @@ These tutorials focus on the :py:mod:`spikeinterface.core` module.
 .. grid:: 1 2 2 3
    :gutter: 2
 
-   .. grid-item-card::
+   .. grid-item-card:: Recording objects
       :link-type: ref
       :link: sphx_glr_tutorials_core_plot_1_recording_extractor.py
       :img-top: /tutorials/core/images/thumb/sphx_glr_plot_1_recording_extractor_thumb.png
       :img-alt: Recording objects
       :class-card: gallery-card
+      :text-align: center
 
-      .. raw:: html
-
-         <div class="grid-item-card-title default-title">Recording objects</div>
-         <div class="hover-content">Manage loaded recordings in SpikeInterface</div>
-
-   .. grid-item-card::
+   .. grid-item-card:: Sorting objects
       :link-type: ref
       :link: sphx_glr_tutorials_core_plot_2_sorting_extractor.py
       :img-top: /tutorials/core/images/thumb/sphx_glr_plot_2_sorting_extractor_thumb.png
       :img-alt: Sorting objects
       :class-card: gallery-card
+      :text-align: center
 
-      .. raw:: html
-
-         <div class="grid-item-card-title default-title">Sorting objects</div>
-         <div class="hover-content">Explore sorting extractor features</div>
-
-   .. grid-item-card::
+   .. grid-item-card:: Handling probe information
       :link-type: ref
       :link: sphx_glr_tutorials_core_plot_3_handle_probe_info.py
       :img-top: /tutorials/core/images/thumb/sphx_glr_plot_3_handle_probe_info_thumb.png
       :img-alt: Handling probe information
       :class-card: gallery-card
+      :text-align: center
 
-      .. raw:: html
-
-         <div class="grid-item-card-title default-title">Handling probe information</div>
-         <div class="hover-content">Handle and visualize probe information</div>
-
-   .. grid-item-card::
+   .. grid-item-card:: SortingAnalyzer
       :link-type: ref
       :link: sphx_glr_tutorials_core_plot_4_sorting_analyzer.py
       :img-top: /tutorials/core/images/thumb/sphx_glr_plot_4_sorting_analyzer_thumb.png
       :img-alt: SortingAnalyzer
       :class-card: gallery-card
+      :text-align: center
 
-      .. raw:: html
-
-         <div class="grid-item-card-title default-title">SortingAnalyzer</div>
-         <div class="hover-content">Analyze sorting results with ease</div>
-
-   .. grid-item-card::
+   .. grid-item-card:: Append and/or concatenate segments
       :link-type: ref
       :link: sphx_glr_tutorials_core_plot_5_append_concatenate_segments.py
       :img-top: /tutorials/core/images/thumb/sphx_glr_plot_5_append_concatenate_segments_thumb.png
       :img-alt: Append/Concatenate segments
       :class-card: gallery-card
+      :text-align: center
 
-      .. raw:: html
-
-         <div class="grid-item-card-title default-title">Append and/or concatenate segments</div>
-         <div class="hover-content">Combine segments efficiently</div>
-
-   .. grid-item-card::
+   .. grid-item-card:: Handle time information
       :link-type: ref
       :link: sphx_glr_tutorials_core_plot_6_handle_times.py
       :img-top: /tutorials/core/images/thumb/sphx_glr_plot_6_handle_times_thumb.png
       :img-alt: Handle time information
       :class-card: gallery-card
-
-      .. raw:: html
-
-         <div class="grid-item-card-title default-title">Handle time information</div>
-         <div class="hover-content">Manage and analyze time information</div>
+      :text-align: center
 
 Extractors tutorials
 --------------------
@@ -115,29 +93,21 @@ The :py:mod:`spikeinterface.extractors` module is designed to load and save reco
 .. grid:: 1 2 2 3
    :gutter: 2
 
-   .. grid-item-card::
+   .. grid-item-card:: Read various formats
       :link-type: ref
       :link: sphx_glr_tutorials_extractors_plot_1_read_various_formats.py
       :img-top: /tutorials/extractors/images/thumb/sphx_glr_plot_1_read_various_formats_thumb.png
       :img-alt: Read various formats
       :class-card: gallery-card
+      :text-align: center
 
-      .. raw:: html
-
-         <div class="grid-item-card-title default-title">Read various formats</div>
-         <div class="hover-content">Read different recording formats efficiently</div>
-
-   .. grid-item-card::
+   .. grid-item-card:: Working with unscaled traces
       :link-type: ref
       :link: sphx_glr_tutorials_extractors_plot_2_working_with_unscaled_traces.py
       :img-top: /tutorials/extractors/images/thumb/sphx_glr_plot_2_working_with_unscaled_traces_thumb.png
       :img-alt: Unscaled traces
       :class-card: gallery-card
-
-      .. raw:: html
-
-         <div class="grid-item-card-title default-title">Working with unscaled traces</div>
-         <div class="hover-content">Learn about managing unscaled traces</div>
+      :text-align: center
 
 Quality metrics tutorial
 ------------------------
@@ -147,29 +117,21 @@ The :code:`spikeinterface.qualitymetrics` module allows users to compute various
 .. grid:: 1 2 2 3
    :gutter: 2
 
-   .. grid-item-card::
+   .. grid-item-card:: Quality Metrics
       :link-type: ref
       :link: sphx_glr_tutorials_qualitymetrics_plot_3_quality_mertics.py
       :img-top: /tutorials/qualitymetrics/images/thumb/sphx_glr_plot_3_quality_mertics_thumb.png
       :img-alt: Quality Metrics
       :class-card: gallery-card
+      :text-align: center
 
-      .. raw:: html
-
-         <div class="grid-item-card-title default-title">Quality Metrics</div>
-         <div class="hover-content">Evaluate sorting quality using metrics</div>
-
-   .. grid-item-card::
+   .. grid-item-card:: Curation Tutorial
       :link-type: ref
       :link: sphx_glr_tutorials_qualitymetrics_plot_4_curation.py
       :img-top: /tutorials/qualitymetrics/images/thumb/sphx_glr_plot_4_curation_thumb.png
       :img-alt: Curation Tutorial
       :class-card: gallery-card
-
-      .. raw:: html
-
-         <div class="grid-item-card-title default-title">Curation Tutorial</div>
-         <div class="hover-content">Learn how to curate spike sorting data</div>
+      :text-align: center
 
 Comparison tutorial
 -------------------
@@ -179,17 +141,13 @@ The :code:`spikeinterface.comparison` module allows you to compare sorter output
 .. grid:: 1 2 2 3
    :gutter: 2
 
-   .. grid-item-card::
+   .. grid-item-card:: Sorter Comparison
       :link-type: ref
       :link: sphx_glr_tutorials_comparison_plot_5_comparison_sorter_weaknesses.py
       :img-top: /tutorials/comparison/images/thumb/sphx_glr_plot_5_comparison_sorter_weaknesses_thumb.png
       :img-alt: Sorter Comparison
       :class-card: gallery-card
-
-      .. raw:: html
-
-         <div class="grid-item-card-title default-title">Sorter Comparison</div>
-         <div class="hover-content">Compare sorter outputs and assess weaknesses</div>
+      :text-align: center
 
 Widgets tutorials
 -----------------
@@ -199,53 +157,37 @@ The :code:`widgets` module contains several plotting routines (widgets) for visu
 .. grid:: 1 2 2 3
    :gutter: 2
 
-   .. grid-item-card::
+   .. grid-item-card:: RecordingExtractor Widgets
       :link-type: ref
       :link: sphx_glr_tutorials_widgets_plot_1_rec_gallery.py
       :img-top: /tutorials/widgets/images/thumb/sphx_glr_plot_1_rec_gallery_thumb.png
       :img-alt: Recording Widgets
       :class-card: gallery-card
+      :text-align: center
 
-      .. raw:: html
-
-         <div class="grid-item-card-title default-title">RecordingExtractor Widgets</div>
-         <div class="hover-content">Visualize recordings with widgets</div>
-
-   .. grid-item-card::
+   .. grid-item-card:: SortingExtractor Widgets
       :link-type: ref
       :link: sphx_glr_tutorials_widgets_plot_2_sort_gallery.py
       :img-top: /tutorials/widgets/images/thumb/sphx_glr_plot_2_sort_gallery_thumb.png
       :img-alt: Sorting Widgets
       :class-card: gallery-card
+      :text-align: center
 
-      .. raw:: html
-
-         <div class="grid-item-card-title default-title">SortingExtractor Widgets</div>
-         <div class="hover-content">Explore sorting data using widgets</div>
-
-   .. grid-item-card::
+   .. grid-item-card:: Waveforms Widgets
       :link-type: ref
       :link: sphx_glr_tutorials_widgets_plot_3_waveforms_gallery.py
       :img-top: /tutorials/widgets/images/thumb/sphx_glr_plot_3_waveforms_gallery_thumb.png
       :img-alt: Waveforms Widgets
       :class-card: gallery-card
+      :text-align: center
 
-      .. raw:: html
-
-         <div class="grid-item-card-title default-title">Waveforms Widgets</div>
-         <div class="hover-content">Display waveforms using SpikeInterface</div>
-
-   .. grid-item-card::
+   .. grid-item-card:: Peaks Widgets
       :link-type: ref
       :link: sphx_glr_tutorials_widgets_plot_4_peaks_gallery.py
       :img-top: /tutorials/widgets/images/thumb/sphx_glr_plot_4_peaks_gallery_thumb.png
       :img-alt: Peaks Widgets
       :class-card: gallery-card
-
-      .. raw:: html
-
-         <div class="grid-item-card-title default-title">Peaks Widgets</div>
-         <div class="hover-content">Visualize detected peaks</div>
+      :text-align: center
 
 Download All Examples
 ---------------------

From 74ef4eba21ec8bb7d413f5221d899d3f35c8287f Mon Sep 17 00:00:00 2001
From: Charlie Windolf <charliexwindolf@gmail.com>
Date: Fri, 1 Nov 2024 17:51:15 -0400
Subject: [PATCH 166/344] Remove remaining array.ptp()s

---
 .../postprocessing/localization_tools.py       | 10 ++++++----
 .../sortingcomponents/motion/dredge.py         | 18 ++++++------------
 2 files changed, 12 insertions(+), 16 deletions(-)

diff --git a/src/spikeinterface/postprocessing/localization_tools.py b/src/spikeinterface/postprocessing/localization_tools.py
index 837b983059..685dcad1f0 100644
--- a/src/spikeinterface/postprocessing/localization_tools.py
+++ b/src/spikeinterface/postprocessing/localization_tools.py
@@ -3,6 +3,10 @@
 import warnings
 
 import numpy as np
+from spikeinterface.core import SortingAnalyzer, Templates, compute_sparsity
+from spikeinterface.core.template_tools import (_get_nbefore,
+                                                get_dense_templates_array,
+                                                get_template_extremum_channel)
 
 try:
     import numba
@@ -12,8 +16,6 @@
     HAVE_NUMBA = False
 
 
-from spikeinterface.core import compute_sparsity, SortingAnalyzer, Templates
-from spikeinterface.core.template_tools import get_template_extremum_channel, _get_nbefore, get_dense_templates_array
 
 
 def compute_monopolar_triangulation(
@@ -110,7 +112,7 @@ def compute_monopolar_triangulation(
         # wf is (nsample, nchan) - chann is only nieghboor
         wf = templates[i, :, :][:, chan_inds]
         if feature == "ptp":
-            wf_data = wf.ptp(axis=0)
+            wf_data = np.ptp(wf, axis=0)
         elif feature == "energy":
             wf_data = np.linalg.norm(wf, axis=0)
         elif feature == "peak_voltage":
@@ -188,7 +190,7 @@ def compute_center_of_mass(
         wf = templates[i, :, :]
 
         if feature == "ptp":
-            wf_data = (wf[:, chan_inds]).ptp(axis=0)
+            wf_data = np.ptp(wf[:, chan_inds], axis=0)
         elif feature == "mean":
             wf_data = (wf[:, chan_inds]).mean(axis=0)
         elif feature == "energy":
diff --git a/src/spikeinterface/sortingcomponents/motion/dredge.py b/src/spikeinterface/sortingcomponents/motion/dredge.py
index e2b6b1a2bc..4db6bb1cb2 100644
--- a/src/spikeinterface/sortingcomponents/motion/dredge.py
+++ b/src/spikeinterface/sortingcomponents/motion/dredge.py
@@ -22,21 +22,15 @@
 
 """
 
+import gc
 import warnings
 
-from tqdm.auto import trange
 import numpy as np
+from tqdm.auto import trange
 
-import gc
-
-from .motion_utils import (
-    Motion,
-    get_spatial_windows,
-    get_window_domains,
-    scipy_conv1d,
-    make_2d_motion_histogram,
-    get_spatial_bin_edges,
-)
+from .motion_utils import (Motion, get_spatial_bin_edges, get_spatial_windows,
+                           get_window_domains, make_2d_motion_histogram,
+                           scipy_conv1d)
 
 
 # simple class wrapper to be compliant with estimate_motion
@@ -979,7 +973,7 @@ def xcorr_windows(
 
     if max_disp_um is None:
         if rigid:
-            max_disp_um = int(spatial_bin_edges_um.ptp() // 4)
+            max_disp_um = int(np.ptp(spatial_bin_edges_um) // 4)
         else:
             max_disp_um = int(win_scale_um // 4)
 

From 43b085fefe1574de8bc65764ecd0b246408ebed0 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Fri, 1 Nov 2024 21:53:15 +0000
Subject: [PATCH 167/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 .../postprocessing/localization_tools.py              |  6 +-----
 src/spikeinterface/sortingcomponents/motion/dredge.py | 11 ++++++++---
 2 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/src/spikeinterface/postprocessing/localization_tools.py b/src/spikeinterface/postprocessing/localization_tools.py
index 685dcad1f0..59c12a9923 100644
--- a/src/spikeinterface/postprocessing/localization_tools.py
+++ b/src/spikeinterface/postprocessing/localization_tools.py
@@ -4,9 +4,7 @@
 
 import numpy as np
 from spikeinterface.core import SortingAnalyzer, Templates, compute_sparsity
-from spikeinterface.core.template_tools import (_get_nbefore,
-                                                get_dense_templates_array,
-                                                get_template_extremum_channel)
+from spikeinterface.core.template_tools import _get_nbefore, get_dense_templates_array, get_template_extremum_channel
 
 try:
     import numba
@@ -16,8 +14,6 @@
     HAVE_NUMBA = False
 
 
-
-
 def compute_monopolar_triangulation(
     sorting_analyzer_or_templates: SortingAnalyzer | Templates,
     unit_ids=None,
diff --git a/src/spikeinterface/sortingcomponents/motion/dredge.py b/src/spikeinterface/sortingcomponents/motion/dredge.py
index 4db6bb1cb2..bfedd4e1ee 100644
--- a/src/spikeinterface/sortingcomponents/motion/dredge.py
+++ b/src/spikeinterface/sortingcomponents/motion/dredge.py
@@ -28,9 +28,14 @@
 import numpy as np
 from tqdm.auto import trange
 
-from .motion_utils import (Motion, get_spatial_bin_edges, get_spatial_windows,
-                           get_window_domains, make_2d_motion_histogram,
-                           scipy_conv1d)
+from .motion_utils import (
+    Motion,
+    get_spatial_bin_edges,
+    get_spatial_windows,
+    get_window_domains,
+    make_2d_motion_histogram,
+    scipy_conv1d,
+)
 
 
 # simple class wrapper to be compliant with estimate_motion

From 507b6b3cf19d0f10069e2415f134dca7fb709b47 Mon Sep 17 00:00:00 2001
From: Charlie Windolf <charliexwindolf@gmail.com>
Date: Sun, 3 Nov 2024 19:16:26 -0500
Subject: [PATCH 168/344] Address time bin issue arising in LFP-based reg,
 which AP-based reg doesn't trigger

---
 .../motion/motion_interpolation.py              | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
index a5e6ded519..975f43919d 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
@@ -3,7 +3,8 @@
 import numpy as np
 from spikeinterface.core.core_tools import define_function_from_class
 from spikeinterface.preprocessing import get_spatial_interpolation_kernel
-from spikeinterface.preprocessing.basepreprocessor import BasePreprocessor, BasePreprocessorSegment
+from spikeinterface.preprocessing.basepreprocessor import (
+    BasePreprocessor, BasePreprocessorSegment)
 from spikeinterface.preprocessing.filter import fix_dtype
 
 
@@ -122,14 +123,18 @@ def interpolate_motion_on_traces(
     time_bins = interpolation_time_bin_centers_s
     if time_bins is None:
         time_bins = motion.temporal_bins_s[segment_index]
+
+    # nearest interpolation bin:
+    # seachsorted(b, t, side="right") == i means that b[i-1] <= t < b[i]
+    # hence the -1. doing it with "left" is not as nice.
+    # time_bins are bin centers, so subtract half the bin length. this leads
+    # to snapping to the nearest bin center.
     bin_s = time_bins[1] - time_bins[0]
-    bins_start = time_bins[0] - 0.5 * bin_s
-    # nearest bin center for each frame?
-    bin_inds = (times - bins_start) // bin_s
-    bin_inds = bin_inds.astype(int)
+    bin_inds = np.searchsorted(time_bins - bin_s / 2, times, side="right") - 1
+
     # the time bins may not cover the whole set of times in the recording,
     # so we need to clip these indices to the valid range
-    np.clip(bin_inds, 0, time_bins.size, out=bin_inds)
+    np.clip(bin_inds, 0, time_bins.size - 1, out=bin_inds)
 
     # -- what are the possibilities here anyway?
     bins_here = np.arange(bin_inds[0], bin_inds[-1] + 1)

From 0e44185c2918a2d7b53cfe55879fde134c478b57 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Mon, 4 Nov 2024 11:05:26 +0100
Subject: [PATCH 169/344] Apply suggestions from code review

---
 src/spikeinterface/core/node_pipeline.py               | 2 +-
 src/spikeinterface/sortingcomponents/peak_detection.py | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/core/node_pipeline.py b/src/spikeinterface/core/node_pipeline.py
index 8ca4ba7f3a..53c2445c77 100644
--- a/src/spikeinterface/core/node_pipeline.py
+++ b/src/spikeinterface/core/node_pipeline.py
@@ -544,7 +544,7 @@ def run_node_pipeline(
     recording_slices : None | list[tuple]
         Optionaly give a list of slices to run the pipeline only on some chunks of the recording.
         It must be a list of (segment_index, frame_start, frame_stop).
-        If None (default), the entire recording is computed.
+        If None (default), the function iterates over the entire duration of the recording.
 
     Returns
     -------
diff --git a/src/spikeinterface/sortingcomponents/peak_detection.py b/src/spikeinterface/sortingcomponents/peak_detection.py
index 233b16dcf7..d03744f8f9 100644
--- a/src/spikeinterface/sortingcomponents/peak_detection.py
+++ b/src/spikeinterface/sortingcomponents/peak_detection.py
@@ -87,7 +87,7 @@ def detect_peaks(
     recording_slices : None | list[tuple]
         Optionaly give a list of slices to run the pipeline only on some chunks of the recording.
         It must be a list of (segment_index, frame_start, frame_stop).
-        If None (default), the entire recording is computed.
+        If None (default), the function iterates over the entire duration of the recording.
 
     {method_doc}
     {job_doc}

From 2faed131014fe46fd0fafddcb9b94872f889ca7c Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Mon, 4 Nov 2024 16:05:42 +0100
Subject: [PATCH 170/344] Remove the need of template_similarity extension for
 autocorrelogram plot

---
 src/spikeinterface/exporters/report.py          | 4 ++--
 src/spikeinterface/widgets/autocorrelograms.py  | 8 +++++++-
 src/spikeinterface/widgets/crosscorrelograms.py | 3 ++-
 src/spikeinterface/widgets/unit_summary.py      | 4 ++--
 4 files changed, 13 insertions(+), 6 deletions(-)

diff --git a/src/spikeinterface/exporters/report.py b/src/spikeinterface/exporters/report.py
index 484da83342..ab08401382 100644
--- a/src/spikeinterface/exporters/report.py
+++ b/src/spikeinterface/exporters/report.py
@@ -22,8 +22,8 @@ def export_report(
     """
     Exports a SI spike sorting report. The report includes summary figures of the spike sorting output.
     What is plotted depends on what has been calculated. Unit locations and unit waveforms are always included.
-    Unit waveform densities, correlograms and spike amplitudes are plotted if `waveforms`, `correlograms`
-    and 'template_similarity', and `spike_amplitudes` have been computed for the given `sorting_analyzer`.
+    Unit waveform densities, correlograms and spike amplitudes are plotted if `waveforms`, `correlograms`,
+    and `spike_amplitudes` have been computed for the given `sorting_analyzer`.
 
     Parameters
     ----------
diff --git a/src/spikeinterface/widgets/autocorrelograms.py b/src/spikeinterface/widgets/autocorrelograms.py
index c8acd93dc2..c211a277f8 100644
--- a/src/spikeinterface/widgets/autocorrelograms.py
+++ b/src/spikeinterface/widgets/autocorrelograms.py
@@ -9,7 +9,13 @@ class AutoCorrelogramsWidget(CrossCorrelogramsWidget):
     # the doc is copied form CrossCorrelogramsWidget
 
     def __init__(self, *args, **kargs):
-        CrossCorrelogramsWidget.__init__(self, *args, **kargs)
+        _ = kargs.pop("min_similarity_for_correlograms", 0.0)
+        CrossCorrelogramsWidget.__init__(
+            self,
+            *args,
+            **kargs,
+            min_similarity_for_correlograms=None,
+        )
 
     def plot_matplotlib(self, data_plot, **backend_kwargs):
         import matplotlib.pyplot as plt
diff --git a/src/spikeinterface/widgets/crosscorrelograms.py b/src/spikeinterface/widgets/crosscorrelograms.py
index cdb2041aa3..88dd803323 100644
--- a/src/spikeinterface/widgets/crosscorrelograms.py
+++ b/src/spikeinterface/widgets/crosscorrelograms.py
@@ -21,7 +21,8 @@ class CrossCorrelogramsWidget(BaseWidget):
         List of unit ids
     min_similarity_for_correlograms : float, default: 0.2
         For sortingview backend. Threshold for computing pair-wise cross-correlograms.
-        If template similarity between two units is below this threshold, the cross-correlogram is not displayed
+        If template similarity between two units is below this threshold, the cross-correlogram is not displayed.
+        For auto-correlograms plot, this is automatically set to None.
     window_ms : float, default: 100.0
         Window for CCGs in ms. If correlograms are already computed (e.g. with SortingAnalyzer),
         this argument is ignored
diff --git a/src/spikeinterface/widgets/unit_summary.py b/src/spikeinterface/widgets/unit_summary.py
index d8cbeb7bb3..9466110110 100644
--- a/src/spikeinterface/widgets/unit_summary.py
+++ b/src/spikeinterface/widgets/unit_summary.py
@@ -108,7 +108,7 @@ def plot_matplotlib(self, data_plot, **backend_kwargs):
         fig = self.figure
         nrows = 2
         ncols = 2
-        if sorting_analyzer.has_extension("correlograms") and sorting_analyzer.has_extension("template_similarity"):
+        if sorting_analyzer.has_extension("correlograms"):
             ncols += 1
         if sorting_analyzer.has_extension("waveforms"):
             ncols += 1
@@ -172,7 +172,7 @@ def plot_matplotlib(self, data_plot, **backend_kwargs):
             col_counter += 1
             ax_waveform_density.set_ylabel(None)
 
-        if sorting_analyzer.has_extension("correlograms") and sorting_analyzer.has_extension("template_similarity"):
+        if sorting_analyzer.has_extension("correlograms"):
             ax_correlograms = fig.add_subplot(gs[:2, col_counter])
             AutoCorrelogramsWidget(
                 sorting_analyzer,

From 4e38ac18be65051d30d15f3d25bada943af3e31f Mon Sep 17 00:00:00 2001
From: Charlie Windolf <charliexwindolf@gmail.com>
Date: Mon, 4 Nov 2024 11:06:46 -0500
Subject: [PATCH 171/344] Fix LFP-based AP interp bug and allow time_vector in
 interpolation

---
 .../motion/motion_interpolation.py            | 18 +++--
 .../motion/tests/test_motion_interpolation.py | 78 ++++++++++++++++---
 2 files changed, 77 insertions(+), 19 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
index 975f43919d..4fd42a8b39 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
@@ -126,11 +126,16 @@ def interpolate_motion_on_traces(
 
     # nearest interpolation bin:
     # seachsorted(b, t, side="right") == i means that b[i-1] <= t < b[i]
-    # hence the -1. doing it with "left" is not as nice.
-    # time_bins are bin centers, so subtract half the bin length. this leads
-    # to snapping to the nearest bin center.
-    bin_s = time_bins[1] - time_bins[0]
-    bin_inds = np.searchsorted(time_bins - bin_s / 2, times, side="right") - 1
+    # hence the -1. doing it with "left" is not as nice -- we want t==b[0]
+    # to lead to i=1 (rounding down).
+    # time_bins are bin centers, but we want to snap to the nearest center.
+    # idea is to get the left bin edges and bin the interp times.
+    # this is like subtracting bin_dt_s/2, but allows non-equally-spaced bins.
+    bin_left = np.zeros_like(time_bins)
+    # it's fine to use the first bin center for the first left edge
+    bin_left[0] = time_bins[0]
+    bin_left[1:] = 0.5 * (time_bins[1:] + time_bins[:-1])
+    bin_inds = np.searchsorted(bin_left, times, side="right") - 1
 
     # the time bins may not cover the whole set of times in the recording,
     # so we need to clip these indices to the valid range
@@ -438,9 +443,6 @@ def __init__(
         self.motion = motion
 
     def get_traces(self, start_frame, end_frame, channel_indices):
-        if self.time_vector is not None:
-            raise NotImplementedError("InterpolateMotionRecording does not yet support recordings with time_vectors.")
-
         if start_frame is None:
             start_frame = 0
         if end_frame is None:
diff --git a/src/spikeinterface/sortingcomponents/motion/tests/test_motion_interpolation.py b/src/spikeinterface/sortingcomponents/motion/tests/test_motion_interpolation.py
index e022f0cc6c..69f681a1be 100644
--- a/src/spikeinterface/sortingcomponents/motion/tests/test_motion_interpolation.py
+++ b/src/spikeinterface/sortingcomponents/motion/tests/test_motion_interpolation.py
@@ -1,16 +1,11 @@
-from pathlib import Path
+import warnings
 
 import numpy as np
-import pytest
 import spikeinterface.core as sc
-from spikeinterface import download_dataset
-from spikeinterface.sortingcomponents.motion.motion_interpolation import (
-    InterpolateMotionRecording,
-    correct_motion_on_peaks,
-    interpolate_motion,
-    interpolate_motion_on_traces,
-)
 from spikeinterface.sortingcomponents.motion import Motion
+from spikeinterface.sortingcomponents.motion.motion_interpolation import (
+    InterpolateMotionRecording, correct_motion_on_peaks, interpolate_motion,
+    interpolate_motion_on_traces)
 from spikeinterface.sortingcomponents.tests.common import make_dataset
 
 
@@ -115,6 +110,66 @@ def test_interpolation_simple():
     assert np.all(traces_corrected[:, 2:] == 0)
 
 
+def test_cross_band_interpolation():
+    """Simple version of using LFP to interpolate AP data
+
+    This also tests the time vector implementation in interpolation.
+    The idea is to have two recordings which are all 0s with a 1 that
+    moves from one channel to another after 3s. They're at different
+    sampling frequencies. motion estimation in one sampling frequency
+    applied to the other should still lead to perfect correction.
+    """
+    from spikeinterface.sortingcomponents.motion import estimate_motion
+
+    # sampling freqs and timing for AP and LFP recordings
+    fs_lfp = 50.0
+    fs_ap = 300.0
+    t_start = 10.0
+    total_duration = 5.0
+    nt_lfp = int(fs_lfp * total_duration)
+    nt_ap = int(fs_ap * total_duration)
+    t_switch = 3
+
+    # because interpolation uses bin centers logic, there will be a half
+    # bin offset at the change point in the AP recording.
+    halfbin_ap_lfp = int(0.5 * (fs_ap / fs_lfp))
+
+    # channel geometry
+    nc = 10
+    geom = np.c_[np.zeros(nc), np.arange(nc)]
+
+    # make an LFP recording which drifts a bit
+    traces_lfp = np.zeros((nt_lfp, nc))
+    traces_lfp[: int(t_switch * fs_lfp), 5] = 1.0
+    traces_lfp[int(t_switch * fs_lfp) :, 6] = 1.0
+    rec_lfp = sc.NumpyRecording(traces_lfp, sampling_frequency=fs_lfp)
+    rec_lfp.set_dummy_probe_from_locations(geom)
+
+    # same for AP
+    traces_ap = np.zeros((nt_ap, nc))
+    traces_ap[: int(t_switch * fs_ap) - halfbin_ap_lfp, 5] = 1.0
+    traces_ap[int(t_switch * fs_ap) - halfbin_ap_lfp :, 6] = 1.0
+    rec_ap = sc.NumpyRecording(traces_ap, sampling_frequency=fs_ap)
+    rec_ap.set_dummy_probe_from_locations(geom)
+
+    # set times for both, and silence the warning
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", category=UserWarning)
+        rec_lfp.set_times(t_start + np.arange(nt_lfp) / fs_lfp)
+        rec_ap.set_times(t_start + np.arange(nt_ap) / fs_ap)
+
+    # estimate motion
+    motion = estimate_motion(rec_lfp, method="dredge_lfp", rigid=True)
+
+    # nearest to keep it simple
+    rec_corrected = interpolate_motion(rec_ap, motion, spatial_interpolation_method="nearest", num_closest=2)
+    traces_corrected = rec_corrected.get_traces()
+    target = np.zeros((nt_ap, nc - 2))
+    target[:, 4] = 1
+    ii, jj = np.nonzero(traces_corrected)
+    assert np.array_equal(traces_corrected, target)
+
+
 def test_InterpolateMotionRecording():
     rec, sorting = make_dataset()
     motion = make_fake_motion(rec)
@@ -148,5 +203,6 @@ def test_InterpolateMotionRecording():
 if __name__ == "__main__":
     # test_correct_motion_on_peaks()
     # test_interpolate_motion_on_traces()
-    test_interpolation_simple()
-    test_InterpolateMotionRecording()
+    # test_interpolation_simple()
+    # test_InterpolateMotionRecording()
+    test_cross_band_interpolation()

From 726170b1526b954b5a26edd70d3162e476ed9f53 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 4 Nov 2024 16:28:44 +0000
Subject: [PATCH 172/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 .../sortingcomponents/motion/motion_interpolation.py       | 3 +--
 .../motion/tests/test_motion_interpolation.py              | 7 +++++--
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
index 4fd42a8b39..810264d9e4 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
@@ -3,8 +3,7 @@
 import numpy as np
 from spikeinterface.core.core_tools import define_function_from_class
 from spikeinterface.preprocessing import get_spatial_interpolation_kernel
-from spikeinterface.preprocessing.basepreprocessor import (
-    BasePreprocessor, BasePreprocessorSegment)
+from spikeinterface.preprocessing.basepreprocessor import BasePreprocessor, BasePreprocessorSegment
 from spikeinterface.preprocessing.filter import fix_dtype
 
 
diff --git a/src/spikeinterface/sortingcomponents/motion/tests/test_motion_interpolation.py b/src/spikeinterface/sortingcomponents/motion/tests/test_motion_interpolation.py
index 69f681a1be..88af619220 100644
--- a/src/spikeinterface/sortingcomponents/motion/tests/test_motion_interpolation.py
+++ b/src/spikeinterface/sortingcomponents/motion/tests/test_motion_interpolation.py
@@ -4,8 +4,11 @@
 import spikeinterface.core as sc
 from spikeinterface.sortingcomponents.motion import Motion
 from spikeinterface.sortingcomponents.motion.motion_interpolation import (
-    InterpolateMotionRecording, correct_motion_on_peaks, interpolate_motion,
-    interpolate_motion_on_traces)
+    InterpolateMotionRecording,
+    correct_motion_on_peaks,
+    interpolate_motion,
+    interpolate_motion_on_traces,
+)
 from spikeinterface.sortingcomponents.tests.common import make_dataset
 
 

From 812376ee39a74e9c1a158e4aea2c96ee8885cc42 Mon Sep 17 00:00:00 2001
From: Zach McKenzie <92116279+zm711@users.noreply.github.com>
Date: Mon, 4 Nov 2024 15:19:28 -0500
Subject: [PATCH 173/344] Alessio's idea

Co-authored-by: Alessio Buccino <alejoe9187@gmail.com>
---
 src/spikeinterface/qualitymetrics/quality_metric_calculator.py | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
index c16241710a..24ac5fa390 100644
--- a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
+++ b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
@@ -132,6 +132,8 @@ def _merge_extension_data(
         # pandas.to_numeric. coerce allows us to keep the nan values.
         for column in metrics.columns:
             metrics[column] = pd.to_numeric(metrics[column], errors="coerce")
+            if np.all(np.mod(metrics[column], 1) == 0):
+                metrics[column] = metrics[column].astype(int)
 
         metrics.loc[not_new_ids, :] = old_metrics.loc[not_new_ids, :]
         metrics.loc[new_unit_ids, :] = self._compute_metrics(

From 4a6b1e38c04c827cae91ecd43732b3e4aaed906d Mon Sep 17 00:00:00 2001
From: zm711 <92116279+zm711@users.noreply.github.com>
Date: Mon, 4 Nov 2024 15:23:21 -0500
Subject: [PATCH 174/344] add int test

---
 .../qualitymetrics/tests/test_quality_metric_calculator.py     | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py b/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py
index f4d37aafee..33cb84c5ed 100644
--- a/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py
+++ b/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py
@@ -75,6 +75,9 @@ def test_merging_quality_metrics(sorting_analyzer_simple):
     # dtype should be fine after merge but is cast from Float64->float64
     assert np.float64 == new_metrics["snr"].dtype
 
+    # test that we appropriate convert int based metrics to int
+    assert np.int32 == new_metrics['num_spikes'].dtype
+
 
 def test_compute_quality_metrics_recordingless(sorting_analyzer_simple):
 

From 1f2e2f1d803b8150c15432c8eb1ce3757641e1a2 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 4 Nov 2024 20:24:16 +0000
Subject: [PATCH 175/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 .../qualitymetrics/tests/test_quality_metric_calculator.py      | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py b/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py
index 33cb84c5ed..cff8d88cca 100644
--- a/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py
+++ b/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py
@@ -76,7 +76,7 @@ def test_merging_quality_metrics(sorting_analyzer_simple):
     assert np.float64 == new_metrics["snr"].dtype
 
     # test that we appropriate convert int based metrics to int
-    assert np.int32 == new_metrics['num_spikes'].dtype
+    assert np.int32 == new_metrics["num_spikes"].dtype
 
 
 def test_compute_quality_metrics_recordingless(sorting_analyzer_simple):

From 0cc1fa1a09ffaa0d3f74e4fd301a21a8d807a8e4 Mon Sep 17 00:00:00 2001
From: zm711 <92116279+zm711@users.noreply.github.com>
Date: Mon, 4 Nov 2024 15:54:52 -0500
Subject: [PATCH 176/344] try different dtype approach

---
 .../qualitymetrics/quality_metric_calculator.py   | 15 +++++++--------
 .../tests/test_quality_metric_calculator.py       |  8 ++------
 2 files changed, 9 insertions(+), 14 deletions(-)

diff --git a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
index 24ac5fa390..bcea6ab612 100644
--- a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
+++ b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
@@ -126,20 +126,19 @@ def _merge_extension_data(
         not_new_ids = all_unit_ids[~np.isin(all_unit_ids, new_unit_ids)]
 
         # this creates a new metrics dictionary, but the dtype for everything will be
-        # object
+        # object. So we will need to fix this later after computing metrics
         metrics = pd.DataFrame(index=all_unit_ids, columns=old_metrics.columns)
-        # we can iterate through the columns and convert them back to numbers with
-        # pandas.to_numeric. coerce allows us to keep the nan values.
-        for column in metrics.columns:
-            metrics[column] = pd.to_numeric(metrics[column], errors="coerce")
-            if np.all(np.mod(metrics[column], 1) == 0):
-                metrics[column] = metrics[column].astype(int)
-
         metrics.loc[not_new_ids, :] = old_metrics.loc[not_new_ids, :]
         metrics.loc[new_unit_ids, :] = self._compute_metrics(
             new_sorting_analyzer, new_unit_ids, verbose, metric_names, **job_kwargs
         )
 
+        # we need to fix the dtypes after we compute everything because we have nans
+        # we can iterate through the columns and convert them back to the dtype
+        # of the original quality dataframe.
+        for column in old_metrics.columns:
+            metrics[column] = metrics[column].astype(old_metrics[column].dtype)
+
         new_data = dict(metrics=metrics)
         return new_data
 
diff --git a/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py b/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py
index cff8d88cca..c4c1778cf2 100644
--- a/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py
+++ b/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py
@@ -68,16 +68,12 @@ def test_merging_quality_metrics(sorting_analyzer_simple):
     # we should copy over the metrics after merge
     for column in metrics.columns:
         assert column in new_metrics.columns
+        # should copy dtype too
+        assert metrics[column].dtype == new_metrics[column].dtype
 
     # 10 units vs 9 units
     assert len(metrics.index) > len(new_metrics.index)
 
-    # dtype should be fine after merge but is cast from Float64->float64
-    assert np.float64 == new_metrics["snr"].dtype
-
-    # test that we appropriate convert int based metrics to int
-    assert np.int32 == new_metrics["num_spikes"].dtype
-
 
 def test_compute_quality_metrics_recordingless(sorting_analyzer_simple):
 

From 2ba37a8b3990af3919a3c1b294700909d144a457 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Tue, 5 Nov 2024 15:58:45 +0100
Subject: [PATCH 177/344] Don't let decimate mess with times and skim tests

---
 src/spikeinterface/preprocessing/decimate.py  | 26 +++++++++----------
 .../preprocessing/tests/test_decimate.py      | 20 +++++++-------
 2 files changed, 23 insertions(+), 23 deletions(-)

diff --git a/src/spikeinterface/preprocessing/decimate.py b/src/spikeinterface/preprocessing/decimate.py
index 334ebb02d2..c1b1cd9f80 100644
--- a/src/spikeinterface/preprocessing/decimate.py
+++ b/src/spikeinterface/preprocessing/decimate.py
@@ -63,18 +63,15 @@ def __init__(
                 f"Consider combining DecimateRecording with FrameSliceRecording for fine control on the recording start/end frames."
             )
         self._decimation_offset = decimation_offset
-        resample_rate = self._orig_samp_freq / self._decimation_factor
+        decimated_sampling_frequency = self._orig_samp_freq / self._decimation_factor
 
-        BasePreprocessor.__init__(self, recording, sampling_frequency=resample_rate)
+        BasePreprocessor.__init__(self, recording, sampling_frequency=decimated_sampling_frequency)
 
-        # in case there was a time_vector, it will be dropped for sanity.
-        # This is not necessary but consistent with ResampleRecording
         for parent_segment in recording._recording_segments:
-            parent_segment.time_vector = None
             self.add_recording_segment(
                 DecimateRecordingSegment(
                     parent_segment,
-                    resample_rate,
+                    decimated_sampling_frequency,
                     self._orig_samp_freq,
                     decimation_factor,
                     decimation_offset,
@@ -93,22 +90,25 @@ class DecimateRecordingSegment(BaseRecordingSegment):
     def __init__(
         self,
         parent_recording_segment,
-        resample_rate,
+        decimated_sampling_frequency,
         parent_rate,
         decimation_factor,
         decimation_offset,
         dtype,
     ):
-        if parent_recording_segment.t_start is None:
-            new_t_start = None
+        if parent_recording_segment.time_vector is not None:
+            time_vector = parent_recording_segment.time_vector[decimation_offset::decimation_factor]
+            decimated_sampling_frequency = None
         else:
-            new_t_start = parent_recording_segment.t_start + decimation_offset / parent_rate
+            time_vector = None
+            if parent_recording_segment.t_start is None:
+                t_start = None
+            else:
+                t_start = parent_recording_segment.t_start + decimation_offset / parent_rate
 
         # Do not use BasePreprocessorSegment bcause we have to reset the sampling rate!
         BaseRecordingSegment.__init__(
-            self,
-            sampling_frequency=resample_rate,
-            t_start=new_t_start,
+            self, sampling_frequency=decimated_sampling_frequency, t_start=t_start, time_vector=time_vector
         )
         self._parent_segment = parent_recording_segment
         self._decimation_factor = decimation_factor
diff --git a/src/spikeinterface/preprocessing/tests/test_decimate.py b/src/spikeinterface/preprocessing/tests/test_decimate.py
index 100972f762..adfcbd0d4a 100644
--- a/src/spikeinterface/preprocessing/tests/test_decimate.py
+++ b/src/spikeinterface/preprocessing/tests/test_decimate.py
@@ -8,19 +8,19 @@
 import numpy as np
 
 
-@pytest.mark.parametrize("N_segments", [1, 2])
-@pytest.mark.parametrize("decimation_offset", [0, 1, 9, 10, 11, 100, 101])
-@pytest.mark.parametrize("decimation_factor", [1, 9, 10, 11, 100, 101])
+@pytest.mark.parametrize("num_segments", [1, 2])
+@pytest.mark.parametrize("decimation_offset", [0, 5, 21, 101])
+@pytest.mark.parametrize("decimation_factor", [1, 7, 50])
 @pytest.mark.parametrize("start_frame", [0, 1, 5, None, 1000])
 @pytest.mark.parametrize("end_frame", [0, 1, 5, None, 1000])
-def test_decimate(N_segments, decimation_offset, decimation_factor, start_frame, end_frame):
+def test_decimate(num_segments, decimation_offset, decimation_factor, start_frame, end_frame):
     rec = generate_recording()
 
-    segment_num_samps = [101 + i for i in range(N_segments)]
+    segment_num_samps = [101 + i for i in range(num_segments)]
 
     rec = NumpyRecording([np.arange(2 * N).reshape(N, 2) for N in segment_num_samps], 1)
 
-    parent_traces = [rec.get_traces(i) for i in range(N_segments)]
+    parent_traces = [rec.get_traces(i) for i in range(num_segments)]
 
     if decimation_offset >= min(segment_num_samps) or decimation_offset >= decimation_factor:
         with pytest.raises(ValueError):
@@ -28,14 +28,14 @@ def test_decimate(N_segments, decimation_offset, decimation_factor, start_frame,
         return
 
     decimated_rec = DecimateRecording(rec, decimation_factor, decimation_offset=decimation_offset)
-    decimated_parent_traces = [parent_traces[i][decimation_offset::decimation_factor] for i in range(N_segments)]
+    decimated_parent_traces = [parent_traces[i][decimation_offset::decimation_factor] for i in range(num_segments)]
 
     if start_frame is None:
-        start_frame = max(decimated_rec.get_num_samples(i) for i in range(N_segments))
+        start_frame = max(decimated_rec.get_num_samples(i) for i in range(num_segments))
     if end_frame is None:
-        end_frame = max(decimated_rec.get_num_samples(i) for i in range(N_segments))
+        end_frame = max(decimated_rec.get_num_samples(i) for i in range(num_segments))
 
-    for i in range(N_segments):
+    for i in range(num_segments):
         assert decimated_rec.get_num_samples(i) == decimated_parent_traces[i].shape[0]
         assert np.all(
             decimated_rec.get_traces(i, start_frame, end_frame) == decimated_parent_traces[i][start_frame:end_frame]

From f90011803da2327d7ace74ff2a35b91b30c70d32 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Tue, 5 Nov 2024 16:35:27 +0100
Subject: [PATCH 178/344] More skimming and test decimate with times

---
 src/spikeinterface/preprocessing/decimate.py  |  1 +
 .../preprocessing/tests/test_decimate.py      | 57 +++++++++++++++----
 2 files changed, 47 insertions(+), 11 deletions(-)

diff --git a/src/spikeinterface/preprocessing/decimate.py b/src/spikeinterface/preprocessing/decimate.py
index c1b1cd9f80..2b47601fc2 100644
--- a/src/spikeinterface/preprocessing/decimate.py
+++ b/src/spikeinterface/preprocessing/decimate.py
@@ -99,6 +99,7 @@ def __init__(
         if parent_recording_segment.time_vector is not None:
             time_vector = parent_recording_segment.time_vector[decimation_offset::decimation_factor]
             decimated_sampling_frequency = None
+            t_start = None
         else:
             time_vector = None
             if parent_recording_segment.t_start is None:
diff --git a/src/spikeinterface/preprocessing/tests/test_decimate.py b/src/spikeinterface/preprocessing/tests/test_decimate.py
index adfcbd0d4a..dd521cbe9b 100644
--- a/src/spikeinterface/preprocessing/tests/test_decimate.py
+++ b/src/spikeinterface/preprocessing/tests/test_decimate.py
@@ -11,13 +11,8 @@
 @pytest.mark.parametrize("num_segments", [1, 2])
 @pytest.mark.parametrize("decimation_offset", [0, 5, 21, 101])
 @pytest.mark.parametrize("decimation_factor", [1, 7, 50])
-@pytest.mark.parametrize("start_frame", [0, 1, 5, None, 1000])
-@pytest.mark.parametrize("end_frame", [0, 1, 5, None, 1000])
-def test_decimate(num_segments, decimation_offset, decimation_factor, start_frame, end_frame):
-    rec = generate_recording()
-
-    segment_num_samps = [101 + i for i in range(num_segments)]
-
+def test_decimate(num_segments, decimation_offset, decimation_factor):
+    segment_num_samps = [20000, 40000]
     rec = NumpyRecording([np.arange(2 * N).reshape(N, 2) for N in segment_num_samps], 1)
 
     parent_traces = [rec.get_traces(i) for i in range(num_segments)]
@@ -30,10 +25,19 @@ def test_decimate(num_segments, decimation_offset, decimation_factor, start_fram
     decimated_rec = DecimateRecording(rec, decimation_factor, decimation_offset=decimation_offset)
     decimated_parent_traces = [parent_traces[i][decimation_offset::decimation_factor] for i in range(num_segments)]
 
-    if start_frame is None:
-        start_frame = max(decimated_rec.get_num_samples(i) for i in range(num_segments))
-    if end_frame is None:
-        end_frame = max(decimated_rec.get_num_samples(i) for i in range(num_segments))
+    for start_frame in [0, 1, 5, None, 1000]:
+        for end_frame in [0, 1, 5, None, 1000]:
+            if start_frame is None:
+                start_frame = max(decimated_rec.get_num_samples(i) for i in range(num_segments))
+            if end_frame is None:
+                end_frame = max(decimated_rec.get_num_samples(i) for i in range(num_segments))
+
+            for i in range(num_segments):
+                assert decimated_rec.get_num_samples(i) == decimated_parent_traces[i].shape[0]
+                assert np.all(
+                    decimated_rec.get_traces(i, start_frame, end_frame)
+                    == decimated_parent_traces[i][start_frame:end_frame]
+                )
 
     for i in range(num_segments):
         assert decimated_rec.get_num_samples(i) == decimated_parent_traces[i].shape[0]
@@ -42,5 +46,36 @@ def test_decimate(num_segments, decimation_offset, decimation_factor, start_fram
         )
 
 
+def test_decimate_with_times():
+    rec = generate_recording(durations=[5, 10])
+
+    # test with times
+    times = [rec.get_times(0) + 10, rec.get_times(1) + 20]
+    for i, t in enumerate(times):
+        rec.set_times(t, i)
+
+    decimation_factor = 2
+    decimation_offset = 1
+    decimated_rec = DecimateRecording(rec, decimation_factor, decimation_offset=decimation_offset)
+
+    for segment_index in range(rec.get_num_segments()):
+        assert np.allclose(
+            decimated_rec.get_times(segment_index),
+            rec.get_times(segment_index)[decimation_offset::decimation_factor],
+        )
+
+    # test with t_start
+    rec = generate_recording(durations=[5, 10])
+    t_starts = [10, 20]
+    for t_start, rec_segment in zip(t_starts, rec._recording_segments):
+        rec_segment.t_start = t_start
+    decimated_rec = DecimateRecording(rec, decimation_factor, decimation_offset=decimation_offset)
+    for segment_index in range(rec.get_num_segments()):
+        assert np.allclose(
+            decimated_rec.get_times(segment_index),
+            rec.get_times(segment_index)[decimation_offset::decimation_factor],
+        )
+
+
 if __name__ == "__main__":
     test_decimate()

From 2d843f8770a8587c32920d3af4dcc54bb8c05411 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Wed, 6 Nov 2024 10:09:56 +0100
Subject: [PATCH 179/344] Zach's comments

---
 src/spikeinterface/preprocessing/decimate.py            | 2 +-
 src/spikeinterface/preprocessing/tests/test_decimate.py | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/preprocessing/decimate.py b/src/spikeinterface/preprocessing/decimate.py
index 2b47601fc2..d5fc9d2025 100644
--- a/src/spikeinterface/preprocessing/decimate.py
+++ b/src/spikeinterface/preprocessing/decimate.py
@@ -105,7 +105,7 @@ def __init__(
             if parent_recording_segment.t_start is None:
                 t_start = None
             else:
-                t_start = parent_recording_segment.t_start + decimation_offset / parent_rate
+                t_start = parent_recording_segment.t_start + (decimation_offset / parent_rate)
 
         # Do not use BasePreprocessorSegment bcause we have to reset the sampling rate!
         BaseRecordingSegment.__init__(
diff --git a/src/spikeinterface/preprocessing/tests/test_decimate.py b/src/spikeinterface/preprocessing/tests/test_decimate.py
index dd521cbe9b..aab17560a6 100644
--- a/src/spikeinterface/preprocessing/tests/test_decimate.py
+++ b/src/spikeinterface/preprocessing/tests/test_decimate.py
@@ -9,7 +9,7 @@
 
 
 @pytest.mark.parametrize("num_segments", [1, 2])
-@pytest.mark.parametrize("decimation_offset", [0, 5, 21, 101])
+@pytest.mark.parametrize("decimation_offset", [0, 1, 5, 21, 101])
 @pytest.mark.parametrize("decimation_factor", [1, 7, 50])
 def test_decimate(num_segments, decimation_offset, decimation_factor):
     segment_num_samps = [20000, 40000]

From d6b4c1e7474c372c6d9f71787ddbe707854bd11f Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Thu, 7 Nov 2024 11:44:13 +0100
Subject: [PATCH 180/344] Fix cbin_file_path

---
 src/spikeinterface/extractors/cbin_ibl.py | 30 +++++++++++++++--------
 1 file changed, 20 insertions(+), 10 deletions(-)

diff --git a/src/spikeinterface/extractors/cbin_ibl.py b/src/spikeinterface/extractors/cbin_ibl.py
index d7e5b58e11..88e1029ab0 100644
--- a/src/spikeinterface/extractors/cbin_ibl.py
+++ b/src/spikeinterface/extractors/cbin_ibl.py
@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from pathlib import Path
+import warnings
 import numpy as np
 
 import probeinterface
@@ -30,8 +31,10 @@ class CompressedBinaryIblExtractor(BaseRecording):
     stream_name : {"ap", "lp"}, default: "ap".
         Whether to load AP or LFP band, one
         of "ap" or "lp".
-    cbin_file : str or None, default None
+    cbin_file_path : str or None, default None
         The cbin file of the recording. If None, searches in `folder_path` for file.
+    cbin_file : str or None, default None
+        (deprecated) The cbin file of the recording. If None, searches in `folder_path` for file.
 
     Returns
     -------
@@ -41,14 +44,21 @@ class CompressedBinaryIblExtractor(BaseRecording):
 
     installation_mesg = "To use the CompressedBinaryIblExtractor, install mtscomp: \n\n pip install mtscomp\n\n"
 
-    def __init__(self, folder_path=None, load_sync_channel=False, stream_name="ap", cbin_file=None):
+    def __init__(
+        self, folder_path=None, load_sync_channel=False, stream_name="ap", cbin_file_path=None, cbin_file=None
+    ):
         from neo.rawio.spikeglxrawio import read_meta_file
 
         try:
             import mtscomp
         except ImportError:
             raise ImportError(self.installation_mesg)
-        if cbin_file is None:
+        if cbin_file is not None:
+            warnings.warn(
+                "The `cbin_file` argument is deprecated, please use `cbin_file_path` instead", DeprecationWarning
+            )
+            cbin_file_path = cbin_file
+        if cbin_file_path is None:
             folder_path = Path(folder_path)
             # check bands
             assert stream_name in ["ap", "lp"], "stream_name must be one of: 'ap', 'lp'"
@@ -60,17 +70,17 @@ def __init__(self, folder_path=None, load_sync_channel=False, stream_name="ap",
             assert (
                 len(curr_cbin_files) == 1
             ), f"There should only be one `*.cbin` file in the folder, but {print(curr_cbin_files)} have been found"
-            cbin_file = curr_cbin_files[0]
+            cbin_file_path = curr_cbin_files[0]
         else:
-            cbin_file = Path(cbin_file)
-            folder_path = cbin_file.parent
+            cbin_file_path = Path(cbin_file_path)
+            folder_path = cbin_file_path.parent
 
-        ch_file = cbin_file.with_suffix(".ch")
-        meta_file = cbin_file.with_suffix(".meta")
+        ch_file = cbin_file_path.with_suffix(".ch")
+        meta_file = cbin_file_path.with_suffix(".meta")
 
         # reader
         cbuffer = mtscomp.Reader()
-        cbuffer.open(cbin_file, ch_file)
+        cbuffer.open(cbin_file_path, ch_file)
 
         # meta data
         meta = read_meta_file(meta_file)
@@ -119,7 +129,7 @@ def __init__(self, folder_path=None, load_sync_channel=False, stream_name="ap",
         self._kwargs = {
             "folder_path": str(Path(folder_path).resolve()),
             "load_sync_channel": load_sync_channel,
-            "cbin_file": str(Path(cbin_file).resolve()),
+            "cbin_file_path": str(Path(cbin_file_path).resolve()),
         }
 
 

From e6f45056852e181fb8d6909c8a3365a08cb2c8f5 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Thu, 7 Nov 2024 15:56:48 +0100
Subject: [PATCH 181/344] Update src/spikeinterface/extractors/cbin_ibl.py

---
 src/spikeinterface/extractors/cbin_ibl.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/extractors/cbin_ibl.py b/src/spikeinterface/extractors/cbin_ibl.py
index 88e1029ab0..357afde04e 100644
--- a/src/spikeinterface/extractors/cbin_ibl.py
+++ b/src/spikeinterface/extractors/cbin_ibl.py
@@ -55,7 +55,7 @@ def __init__(
             raise ImportError(self.installation_mesg)
         if cbin_file is not None:
             warnings.warn(
-                "The `cbin_file` argument is deprecated, please use `cbin_file_path` instead", DeprecationWarning
+                "The `cbin_file` argument is deprecated, please use `cbin_file_path` instead", DeprecationWarning, stacklevel=2
             )
             cbin_file_path = cbin_file
         if cbin_file_path is None:

From 471ce724faac7245766538880b7fcd196f49fa30 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Thu, 7 Nov 2024 14:57:14 +0000
Subject: [PATCH 182/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/extractors/cbin_ibl.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/spikeinterface/extractors/cbin_ibl.py b/src/spikeinterface/extractors/cbin_ibl.py
index 357afde04e..8fe19f3d7e 100644
--- a/src/spikeinterface/extractors/cbin_ibl.py
+++ b/src/spikeinterface/extractors/cbin_ibl.py
@@ -55,7 +55,9 @@ def __init__(
             raise ImportError(self.installation_mesg)
         if cbin_file is not None:
             warnings.warn(
-                "The `cbin_file` argument is deprecated, please use `cbin_file_path` instead", DeprecationWarning, stacklevel=2
+                "The `cbin_file` argument is deprecated, please use `cbin_file_path` instead",
+                DeprecationWarning,
+                stacklevel=2,
             )
             cbin_file_path = cbin_file
         if cbin_file_path is None:

From e0ef39b412c92421599fd2609ec1d0d2968dedbe Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Fri, 8 Nov 2024 12:47:18 +0100
Subject: [PATCH 183/344] proof of concept of chunkexecutor with thread

---
 src/spikeinterface/core/job_tools.py          | 104 ++++++++++++------
 .../core/tests/test_job_tools.py              |  25 ++++-
 2 files changed, 89 insertions(+), 40 deletions(-)

diff --git a/src/spikeinterface/core/job_tools.py b/src/spikeinterface/core/job_tools.py
index 7a6172369b..70a4fe2345 100644
--- a/src/spikeinterface/core/job_tools.py
+++ b/src/spikeinterface/core/job_tools.py
@@ -12,7 +12,7 @@
 import sys
 from tqdm.auto import tqdm
 
-from concurrent.futures import ProcessPoolExecutor
+from concurrent.futures import ProcessPoolExecutor, ThreadPoolExecutor
 import multiprocessing as mp
 from threadpoolctl import threadpool_limits
 
@@ -329,6 +329,7 @@ def __init__(
         progress_bar=False,
         handle_returns=False,
         gather_func=None,
+        pool_engine="process",
         n_jobs=1,
         total_memory=None,
         chunk_size=None,
@@ -370,6 +371,8 @@ def __init__(
         self.job_name = job_name
         self.max_threads_per_process = max_threads_per_process
 
+        self.pool_engine = pool_engine
+
         if verbose:
             chunk_memory = self.chunk_size * recording.get_num_channels() * np.dtype(recording.get_dtype()).itemsize
             total_memory = chunk_memory * self.n_jobs
@@ -402,7 +405,7 @@ def run(self, recording_slices=None):
 
         if self.n_jobs == 1:
             if self.progress_bar:
-                recording_slices = tqdm(recording_slices, ascii=True, desc=self.job_name)
+                recording_slices = tqdm(recording_slices, desc=self.job_name, total=len(recording_slices))
 
             worker_ctx = self.init_func(*self.init_args)
             for segment_index, frame_start, frame_stop in recording_slices:
@@ -411,60 +414,89 @@ def run(self, recording_slices=None):
                     returns.append(res)
                 if self.gather_func is not None:
                     self.gather_func(res)
+
         else:
             n_jobs = min(self.n_jobs, len(recording_slices))
 
-            # parallel
-            with ProcessPoolExecutor(
-                max_workers=n_jobs,
-                initializer=worker_initializer,
-                mp_context=mp.get_context(self.mp_context),
-                initargs=(self.func, self.init_func, self.init_args, self.max_threads_per_process),
-            ) as executor:
-                results = executor.map(function_wrapper, recording_slices)
+            if self.pool_engine == "process":
+
+                # parallel
+                with ProcessPoolExecutor(
+                    max_workers=n_jobs,
+                    initializer=process_worker_initializer,
+                    mp_context=mp.get_context(self.mp_context),
+                    initargs=(self.func, self.init_func, self.init_args, self.max_threads_per_process),
+                ) as executor:
+                    results = executor.map(process_function_wrapper, recording_slices)
+            
+            elif self.pool_engine == "thread":
+                # only one shared context
+
+                worker_dict = self.init_func(*self.init_args)
+                thread_func = WorkerFuncWrapper(self.func, worker_dict, self.max_threads_per_process)
+
+                with ThreadPoolExecutor(
+                    max_workers=n_jobs,
+                ) as executor:
+                    results = executor.map(thread_func, recording_slices)
+
 
-                if self.progress_bar:
-                    results = tqdm(results, desc=self.job_name, total=len(recording_slices))
+            else:
+                raise ValueError("If n_jobs>1 pool_engine must be 'process' or 'thread'")
+            
+
+            if self.progress_bar:
+                results = tqdm(results, desc=self.job_name, total=len(recording_slices))
+
+            for res in results:
+                if self.handle_returns:
+                    returns.append(res)
+                if self.gather_func is not None:
+                    self.gather_func(res)
+        
 
-                for res in results:
-                    if self.handle_returns:
-                        returns.append(res)
-                    if self.gather_func is not None:
-                        self.gather_func(res)
 
         return returns
 
 
+
+class WorkerFuncWrapper:
+    def __init__(self, func, worker_dict, max_threads_per_process):
+        self.func = func
+        self.worker_dict = worker_dict
+        self.max_threads_per_process = max_threads_per_process
+    
+    def __call__(self, args):
+        segment_index, start_frame, end_frame = args
+        if self.max_threads_per_process is None:
+            return self.func(segment_index, start_frame, end_frame, self.worker_dict)
+        else:
+            with threadpool_limits(limits=self.max_threads_per_process):
+                return self.func(segment_index, start_frame, end_frame, self.worker_dict)
+
 # see
 # https://stackoverflow.com/questions/10117073/how-to-use-initializer-to-set-up-my-multiprocess-pool
 # the tricks is : theses 2 variables are global per worker
 # so they are not share in the same process
-global _worker_ctx
-global _func
+# global _worker_ctx
+# global _func
+global _process_func_wrapper
 
 
-def worker_initializer(func, init_func, init_args, max_threads_per_process):
-    global _worker_ctx
+def process_worker_initializer(func, init_func, init_args, max_threads_per_process):
+    global _process_func_wrapper
     if max_threads_per_process is None:
-        _worker_ctx = init_func(*init_args)
+        worker_dict = init_func(*init_args)
     else:
         with threadpool_limits(limits=max_threads_per_process):
-            _worker_ctx = init_func(*init_args)
-    _worker_ctx["max_threads_per_process"] = max_threads_per_process
-    global _func
-    _func = func
+            worker_dict = init_func(*init_args)
+    _process_func_wrapper = WorkerFuncWrapper(func, worker_dict, max_threads_per_process)
 
 
-def function_wrapper(args):
-    segment_index, start_frame, end_frame = args
-    global _func
-    global _worker_ctx
-    max_threads_per_process = _worker_ctx["max_threads_per_process"]
-    if max_threads_per_process is None:
-        return _func(segment_index, start_frame, end_frame, _worker_ctx)
-    else:
-        with threadpool_limits(limits=max_threads_per_process):
-            return _func(segment_index, start_frame, end_frame, _worker_ctx)
+def process_function_wrapper(args):
+    global _process_func_wrapper
+    return _process_func_wrapper(args)
+
 
 
 # Here some utils copy/paste from DART (Charlie Windolf)
diff --git a/src/spikeinterface/core/tests/test_job_tools.py b/src/spikeinterface/core/tests/test_job_tools.py
index 2f3aff0023..3ed4272af0 100644
--- a/src/spikeinterface/core/tests/test_job_tools.py
+++ b/src/spikeinterface/core/tests/test_job_tools.py
@@ -139,7 +139,7 @@ def __call__(self, res):
 
     gathering_func2 = GatherClass()
 
-    # chunk + parallel + gather_func
+    # process + gather_func
     processor = ChunkRecordingExecutor(
         recording,
         func,
@@ -148,6 +148,7 @@ def __call__(self, res):
         verbose=True,
         progress_bar=True,
         gather_func=gathering_func2,
+        pool_engine="process",
         n_jobs=2,
         chunk_duration="200ms",
         job_name="job_name",
@@ -157,7 +158,7 @@ def __call__(self, res):
 
     assert gathering_func2.pos == num_chunks
 
-    # chunk + parallel + spawn
+    # process spawn
     processor = ChunkRecordingExecutor(
         recording,
         func,
@@ -165,6 +166,7 @@ def __call__(self, res):
         init_args,
         verbose=True,
         progress_bar=True,
+        pool_engine="process",
         mp_context="spawn",
         n_jobs=2,
         chunk_duration="200ms",
@@ -172,6 +174,21 @@ def __call__(self, res):
     )
     processor.run()
 
+    # thread
+    processor = ChunkRecordingExecutor(
+        recording,
+        func,
+        init_func,
+        init_args,
+        verbose=True,
+        progress_bar=True,
+        pool_engine="thread",
+        n_jobs=2,
+        chunk_duration="200ms",
+        job_name="job_name",
+    )
+    processor.run()
+
 
 def test_fix_job_kwargs():
     # test negative n_jobs
@@ -224,6 +241,6 @@ def test_split_job_kwargs():
     # test_divide_segment_into_chunks()
     # test_ensure_n_jobs()
     # test_ensure_chunk_size()
-    # test_ChunkRecordingExecutor()
-    test_fix_job_kwargs()
+    test_ChunkRecordingExecutor()
+    # test_fix_job_kwargs()
     # test_split_job_kwargs()

From a28c33d5af6f153f1bdfbe2998959ee2139ed250 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Fri, 8 Nov 2024 13:12:01 +0100
Subject: [PATCH 184/344] for progress_bar the for res in results need to be
 inside the with

---
 src/spikeinterface/core/job_tools.py | 26 ++++++++++++++++++--------
 1 file changed, 18 insertions(+), 8 deletions(-)

diff --git a/src/spikeinterface/core/job_tools.py b/src/spikeinterface/core/job_tools.py
index 70a4fe2345..4e0819d0d9 100644
--- a/src/spikeinterface/core/job_tools.py
+++ b/src/spikeinterface/core/job_tools.py
@@ -428,6 +428,15 @@ def run(self, recording_slices=None):
                     initargs=(self.func, self.init_func, self.init_args, self.max_threads_per_process),
                 ) as executor:
                     results = executor.map(process_function_wrapper, recording_slices)
+
+                    if self.progress_bar:
+                        results = tqdm(results, desc=self.job_name, total=len(recording_slices))
+
+                    for res in results:
+                        if self.handle_returns:
+                            returns.append(res)
+                        if self.gather_func is not None:
+                            self.gather_func(res)
             
             elif self.pool_engine == "thread":
                 # only one shared context
@@ -440,19 +449,20 @@ def run(self, recording_slices=None):
                 ) as executor:
                     results = executor.map(thread_func, recording_slices)
 
+                    if self.progress_bar:
+                        results = tqdm(results, desc=self.job_name, total=len(recording_slices))
+
+                    for res in results:
+                        if self.handle_returns:
+                            returns.append(res)
+                        if self.gather_func is not None:
+                            self.gather_func(res)
+
 
             else:
                 raise ValueError("If n_jobs>1 pool_engine must be 'process' or 'thread'")
             
 
-            if self.progress_bar:
-                results = tqdm(results, desc=self.job_name, total=len(recording_slices))
-
-            for res in results:
-                if self.handle_returns:
-                    returns.append(res)
-                if self.gather_func is not None:
-                    self.gather_func(res)
         
 
 

From 67b055b946d4878249e48ee1ce56ab3ffb765181 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Fri, 8 Nov 2024 13:46:56 +0100
Subject: [PATCH 185/344] wip

---
 src/spikeinterface/core/job_tools.py            | 9 ++++-----
 src/spikeinterface/core/tests/test_job_tools.py | 2 --
 2 files changed, 4 insertions(+), 7 deletions(-)

diff --git a/src/spikeinterface/core/job_tools.py b/src/spikeinterface/core/job_tools.py
index 4e0819d0d9..db23a78b31 100644
--- a/src/spikeinterface/core/job_tools.py
+++ b/src/spikeinterface/core/job_tools.py
@@ -39,6 +39,7 @@
 
 
 job_keys = (
+    "pool_engine",
     "n_jobs",
     "total_memory",
     "chunk_size",
@@ -292,6 +293,8 @@ class ChunkRecordingExecutor:
     gather_func : None or callable, default: None
         Optional function that is called in the main thread and retrieves the results of each worker.
         This function can be used instead of `handle_returns` to implement custom storage on-the-fly.
+    pool_engine : "process" | "thread"
+        If n_jobs>1 then use ProcessPoolExecutor or ThreadPoolExecutor
     n_jobs : int, default: 1
         Number of jobs to be used. Use -1 to use as many jobs as number of cores
     total_memory : str, default: None
@@ -383,6 +386,7 @@ def __init__(
             print(
                 self.job_name,
                 "\n"
+                f"engine={self.pool_engine} - "
                 f"n_jobs={self.n_jobs} - "
                 f"samples_per_chunk={self.chunk_size:,} - "
                 f"chunk_memory={chunk_memory_str} - "
@@ -458,14 +462,9 @@ def run(self, recording_slices=None):
                         if self.gather_func is not None:
                             self.gather_func(res)
 
-
             else:
                 raise ValueError("If n_jobs>1 pool_engine must be 'process' or 'thread'")
             
-
-        
-
-
         return returns
 
 
diff --git a/src/spikeinterface/core/tests/test_job_tools.py b/src/spikeinterface/core/tests/test_job_tools.py
index 3ed4272af0..c46914ab03 100644
--- a/src/spikeinterface/core/tests/test_job_tools.py
+++ b/src/spikeinterface/core/tests/test_job_tools.py
@@ -97,8 +97,6 @@ def init_func(arg1, arg2, arg3):
 
 def test_ChunkRecordingExecutor():
     recording = generate_recording(num_channels=2)
-    # make serializable
-    recording = recording.save()
 
     init_args = "a", 120, "yep"
 

From f293303bef50073cb71add06e94410635615384b Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Fri, 8 Nov 2024 16:06:30 +0100
Subject: [PATCH 186/344] Removing useless dependencies

---
 src/spikeinterface/postprocessing/template_metrics.py    | 2 +-
 src/spikeinterface/postprocessing/template_similarity.py | 2 +-
 src/spikeinterface/postprocessing/unit_locations.py      | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/spikeinterface/postprocessing/template_metrics.py b/src/spikeinterface/postprocessing/template_metrics.py
index 306e9594b8..6e7bcf21b8 100644
--- a/src/spikeinterface/postprocessing/template_metrics.py
+++ b/src/spikeinterface/postprocessing/template_metrics.py
@@ -97,7 +97,7 @@ class ComputeTemplateMetrics(AnalyzerExtension):
 
     extension_name = "template_metrics"
     depend_on = ["templates"]
-    need_recording = True
+    need_recording = False
     use_nodepipeline = False
     need_job_kwargs = False
 
diff --git a/src/spikeinterface/postprocessing/template_similarity.py b/src/spikeinterface/postprocessing/template_similarity.py
index cfa9d89fea..6c30e2730b 100644
--- a/src/spikeinterface/postprocessing/template_similarity.py
+++ b/src/spikeinterface/postprocessing/template_similarity.py
@@ -44,7 +44,7 @@ class ComputeTemplateSimilarity(AnalyzerExtension):
 
     extension_name = "template_similarity"
     depend_on = ["templates"]
-    need_recording = True
+    need_recording = False
     use_nodepipeline = False
     need_job_kwargs = False
     need_backward_compatibility_on_load = True
diff --git a/src/spikeinterface/postprocessing/unit_locations.py b/src/spikeinterface/postprocessing/unit_locations.py
index 4029fc88c7..3f6dd47eec 100644
--- a/src/spikeinterface/postprocessing/unit_locations.py
+++ b/src/spikeinterface/postprocessing/unit_locations.py
@@ -39,7 +39,7 @@ class ComputeUnitLocations(AnalyzerExtension):
 
     extension_name = "unit_locations"
     depend_on = ["templates"]
-    need_recording = True
+    need_recording = False
     use_nodepipeline = False
     need_job_kwargs = False
     need_backward_compatibility_on_load = True

From e791fe18671c2998fde9d44295c54a5781ca2e46 Mon Sep 17 00:00:00 2001
From: Charlie Windolf <charliexwindolf@gmail.com>
Date: Mon, 11 Nov 2024 10:43:48 -0500
Subject: [PATCH 187/344] Cache bin edges in 2 places as discussed with Sam

---
 .../motion/motion_interpolation.py            | 39 +++++++++++++------
 .../sortingcomponents/motion/motion_utils.py  | 24 +++++++++++-
 .../motion/tests/test_motion_interpolation.py | 28 ++++++-------
 3 files changed, 66 insertions(+), 25 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
index 4fd42a8b39..89696f5041 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
@@ -7,6 +7,8 @@
     BasePreprocessor, BasePreprocessorSegment)
 from spikeinterface.preprocessing.filter import fix_dtype
 
+from .motion_utils import ensure_time_bin_edges, ensure_time_bins
+
 
 def correct_motion_on_peaks(peaks, peak_locations, motion, recording) -> np.ndarray:
     """
@@ -55,6 +57,7 @@ def interpolate_motion_on_traces(
     segment_index=None,
     channel_inds=None,
     interpolation_time_bin_centers_s=None,
+    interpolation_time_bin_edges_s=None,
     spatial_interpolation_method="kriging",
     spatial_interpolation_kwargs={},
     dtype=None,
@@ -120,9 +123,11 @@ def interpolate_motion_on_traces(
     total_num_chans = channel_locations.shape[0]
 
     # -- determine the blocks of frames that will land in the same interpolation time bin
-    time_bins = interpolation_time_bin_centers_s
-    if time_bins is None:
-        time_bins = motion.temporal_bins_s[segment_index]
+    if interpolation_time_bin_centers_s is None and interpolation_time_bin_edges_s is None:
+        bin_centers_s = motion.temporal_bin_edges_s[segment_index]
+        bin_edges_s = motion.temporal_bin_edges_s[segment_index]
+    else:
+        bin_centers_s, bin_edges_s = ensure_time_bins(interpolation_time_bin_centers_s, interpolation_time_bin_edges_s)
 
     # nearest interpolation bin:
     # seachsorted(b, t, side="right") == i means that b[i-1] <= t < b[i]
@@ -131,15 +136,13 @@ def interpolate_motion_on_traces(
     # time_bins are bin centers, but we want to snap to the nearest center.
     # idea is to get the left bin edges and bin the interp times.
     # this is like subtracting bin_dt_s/2, but allows non-equally-spaced bins.
-    bin_left = np.zeros_like(time_bins)
     # it's fine to use the first bin center for the first left edge
-    bin_left[0] = time_bins[0]
-    bin_left[1:] = 0.5 * (time_bins[1:] + time_bins[:-1])
-    bin_inds = np.searchsorted(bin_left, times, side="right") - 1
+    bin_inds = np.searchsorted(bin_edges_s, times, side="right") - 1
 
     # the time bins may not cover the whole set of times in the recording,
     # so we need to clip these indices to the valid range
-    np.clip(bin_inds, 0, time_bins.size - 1, out=bin_inds)
+    n_bins = bin_edges_s.shape[0] - 1
+    np.clip(bin_inds, 0, n_bins - 1, out=bin_inds)
 
     # -- what are the possibilities here anyway?
     bins_here = np.arange(bin_inds[0], bin_inds[-1] + 1)
@@ -148,7 +151,7 @@ def interpolate_motion_on_traces(
     interp_times = np.empty(total_num_chans)
     current_start_index = 0
     for bin_ind in bins_here:
-        bin_time = time_bins[bin_ind]
+        bin_time = bin_centers_s[bin_ind]
         interp_times.fill(bin_time)
         channel_motions = motion.get_displacement_at_time_and_depth(
             interp_times,
@@ -307,6 +310,7 @@ def __init__(
         p=1,
         num_closest=3,
         interpolation_time_bin_centers_s=None,
+        interpolation_time_bin_edges_s=None,
         interpolation_time_bin_size_s=None,
         dtype=None,
         **spatial_interpolation_kwargs,
@@ -373,9 +377,14 @@ def __init__(
 
         # handle manual interpolation_time_bin_centers_s
         # the case where interpolation_time_bin_size_s is set is handled per-segment below
-        if interpolation_time_bin_centers_s is None:
+        if interpolation_time_bin_centers_s is None and interpolation_time_bin_edges_s is None:
             if interpolation_time_bin_size_s is None:
                 interpolation_time_bin_centers_s = motion.temporal_bins_s
+                interpolation_time_bin_edges_s = motion.temporal_bin_edges_s
+        else:
+            interpolation_time_bin_centers_s, interpolation_time_bin_edges_s = ensure_time_bins(
+                interpolation_time_bin_centers_s, interpolation_time_bin_edges_s
+            )
 
         for segment_index, parent_segment in enumerate(recording._recording_segments):
             # finish the per-segment part of the time bin logic
@@ -385,8 +394,13 @@ def __init__(
                 t_start, t_end = parent_segment.sample_index_to_time(np.array([0, s_end]))
                 halfbin = interpolation_time_bin_size_s / 2.0
                 segment_interpolation_time_bins_s = np.arange(t_start + halfbin, t_end, interpolation_time_bin_size_s)
+                segment_interpolation_time_bin_edges_s = np.arange(
+                    t_start, t_end + halfbin, interpolation_time_bin_size_s
+                )
+                assert segment_interpolation_time_bin_edges_s.shape == (segment_interpolation_time_bins_s.shape[0] + 1,)
             else:
                 segment_interpolation_time_bins_s = interpolation_time_bin_centers_s[segment_index]
+                segment_interpolation_time_bin_edges_s = interpolation_time_bin_edges_s[segment_index]
 
             rec_segment = InterpolateMotionRecordingSegment(
                 parent_segment,
@@ -397,6 +411,7 @@ def __init__(
                 channel_inds,
                 segment_index,
                 segment_interpolation_time_bins_s,
+                segment_interpolation_time_bin_edges_s,
                 dtype=dtype_,
             )
             self.add_recording_segment(rec_segment)
@@ -430,6 +445,7 @@ def __init__(
         channel_inds,
         segment_index,
         interpolation_time_bin_centers_s,
+        interpolation_time_bin_edges_s,
         dtype="float32",
     ):
         BasePreprocessorSegment.__init__(self, parent_recording_segment)
@@ -439,6 +455,7 @@ def __init__(
         self.channel_inds = channel_inds
         self.segment_index = segment_index
         self.interpolation_time_bin_centers_s = interpolation_time_bin_centers_s
+        self.interpolation_time_bin_edges_s = interpolation_time_bin_edges_s
         self.dtype = dtype
         self.motion = motion
 
@@ -460,7 +477,7 @@ def get_traces(self, start_frame, end_frame, channel_indices):
             channel_inds=self.channel_inds,
             spatial_interpolation_method=self.spatial_interpolation_method,
             spatial_interpolation_kwargs=self.spatial_interpolation_kwargs,
-            interpolation_time_bin_centers_s=self.interpolation_time_bin_centers_s,
+            interpolation_time_bin_edges_s=self.interpolation_time_bin_edges_s,
         )
 
         if channel_indices is not None:
diff --git a/src/spikeinterface/sortingcomponents/motion/motion_utils.py b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
index 635624cca8..ec0a55a8f8 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_utils.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
@@ -1,5 +1,5 @@
-import warnings
 import json
+import warnings
 from pathlib import Path
 
 import numpy as np
@@ -54,6 +54,7 @@ def __init__(self, displacement, temporal_bins_s, spatial_bins_um, direction="y"
         self.direction = direction
         self.dim = ["x", "y", "z"].index(direction)
         self.check_properties()
+        self.temporal_bin_edges_s = [ensure_time_bin_edges(tbins) for tbins in self.temporal_bins_s]
 
     def check_properties(self):
         assert all(d.ndim == 2 for d in self.displacement)
@@ -576,3 +577,24 @@ def make_3d_motion_histograms(
         motion_histograms = np.log2(1 + motion_histograms)
 
     return motion_histograms, temporal_bin_edges, spatial_bin_edges
+
+
+def ensure_time_bins(time_bin_centers_s=None, time_bin_edges_s=None):
+    if time_bin_centers_s is None and time_bin_edges_s is None:
+        raise ValueError("Need at least one of time_bin_centers_s or time_bin_edges_s.")
+
+    if time_bin_centers_s is None:
+        assert time_bin_edges_s.ndim == 1 and time_bin_edges_s.size >= 2
+        time_bin_centers_s = 0.5 * (time_bin_edges_s[1:] + time_bin_edges_s[:-1])
+
+    if time_bin_edges_s is None:
+        time_bin_edges_s = np.empty(time_bin_centers_s.shape[0] + 1, dtype=time_bin_centers_s.dtype)
+        time_bin_edges_s[[0, -1]] = time_bin_centers_s[[0, -1]]
+        if time_bin_centers_s.size > 2:
+            time_bin_edges_s[1:-1] = 0.5 * (time_bin_centers_s[1:] + time_bin_centers_s[:-1])
+
+    return time_bin_centers_s, time_bin_edges_s
+
+
+def ensure_time_bin_edges(time_bin_centers_s=None, time_bin_edges_s=None):
+    return ensure_time_bins(time_bin_centers_s, time_bin_edges_s)[1]
diff --git a/src/spikeinterface/sortingcomponents/motion/tests/test_motion_interpolation.py b/src/spikeinterface/sortingcomponents/motion/tests/test_motion_interpolation.py
index 69f681a1be..07cb5b8ab6 100644
--- a/src/spikeinterface/sortingcomponents/motion/tests/test_motion_interpolation.py
+++ b/src/spikeinterface/sortingcomponents/motion/tests/test_motion_interpolation.py
@@ -62,18 +62,20 @@ def test_interpolate_motion_on_traces():
     times = rec.get_times()[0:30000]
 
     for method in ("kriging", "idw", "nearest"):
-        traces_corrected = interpolate_motion_on_traces(
-            traces,
-            times,
-            channel_locations,
-            motion,
-            channel_inds=None,
-            spatial_interpolation_method=method,
-            # spatial_interpolation_kwargs={},
-            spatial_interpolation_kwargs={"force_extrapolate": True},
-        )
-        assert traces.shape == traces_corrected.shape
-        assert traces.dtype == traces_corrected.dtype
+        for interpolation_time_bin_centers_s in (None, np.linspace(*times[[0, -1]], num=3)):
+            traces_corrected = interpolate_motion_on_traces(
+                traces,
+                times,
+                channel_locations,
+                motion,
+                channel_inds=None,
+                spatial_interpolation_method=method,
+                interpolation_time_bin_centers_s=interpolation_time_bin_centers_s,
+                # spatial_interpolation_kwargs={},
+                spatial_interpolation_kwargs={"force_extrapolate": True},
+            )
+            assert traces.shape == traces_corrected.shape
+            assert traces.dtype == traces_corrected.dtype
 
 
 def test_interpolation_simple():
@@ -202,7 +204,7 @@ def test_InterpolateMotionRecording():
 
 if __name__ == "__main__":
     # test_correct_motion_on_peaks()
-    # test_interpolate_motion_on_traces()
+    test_interpolate_motion_on_traces()
     # test_interpolation_simple()
     # test_InterpolateMotionRecording()
     test_cross_band_interpolation()

From d8f39b5a70dd83f4e1fff71d41036692fba20b38 Mon Sep 17 00:00:00 2001
From: Charlie Windolf <charliexwindolf@gmail.com>
Date: Mon, 11 Nov 2024 12:30:32 -0500
Subject: [PATCH 188/344] Sorry if this is shoe-horning in a change...

---
 src/spikeinterface/core/baserecording.py | 17 +++++++----------
 1 file changed, 7 insertions(+), 10 deletions(-)

diff --git a/src/spikeinterface/core/baserecording.py b/src/spikeinterface/core/baserecording.py
index 5e2e9e4014..b95bfb1ad0 100644
--- a/src/spikeinterface/core/baserecording.py
+++ b/src/spikeinterface/core/baserecording.py
@@ -1,20 +1,17 @@
 from __future__ import annotations
+
 import warnings
 from pathlib import Path
 
 import numpy as np
-from probeinterface import Probe, ProbeGroup, read_probeinterface, select_axes, write_probeinterface
+from probeinterface import (Probe, ProbeGroup, read_probeinterface,
+                            select_axes, write_probeinterface)
 
 from .base import BaseSegment
 from .baserecordingsnippets import BaseRecordingSnippets
-from .core_tools import (
-    convert_bytes_to_str,
-    convert_seconds_to_str,
-)
-from .recording_tools import write_binary_recording
-
-
+from .core_tools import convert_bytes_to_str, convert_seconds_to_str
 from .job_tools import split_job_kwargs
+from .recording_tools import write_binary_recording
 
 
 class BaseRecording(BaseRecordingSnippets):
@@ -921,11 +918,11 @@ def time_to_sample_index(self, time_s):
                 sample_index = time_s * self.sampling_frequency
             else:
                 sample_index = (time_s - self.t_start) * self.sampling_frequency
-            sample_index = round(sample_index)
+            sample_index = np.round(sample_index).astype(int)
         else:
             sample_index = np.searchsorted(self.time_vector, time_s, side="right") - 1
 
-        return int(sample_index)
+        return sample_index
 
     def get_num_samples(self) -> int:
         """Returns the number of samples in this signal segment

From 0a201e17a0b3de283f06c5456010fb20fd8cd209 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 11 Nov 2024 17:31:00 +0000
Subject: [PATCH 189/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/core/baserecording.py | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/spikeinterface/core/baserecording.py b/src/spikeinterface/core/baserecording.py
index b95bfb1ad0..6d4509db12 100644
--- a/src/spikeinterface/core/baserecording.py
+++ b/src/spikeinterface/core/baserecording.py
@@ -4,8 +4,7 @@
 from pathlib import Path
 
 import numpy as np
-from probeinterface import (Probe, ProbeGroup, read_probeinterface,
-                            select_axes, write_probeinterface)
+from probeinterface import Probe, ProbeGroup, read_probeinterface, select_axes, write_probeinterface
 
 from .base import BaseSegment
 from .baserecordingsnippets import BaseRecordingSnippets

From cecb211b4482af487dd0278fa2fd5e67f2efb0bf Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Tue, 12 Nov 2024 13:55:49 +0100
Subject: [PATCH 190/344] wip

---
 src/spikeinterface/core/job_tools.py | 33 +++++++++++++++++++++++-----
 1 file changed, 28 insertions(+), 5 deletions(-)

diff --git a/src/spikeinterface/core/job_tools.py b/src/spikeinterface/core/job_tools.py
index db23a78b31..c514d4c74e 100644
--- a/src/spikeinterface/core/job_tools.py
+++ b/src/spikeinterface/core/job_tools.py
@@ -14,6 +14,7 @@
 
 from concurrent.futures import ProcessPoolExecutor, ThreadPoolExecutor
 import multiprocessing as mp
+import threading
 from threadpoolctl import threadpool_limits
 
 
@@ -445,13 +446,18 @@ def run(self, recording_slices=None):
             elif self.pool_engine == "thread":
                 # only one shared context
 
-                worker_dict = self.init_func(*self.init_args)
-                thread_func = WorkerFuncWrapper(self.func, worker_dict, self.max_threads_per_process)
+                # worker_dict = self.init_func(*self.init_args)
+                # thread_func = WorkerFuncWrapper(self.func, worker_dict, self.max_threads_per_process)
+
+                thread_data = threading.local()
 
                 with ThreadPoolExecutor(
                     max_workers=n_jobs,
+                    initializer=thread_worker_initializer,
+                    initargs=(self.func, self.init_func, self.init_args, self.max_threads_per_process, thread_data),
                 ) as executor:
-                    results = executor.map(thread_func, recording_slices)
+                    recording_slices2 = [(thread_data, ) + args for args in recording_slices]
+                    results = executor.map(thread_function_wrapper, recording_slices2)
 
                     if self.progress_bar:
                         results = tqdm(results, desc=self.job_name, total=len(recording_slices))
@@ -485,7 +491,7 @@ def __call__(self, args):
 
 # see
 # https://stackoverflow.com/questions/10117073/how-to-use-initializer-to-set-up-my-multiprocess-pool
-# the tricks is : theses 2 variables are global per worker
+# the tricks is : thiw variables are global per worker
 # so they are not share in the same process
 # global _worker_ctx
 # global _func
@@ -501,11 +507,28 @@ def process_worker_initializer(func, init_func, init_args, max_threads_per_proce
             worker_dict = init_func(*init_args)
     _process_func_wrapper = WorkerFuncWrapper(func, worker_dict, max_threads_per_process)
 
-
 def process_function_wrapper(args):
     global _process_func_wrapper
     return _process_func_wrapper(args)
 
+def thread_worker_initializer(func, init_func, init_args, max_threads_per_process, thread_data):
+    if max_threads_per_process is None:
+        worker_dict = init_func(*init_args)
+    else:
+        with threadpool_limits(limits=max_threads_per_process):
+            worker_dict = init_func(*init_args)
+    thread_data._func_wrapper = WorkerFuncWrapper(func, worker_dict, max_threads_per_process)
+    # print("ici", thread_data._func_wrapper)
+
+def thread_function_wrapper(args):
+    thread_data = args[0]
+    args = args[1:]
+    # thread_data = threading.local()
+    # print("la", thread_data._func_wrapper)
+    return thread_data._func_wrapper(args)
+
+
+
 
 
 # Here some utils copy/paste from DART (Charlie Windolf)

From d27cd31924de014fb5e71d1a00a6cfd99b928271 Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Wed, 13 Nov 2024 09:10:16 +0100
Subject: [PATCH 191/344] Cleaning API

---
 .../sortingcomponents/clustering/circus.py    |  5 +----
 .../sortingcomponents/clustering/dummy.py     |  2 +-
 .../sortingcomponents/clustering/main.py      |  2 +-
 .../sortingcomponents/clustering/position.py  |  5 ++---
 .../clustering/position_and_features.py       | 19 +++++--------------
 .../clustering/position_and_pca.py            |  9 ++++-----
 .../clustering/position_ptp_scaled.py         |  5 ++---
 .../clustering/random_projections.py          |  6 +-----
 .../clustering/sliding_hdbscan.py             |  7 +++----
 .../clustering/sliding_nn.py                  | 13 ++++++-------
 .../sortingcomponents/clustering/tdc.py       |  5 +----
 .../sortingcomponents/clustering/tools.py     |  4 ----
 12 files changed, 27 insertions(+), 55 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/clustering/circus.py b/src/spikeinterface/sortingcomponents/clustering/circus.py
index 99c59f493e..78227a65f3 100644
--- a/src/spikeinterface/sortingcomponents/clustering/circus.py
+++ b/src/spikeinterface/sortingcomponents/clustering/circus.py
@@ -63,16 +63,13 @@ class CircusClustering:
         "rank": 5,
         "noise_levels": None,
         "tmp_folder": None,
-        "job_kwargs": {},
         "verbose": True,
     }
 
     @classmethod
-    def main_function(cls, recording, peaks, params):
+    def main_function(cls, recording, peaks, params, job_kwargs=dict()):
         assert HAVE_HDBSCAN, "random projections clustering needs hdbscan to be installed"
 
-        job_kwargs = fix_job_kwargs(params["job_kwargs"])
-
         d = params
         verbose = d["verbose"]
 
diff --git a/src/spikeinterface/sortingcomponents/clustering/dummy.py b/src/spikeinterface/sortingcomponents/clustering/dummy.py
index c1032ee6c6..b5761ad5cf 100644
--- a/src/spikeinterface/sortingcomponents/clustering/dummy.py
+++ b/src/spikeinterface/sortingcomponents/clustering/dummy.py
@@ -13,7 +13,7 @@ class DummyClustering:
     _default_params = {}
 
     @classmethod
-    def main_function(cls, recording, peaks, params):
+    def main_function(cls, recording, peaks, params, job_kwargs=dict()):
         labels = np.arange(recording.get_num_channels(), dtype="int64")
         peak_labels = peaks["channel_index"]
         return labels, peak_labels
diff --git a/src/spikeinterface/sortingcomponents/clustering/main.py b/src/spikeinterface/sortingcomponents/clustering/main.py
index 99881f2f34..ba0fe6f9ac 100644
--- a/src/spikeinterface/sortingcomponents/clustering/main.py
+++ b/src/spikeinterface/sortingcomponents/clustering/main.py
@@ -41,7 +41,7 @@ def find_cluster_from_peaks(recording, peaks, method="stupid", method_kwargs={},
     params = method_class._default_params.copy()
     params.update(**method_kwargs)
 
-    outputs = method_class.main_function(recording, peaks, params)
+    outputs = method_class.main_function(recording, peaks, params, job_kwargs=job_kwargs)
 
     if extra_outputs:
         return outputs
diff --git a/src/spikeinterface/sortingcomponents/clustering/position.py b/src/spikeinterface/sortingcomponents/clustering/position.py
index ae772206bb..dc76d787f6 100644
--- a/src/spikeinterface/sortingcomponents/clustering/position.py
+++ b/src/spikeinterface/sortingcomponents/clustering/position.py
@@ -25,18 +25,17 @@ class PositionClustering:
         "hdbscan_kwargs": {"min_cluster_size": 20, "allow_single_cluster": True, "core_dist_n_jobs": -1},
         "debug": False,
         "tmp_folder": None,
-        "job_kwargs": {"n_jobs": -1, "chunk_memory": "10M"},
     }
 
     @classmethod
-    def main_function(cls, recording, peaks, params):
+    def main_function(cls, recording, peaks, params, job_kwargs=dict()):
         assert HAVE_HDBSCAN, "position clustering need hdbscan to be installed"
         d = params
 
         if d["peak_locations"] is None:
             from spikeinterface.sortingcomponents.peak_localization import localize_peaks
 
-            peak_locations = localize_peaks(recording, peaks, **d["peak_localization_kwargs"], **d["job_kwargs"])
+            peak_locations = localize_peaks(recording, peaks, **d["peak_localization_kwargs"], **job_kwargs)
         else:
             peak_locations = d["peak_locations"]
 
diff --git a/src/spikeinterface/sortingcomponents/clustering/position_and_features.py b/src/spikeinterface/sortingcomponents/clustering/position_and_features.py
index d23eb26239..513e8085ed 100644
--- a/src/spikeinterface/sortingcomponents/clustering/position_and_features.py
+++ b/src/spikeinterface/sortingcomponents/clustering/position_and_features.py
@@ -42,23 +42,14 @@ class PositionAndFeaturesClustering:
         "ms_before": 1.5,
         "ms_after": 1.5,
         "cleaning_method": "dip",
-        "job_kwargs": {"n_jobs": -1, "chunk_memory": "10M", "progress_bar": True},
     }
 
     @classmethod
-    def main_function(cls, recording, peaks, params):
+    def main_function(cls, recording, peaks, params, job_kwargs=dict()):
         from sklearn.preprocessing import QuantileTransformer
 
         assert HAVE_HDBSCAN, "twisted clustering needs hdbscan to be installed"
 
-        if "n_jobs" in params["job_kwargs"]:
-            if params["job_kwargs"]["n_jobs"] == -1:
-                params["job_kwargs"]["n_jobs"] = os.cpu_count()
-
-        if "core_dist_n_jobs" in params["hdbscan_kwargs"]:
-            if params["hdbscan_kwargs"]["core_dist_n_jobs"] == -1:
-                params["hdbscan_kwargs"]["core_dist_n_jobs"] = os.cpu_count()
-
         d = params
 
         peak_dtype = [("sample_index", "int64"), ("unit_index", "int64"), ("segment_index", "int64")]
@@ -80,7 +71,7 @@ def main_function(cls, recording, peaks, params):
         }
 
         features_data = compute_features_from_peaks(
-            recording, peaks, features_list, features_params, ms_before=1, ms_after=1, **params["job_kwargs"]
+            recording, peaks, features_list, features_params, ms_before=1, ms_after=1, **job_kwargs
         )
 
         hdbscan_data = np.zeros((len(peaks), 3), dtype=np.float32)
@@ -150,7 +141,7 @@ def main_function(cls, recording, peaks, params):
                 dtype=recording.get_dtype(),
                 sparsity_mask=None,
                 copy=True,
-                **params["job_kwargs"],
+                **job_kwargs,
             )
 
             noise_levels = get_noise_levels(recording, return_scaled=False)
@@ -181,7 +172,7 @@ def main_function(cls, recording, peaks, params):
                 nbefore,
                 nafter,
                 return_scaled=False,
-                **params["job_kwargs"],
+                **job_kwargs,
             )
             templates = Templates(
                 templates_array=templates_array,
@@ -193,7 +184,7 @@ def main_function(cls, recording, peaks, params):
             )
 
             labels, peak_labels = remove_duplicates_via_matching(
-                templates, peak_labels, job_kwargs=params["job_kwargs"], **params["cleaning_kwargs"]
+                templates, peak_labels, job_kwargs=job_kwargs, **params["cleaning_kwargs"]
             )
             shutil.rmtree(tmp_folder)
 
diff --git a/src/spikeinterface/sortingcomponents/clustering/position_and_pca.py b/src/spikeinterface/sortingcomponents/clustering/position_and_pca.py
index 4dfe3c960c..3b730752c1 100644
--- a/src/spikeinterface/sortingcomponents/clustering/position_and_pca.py
+++ b/src/spikeinterface/sortingcomponents/clustering/position_and_pca.py
@@ -38,7 +38,6 @@ class PositionAndPCAClustering:
         "ms_after": 2.5,
         "n_components_by_channel": 3,
         "n_components": 5,
-        "job_kwargs": {"n_jobs": -1, "chunk_memory": "10M", "progress_bar": True},
         "hdbscan_global_kwargs": {"min_cluster_size": 20, "allow_single_cluster": True, "core_dist_n_jobs": -1},
         "hdbscan_local_kwargs": {"min_cluster_size": 20, "allow_single_cluster": True, "core_dist_n_jobs": -1},
         "waveform_mode": "shared_memory",
@@ -73,7 +72,7 @@ def _check_params(cls, recording, peaks, params):
         return params2
 
     @classmethod
-    def main_function(cls, recording, peaks, params):
+    def main_function(cls, recording, peaks, params, job_kwargs=dict()):
         # res = PositionClustering(recording, peaks, params)
 
         assert HAVE_HDBSCAN, "position_and_pca clustering need hdbscan to be installed"
@@ -86,7 +85,7 @@ def main_function(cls, recording, peaks, params):
             from spikeinterface.sortingcomponents.peak_localization import localize_peaks
 
             peak_locations = localize_peaks(
-                recording, peaks, **params["peak_localization_kwargs"], **params["job_kwargs"]
+                recording, peaks, **params["peak_localization_kwargs"], **job_kwargs
             )
         else:
             peak_locations = params["peak_locations"]
@@ -155,7 +154,7 @@ def main_function(cls, recording, peaks, params):
             dtype=recording.get_dtype(),
             sparsity_mask=sparsity_mask,
             copy=(params["waveform_mode"] == "shared_memory"),
-            **params["job_kwargs"],
+            **job_kwargs,
         )
 
         noise = get_random_data_chunks(
@@ -222,7 +221,7 @@ def main_function(cls, recording, peaks, params):
             dtype=recording.get_dtype(),
             sparsity_mask=sparsity_mask3,
             copy=(params["waveform_mode"] == "shared_memory"),
-            **params["job_kwargs"],
+            **job_kwargs,
         )
 
         clean_peak_labels, peak_sample_shifts = auto_clean_clustering(
diff --git a/src/spikeinterface/sortingcomponents/clustering/position_ptp_scaled.py b/src/spikeinterface/sortingcomponents/clustering/position_ptp_scaled.py
index 788addf1e6..0f7390d7ac 100644
--- a/src/spikeinterface/sortingcomponents/clustering/position_ptp_scaled.py
+++ b/src/spikeinterface/sortingcomponents/clustering/position_ptp_scaled.py
@@ -26,7 +26,6 @@ class PositionPTPScaledClustering:
         "ptps": None,
         "scales": (1, 1, 10),
         "peak_localization_kwargs": {"method": "center_of_mass"},
-        "job_kwargs": {"n_jobs": -1, "chunk_memory": "10M", "progress_bar": True},
         "hdbscan_kwargs": {
             "min_cluster_size": 20,
             "min_samples": 20,
@@ -38,7 +37,7 @@ class PositionPTPScaledClustering:
     }
 
     @classmethod
-    def main_function(cls, recording, peaks, params):
+    def main_function(cls, recording, peaks, params, job_kwargs=dict()):
         assert HAVE_HDBSCAN, "position clustering need hdbscan to be installed"
         d = params
 
@@ -60,7 +59,7 @@ def main_function(cls, recording, peaks, params):
 
         if d["ptps"] is None:
             (ptps,) = compute_features_from_peaks(
-                recording, peaks, ["ptp"], feature_params={"ptp": {"all_channels": True}}, **d["job_kwargs"]
+                recording, peaks, ["ptp"], feature_params={"ptp": {"all_channels": True}}, **job_kwargs
             )
         else:
             ptps = d["ptps"]
diff --git a/src/spikeinterface/sortingcomponents/clustering/random_projections.py b/src/spikeinterface/sortingcomponents/clustering/random_projections.py
index f7ca999d53..36033c61e1 100644
--- a/src/spikeinterface/sortingcomponents/clustering/random_projections.py
+++ b/src/spikeinterface/sortingcomponents/clustering/random_projections.py
@@ -17,7 +17,6 @@
 from spikeinterface.core.waveform_tools import estimate_templates
 from .clustering_tools import remove_duplicates_via_matching
 from spikeinterface.core.recording_tools import get_noise_levels, get_channel_distances
-from spikeinterface.core.job_tools import fix_job_kwargs
 from spikeinterface.sortingcomponents.waveforms.savgol_denoiser import SavGolDenoiser
 from spikeinterface.sortingcomponents.features_from_peaks import RandomProjectionsFeature
 from spikeinterface.core.template import Templates
@@ -55,16 +54,13 @@ class RandomProjectionClustering:
         "noise_levels": None,
         "smoothing_kwargs": {"window_length_ms": 0.25},
         "tmp_folder": None,
-        "job_kwargs": {},
         "verbose": True,
     }
 
     @classmethod
-    def main_function(cls, recording, peaks, params):
+    def main_function(cls, recording, peaks, params, job_kwargs=dict()):
         assert HAVE_HDBSCAN, "random projections clustering need hdbscan to be installed"
 
-        job_kwargs = fix_job_kwargs(params["job_kwargs"])
-
         d = params
         verbose = d["verbose"]
 
diff --git a/src/spikeinterface/sortingcomponents/clustering/sliding_hdbscan.py b/src/spikeinterface/sortingcomponents/clustering/sliding_hdbscan.py
index 8b9acbc92d..ee56894b13 100644
--- a/src/spikeinterface/sortingcomponents/clustering/sliding_hdbscan.py
+++ b/src/spikeinterface/sortingcomponents/clustering/sliding_hdbscan.py
@@ -55,11 +55,10 @@ class SlidingHdbscanClustering:
         "auto_merge_quantile_limit": 0.8,
         "ratio_num_channel_intersect": 0.5,
         # ~ 'auto_trash_misalignment_shift' : 4,
-        "job_kwargs": {"n_jobs": -1, "chunk_memory": "10M", "progress_bar": True},
     }
 
     @classmethod
-    def main_function(cls, recording, peaks, params):
+    def main_function(cls, recording, peaks, params, job_kwargs=dict()):
         assert HAVE_HDBSCAN, "sliding_hdbscan clustering need hdbscan to be installed"
         params = cls._check_params(recording, peaks, params)
         wfs_arrays, sparsity_mask, noise = cls._initialize_folder(recording, peaks, params)
@@ -145,7 +144,7 @@ def _initialize_folder(cls, recording, peaks, params):
             dtype=dtype,
             sparsity_mask=sparsity_mask,
             copy=(d["waveform_mode"] == "shared_memory"),
-            **d["job_kwargs"],
+            **job_kwargs,
         )
 
         # noise
@@ -465,7 +464,7 @@ def _prepare_clean(cls, recording, peaks, wfs_arrays, sparsity_mask, peak_labels
             dtype=recording.get_dtype(),
             sparsity_mask=sparsity_mask2,
             copy=(d["waveform_mode"] == "shared_memory"),
-            **d["job_kwargs"],
+            **job_kwargs,
         )
 
         return wfs_arrays2, sparsity_mask2
diff --git a/src/spikeinterface/sortingcomponents/clustering/sliding_nn.py b/src/spikeinterface/sortingcomponents/clustering/sliding_nn.py
index a6ffa5fdc2..40cedacdc5 100644
--- a/src/spikeinterface/sortingcomponents/clustering/sliding_nn.py
+++ b/src/spikeinterface/sortingcomponents/clustering/sliding_nn.py
@@ -71,11 +71,10 @@ class SlidingNNClustering:
         "tmp_folder": None,
         "verbose": False,
         "tmp_folder": None,
-        "job_kwargs": {"n_jobs": -1},
     }
 
     @classmethod
-    def _initialize_folder(cls, recording, peaks, params):
+    def _initialize_folder(cls, recording, peaks, params, job_kwargs=dict()):
         assert HAVE_NUMBA, "SlidingNN needs numba to work"
         assert HAVE_TORCH, "SlidingNN needs torch to work"
         assert HAVE_NNDESCENT, "SlidingNN needs pynndescent to work"
@@ -126,16 +125,16 @@ def _initialize_folder(cls, recording, peaks, params):
             dtype=dtype,
             sparsity_mask=sparsity_mask,
             copy=(d["waveform_mode"] == "shared_memory"),
-            **d["job_kwargs"],
+            **job_kwargs,
         )
 
         return wfs_arrays, sparsity_mask
 
     @classmethod
-    def main_function(cls, recording, peaks, params):
+    def main_function(cls, recording, peaks, params, job_kwargs=dict()):
         d = params
 
-        # wfs_arrays, sparsity_mask, noise = cls._initialize_folder(recording, peaks, params)
+        # wfs_arrays, sparsity_mask, noise = cls._initialize_folder(recording, peaks, params, job_kwargs)
 
         # prepare neighborhood parameters
         fs = recording.get_sampling_frequency()
@@ -228,7 +227,7 @@ def main_function(cls, recording, peaks, params):
                 n_channel_neighbors=d["n_channel_neighbors"],
                 low_memory=d["low_memory"],
                 knn_verbose=d["verbose"],
-                n_jobs=d["job_kwargs"]["n_jobs"],
+                n_jobs=job_kwargs["n_jobs"],
             )
             # remove the first nearest neighbor (which should be self)
             knn_distances = knn_distances[:, 1:]
@@ -297,7 +296,7 @@ def main_function(cls, recording, peaks, params):
                     # TODO HDBSCAN can be done on GPU with NVIDIA RAPIDS for speed
                     clusterer = hdbscan.HDBSCAN(
                         prediction_data=True,
-                        core_dist_n_jobs=d["job_kwargs"]["n_jobs"],
+                        core_dist_n_jobs=job_kwargs["n_jobs"],
                         **d["hdbscan_kwargs"],
                     ).fit(embeddings_chunk)
 
diff --git a/src/spikeinterface/sortingcomponents/clustering/tdc.py b/src/spikeinterface/sortingcomponents/clustering/tdc.py
index 13af5b0fab..c6b94eaa48 100644
--- a/src/spikeinterface/sortingcomponents/clustering/tdc.py
+++ b/src/spikeinterface/sortingcomponents/clustering/tdc.py
@@ -50,15 +50,12 @@ class TdcClustering:
             "merge_radius_um": 40.0,
             "threshold_diff": 1.5,
         },
-        "job_kwargs": {},
     }
 
     @classmethod
-    def main_function(cls, recording, peaks, params):
+    def main_function(cls, recording, peaks, params, job_kwargs=dict()):
         import hdbscan
 
-        job_kwargs = params["job_kwargs"]
-
         if params["folder"] is None:
             randname = "".join(random.choices(string.ascii_uppercase + string.digits, k=6))
             clustering_folder = get_global_tmp_folder() / f"tdcclustering_{randname}"
diff --git a/src/spikeinterface/sortingcomponents/clustering/tools.py b/src/spikeinterface/sortingcomponents/clustering/tools.py
index e2a0d273d6..64cc0f39c4 100644
--- a/src/spikeinterface/sortingcomponents/clustering/tools.py
+++ b/src/spikeinterface/sortingcomponents/clustering/tools.py
@@ -172,8 +172,6 @@ def apply_waveforms_shift(waveforms, peak_shifts, inplace=False):
 
     """
 
-    print("apply_waveforms_shift")
-
     if inplace:
         aligned_waveforms = waveforms
     else:
@@ -193,6 +191,4 @@ def apply_waveforms_shift(waveforms, peak_shifts, inplace=False):
         else:
             aligned_waveforms[mask, -shift:, :] = wfs[:, :-shift, :]
 
-    print("apply_waveforms_shift DONE")
-
     return aligned_waveforms

From 32f2a38360e501381e71855496f7c405eb7098be Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Wed, 13 Nov 2024 09:14:49 +0100
Subject: [PATCH 192/344] WIP

---
 src/spikeinterface/sortingcomponents/clustering/circus.py | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/clustering/circus.py b/src/spikeinterface/sortingcomponents/clustering/circus.py
index 78227a65f3..3eae272fbe 100644
--- a/src/spikeinterface/sortingcomponents/clustering/circus.py
+++ b/src/spikeinterface/sortingcomponents/clustering/circus.py
@@ -257,13 +257,10 @@ def main_function(cls, recording, peaks, params, job_kwargs=dict()):
         if verbose:
             print("We found %d raw clusters, starting to clean with matching..." % (len(templates.unit_ids)))
 
-        cleaning_matching_params = params["job_kwargs"].copy()
-        cleaning_matching_params["n_jobs"] = 1
-        cleaning_matching_params["progress_bar"] = False
         cleaning_params = params["cleaning_kwargs"].copy()
 
         labels, peak_labels = remove_duplicates_via_matching(
-            templates, peak_labels, job_kwargs=cleaning_matching_params, **cleaning_params
+            templates, peak_labels, job_kwargs=job_kwargs, **cleaning_params
         )
 
         if verbose:

From d8d5b7052cb20c7a5cc085031817e158bbac1550 Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Wed, 13 Nov 2024 09:16:25 +0100
Subject: [PATCH 193/344] WIP

---
 src/spikeinterface/sortingcomponents/clustering/circus.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/spikeinterface/sortingcomponents/clustering/circus.py b/src/spikeinterface/sortingcomponents/clustering/circus.py
index 3eae272fbe..5982c270cb 100644
--- a/src/spikeinterface/sortingcomponents/clustering/circus.py
+++ b/src/spikeinterface/sortingcomponents/clustering/circus.py
@@ -257,10 +257,12 @@ def main_function(cls, recording, peaks, params, job_kwargs=dict()):
         if verbose:
             print("We found %d raw clusters, starting to clean with matching..." % (len(templates.unit_ids)))
 
+        cleaning_job_kwargs = job_kwargs.copy()
+        cleaning_job_kwargs["progress_bar"] = False
         cleaning_params = params["cleaning_kwargs"].copy()
 
         labels, peak_labels = remove_duplicates_via_matching(
-            templates, peak_labels, job_kwargs=job_kwargs, **cleaning_params
+            templates, peak_labels, job_kwargs=cleaning_job_kwargs, **cleaning_params
         )
 
         if verbose:

From bd82f45382eb89b9acb4aaa2f18bc0f61286dcec Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Wed, 13 Nov 2024 09:24:15 +0100
Subject: [PATCH 194/344] Cleaning clustering

---
 .../sortingcomponents/clustering/clean.py            |  2 --
 .../clustering/random_projections.py                 | 12 +++---------
 2 files changed, 3 insertions(+), 11 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/clustering/clean.py b/src/spikeinterface/sortingcomponents/clustering/clean.py
index c7d57b14e4..e8bc5a1d49 100644
--- a/src/spikeinterface/sortingcomponents/clustering/clean.py
+++ b/src/spikeinterface/sortingcomponents/clustering/clean.py
@@ -32,7 +32,6 @@ def clean_clusters(
     count = np.zeros(n, dtype="int64")
     for i, label in enumerate(labels_set):
         count[i] = np.sum(peak_labels == label)
-    print(count)
 
     templates = compute_template_from_sparse(peaks, peak_labels, labels_set, sparse_wfs, sparse_mask, total_channels)
 
@@ -42,6 +41,5 @@ def clean_clusters(
         max_values = -np.min(templates, axis=(1, 2))
     elif peak_sign == "pos":
         max_values = np.max(templates, axis=(1, 2))
-    print(max_values)
 
     return clean_labels
diff --git a/src/spikeinterface/sortingcomponents/clustering/random_projections.py b/src/spikeinterface/sortingcomponents/clustering/random_projections.py
index 36033c61e1..40bb4ac987 100644
--- a/src/spikeinterface/sortingcomponents/clustering/random_projections.py
+++ b/src/spikeinterface/sortingcomponents/clustering/random_projections.py
@@ -152,18 +152,12 @@ def main_function(cls, recording, peaks, params, job_kwargs=dict()):
         if verbose:
             print("We found %d raw clusters, starting to clean with matching..." % (len(templates.unit_ids)))
 
-        cleaning_matching_params = job_kwargs.copy()
-        for value in ["chunk_size", "chunk_memory", "total_memory", "chunk_duration"]:
-            if value in cleaning_matching_params:
-                cleaning_matching_params[value] = None
-        cleaning_matching_params["chunk_duration"] = "100ms"
-        cleaning_matching_params["n_jobs"] = 1
-        cleaning_matching_params["progress_bar"] = False
-
+        cleaning_job_kwargs = job_kwargs.copy()
+        cleaning_job_kwargs["progress_bar"] = False
         cleaning_params = params["cleaning_kwargs"].copy()
 
         labels, peak_labels = remove_duplicates_via_matching(
-            templates, peak_labels, job_kwargs=cleaning_matching_params, **cleaning_params
+            templates, peak_labels, job_kwargs=cleaning_job_kwargs, **cleaning_params
         )
 
         if verbose:

From dbe5fa3f914838fe6f6bd10e23a6342396d44448 Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Wed, 13 Nov 2024 09:27:44 +0100
Subject: [PATCH 195/344] WIP

---
 src/spikeinterface/sorters/internal/spyking_circus2.py | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/spikeinterface/sorters/internal/spyking_circus2.py b/src/spikeinterface/sorters/internal/spyking_circus2.py
index eed693b343..5cce8b54f5 100644
--- a/src/spikeinterface/sorters/internal/spyking_circus2.py
+++ b/src/spikeinterface/sorters/internal/spyking_circus2.py
@@ -219,7 +219,6 @@ def _run_from_folder(cls, sorter_output_folder, params, verbose):
             clustering_params["radius_um"] = radius_um
             clustering_params["waveforms"]["ms_before"] = ms_before
             clustering_params["waveforms"]["ms_after"] = ms_after
-            clustering_params["job_kwargs"] = job_kwargs
             clustering_params["noise_levels"] = noise_levels
             clustering_params["ms_before"] = exclude_sweep_ms
             clustering_params["ms_after"] = exclude_sweep_ms
@@ -233,7 +232,7 @@ def _run_from_folder(cls, sorter_output_folder, params, verbose):
                 clustering_method = "random_projections"
 
             labels, peak_labels = find_cluster_from_peaks(
-                recording_w, selected_peaks, method=clustering_method, method_kwargs=clustering_params
+                recording_w, selected_peaks, method=clustering_method, method_kwargs=clustering_params, **job_kwargs
             )
 
             ## We get the labels for our peaks

From 3a78e7ad216ff8e9b927204555c94e4d42aaad17 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Wed, 13 Nov 2024 08:30:34 +0000
Subject: [PATCH 196/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 .../sortingcomponents/clustering/position_and_pca.py          | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/clustering/position_and_pca.py b/src/spikeinterface/sortingcomponents/clustering/position_and_pca.py
index 3b730752c1..c4f372fc21 100644
--- a/src/spikeinterface/sortingcomponents/clustering/position_and_pca.py
+++ b/src/spikeinterface/sortingcomponents/clustering/position_and_pca.py
@@ -84,9 +84,7 @@ def main_function(cls, recording, peaks, params, job_kwargs=dict()):
         if params["peak_locations"] is None:
             from spikeinterface.sortingcomponents.peak_localization import localize_peaks
 
-            peak_locations = localize_peaks(
-                recording, peaks, **params["peak_localization_kwargs"], **job_kwargs
-            )
+            peak_locations = localize_peaks(recording, peaks, **params["peak_localization_kwargs"], **job_kwargs)
         else:
             peak_locations = params["peak_locations"]
 

From 620f8013b8bf4f1332a7802dd3f6804ce068493c Mon Sep 17 00:00:00 2001
From: JoeZiminski <Joseph.j.ziminski@gmail.com>
Date: Wed, 13 Nov 2024 13:37:50 +0000
Subject: [PATCH 197/344] Apply to all segments if 'segment_index' is 'None'.

---
 src/spikeinterface/core/baserecording.py | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)

diff --git a/src/spikeinterface/core/baserecording.py b/src/spikeinterface/core/baserecording.py
index b8a0420794..7392caa69b 100644
--- a/src/spikeinterface/core/baserecording.py
+++ b/src/spikeinterface/core/baserecording.py
@@ -521,13 +521,20 @@ def shift_start_time(self, shift, segment_index=None):
         segment_index : int | None
             The segment on which to shift the times.
         """
-        segment_index = self._check_segment_index(segment_index)
-        rs = self._recording_segments[segment_index]
+        self._check_segment_index(segment_index)
 
-        if self.has_time_vector():
-            rs.time_vector += shift
+        if segment_index is None:
+            segments_to_shift = range(self.get_num_segments())
         else:
-            rs.t_start += shift
+            segments_to_shift = (segment_index,)
+
+        for idx in segments_to_shift:
+            rs = self._recording_segments[idx]
+
+            if self.has_time_vector():
+                rs.time_vector += shift
+            else:
+                rs.t_start += shift
 
     def sample_index_to_time(self, sample_ind, segment_index=None):
         """

From 22d5dfc2a552e00d7b55d7c28681e25a1f51a711 Mon Sep 17 00:00:00 2001
From: JoeZiminski <Joseph.j.ziminski@gmail.com>
Date: Wed, 13 Nov 2024 13:39:34 +0000
Subject: [PATCH 198/344] Add type hints.

---
 src/spikeinterface/core/baserecording.py | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/src/spikeinterface/core/baserecording.py b/src/spikeinterface/core/baserecording.py
index 7392caa69b..0af9c4bb6a 100644
--- a/src/spikeinterface/core/baserecording.py
+++ b/src/spikeinterface/core/baserecording.py
@@ -509,7 +509,7 @@ def reset_times(self):
             rs.t_start = None
             rs.sampling_frequency = self.sampling_frequency
 
-    def shift_start_time(self, shift, segment_index=None):
+    def shift_start_time(self, shift: int | float, segment_index: int | None = None) -> None:
         """
         Shift the starting time of the times.
 
@@ -536,15 +536,14 @@ def shift_start_time(self, shift, segment_index=None):
             else:
                 rs.t_start += shift
 
-    def sample_index_to_time(self, sample_ind, segment_index=None):
-        """
-        Transform sample index into time in seconds
-        """
+    def sample_index_to_time(self, sample_ind: int, segment_index: int | None = None):
+        """ """
         segment_index = self._check_segment_index(segment_index)
         rs = self._recording_segments[segment_index]
         return rs.sample_index_to_time(sample_ind)
 
-    def time_to_sample_index(self, time_s, segment_index=None):
+    def time_to_sample_index(self, time_s: float, segment_index: int | None = None):
+        """ """
         segment_index = self._check_segment_index(segment_index)
         rs = self._recording_segments[segment_index]
         return rs.time_to_sample_index(time_s)

From 458a3dcc201380740583ef1f075951e83ee77ed8 Mon Sep 17 00:00:00 2001
From: JoeZiminski <Joseph.j.ziminski@gmail.com>
Date: Wed, 13 Nov 2024 13:43:45 +0000
Subject: [PATCH 199/344] Update name and docstring.

---
 src/spikeinterface/core/baserecording.py | 19 ++++++++++++-------
 1 file changed, 12 insertions(+), 7 deletions(-)

diff --git a/src/spikeinterface/core/baserecording.py b/src/spikeinterface/core/baserecording.py
index 0af9c4bb6a..91f99f17b0 100644
--- a/src/spikeinterface/core/baserecording.py
+++ b/src/spikeinterface/core/baserecording.py
@@ -509,19 +509,24 @@ def reset_times(self):
             rs.t_start = None
             rs.sampling_frequency = self.sampling_frequency
 
-    def shift_start_time(self, shift: int | float, segment_index: int | None = None) -> None:
+    def shift_times(self, shift: int | float, segment_index: int | None = None) -> None:
         """
-        Shift the starting time of the times.
+        Shift all times by a scalar value. The default behaviour is to
+        shift all segments uniformly.
 
+        Parameters
+        ----------
         shift : int | float
-            The shift to apply to the first time point. If positive,
-            the current start time will be increased by `shift`. If
-            negative, the start time will be decreased.
+            The shift to apply. If positive, times will be increased by `shift`.
+            e.g. shifting by 1 will be like the recording started 1 second later.
+            If negative, the start time will be decreased i.e. as if the recording
+            started earlier.
 
         segment_index : int | None
-            The segment on which to shift the times.
+            The segment on which to shift the times. if `None`, all
+            segments will be shifted.
         """
-        self._check_segment_index(segment_index)
+        self._check_segment_index(segment_index)  # Check the segment index is valid only
 
         if segment_index is None:
             segments_to_shift = range(self.get_num_segments())

From 035d8d2a4f24f27a5cb9f314e05acb2b3448fb98 Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Wed, 13 Nov 2024 15:36:44 +0100
Subject: [PATCH 200/344] Fix

---
 .../sortingcomponents/clustering/sliding_hdbscan.py           | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/clustering/sliding_hdbscan.py b/src/spikeinterface/sortingcomponents/clustering/sliding_hdbscan.py
index ee56894b13..56f7e35096 100644
--- a/src/spikeinterface/sortingcomponents/clustering/sliding_hdbscan.py
+++ b/src/spikeinterface/sortingcomponents/clustering/sliding_hdbscan.py
@@ -65,7 +65,7 @@ def main_function(cls, recording, peaks, params, job_kwargs=dict()):
         peak_labels = cls._find_clusters(recording, peaks, wfs_arrays, sparsity_mask, noise, params)
 
         wfs_arrays2, sparsity_mask2 = cls._prepare_clean(
-            recording, peaks, wfs_arrays, sparsity_mask, peak_labels, params
+            recording, peaks, wfs_arrays, sparsity_mask, peak_labels, params, job_kwargs
         )
 
         clean_peak_labels, peak_sample_shifts = cls._clean_cluster(
@@ -400,7 +400,7 @@ def _find_clusters(cls, recording, peaks, wfs_arrays, sparsity_mask, noise, d):
         return peak_labels
 
     @classmethod
-    def _prepare_clean(cls, recording, peaks, wfs_arrays, sparsity_mask, peak_labels, d):
+    def _prepare_clean(cls, recording, peaks, wfs_arrays, sparsity_mask, peak_labels, d, job_kwargs):
         tmp_folder = d["tmp_folder"]
         if tmp_folder is None:
             wf_folder = None

From 8845d3d7eb6caad8c6a5f0c12842f480766d3a26 Mon Sep 17 00:00:00 2001
From: chrishalcrow <57948917+chrishalcrow@users.noreply.github.com>
Date: Wed, 13 Nov 2024 14:40:16 +0000
Subject: [PATCH 201/344] Add verbose kwarg to mda write_recording

---
 src/spikeinterface/extractors/mdaextractors.py | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/src/spikeinterface/extractors/mdaextractors.py b/src/spikeinterface/extractors/mdaextractors.py
index f055e1d7c9..d2886d9e79 100644
--- a/src/spikeinterface/extractors/mdaextractors.py
+++ b/src/spikeinterface/extractors/mdaextractors.py
@@ -72,6 +72,7 @@ def write_recording(
         params_fname="params.json",
         geom_fname="geom.csv",
         dtype=None,
+        verbose=False,
         **job_kwargs,
     ):
         """Write a recording to file in MDA format.
@@ -93,6 +94,8 @@ def write_recording(
             File name of geom file
         dtype : dtype or None, default: None
             Data type to be used. If None dtype is same as recording traces.
+        verbose : bool
+            If True, shows progress bar when saving recording.
         **job_kwargs:
             Use by job_tools modules to set:
 
@@ -130,6 +133,7 @@ def write_recording(
             dtype=dtype,
             byte_offset=header_size,
             add_file_extension=False,
+            verbose=verbose,
             **job_kwargs,
         )
 

From 389c86cb07322107f927225868e61c6bf20c263b Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Wed, 13 Nov 2024 16:01:34 +0100
Subject: [PATCH 202/344] Fixes

---
 .../sortingcomponents/clustering/sliding_hdbscan.py           | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/clustering/sliding_hdbscan.py b/src/spikeinterface/sortingcomponents/clustering/sliding_hdbscan.py
index 56f7e35096..2ae810ae20 100644
--- a/src/spikeinterface/sortingcomponents/clustering/sliding_hdbscan.py
+++ b/src/spikeinterface/sortingcomponents/clustering/sliding_hdbscan.py
@@ -99,7 +99,7 @@ def _check_params(cls, recording, peaks, params):
         return params2
 
     @classmethod
-    def _initialize_folder(cls, recording, peaks, params):
+    def _initialize_folder(cls, recording, peaks, params, job_kwargs=dict()):
         d = params
         tmp_folder = params["tmp_folder"]
 
@@ -400,7 +400,7 @@ def _find_clusters(cls, recording, peaks, wfs_arrays, sparsity_mask, noise, d):
         return peak_labels
 
     @classmethod
-    def _prepare_clean(cls, recording, peaks, wfs_arrays, sparsity_mask, peak_labels, d, job_kwargs):
+    def _prepare_clean(cls, recording, peaks, wfs_arrays, sparsity_mask, peak_labels, d, job_kwargs=dict()):
         tmp_folder = d["tmp_folder"]
         if tmp_folder is None:
             wf_folder = None

From 3e98c670a27671590613b7c1c4118780a8c47ce8 Mon Sep 17 00:00:00 2001
From: JoeZiminski <Joseph.j.ziminski@gmail.com>
Date: Wed, 13 Nov 2024 18:32:48 +0000
Subject: [PATCH 203/344] Add tests.

---
 .../core/tests/test_time_handling.py          | 92 ++++++++++++++++++-
 1 file changed, 89 insertions(+), 3 deletions(-)

diff --git a/src/spikeinterface/core/tests/test_time_handling.py b/src/spikeinterface/core/tests/test_time_handling.py
index a129316ee7..9b7ed11bbb 100644
--- a/src/spikeinterface/core/tests/test_time_handling.py
+++ b/src/spikeinterface/core/tests/test_time_handling.py
@@ -15,7 +15,10 @@ class TestTimeHandling:
     is generated on the fly. Both time representations are tested here.
     """
 
-    # Fixtures #####
+    # #########################################################################
+    # Fixtures
+    # #########################################################################
+
     @pytest.fixture(scope="session")
     def time_vector_recording(self):
         """
@@ -95,7 +98,10 @@ def _get_fixture_data(self, request, fixture_name):
         raw_recording, times_recording, all_times = time_recording_fixture
         return (raw_recording, times_recording, all_times)
 
-    # Tests #####
+    # #########################################################################
+    # Tests
+    # #########################################################################
+
     def test_has_time_vector(self, time_vector_recording):
         """
         Test the `has_time_vector` function returns `False` before
@@ -305,7 +311,87 @@ def test_sorting_analyzer_get_durations_no_recording(self, time_vector_recording
 
         assert np.array_equal(sorting_analyzer.get_total_duration(), raw_recording.get_total_duration())
 
-    # Helpers ####
+    @pytest.mark.parametrize("fixture_name", ["time_vector_recording", "t_start_recording"])
+    @pytest.mark.parametrize("shift", [-123.456, 123.456])
+    def test_shift_time_all_segments(self, request, fixture_name, shift):
+        """
+        Shift the times in every segment using the `None` default, then
+        check that every segment of the recording is shifted as expected.
+        """
+        _, times_recording, all_times = self._get_fixture_data(request, fixture_name)
+
+        num_segments, orig_seg_data = self._store_all_times(times_recording)
+
+        times_recording.shift_times(shift)  # use default `segment_index=None`
+
+        for idx in range(num_segments):
+            assert np.allclose(
+                orig_seg_data[idx], times_recording.get_times(segment_index=idx) - shift, rtol=0, atol=1e-8
+            )
+
+    @pytest.mark.parametrize("fixture_name", ["time_vector_recording", "t_start_recording"])
+    @pytest.mark.parametrize("shift", [-123.456, 123.456])
+    def test_shift_times_different_segments(self, request, fixture_name, shift):
+        """
+        Shift each segment separately, and check the shifted segment only
+        is shifted as expected.
+        """
+        _, times_recording, all_times = self._get_fixture_data(request, fixture_name)
+
+        num_segments, orig_seg_data = self._store_all_times(times_recording)
+
+        # For each segment, shift the segment only and check the
+        # times are updated as expected.
+        for idx in range(num_segments):
+
+            scaler = idx + 2
+            times_recording.shift_times(shift * scaler, segment_index=idx)
+
+            assert np.allclose(
+                orig_seg_data[idx], times_recording.get_times(segment_index=idx) - shift * scaler, rtol=0, atol=1e-8
+            )
+
+            # Just do a little check that we are not
+            # accidentally changing some other segments,
+            # which should remain unchanged at this point in the loop.
+            if idx != num_segments - 1:
+                assert np.array_equal(orig_seg_data[idx + 1], times_recording.get_times(segment_index=idx + 1))
+
+    @pytest.mark.parametrize("fixture_name", ["time_vector_recording", "t_start_recording"])
+    def test_save_and_load_time_shift(self, request, fixture_name, tmp_path):
+        """
+        Save the shifted data and check the shift is propagated correctly.
+        """
+        _, times_recording, all_times = self._get_fixture_data(request, fixture_name)
+
+        shift = 100
+        times_recording.shift_times(shift=shift)
+
+        times_recording.save(folder=tmp_path / "my_file")
+
+        loaded_recording = si.load_extractor(tmp_path / "my_file")
+
+        for idx in range(times_recording.get_num_segments()):
+            assert np.array_equal(
+                times_recording.get_times(segment_index=idx), loaded_recording.get_times(segment_index=idx)
+            )
+
+    def _store_all_times(self, recording):
+        """
+        Convenience function to store original times of all segments to a dict.
+        """
+        num_segments = recording.get_num_segments()
+        seg_data = {}
+
+        for idx in range(num_segments):
+            seg_data[idx] = copy.deepcopy(recording.get_times(segment_index=idx))
+
+        return num_segments, seg_data
+
+    # #########################################################################
+    # Helpers
+    # #########################################################################
+
     def _check_times_match(self, recording, all_times):
         """
         For every segment in a recording, check the `get_times()`

From 4d7246a529e3d17747cf5a496a0a04bd97f4eb09 Mon Sep 17 00:00:00 2001
From: JoeZiminski <Joseph.j.ziminski@gmail.com>
Date: Wed, 13 Nov 2024 18:33:17 +0000
Subject: [PATCH 204/344] Fixes on shift function.

---
 src/spikeinterface/core/baserecording.py | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/src/spikeinterface/core/baserecording.py b/src/spikeinterface/core/baserecording.py
index 91f99f17b0..4b545dc7c7 100644
--- a/src/spikeinterface/core/baserecording.py
+++ b/src/spikeinterface/core/baserecording.py
@@ -526,8 +526,6 @@ def shift_times(self, shift: int | float, segment_index: int | None = None) -> N
             The segment on which to shift the times. if `None`, all
             segments will be shifted.
         """
-        self._check_segment_index(segment_index)  # Check the segment index is valid only
-
         if segment_index is None:
             segments_to_shift = range(self.get_num_segments())
         else:
@@ -536,7 +534,7 @@ def shift_times(self, shift: int | float, segment_index: int | None = None) -> N
         for idx in segments_to_shift:
             rs = self._recording_segments[idx]
 
-            if self.has_time_vector():
+            if self.has_time_vector(segment_index=idx):
                 rs.time_vector += shift
             else:
                 rs.t_start += shift

From a1cf3367d18a549281208b25c622f2a1ee773226 Mon Sep 17 00:00:00 2001
From: JoeZiminski <Joseph.j.ziminski@gmail.com>
Date: Wed, 13 Nov 2024 18:35:32 +0000
Subject: [PATCH 205/344] Undo out of scope changes.

---
 src/spikeinterface/core/baserecording.py | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/src/spikeinterface/core/baserecording.py b/src/spikeinterface/core/baserecording.py
index 4b545dc7c7..886f7db79f 100644
--- a/src/spikeinterface/core/baserecording.py
+++ b/src/spikeinterface/core/baserecording.py
@@ -539,14 +539,15 @@ def shift_times(self, shift: int | float, segment_index: int | None = None) -> N
             else:
                 rs.t_start += shift
 
-    def sample_index_to_time(self, sample_ind: int, segment_index: int | None = None):
-        """ """
+    def sample_index_to_time(self, sample_ind, segment_index=None):
+        """
+        Transform sample index into time in seconds
+        """
         segment_index = self._check_segment_index(segment_index)
         rs = self._recording_segments[segment_index]
         return rs.sample_index_to_time(sample_ind)
 
-    def time_to_sample_index(self, time_s: float, segment_index: int | None = None):
-        """ """
+    def time_to_sample_index(self, time_s, segment_index=None):
         segment_index = self._check_segment_index(segment_index)
         rs = self._recording_segments[segment_index]
         return rs.time_to_sample_index(time_s)

From 469b3b0e36fdbc0571d37e100d99d6c741af1377 Mon Sep 17 00:00:00 2001
From: JoeZiminski <Joseph.j.ziminski@gmail.com>
Date: Wed, 13 Nov 2024 18:37:20 +0000
Subject: [PATCH 206/344] Fix docstring.

---
 src/spikeinterface/core/baserecording.py | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/src/spikeinterface/core/baserecording.py b/src/spikeinterface/core/baserecording.py
index 886f7db79f..6d9d2a827f 100644
--- a/src/spikeinterface/core/baserecording.py
+++ b/src/spikeinterface/core/baserecording.py
@@ -511,8 +511,7 @@ def reset_times(self):
 
     def shift_times(self, shift: int | float, segment_index: int | None = None) -> None:
         """
-        Shift all times by a scalar value. The default behaviour is to
-        shift all segments uniformly.
+        Shift all times by a scalar value.
 
         Parameters
         ----------
@@ -523,8 +522,8 @@ def shift_times(self, shift: int | float, segment_index: int | None = None) -> N
             started earlier.
 
         segment_index : int | None
-            The segment on which to shift the times. if `None`, all
-            segments will be shifted.
+            The segment on which to shift the times.
+            If `None`, all segments will be shifted.
         """
         if segment_index is None:
             segments_to_shift = range(self.get_num_segments())

From 530864bceda4b436f5cf16fd5258efd19ccaa76d Mon Sep 17 00:00:00 2001
From: chrishalcrow <57948917+chrishalcrow@users.noreply.github.com>
Date: Thu, 14 Nov 2024 09:33:03 +0000
Subject: [PATCH 207/344] Replace qm_params with metric_params

---
 .../qualitymetrics/pca_metrics.py             | 36 ++++++++++++-------
 .../quality_metric_calculator.py              | 30 ++++++++++------
 .../tests/test_metrics_functions.py           | 10 +++---
 3 files changed, 47 insertions(+), 29 deletions(-)

diff --git a/src/spikeinterface/qualitymetrics/pca_metrics.py b/src/spikeinterface/qualitymetrics/pca_metrics.py
index 4c68dfea59..b4952bfe6d 100644
--- a/src/spikeinterface/qualitymetrics/pca_metrics.py
+++ b/src/spikeinterface/qualitymetrics/pca_metrics.py
@@ -6,6 +6,7 @@
 from copy import deepcopy
 import platform
 from tqdm.auto import tqdm
+from warnings import warn
 
 import numpy as np
 
@@ -52,6 +53,7 @@ def get_quality_pca_metric_list():
 def compute_pc_metrics(
     sorting_analyzer,
     metric_names=None,
+    metric_params=None,
     qm_params=None,
     unit_ids=None,
     seed=None,
@@ -70,7 +72,7 @@ def compute_pc_metrics(
     metric_names : list of str, default: None
         The list of PC metrics to compute.
         If not provided, defaults to all PC metrics.
-    qm_params : dict or None
+    metric_params : dict or None
         Dictionary with parameters for each PC metric function.
     unit_ids : list of int or None
         List of unit ids to compute metrics for.
@@ -86,6 +88,14 @@ def compute_pc_metrics(
     pc_metrics : dict
         The computed PC metrics.
     """
+
+    if qm_params is not None and metric_params is None:
+        deprecation_msg = (
+            "`qm_params` is deprecated and will be removed in version 0.104.0 Please use metric_params instead"
+        )
+        metric_params = qm_params
+        warn(deprecation_msg, category=DeprecationWarning, stacklevel=2)
+
     pca_ext = sorting_analyzer.get_extension("principal_components")
     assert pca_ext is not None, "calculate_pc_metrics() need extension 'principal_components'"
 
@@ -93,8 +103,8 @@ def compute_pc_metrics(
 
     if metric_names is None:
         metric_names = _possible_pc_metric_names.copy()
-    if qm_params is None:
-        qm_params = _default_params
+    if metric_params is None:
+        metric_params = _default_params
 
     extremum_channels = get_template_extremum_channel(sorting_analyzer)
 
@@ -147,7 +157,7 @@ def compute_pc_metrics(
         pcs = dense_projections[np.isin(all_labels, neighbor_unit_ids)][:, :, neighbor_channel_indices]
         pcs_flat = pcs.reshape(pcs.shape[0], -1)
 
-        func_args = (pcs_flat, labels, non_nn_metrics, unit_id, unit_ids, qm_params, max_threads_per_process)
+        func_args = (pcs_flat, labels, non_nn_metrics, unit_id, unit_ids, metric_params, max_threads_per_process)
         items.append(func_args)
 
     if not run_in_parallel and non_nn_metrics:
@@ -184,7 +194,7 @@ def compute_pc_metrics(
             units_loop = tqdm(units_loop, desc=f"calculate {metric_name} metric", total=len(unit_ids))
 
         func = _nn_metric_name_to_func[metric_name]
-        metric_params = qm_params[metric_name] if metric_name in qm_params else {}
+        metric_params = metric_params[metric_name] if metric_name in metric_params else {}
 
         for _, unit_id in units_loop:
             try:
@@ -213,7 +223,7 @@ def compute_pc_metrics(
 
 
 def calculate_pc_metrics(
-    sorting_analyzer, metric_names=None, qm_params=None, unit_ids=None, seed=None, n_jobs=1, progress_bar=False
+    sorting_analyzer, metric_names=None, metric_params=None, unit_ids=None, seed=None, n_jobs=1, progress_bar=False
 ):
     warnings.warn(
         "The `calculate_pc_metrics` function is deprecated and will be removed in 0.103.0. Please use compute_pc_metrics instead",
@@ -224,7 +234,7 @@ def calculate_pc_metrics(
     pc_metrics = compute_pc_metrics(
         sorting_analyzer,
         metric_names=metric_names,
-        qm_params=qm_params,
+        metric_params=metric_params,
         unit_ids=unit_ids,
         seed=seed,
         n_jobs=n_jobs,
@@ -977,16 +987,16 @@ def _compute_isolation(pcs_target_unit, pcs_other_unit, n_neighbors: int):
 
 
 def pca_metrics_one_unit(args):
-    (pcs_flat, labels, metric_names, unit_id, unit_ids, qm_params, max_threads_per_process) = args
+    (pcs_flat, labels, metric_names, unit_id, unit_ids, metric_params, max_threads_per_process) = args
 
     if max_threads_per_process is None:
-        return _pca_metrics_one_unit(pcs_flat, labels, metric_names, unit_id, unit_ids, qm_params)
+        return _pca_metrics_one_unit(pcs_flat, labels, metric_names, unit_id, unit_ids, metric_params)
     else:
         with threadpool_limits(limits=int(max_threads_per_process)):
-            return _pca_metrics_one_unit(pcs_flat, labels, metric_names, unit_id, unit_ids, qm_params)
+            return _pca_metrics_one_unit(pcs_flat, labels, metric_names, unit_id, unit_ids, metric_params)
 
 
-def _pca_metrics_one_unit(pcs_flat, labels, metric_names, unit_id, unit_ids, qm_params):
+def _pca_metrics_one_unit(pcs_flat, labels, metric_names, unit_id, unit_ids, metric_params):
     pc_metrics = {}
     # metrics
     if "isolation_distance" in metric_names or "l_ratio" in metric_names:
@@ -1015,7 +1025,7 @@ def _pca_metrics_one_unit(pcs_flat, labels, metric_names, unit_id, unit_ids, qm_
     if "nearest_neighbor" in metric_names:
         try:
             nn_hit_rate, nn_miss_rate = nearest_neighbors_metrics(
-                pcs_flat, labels, unit_id, **qm_params["nearest_neighbor"]
+                pcs_flat, labels, unit_id, **metric_params["nearest_neighbor"]
             )
         except:
             nn_hit_rate = np.nan
@@ -1024,7 +1034,7 @@ def _pca_metrics_one_unit(pcs_flat, labels, metric_names, unit_id, unit_ids, qm_
         pc_metrics["nn_miss_rate"] = nn_miss_rate
 
     if "silhouette" in metric_names:
-        silhouette_method = qm_params["silhouette"]["method"]
+        silhouette_method = metric_params["silhouette"]["method"]
         if "simplified" in silhouette_method:
             try:
                 unit_silhouette_score = simplified_silhouette_score(pcs_flat, labels, unit_id)
diff --git a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
index b6a50d60f5..eb380304b6 100644
--- a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
+++ b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
@@ -6,6 +6,7 @@
 from copy import deepcopy
 
 import numpy as np
+from warnings import warn
 
 from spikeinterface.core.job_tools import fix_job_kwargs
 from spikeinterface.core.sortinganalyzer import register_result_extension, AnalyzerExtension
@@ -31,7 +32,7 @@ class ComputeQualityMetrics(AnalyzerExtension):
         A SortingAnalyzer object.
     metric_names : list or None
         List of quality metrics to compute.
-    qm_params : dict or None
+    metric_params : dict or None
         Dictionary with parameters for quality metrics calculation.
         Default parameters can be obtained with: `si.qualitymetrics.get_default_qm_params()`
     skip_pc_metrics : bool, default: False
@@ -58,6 +59,7 @@ class ComputeQualityMetrics(AnalyzerExtension):
     def _set_params(
         self,
         metric_names=None,
+        metric_params=None,
         qm_params=None,
         peak_sign=None,
         seed=None,
@@ -65,6 +67,12 @@ def _set_params(
         delete_existing_metrics=False,
         metrics_to_compute=None,
     ):
+        if qm_params is not None and metric_params is None:
+            deprecation_msg = (
+                "`qm_params` is deprecated and will be removed in version 0.104.0 Please use metric_params instead"
+            )
+            metric_params = qm_params
+            warn(deprecation_msg, category=DeprecationWarning, stacklevel=2)
 
         if metric_names is None:
             metric_names = list(_misc_metric_name_to_func.keys())
@@ -80,12 +88,12 @@ def _set_params(
                 if "drift" in metric_names:
                     metric_names.remove("drift")
 
-        qm_params_ = get_default_qm_params()
-        for k in qm_params_:
-            if qm_params is not None and k in qm_params:
-                qm_params_[k].update(qm_params[k])
-            if "peak_sign" in qm_params_[k] and peak_sign is not None:
-                qm_params_[k]["peak_sign"] = peak_sign
+        metric_params_ = get_default_qm_params()
+        for k in metric_params_:
+            if metric_params is not None and k in metric_params:
+                metric_params_[k].update(metric_params[k])
+            if "peak_sign" in metric_params_[k] and peak_sign is not None:
+                metric_params_[k]["peak_sign"] = peak_sign
 
         metrics_to_compute = metric_names
         qm_extension = self.sorting_analyzer.get_extension("quality_metrics")
@@ -101,7 +109,7 @@ def _set_params(
             metric_names=metric_names,
             peak_sign=peak_sign,
             seed=seed,
-            qm_params=qm_params_,
+            metric_params=metric_params_,
             skip_pc_metrics=skip_pc_metrics,
             delete_existing_metrics=delete_existing_metrics,
             metrics_to_compute=metrics_to_compute,
@@ -141,7 +149,7 @@ def _compute_metrics(self, sorting_analyzer, unit_ids=None, verbose=False, metri
         """
         import pandas as pd
 
-        qm_params = self.params["qm_params"]
+        metric_params = self.params["metric_params"]
         # sparsity = self.params["sparsity"]
         seed = self.params["seed"]
 
@@ -177,7 +185,7 @@ def _compute_metrics(self, sorting_analyzer, unit_ids=None, verbose=False, metri
 
             func = _misc_metric_name_to_func[metric_name]
 
-            params = qm_params[metric_name] if metric_name in qm_params else {}
+            params = metric_params[metric_name] if metric_name in metric_params else {}
             res = func(sorting_analyzer, unit_ids=non_empty_unit_ids, **params)
             # QM with uninstall dependencies might return None
             if res is not None:
@@ -205,7 +213,7 @@ def _compute_metrics(self, sorting_analyzer, unit_ids=None, verbose=False, metri
                 # sparsity=sparsity,
                 progress_bar=progress_bar,
                 n_jobs=n_jobs,
-                qm_params=qm_params,
+                metric_params=metric_params,
                 seed=seed,
             )
             for col, values in pc_metrics.items():
diff --git a/src/spikeinterface/qualitymetrics/tests/test_metrics_functions.py b/src/spikeinterface/qualitymetrics/tests/test_metrics_functions.py
index 4c0890b62b..20869aa44a 100644
--- a/src/spikeinterface/qualitymetrics/tests/test_metrics_functions.py
+++ b/src/spikeinterface/qualitymetrics/tests/test_metrics_functions.py
@@ -69,7 +69,7 @@ def test_compute_new_quality_metrics(small_sorting_analyzer):
     assert calculated_metrics == ["snr"]
 
     small_sorting_analyzer.compute(
-        {"quality_metrics": {"metric_names": list(qm_params.keys()), "qm_params": qm_params}}
+        {"quality_metrics": {"metric_names": list(qm_params.keys()), "metric_params": qm_params}}
     )
     small_sorting_analyzer.compute({"quality_metrics": {"metric_names": ["snr"]}})
 
@@ -96,13 +96,13 @@ def test_compute_new_quality_metrics(small_sorting_analyzer):
     # check that, when parameters are changed, the data and metadata are updated
     old_snr_data = deepcopy(quality_metric_extension.get_data()["snr"].values)
     small_sorting_analyzer.compute(
-        {"quality_metrics": {"metric_names": ["snr"], "qm_params": {"snr": {"peak_mode": "peak_to_peak"}}}}
+        {"quality_metrics": {"metric_names": ["snr"], "metric_params": {"snr": {"peak_mode": "peak_to_peak"}}}}
     )
     new_quality_metric_extension = small_sorting_analyzer.get_extension("quality_metrics")
     new_snr_data = new_quality_metric_extension.get_data()["snr"].values
 
     assert np.all(old_snr_data != new_snr_data)
-    assert new_quality_metric_extension.params["qm_params"]["snr"]["peak_mode"] == "peak_to_peak"
+    assert new_quality_metric_extension.params["metric_params"]["snr"]["peak_mode"] == "peak_to_peak"
 
     # check that all quality metrics are deleted when parents are recomputed, even after
     # recomputation
@@ -280,10 +280,10 @@ def test_unit_id_order_independence(small_sorting_analyzer):
     }
 
     quality_metrics_1 = compute_quality_metrics(
-        small_sorting_analyzer, metric_names=get_quality_metric_list(), qm_params=qm_params
+        small_sorting_analyzer, metric_names=get_quality_metric_list(), metric_params=qm_params
     )
     quality_metrics_2 = compute_quality_metrics(
-        small_sorting_analyzer_2, metric_names=get_quality_metric_list(), qm_params=qm_params
+        small_sorting_analyzer_2, metric_names=get_quality_metric_list(), metric_params=qm_params
     )
 
     for metric, metric_2_data in quality_metrics_2.items():

From 908318a04731f6e8723a9cf3b34914d8e782e900 Mon Sep 17 00:00:00 2001
From: chrishalcrow <57948917+chrishalcrow@users.noreply.github.com>
Date: Thu, 14 Nov 2024 09:38:28 +0000
Subject: [PATCH 208/344] fix tests

---
 .../tests/test_quality_metric_calculator.py          | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py b/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py
index a6415c58e8..60f0490f51 100644
--- a/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py
+++ b/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py
@@ -24,14 +24,14 @@ def test_compute_quality_metrics(sorting_analyzer_simple):
     metrics = compute_quality_metrics(
         sorting_analyzer,
         metric_names=["snr"],
-        qm_params=dict(isi_violation=dict(isi_threshold_ms=2)),
+        metric_params=dict(isi_violation=dict(isi_threshold_ms=2)),
         skip_pc_metrics=True,
         seed=2205,
     )
     # print(metrics)
 
     qm = sorting_analyzer.get_extension("quality_metrics")
-    assert qm.params["qm_params"]["isi_violation"]["isi_threshold_ms"] == 2
+    assert qm.params["metric_params"]["isi_violation"]["isi_threshold_ms"] == 2
     assert "snr" in metrics.columns
     assert "isolation_distance" not in metrics.columns
 
@@ -40,7 +40,7 @@ def test_compute_quality_metrics(sorting_analyzer_simple):
     metrics = compute_quality_metrics(
         sorting_analyzer,
         metric_names=None,
-        qm_params=dict(isi_violation=dict(isi_threshold_ms=2)),
+        metric_params=dict(isi_violation=dict(isi_threshold_ms=2)),
         skip_pc_metrics=False,
         seed=2205,
     )
@@ -54,7 +54,7 @@ def test_compute_quality_metrics_recordingless(sorting_analyzer_simple):
     metrics = compute_quality_metrics(
         sorting_analyzer,
         metric_names=None,
-        qm_params=dict(isi_violation=dict(isi_threshold_ms=2)),
+        metric_params=dict(isi_violation=dict(isi_threshold_ms=2)),
         skip_pc_metrics=False,
         seed=2205,
     )
@@ -68,7 +68,7 @@ def test_compute_quality_metrics_recordingless(sorting_analyzer_simple):
     metrics_norec = compute_quality_metrics(
         sorting_analyzer_norec,
         metric_names=None,
-        qm_params=dict(isi_violation=dict(isi_threshold_ms=2)),
+        metric_params=dict(isi_violation=dict(isi_threshold_ms=2)),
         skip_pc_metrics=False,
         seed=2205,
     )
@@ -101,7 +101,7 @@ def test_empty_units(sorting_analyzer_simple):
     metrics_empty = compute_quality_metrics(
         sorting_analyzer_empty,
         metric_names=None,
-        qm_params=dict(isi_violation=dict(isi_threshold_ms=2)),
+        metric_params=dict(isi_violation=dict(isi_threshold_ms=2)),
         skip_pc_metrics=True,
         seed=2205,
     )

From 2706a0bee9fef9dd3b3a4af99715366aae1c1625 Mon Sep 17 00:00:00 2001
From: chrishalcrow <57948917+chrishalcrow@users.noreply.github.com>
Date: Thu, 14 Nov 2024 09:45:28 +0000
Subject: [PATCH 209/344] Change metrics_kwargs to metric_params and add
 depreciation message

---
 .../postprocessing/template_metrics.py        | 36 +++++++++++--------
 .../tests/test_template_metrics.py            |  2 +-
 2 files changed, 23 insertions(+), 15 deletions(-)

diff --git a/src/spikeinterface/postprocessing/template_metrics.py b/src/spikeinterface/postprocessing/template_metrics.py
index 6e7bcf21b8..ef6abfe51f 100644
--- a/src/spikeinterface/postprocessing/template_metrics.py
+++ b/src/spikeinterface/postprocessing/template_metrics.py
@@ -63,8 +63,8 @@ class ComputeTemplateMetrics(AnalyzerExtension):
     include_multi_channel_metrics : bool, default: False
         Whether to compute multi-channel metrics
     delete_existing_metrics : bool, default: False
-        If True, any template metrics attached to the `sorting_analyzer` are deleted. If False, any metrics which were previously calculated but are not included in `metric_names` are kept, provided the `metrics_kwargs` are unchanged.
-    metrics_kwargs : dict
+        If True, any template metrics attached to the `sorting_analyzer` are deleted. If False, any metrics which were previously calculated but are not included in `metric_names` are kept, provided the `metric_params` are unchanged.
+    metric_params : dict
         Additional arguments to pass to the metric functions. Including:
             * recovery_window_ms: the window in ms after the peak to compute the recovery_slope, default: 0.7
             * peak_relative_threshold: the relative threshold to detect positive and negative peaks, default: 0.2
@@ -109,12 +109,20 @@ def _set_params(
         peak_sign="neg",
         upsampling_factor=10,
         sparsity=None,
+        metric_params=None,
         metrics_kwargs=None,
         include_multi_channel_metrics=False,
         delete_existing_metrics=False,
         **other_kwargs,
     ):
 
+        if metrics_kwargs is not None and metric_params is None:
+            deprecation_msg = (
+                "`qm_params` is deprecated and will be removed in version 0.104.0 Please use metric_params instead"
+            )
+            metric_params = metrics_kwargs
+            warnings.warn(deprecation_msg, category=DeprecationWarning, stacklevel=2)
+
         import pandas as pd
 
         # TODO alessio can you check this : this used to be in the function but now we have ComputeTemplateMetrics.function_factory()
@@ -134,27 +142,27 @@ def _set_params(
         if include_multi_channel_metrics:
             metric_names += get_multi_channel_template_metric_names()
 
-        if metrics_kwargs is None:
-            metrics_kwargs_ = _default_function_kwargs.copy()
+        if metric_params is None:
+            metric_params_ = _default_function_kwargs.copy()
             if len(other_kwargs) > 0:
                 for m in other_kwargs:
-                    if m in metrics_kwargs_:
-                        metrics_kwargs_[m] = other_kwargs[m]
+                    if m in metric_params_:
+                        metric_params_[m] = other_kwargs[m]
         else:
-            metrics_kwargs_ = _default_function_kwargs.copy()
-            metrics_kwargs_.update(metrics_kwargs)
+            metric_params_ = _default_function_kwargs.copy()
+            metric_params_.update(metric_params)
 
         metrics_to_compute = metric_names
         tm_extension = self.sorting_analyzer.get_extension("template_metrics")
         if delete_existing_metrics is False and tm_extension is not None:
 
-            existing_params = tm_extension.params["metrics_kwargs"]
+            existing_params = tm_extension.params["metric_params"]
             # checks that existing metrics were calculated using the same params
-            if existing_params != metrics_kwargs_:
+            if existing_params != metric_params_:
                 warnings.warn(
                     f"The parameters used to calculate the previous template metrics are different"
                     f"than those used now.\nPrevious parameters: {existing_params}\nCurrent "
-                    f"parameters:  {metrics_kwargs_}\nDeleting previous template metrics..."
+                    f"parameters:  {metric_params_}\nDeleting previous template metrics..."
                 )
                 tm_extension.params["metric_names"] = []
                 existing_metric_names = []
@@ -171,7 +179,7 @@ def _set_params(
             sparsity=sparsity,
             peak_sign=peak_sign,
             upsampling_factor=int(upsampling_factor),
-            metrics_kwargs=metrics_kwargs_,
+            metric_params=metric_params_,
             delete_existing_metrics=delete_existing_metrics,
             metrics_to_compute=metrics_to_compute,
         )
@@ -273,7 +281,7 @@ def _compute_metrics(self, sorting_analyzer, unit_ids=None, verbose=False, metri
                             sampling_frequency=sampling_frequency_up,
                             trough_idx=trough_idx,
                             peak_idx=peak_idx,
-                            **self.params["metrics_kwargs"],
+                            **self.params["metric_params"],
                         )
                     except Exception as e:
                         warnings.warn(f"Error computing metric {metric_name} for unit {unit_id}: {e}")
@@ -312,7 +320,7 @@ def _compute_metrics(self, sorting_analyzer, unit_ids=None, verbose=False, metri
                         template_upsampled,
                         channel_locations=channel_locations_sparse,
                         sampling_frequency=sampling_frequency_up,
-                        **self.params["metrics_kwargs"],
+                        **self.params["metric_params"],
                     )
                 except Exception as e:
                     warnings.warn(f"Error computing metric {metric_name} for unit {unit_id}: {e}")
diff --git a/src/spikeinterface/postprocessing/tests/test_template_metrics.py b/src/spikeinterface/postprocessing/tests/test_template_metrics.py
index 5056d4ff2a..1df723bfe3 100644
--- a/src/spikeinterface/postprocessing/tests/test_template_metrics.py
+++ b/src/spikeinterface/postprocessing/tests/test_template_metrics.py
@@ -47,7 +47,7 @@ def test_compute_new_template_metrics(small_sorting_analyzer):
 
     # check that, when parameters are changed, the old metrics are deleted
     small_sorting_analyzer.compute(
-        {"template_metrics": {"metric_names": ["exp_decay"], "metrics_kwargs": {"recovery_window_ms": 0.6}}}
+        {"template_metrics": {"metric_names": ["exp_decay"], "metric_params": {"recovery_window_ms": 0.6}}}
     )
 
 

From 22460710bca1114e5f11f5ba4cbdad1b82941d70 Mon Sep 17 00:00:00 2001
From: chrishalcrow <57948917+chrishalcrow@users.noreply.github.com>
Date: Thu, 14 Nov 2024 09:46:16 +0000
Subject: [PATCH 210/344] Update warning message (oups)

---
 src/spikeinterface/postprocessing/template_metrics.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/postprocessing/template_metrics.py b/src/spikeinterface/postprocessing/template_metrics.py
index ef6abfe51f..9b85f99c0d 100644
--- a/src/spikeinterface/postprocessing/template_metrics.py
+++ b/src/spikeinterface/postprocessing/template_metrics.py
@@ -118,7 +118,7 @@ def _set_params(
 
         if metrics_kwargs is not None and metric_params is None:
             deprecation_msg = (
-                "`qm_params` is deprecated and will be removed in version 0.104.0 Please use metric_params instead"
+                "`metrics_kwargs` is deprecated and will be removed in version 0.104.0 Please use metric_params instead"
             )
             metric_params = metrics_kwargs
             warnings.warn(deprecation_msg, category=DeprecationWarning, stacklevel=2)

From 3579934baf43e25759ca1e8ee7f1e3288180be71 Mon Sep 17 00:00:00 2001
From: chrishalcrow <57948917+chrishalcrow@users.noreply.github.com>
Date: Thu, 14 Nov 2024 10:04:02 +0000
Subject: [PATCH 211/344] Make compute work and add `get_default_tm_params`

---
 .../postprocessing/template_metrics.py        | 45 +++++++++----------
 1 file changed, 20 insertions(+), 25 deletions(-)

diff --git a/src/spikeinterface/postprocessing/template_metrics.py b/src/spikeinterface/postprocessing/template_metrics.py
index 9b85f99c0d..25e0d0d490 100644
--- a/src/spikeinterface/postprocessing/template_metrics.py
+++ b/src/spikeinterface/postprocessing/template_metrics.py
@@ -64,22 +64,10 @@ class ComputeTemplateMetrics(AnalyzerExtension):
         Whether to compute multi-channel metrics
     delete_existing_metrics : bool, default: False
         If True, any template metrics attached to the `sorting_analyzer` are deleted. If False, any metrics which were previously calculated but are not included in `metric_names` are kept, provided the `metric_params` are unchanged.
-    metric_params : dict
-        Additional arguments to pass to the metric functions. Including:
-            * recovery_window_ms: the window in ms after the peak to compute the recovery_slope, default: 0.7
-            * peak_relative_threshold: the relative threshold to detect positive and negative peaks, default: 0.2
-            * peak_width_ms: the width in samples to detect peaks, default: 0.2
-            * depth_direction: the direction to compute velocity above and below, default: "y" (see notes)
-            * min_channels_for_velocity: the minimum number of channels above or below to compute velocity, default: 5
-            * min_r2_velocity: the minimum r2 to accept the velocity fit, default: 0.7
-            * exp_peak_function: the function to use to compute the peak amplitude for the exp decay, default: "ptp"
-            * min_r2_exp_decay: the minimum r2 to accept the exp decay fit, default: 0.5
-            * spread_threshold: the threshold to compute the spread, default: 0.2
-            * spread_smooth_um: the smoothing in um to compute the spread, default: 20
-            * column_range: the range in um in the horizontal direction to consider channels for velocity, default: None
-                - If None, all channels all channels are considered
-                - If 0 or 1, only the "column" that includes the max channel is considered
-                - If > 1, only channels within range (+/-) um from the max channel horizontal position are used
+    metric_params : dict of dicts
+        metric_params : dict of dicts or None
+        Dictionary with parameters for quality metrics calculation.
+        Default parameters can be obtained with: `si.qualitymetrics.get_default_tm_params()`
 
     Returns
     -------
@@ -116,13 +104,6 @@ def _set_params(
         **other_kwargs,
     ):
 
-        if metrics_kwargs is not None and metric_params is None:
-            deprecation_msg = (
-                "`metrics_kwargs` is deprecated and will be removed in version 0.104.0 Please use metric_params instead"
-            )
-            metric_params = metrics_kwargs
-            warnings.warn(deprecation_msg, category=DeprecationWarning, stacklevel=2)
-
         import pandas as pd
 
         # TODO alessio can you check this : this used to be in the function but now we have ComputeTemplateMetrics.function_factory()
@@ -142,6 +123,13 @@ def _set_params(
         if include_multi_channel_metrics:
             metric_names += get_multi_channel_template_metric_names()
 
+        if metrics_kwargs is not None and metric_params is None:
+            deprecation_msg = (
+                "`metrics_kwargs` is deprecated and will be removed in version 0.104.0 Please use metric_params instead"
+            )
+            metric_params = dict(zip(metric_names, [metrics_kwargs] * len(metric_names)))
+            warnings.warn(deprecation_msg, category=DeprecationWarning, stacklevel=2)
+
         if metric_params is None:
             metric_params_ = _default_function_kwargs.copy()
             if len(other_kwargs) > 0:
@@ -281,7 +269,7 @@ def _compute_metrics(self, sorting_analyzer, unit_ids=None, verbose=False, metri
                             sampling_frequency=sampling_frequency_up,
                             trough_idx=trough_idx,
                             peak_idx=peak_idx,
-                            **self.params["metric_params"],
+                            **self.params["metric_params"][metric_name],
                         )
                     except Exception as e:
                         warnings.warn(f"Error computing metric {metric_name} for unit {unit_id}: {e}")
@@ -320,7 +308,7 @@ def _compute_metrics(self, sorting_analyzer, unit_ids=None, verbose=False, metri
                         template_upsampled,
                         channel_locations=channel_locations_sparse,
                         sampling_frequency=sampling_frequency_up,
-                        **self.params["metric_params"],
+                        **self.params["metric_params"][metric_name],
                     )
                 except Exception as e:
                     warnings.warn(f"Error computing metric {metric_name} for unit {unit_id}: {e}")
@@ -380,6 +368,13 @@ def _get_data(self):
 )
 
 
+def get_default_tm_params():
+    metric_names = get_single_channel_template_metric_names() + get_multi_channel_template_metric_names()
+    base_tm_params = _default_function_kwargs
+    metric_params = dict(zip(metric_names, [base_tm_params] * len(metric_names)))
+    return metric_params
+
+
 def get_trough_and_peak_idx(template):
     """
     Return the indices into the input template of the detected trough

From 66190c3857bcabf30ca64af994693a3a029c41e1 Mon Sep 17 00:00:00 2001
From: chrishalcrow <57948917+chrishalcrow@users.noreply.github.com>
Date: Thu, 14 Nov 2024 10:18:46 +0000
Subject: [PATCH 212/344] Update compute_name_to_column_names to
 qm_compute_name_to_column_names

---
 .../qualitymetrics/quality_metric_calculator.py             | 6 +++---
 src/spikeinterface/qualitymetrics/quality_metric_list.py    | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
index eb380304b6..365d7bcc09 100644
--- a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
+++ b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
@@ -16,7 +16,7 @@
     compute_pc_metrics,
     _misc_metric_name_to_func,
     _possible_pc_metric_names,
-    compute_name_to_column_names,
+    qm_compute_name_to_column_names,
 )
 from .misc_metrics import _default_params as misc_metrics_params
 from .pca_metrics import _default_params as pca_metrics_params
@@ -32,7 +32,7 @@ class ComputeQualityMetrics(AnalyzerExtension):
         A SortingAnalyzer object.
     metric_names : list or None
         List of quality metrics to compute.
-    metric_params : dict or None
+    metric_params : dict of dicts or None
         Dictionary with parameters for quality metrics calculation.
         Default parameters can be obtained with: `si.qualitymetrics.get_default_qm_params()`
     skip_pc_metrics : bool, default: False
@@ -254,7 +254,7 @@ def _run(self, verbose=False, **job_kwargs):
         # append the metrics which were previously computed
         for metric_name in set(existing_metrics).difference(metrics_to_compute):
             # some metrics names produce data columns with other names. This deals with that.
-            for column_name in compute_name_to_column_names[metric_name]:
+            for column_name in qm_compute_name_to_column_names[metric_name]:
                 computed_metrics[column_name] = qm_extension.data["metrics"][column_name]
 
         self.data["metrics"] = computed_metrics
diff --git a/src/spikeinterface/qualitymetrics/quality_metric_list.py b/src/spikeinterface/qualitymetrics/quality_metric_list.py
index 375dd320ae..fc7e92b50d 100644
--- a/src/spikeinterface/qualitymetrics/quality_metric_list.py
+++ b/src/spikeinterface/qualitymetrics/quality_metric_list.py
@@ -55,7 +55,7 @@
 }
 
 # a dict converting the name of the metric for computation to the output of that computation
-compute_name_to_column_names = {
+qm_compute_name_to_column_names = {
     "num_spikes": ["num_spikes"],
     "firing_rate": ["firing_rate"],
     "presence_ratio": ["presence_ratio"],

From 2de25b47013c8954ece03af1f47250e5db1f7ffb Mon Sep 17 00:00:00 2001
From: chrishalcrow <57948917+chrishalcrow@users.noreply.github.com>
Date: Thu, 14 Nov 2024 10:19:27 +0000
Subject: [PATCH 213/344] Unify template param checks with quality param checks

---
 .../postprocessing/template_metrics.py        | 63 +++++++++++--------
 1 file changed, 38 insertions(+), 25 deletions(-)

diff --git a/src/spikeinterface/postprocessing/template_metrics.py b/src/spikeinterface/postprocessing/template_metrics.py
index 25e0d0d490..cfdbd122b3 100644
--- a/src/spikeinterface/postprocessing/template_metrics.py
+++ b/src/spikeinterface/postprocessing/template_metrics.py
@@ -130,33 +130,18 @@ def _set_params(
             metric_params = dict(zip(metric_names, [metrics_kwargs] * len(metric_names)))
             warnings.warn(deprecation_msg, category=DeprecationWarning, stacklevel=2)
 
-        if metric_params is None:
-            metric_params_ = _default_function_kwargs.copy()
-            if len(other_kwargs) > 0:
-                for m in other_kwargs:
-                    if m in metric_params_:
-                        metric_params_[m] = other_kwargs[m]
-        else:
-            metric_params_ = _default_function_kwargs.copy()
-            metric_params_.update(metric_params)
+        metric_params_ = get_default_tm_params()
+        for k in metric_params_:
+            if metric_params is not None and k in metric_params:
+                metric_params_[k].update(metric_params[k])
+            if "peak_sign" in metric_params_[k] and peak_sign is not None:
+                metric_params_[k]["peak_sign"] = peak_sign
 
         metrics_to_compute = metric_names
         tm_extension = self.sorting_analyzer.get_extension("template_metrics")
         if delete_existing_metrics is False and tm_extension is not None:
 
-            existing_params = tm_extension.params["metric_params"]
-            # checks that existing metrics were calculated using the same params
-            if existing_params != metric_params_:
-                warnings.warn(
-                    f"The parameters used to calculate the previous template metrics are different"
-                    f"than those used now.\nPrevious parameters: {existing_params}\nCurrent "
-                    f"parameters:  {metric_params_}\nDeleting previous template metrics..."
-                )
-                tm_extension.params["metric_names"] = []
-                existing_metric_names = []
-            else:
-                existing_metric_names = tm_extension.params["metric_names"]
-
+            existing_metric_names = tm_extension.params["metric_names"]
             existing_metric_names_propogated = [
                 metric_name for metric_name in existing_metric_names if metric_name not in metrics_to_compute
             ]
@@ -322,8 +307,8 @@ def _compute_metrics(self, sorting_analyzer, unit_ids=None, verbose=False, metri
 
     def _run(self, verbose=False):
 
-        delete_existing_metrics = self.params["delete_existing_metrics"]
         metrics_to_compute = self.params["metrics_to_compute"]
+        delete_existing_metrics = self.params["delete_existing_metrics"]
 
         # compute the metrics which have been specified by the user
         computed_metrics = self._compute_metrics(
@@ -339,9 +324,21 @@ def _run(self, verbose=False):
         ):
             existing_metrics = tm_extension.params["metric_names"]
 
+        existing_metrics = []
+        # here we get in the loaded via the dict only (to avoid full loading from disk after params reset)
+        tm_extension = self.sorting_analyzer.extensions.get("template_metrics", None)
+        if (
+            delete_existing_metrics is False
+            and tm_extension is not None
+            and tm_extension.data.get("metrics") is not None
+        ):
+            existing_metrics = tm_extension.params["metric_names"]
+
         # append the metrics which were previously computed
         for metric_name in set(existing_metrics).difference(metrics_to_compute):
-            computed_metrics[metric_name] = tm_extension.data["metrics"][metric_name]
+            # some metrics names produce data columns with other names. This deals with that.
+            for column_name in tm_compute_name_to_column_names[metric_name]:
+                computed_metrics[column_name] = tm_extension.data["metrics"][column_name]
 
         self.data["metrics"] = computed_metrics
 
@@ -369,12 +366,28 @@ def _get_data(self):
 
 
 def get_default_tm_params():
-    metric_names = get_single_channel_template_metric_names() + get_multi_channel_template_metric_names()
+    metric_names = get_template_metric_names()
     base_tm_params = _default_function_kwargs
     metric_params = dict(zip(metric_names, [base_tm_params] * len(metric_names)))
     return metric_params
 
 
+# a dict converting the name of the metric for computation to the output of that computation
+tm_compute_name_to_column_names = {
+    "peak_to_valley": ["peak_to_valley"],
+    "peak_trough_ratio": ["peak_trough_ratio"],
+    "half_width": ["half_width"],
+    "repolarization_slope": ["repolarization_slope"],
+    "recovery_slope": ["recovery_slope"],
+    "num_positive_peaks": ["num_positive_peaks"],
+    "num_negative_peaks": ["num_negative_peaks"],
+    "velocity_above": ["velocity_above"],
+    "velocity_below": ["velocity_below"],
+    "exp_decay": ["exp_decay"],
+    "spread": ["spread"],
+}
+
+
 def get_trough_and_peak_idx(template):
     """
     Return the indices into the input template of the detected trough

From 8f6602423d53dc625689da2183a24fe43cbb8629 Mon Sep 17 00:00:00 2001
From: chrishalcrow <57948917+chrishalcrow@users.noreply.github.com>
Date: Thu, 14 Nov 2024 11:07:27 +0000
Subject: [PATCH 214/344] add some tests

---
 .../tests/test_template_metrics.py            | 47 ++++++++++++++++++-
 1 file changed, 46 insertions(+), 1 deletion(-)

diff --git a/src/spikeinterface/postprocessing/tests/test_template_metrics.py b/src/spikeinterface/postprocessing/tests/test_template_metrics.py
index 1df723bfe3..1bf49f64c1 100644
--- a/src/spikeinterface/postprocessing/tests/test_template_metrics.py
+++ b/src/spikeinterface/postprocessing/tests/test_template_metrics.py
@@ -1,5 +1,5 @@
 from spikeinterface.postprocessing.tests.common_extension_tests import AnalyzerExtensionCommonTestSuite
-from spikeinterface.postprocessing import ComputeTemplateMetrics
+from spikeinterface.postprocessing import ComputeTemplateMetrics, compute_template_metrics
 import pytest
 import csv
 
@@ -8,6 +8,49 @@
 template_metrics = list(_single_channel_metric_name_to_func.keys())
 
 
+def test_different_params_template_metrics(small_sorting_analyzer):
+    """
+    Computes template metrics using different params, and check that they are
+    actually calculated using the different params.
+    """
+    compute_template_metrics(
+        sorting_analyzer=small_sorting_analyzer,
+        metric_names=["exp_decay", "spread", "half_width"],
+        metric_params={"exp_decay": {"recovery_window_ms": 0.8}, "spread": {"spread_smooth_um": 15}},
+    )
+
+    tm_extension = small_sorting_analyzer.get_extension("template_metrics")
+    tm_params = tm_extension.params["metric_params"]
+
+    assert tm_params["exp_decay"]["recovery_window_ms"] == 0.8
+    assert tm_params["spread"]["recovery_window_ms"] == 0.7
+    assert tm_params["half_width"]["recovery_window_ms"] == 0.7
+
+    assert tm_params["spread"]["spread_smooth_um"] == 15
+    assert tm_params["exp_decay"]["spread_smooth_um"] == 20
+    assert tm_params["half_width"]["spread_smooth_um"] == 20
+
+
+def test_backwards_compat_params_template_metrics(small_sorting_analyzer):
+    """
+    Computes template metrics using the metrics_kwargs keyword
+    """
+    compute_template_metrics(
+        sorting_analyzer=small_sorting_analyzer,
+        metric_names=["exp_decay", "spread"],
+        metrics_kwargs={"recovery_window_ms": 0.8},
+    )
+
+    tm_extension = small_sorting_analyzer.get_extension("template_metrics")
+    tm_params = tm_extension.params["metric_params"]
+
+    assert tm_params["exp_decay"]["recovery_window_ms"] == 0.8
+    assert tm_params["spread"]["recovery_window_ms"] == 0.8
+
+    assert tm_params["spread"]["spread_smooth_um"] == 20
+    assert tm_params["exp_decay"]["spread_smooth_um"] == 20
+
+
 def test_compute_new_template_metrics(small_sorting_analyzer):
     """
     Computes template metrics then computes a subset of template metrics, and checks
@@ -17,6 +60,8 @@ def test_compute_new_template_metrics(small_sorting_analyzer):
     are deleted.
     """
 
+    small_sorting_analyzer.delete_extension("template_metrics")
+
     # calculate just exp_decay
     small_sorting_analyzer.compute({"template_metrics": {"metric_names": ["exp_decay"]}})
     template_metric_extension = small_sorting_analyzer.get_extension("template_metrics")

From fdc01f5adb81f55c5787166fa469100d7bc06239 Mon Sep 17 00:00:00 2001
From: chrishalcrow <57948917+chrishalcrow@users.noreply.github.com>
Date: Thu, 14 Nov 2024 15:00:15 +0000
Subject: [PATCH 215/344] little fixes

---
 .../postprocessing/template_metrics.py        | 31 +++++++++++--------
 .../qualitymetrics/pca_metrics.py             |  4 +--
 2 files changed, 20 insertions(+), 15 deletions(-)

diff --git a/src/spikeinterface/postprocessing/template_metrics.py b/src/spikeinterface/postprocessing/template_metrics.py
index cfdbd122b3..cbcf38d19d 100644
--- a/src/spikeinterface/postprocessing/template_metrics.py
+++ b/src/spikeinterface/postprocessing/template_metrics.py
@@ -66,8 +66,8 @@ class ComputeTemplateMetrics(AnalyzerExtension):
         If True, any template metrics attached to the `sorting_analyzer` are deleted. If False, any metrics which were previously calculated but are not included in `metric_names` are kept, provided the `metric_params` are unchanged.
     metric_params : dict of dicts
         metric_params : dict of dicts or None
-        Dictionary with parameters for quality metrics calculation.
-        Default parameters can be obtained with: `si.qualitymetrics.get_default_tm_params()`
+        Dictionary with parameters for template metrics calculation.
+        Default parameters can be obtained with: `si.postprocessing.template_metrics.get_default_tm_params()`
 
     Returns
     -------
@@ -124,18 +124,17 @@ def _set_params(
             metric_names += get_multi_channel_template_metric_names()
 
         if metrics_kwargs is not None and metric_params is None:
-            deprecation_msg = (
-                "`metrics_kwargs` is deprecated and will be removed in version 0.104.0 Please use metric_params instead"
-            )
-            metric_params = dict(zip(metric_names, [metrics_kwargs] * len(metric_names)))
-            warnings.warn(deprecation_msg, category=DeprecationWarning, stacklevel=2)
+            deprecation_msg = "`metrics_kwargs` is deprecated and will be removed in version 0.104.0. Please use metric_params instead"
+            warnings.warn(deprecation_msg, category=DeprecationWarning)
+
+            metric_params = {}
+            for metric_name in metric_names:
+                metric_params[metric_name] = deepcopy(metrics_kwargs)
 
-        metric_params_ = get_default_tm_params()
+        metric_params_ = get_default_tm_params(metric_names)
         for k in metric_params_:
             if metric_params is not None and k in metric_params:
                 metric_params_[k].update(metric_params[k])
-            if "peak_sign" in metric_params_[k] and peak_sign is not None:
-                metric_params_[k]["peak_sign"] = peak_sign
 
         metrics_to_compute = metric_names
         tm_extension = self.sorting_analyzer.get_extension("template_metrics")
@@ -365,10 +364,16 @@ def _get_data(self):
 )
 
 
-def get_default_tm_params():
-    metric_names = get_template_metric_names()
+def get_default_tm_params(metric_names):
+    if metric_names is None:
+        metric_names = get_template_metric_names()
+
     base_tm_params = _default_function_kwargs
-    metric_params = dict(zip(metric_names, [base_tm_params] * len(metric_names)))
+
+    metric_params = {}
+    for metric_name in metric_names:
+        metric_params[metric_name] = deepcopy(base_tm_params)
+
     return metric_params
 
 
diff --git a/src/spikeinterface/qualitymetrics/pca_metrics.py b/src/spikeinterface/qualitymetrics/pca_metrics.py
index b4952bfe6d..ca21f1e45f 100644
--- a/src/spikeinterface/qualitymetrics/pca_metrics.py
+++ b/src/spikeinterface/qualitymetrics/pca_metrics.py
@@ -91,10 +91,10 @@ def compute_pc_metrics(
 
     if qm_params is not None and metric_params is None:
         deprecation_msg = (
-            "`qm_params` is deprecated and will be removed in version 0.104.0 Please use metric_params instead"
+            "`qm_params` is deprecated and will be removed in version 0.104.0. Please use metric_params instead"
         )
-        metric_params = qm_params
         warn(deprecation_msg, category=DeprecationWarning, stacklevel=2)
+        metric_params = qm_params
 
     pca_ext = sorting_analyzer.get_extension("principal_components")
     assert pca_ext is not None, "calculate_pc_metrics() need extension 'principal_components'"

From 9db0b83f7c7ad2c773c8673fa3dd09e5c3cdecb6 Mon Sep 17 00:00:00 2001
From: chrishalcrow <57948917+chrishalcrow@users.noreply.github.com>
Date: Thu, 14 Nov 2024 15:11:01 +0000
Subject: [PATCH 216/344] backwards compatible loading

---
 .../postprocessing/template_metrics.py               | 12 ++++++++++++
 .../qualitymetrics/quality_metric_calculator.py      |  7 +++++++
 2 files changed, 19 insertions(+)

diff --git a/src/spikeinterface/postprocessing/template_metrics.py b/src/spikeinterface/postprocessing/template_metrics.py
index cbcf38d19d..477ad04440 100644
--- a/src/spikeinterface/postprocessing/template_metrics.py
+++ b/src/spikeinterface/postprocessing/template_metrics.py
@@ -344,6 +344,18 @@ def _run(self, verbose=False):
     def _get_data(self):
         return self.data["metrics"]
 
+    def load_params(self):
+        AnalyzerExtension.load_params(self)
+        # For backwards compatibility - this reformats metrics_kwargs as metric_params
+        if (metrics_kwargs := self.params.get("metrics_kwargs")) is not None:
+
+            metric_params = {}
+            for metric_name in self.params["metric_names"]:
+                metric_params[metric_name] = deepcopy(metrics_kwargs)
+            self.params["metric_params"] = metric_params
+
+            del self.params["metrics_kwargs"]
+
 
 register_result_extension(ComputeTemplateMetrics)
 compute_template_metrics = ComputeTemplateMetrics.function_factory()
diff --git a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
index 365d7bcc09..e7e7c244ea 100644
--- a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
+++ b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
@@ -262,6 +262,13 @@ def _run(self, verbose=False, **job_kwargs):
     def _get_data(self):
         return self.data["metrics"]
 
+    def load_params(self):
+        AnalyzerExtension.load_params(self)
+        # For backwards compatibility - this renames qm_params as metric_params
+        if (qm_params := self.params.get("qm_params")) is not None:
+            self.params["metric_params"] = qm_params
+            del self.params["qm_params"]
+
 
 register_result_extension(ComputeQualityMetrics)
 compute_quality_metrics = ComputeQualityMetrics.function_factory()

From bdeb30041880e881b10a76cc03642757a020ae87 Mon Sep 17 00:00:00 2001
From: Sebastien <pierre.yger@gmail.com>
Date: Thu, 14 Nov 2024 16:38:30 +0100
Subject: [PATCH 217/344] WIP

---
 src/spikeinterface/sortingcomponents/clustering/circus.py     | 4 +++-
 .../sortingcomponents/clustering/position_and_features.py     | 2 +-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/clustering/circus.py b/src/spikeinterface/sortingcomponents/clustering/circus.py
index 5982c270cb..993bd7fee0 100644
--- a/src/spikeinterface/sortingcomponents/clustering/circus.py
+++ b/src/spikeinterface/sortingcomponents/clustering/circus.py
@@ -245,8 +245,10 @@ def main_function(cls, recording, peaks, params, job_kwargs=dict()):
             probe=recording.get_probe(),
             is_scaled=False,
         )
+        
         if params["noise_levels"] is None:
-            params["noise_levels"] = get_noise_levels(recording, return_scaled=False)
+            params["noise_levels"] = get_noise_levels(recording, return_scaled=False, **job_kwargs)
+    
         sparsity = compute_sparsity(templates, noise_levels=params["noise_levels"], **params["sparsity"])
         templates = templates.to_sparse(sparsity)
         empty_templates = templates.sparsity_mask.sum(axis=1) == 0
diff --git a/src/spikeinterface/sortingcomponents/clustering/position_and_features.py b/src/spikeinterface/sortingcomponents/clustering/position_and_features.py
index 513e8085ed..20067a2eec 100644
--- a/src/spikeinterface/sortingcomponents/clustering/position_and_features.py
+++ b/src/spikeinterface/sortingcomponents/clustering/position_and_features.py
@@ -144,7 +144,7 @@ def main_function(cls, recording, peaks, params, job_kwargs=dict()):
                 **job_kwargs,
             )
 
-            noise_levels = get_noise_levels(recording, return_scaled=False)
+            noise_levels = get_noise_levels(recording, return_scaled=False, **job_kwargs)
             labels, peak_labels = remove_duplicates(
                 wfs_arrays, noise_levels, peak_labels, num_samples, num_chans, **params["cleaning_kwargs"]
             )

From d08df426ac5abfd756aa78d78712570517fdf341 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Thu, 14 Nov 2024 15:40:29 +0000
Subject: [PATCH 218/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/sortingcomponents/clustering/circus.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/clustering/circus.py b/src/spikeinterface/sortingcomponents/clustering/circus.py
index 993bd7fee0..32fe69ee38 100644
--- a/src/spikeinterface/sortingcomponents/clustering/circus.py
+++ b/src/spikeinterface/sortingcomponents/clustering/circus.py
@@ -245,10 +245,10 @@ def main_function(cls, recording, peaks, params, job_kwargs=dict()):
             probe=recording.get_probe(),
             is_scaled=False,
         )
-        
+
         if params["noise_levels"] is None:
             params["noise_levels"] = get_noise_levels(recording, return_scaled=False, **job_kwargs)
-    
+
         sparsity = compute_sparsity(templates, noise_levels=params["noise_levels"], **params["sparsity"])
         templates = templates.to_sparse(sparsity)
         empty_templates = templates.sparsity_mask.sum(axis=1) == 0

From 1e53a5e06b2a90956d72150826a8f590d673b5ce Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Tue, 19 Nov 2024 17:45:40 +0100
Subject: [PATCH 219/344] Update src/spikeinterface/extractors/cbin_ibl.py

Co-authored-by: Heberto Mayorquin <h.mayorquin@gmail.com>
---
 src/spikeinterface/extractors/cbin_ibl.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/extractors/cbin_ibl.py b/src/spikeinterface/extractors/cbin_ibl.py
index 8fe19f3d7e..728d352973 100644
--- a/src/spikeinterface/extractors/cbin_ibl.py
+++ b/src/spikeinterface/extractors/cbin_ibl.py
@@ -31,7 +31,7 @@ class CompressedBinaryIblExtractor(BaseRecording):
     stream_name : {"ap", "lp"}, default: "ap".
         Whether to load AP or LFP band, one
         of "ap" or "lp".
-    cbin_file_path : str or None, default None
+    cbin_file_path : str, Path or None, default None
         The cbin file of the recording. If None, searches in `folder_path` for file.
     cbin_file : str or None, default None
         (deprecated) The cbin file of the recording. If None, searches in `folder_path` for file.

From 43653213d36d988eb674a42e14596eed94d139a3 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 20 Nov 2024 13:50:35 +0100
Subject: [PATCH 220/344] Move worker_index to job_tools.py

---
 src/spikeinterface/core/job_tools.py          | 108 ++++++++---
 .../core/tests/test_job_tools.py              |  59 +++++-
 .../core/tests/test_waveform_tools.py         |  16 +-
 src/spikeinterface/core/waveform_tools.py     | 170 ++++++++----------
 4 files changed, 218 insertions(+), 135 deletions(-)

diff --git a/src/spikeinterface/core/job_tools.py b/src/spikeinterface/core/job_tools.py
index c514d4c74e..2a4af1288c 100644
--- a/src/spikeinterface/core/job_tools.py
+++ b/src/spikeinterface/core/job_tools.py
@@ -13,7 +13,7 @@
 from tqdm.auto import tqdm
 
 from concurrent.futures import ProcessPoolExecutor, ThreadPoolExecutor
-import multiprocessing as mp
+import multiprocessing
 import threading
 from threadpoolctl import threadpool_limits
 
@@ -289,6 +289,8 @@ class ChunkRecordingExecutor:
         If True, output is verbose
     job_name : str, default: ""
         Job name
+    progress_bar : bool, default: False
+        If True, a progress bar is printed to monitor the progress of the process
     handle_returns : bool, default: False
         If True, the function can return values
     gather_func : None or callable, default: None
@@ -313,9 +315,8 @@ class ChunkRecordingExecutor:
         Limit the number of thread per process using threadpoolctl modules.
         This used only when n_jobs>1
         If None, no limits.
-    progress_bar : bool, default: False
-        If True, a progress bar is printed to monitor the progress of the process
-
+    need_worker_index : bool, default False
+        If True then each worker will also have a "worker_index" injected in the local worker dict.
 
     Returns
     -------
@@ -342,6 +343,7 @@ def __init__(
         mp_context=None,
         job_name="",
         max_threads_per_process=1,
+        need_worker_index=False,
     ):
         self.recording = recording
         self.func = func
@@ -377,6 +379,8 @@ def __init__(
 
         self.pool_engine = pool_engine
 
+        self.need_worker_index = need_worker_index
+
         if verbose:
             chunk_memory = self.chunk_size * recording.get_num_channels() * np.dtype(recording.get_dtype()).itemsize
             total_memory = chunk_memory * self.n_jobs
@@ -412,9 +416,12 @@ def run(self, recording_slices=None):
             if self.progress_bar:
                 recording_slices = tqdm(recording_slices, desc=self.job_name, total=len(recording_slices))
 
-            worker_ctx = self.init_func(*self.init_args)
+            worker_dict = self.init_func(*self.init_args)
+            if self.need_worker_index:
+                worker_dict["worker_index"] = 0
+
             for segment_index, frame_start, frame_stop in recording_slices:
-                res = self.func(segment_index, frame_start, frame_stop, worker_ctx)
+                res = self.func(segment_index, frame_start, frame_stop, worker_dict)
                 if self.handle_returns:
                     returns.append(res)
                 if self.gather_func is not None:
@@ -425,12 +432,21 @@ def run(self, recording_slices=None):
 
             if self.pool_engine == "process":
 
+                if self.need_worker_index:
+                    lock = multiprocessing.Lock()
+                    array_pid = multiprocessing.Array("i", n_jobs)
+                    for i in range(n_jobs):
+                        array_pid[i] = -1
+                else:
+                    lock = None
+                    array_pid = None
+
                 # parallel
                 with ProcessPoolExecutor(
                     max_workers=n_jobs,
                     initializer=process_worker_initializer,
-                    mp_context=mp.get_context(self.mp_context),
-                    initargs=(self.func, self.init_func, self.init_args, self.max_threads_per_process),
+                    mp_context=multiprocessing.get_context(self.mp_context),
+                    initargs=(self.func, self.init_func, self.init_args, self.max_threads_per_process, self.need_worker_index, lock, array_pid),
                 ) as executor:
                     results = executor.map(process_function_wrapper, recording_slices)
 
@@ -444,29 +460,41 @@ def run(self, recording_slices=None):
                             self.gather_func(res)
             
             elif self.pool_engine == "thread":
-                # only one shared context
+                # this is need to create a per worker local dict where the initializer will push the func wrapper
+                thread_local_data = threading.local()
 
-                # worker_dict = self.init_func(*self.init_args)
-                # thread_func = WorkerFuncWrapper(self.func, worker_dict, self.max_threads_per_process)
+                global _thread_started
+                _thread_started = 0
 
-                thread_data = threading.local()
+                if self.progress_bar:
+                    # here the tqdm threading do not work (maybe collision) so we need to create a pbar
+                    # before thread spawning
+                    pbar = tqdm(desc=self.job_name, total=len(recording_slices))
+                
+                if self.need_worker_index:
+                    lock = threading.Lock()
+                    thread_started = 0
 
                 with ThreadPoolExecutor(
                     max_workers=n_jobs,
                     initializer=thread_worker_initializer,
-                    initargs=(self.func, self.init_func, self.init_args, self.max_threads_per_process, thread_data),
+                    initargs=(self.func, self.init_func, self.init_args, self.max_threads_per_process, thread_local_data, self.need_worker_index, lock),
                 ) as executor:
-                    recording_slices2 = [(thread_data, ) + args for args in recording_slices]
-                    results = executor.map(thread_function_wrapper, recording_slices2)
 
-                    if self.progress_bar:
-                        results = tqdm(results, desc=self.job_name, total=len(recording_slices))
+
+                    recording_slices2 = [(thread_local_data, ) + args for args in recording_slices]
+                    results = executor.map(thread_function_wrapper, recording_slices2)
 
                     for res in results:
+                        if self.progress_bar:
+                            pbar.update(1)
                         if self.handle_returns:
                             returns.append(res)
                         if self.gather_func is not None:
                             self.gather_func(res)
+                if self.progress_bar:
+                    pbar.close()
+                    del pbar
 
             else:
                 raise ValueError("If n_jobs>1 pool_engine must be 'process' or 'thread'")
@@ -476,6 +504,11 @@ def run(self, recording_slices=None):
 
 
 class WorkerFuncWrapper:
+    """
+    small wraper that handle:
+      * local worker_dict
+      *  max_threads_per_process
+    """
     def __init__(self, func, worker_dict, max_threads_per_process):
         self.func = func
         self.worker_dict = worker_dict
@@ -498,36 +531,57 @@ def __call__(self, args):
 global _process_func_wrapper
 
 
-def process_worker_initializer(func, init_func, init_args, max_threads_per_process):
+def process_worker_initializer(func, init_func, init_args, max_threads_per_process, need_worker_index, lock, array_pid):
     global _process_func_wrapper
     if max_threads_per_process is None:
         worker_dict = init_func(*init_args)
     else:
         with threadpool_limits(limits=max_threads_per_process):
             worker_dict = init_func(*init_args)
+
+    if need_worker_index:
+        child_process = multiprocessing.current_process()
+        lock.acquire()
+        worker_index = None
+        for i in range(len(array_pid)):
+            if array_pid[i] == -1:
+                worker_index = i
+                array_pid[i] = child_process.ident
+                break
+        worker_dict["worker_index"] = worker_index
+        lock.release()
+
     _process_func_wrapper = WorkerFuncWrapper(func, worker_dict, max_threads_per_process)
 
 def process_function_wrapper(args):
     global _process_func_wrapper
     return _process_func_wrapper(args)
 
-def thread_worker_initializer(func, init_func, init_args, max_threads_per_process, thread_data):
+
+# use by thread at init
+global _thread_started
+
+def thread_worker_initializer(func, init_func, init_args, max_threads_per_process, thread_local_data, need_worker_index, lock):
     if max_threads_per_process is None:
         worker_dict = init_func(*init_args)
     else:
         with threadpool_limits(limits=max_threads_per_process):
             worker_dict = init_func(*init_args)
-    thread_data._func_wrapper = WorkerFuncWrapper(func, worker_dict, max_threads_per_process)
-    # print("ici", thread_data._func_wrapper)
 
-def thread_function_wrapper(args):
-    thread_data = args[0]
-    args = args[1:]
-    # thread_data = threading.local()
-    # print("la", thread_data._func_wrapper)
-    return thread_data._func_wrapper(args)
+    if need_worker_index:
+        lock.acquire()
+        global _thread_started
+        worker_index = _thread_started
+        _thread_started += 1
+        worker_dict["worker_index"] = worker_index
+        lock.release()
 
+    thread_local_data.func_wrapper = WorkerFuncWrapper(func, worker_dict, max_threads_per_process)
 
+def thread_function_wrapper(args):
+    thread_local_data = args[0]
+    args = args[1:]
+    return thread_local_data.func_wrapper(args)
 
 
 
diff --git a/src/spikeinterface/core/tests/test_job_tools.py b/src/spikeinterface/core/tests/test_job_tools.py
index c46914ab03..5a32898411 100644
--- a/src/spikeinterface/core/tests/test_job_tools.py
+++ b/src/spikeinterface/core/tests/test_job_tools.py
@@ -1,6 +1,8 @@
 import pytest
 import os
 
+import time
+
 from spikeinterface.core import generate_recording, set_global_job_kwargs, get_global_job_kwargs
 
 from spikeinterface.core.job_tools import (
@@ -77,22 +79,22 @@ def test_ensure_chunk_size():
         assert end_frame == recording.get_num_frames(segment_index=segment_index)
 
 
-def func(segment_index, start_frame, end_frame, worker_ctx):
+def func(segment_index, start_frame, end_frame, worker_dict):
     import os
     import time
 
-    #  print('func', segment_index, start_frame, end_frame, worker_ctx, os.getpid())
+    #  print('func', segment_index, start_frame, end_frame, worker_dict, os.getpid())
     time.sleep(0.010)
     # time.sleep(1.0)
     return os.getpid()
 
 
 def init_func(arg1, arg2, arg3):
-    worker_ctx = {}
-    worker_ctx["arg1"] = arg1
-    worker_ctx["arg2"] = arg2
-    worker_ctx["arg3"] = arg3
-    return worker_ctx
+    worker_dict = {}
+    worker_dict["arg1"] = arg1
+    worker_dict["arg2"] = arg2
+    worker_dict["arg3"] = arg3
+    return worker_dict
 
 
 def test_ChunkRecordingExecutor():
@@ -235,10 +237,51 @@ def test_split_job_kwargs():
     assert "other_param" not in job_kwargs and "n_jobs" in job_kwargs and "progress_bar" in job_kwargs
 
 
+
+
+def func2(segment_index, start_frame, end_frame, worker_dict):
+    time.sleep(0.010)
+    # print(os.getpid(), worker_dict["worker_index"])
+    return worker_dict["worker_index"]
+
+
+def init_func2():
+    # this leave time for other thread/process to start
+    time.sleep(0.010)
+    worker_dict = {}
+    return worker_dict
+
+
+def test_worker_index():
+    recording = generate_recording(num_channels=2)
+    init_args = tuple()
+
+    for i in range(2):
+        # making this 2 times ensure to test that global variables are correctly reset
+        for pool_engine in ("process", "thread"):
+            processor = ChunkRecordingExecutor(
+                recording,
+                func2,
+                init_func2,
+                init_args,
+                progress_bar=False,
+                gather_func=None,
+                pool_engine=pool_engine,
+                n_jobs=2,
+                handle_returns=True,
+                chunk_duration="200ms",
+                need_worker_index=True
+            )
+            res = processor.run()
+            # we should have a mix of 0 and 1
+            assert 0 in res
+            assert 1 in res
+
 if __name__ == "__main__":
     # test_divide_segment_into_chunks()
     # test_ensure_n_jobs()
     # test_ensure_chunk_size()
-    test_ChunkRecordingExecutor()
+    # test_ChunkRecordingExecutor()
     # test_fix_job_kwargs()
     # test_split_job_kwargs()
+    test_worker_index()
diff --git a/src/spikeinterface/core/tests/test_waveform_tools.py b/src/spikeinterface/core/tests/test_waveform_tools.py
index 845eaf1310..d0e9358164 100644
--- a/src/spikeinterface/core/tests/test_waveform_tools.py
+++ b/src/spikeinterface/core/tests/test_waveform_tools.py
@@ -176,17 +176,25 @@ def test_estimate_templates_with_accumulator():
     templates = estimate_templates_with_accumulator(
         recording, spikes, sorting.unit_ids, nbefore, nafter, return_scaled=True, **job_kwargs
     )
-    print(templates.shape)
+    # print(templates.shape)
     assert templates.shape[0] == sorting.unit_ids.size
     assert templates.shape[1] == nbefore + nafter
     assert templates.shape[2] == recording.get_num_channels()
 
     assert np.any(templates != 0)
 
+    job_kwargs = dict(n_jobs=1, progress_bar=True, chunk_duration="1s")
+    templates_loop = estimate_templates_with_accumulator(
+        recording, spikes, sorting.unit_ids, nbefore, nafter, return_scaled=True, **job_kwargs
+    )
+    np.testing.assert_almost_equal(templates, templates_loop, decimal=4)
+    
     # import matplotlib.pyplot as plt
     # fig, ax = plt.subplots()
     # for unit_index, unit_id in enumerate(sorting.unit_ids):
-    #     ax.plot(templates[unit_index, :, :].T.flatten())
+        # ax.plot(templates[unit_index, :, :].T.flatten())
+        # ax.plot(templates_loop[unit_index, :, :].T.flatten(), color="k", ls="--")
+        # ax.plot((templates - templates_loop)[unit_index, :, :].T.flatten(), color="k", ls="--")
     # plt.show()
 
 
@@ -225,6 +233,6 @@ def test_estimate_templates():
 
 
 if __name__ == "__main__":
-    test_waveform_tools()
+    # test_waveform_tools()
     test_estimate_templates_with_accumulator()
-    test_estimate_templates()
+    # test_estimate_templates()
diff --git a/src/spikeinterface/core/waveform_tools.py b/src/spikeinterface/core/waveform_tools.py
index 3affd7f0ec..8a7b15f886 100644
--- a/src/spikeinterface/core/waveform_tools.py
+++ b/src/spikeinterface/core/waveform_tools.py
@@ -296,17 +296,17 @@ def _init_worker_distribute_buffers(
     recording, unit_ids, spikes, arrays_info, nbefore, nafter, return_scaled, inds_by_unit, mode, sparsity_mask
 ):
     # create a local dict per worker
-    worker_ctx = {}
+    worker_dict = {}
     if isinstance(recording, dict):
         from spikeinterface.core import load_extractor
 
         recording = load_extractor(recording)
-    worker_ctx["recording"] = recording
+    worker_dict["recording"] = recording
 
     if mode == "memmap":
         # in memmap mode we have the "too many open file" problem with linux
         # memmap file will be open on demand and not globally per worker
-        worker_ctx["arrays_info"] = arrays_info
+        worker_dict["arrays_info"] = arrays_info
     elif mode == "shared_memory":
         from multiprocessing.shared_memory import SharedMemory
 
@@ -321,33 +321,33 @@ def _init_worker_distribute_buffers(
             waveforms_by_units[unit_id] = arr
             # we need a reference to all sham otherwise we get segment fault!!!
             shms[unit_id] = shm
-        worker_ctx["shms"] = shms
-        worker_ctx["waveforms_by_units"] = waveforms_by_units
+        worker_dict["shms"] = shms
+        worker_dict["waveforms_by_units"] = waveforms_by_units
 
-    worker_ctx["unit_ids"] = unit_ids
-    worker_ctx["spikes"] = spikes
+    worker_dict["unit_ids"] = unit_ids
+    worker_dict["spikes"] = spikes
 
-    worker_ctx["nbefore"] = nbefore
-    worker_ctx["nafter"] = nafter
-    worker_ctx["return_scaled"] = return_scaled
-    worker_ctx["inds_by_unit"] = inds_by_unit
-    worker_ctx["sparsity_mask"] = sparsity_mask
-    worker_ctx["mode"] = mode
+    worker_dict["nbefore"] = nbefore
+    worker_dict["nafter"] = nafter
+    worker_dict["return_scaled"] = return_scaled
+    worker_dict["inds_by_unit"] = inds_by_unit
+    worker_dict["sparsity_mask"] = sparsity_mask
+    worker_dict["mode"] = mode
 
-    return worker_ctx
+    return worker_dict
 
 
 # used by ChunkRecordingExecutor
-def _worker_distribute_buffers(segment_index, start_frame, end_frame, worker_ctx):
+def _worker_distribute_buffers(segment_index, start_frame, end_frame, worker_dict):
     # recover variables of the worker
-    recording = worker_ctx["recording"]
-    unit_ids = worker_ctx["unit_ids"]
-    spikes = worker_ctx["spikes"]
-    nbefore = worker_ctx["nbefore"]
-    nafter = worker_ctx["nafter"]
-    return_scaled = worker_ctx["return_scaled"]
-    inds_by_unit = worker_ctx["inds_by_unit"]
-    sparsity_mask = worker_ctx["sparsity_mask"]
+    recording = worker_dict["recording"]
+    unit_ids = worker_dict["unit_ids"]
+    spikes = worker_dict["spikes"]
+    nbefore = worker_dict["nbefore"]
+    nafter = worker_dict["nafter"]
+    return_scaled = worker_dict["return_scaled"]
+    inds_by_unit = worker_dict["inds_by_unit"]
+    sparsity_mask = worker_dict["sparsity_mask"]
 
     seg_size = recording.get_num_samples(segment_index=segment_index)
 
@@ -383,12 +383,12 @@ def _worker_distribute_buffers(segment_index, start_frame, end_frame, worker_ctx
             if in_chunk_pos.size == 0:
                 continue
 
-            if worker_ctx["mode"] == "memmap":
+            if worker_dict["mode"] == "memmap":
                 # open file in demand (and also autoclose it after)
-                filename = worker_ctx["arrays_info"][unit_id]
+                filename = worker_dict["arrays_info"][unit_id]
                 wfs = np.load(str(filename), mmap_mode="r+")
-            elif worker_ctx["mode"] == "shared_memory":
-                wfs = worker_ctx["waveforms_by_units"][unit_id]
+            elif worker_dict["mode"] == "shared_memory":
+                wfs = worker_dict["waveforms_by_units"][unit_id]
 
             for pos in in_chunk_pos:
                 sample_index = spikes[inds[pos]]["sample_index"]
@@ -548,50 +548,50 @@ def extract_waveforms_to_single_buffer(
 def _init_worker_distribute_single_buffer(
     recording, spikes, wf_array_info, nbefore, nafter, return_scaled, mode, sparsity_mask
 ):
-    worker_ctx = {}
-    worker_ctx["recording"] = recording
-    worker_ctx["wf_array_info"] = wf_array_info
-    worker_ctx["spikes"] = spikes
-    worker_ctx["nbefore"] = nbefore
-    worker_ctx["nafter"] = nafter
-    worker_ctx["return_scaled"] = return_scaled
-    worker_ctx["sparsity_mask"] = sparsity_mask
-    worker_ctx["mode"] = mode
+    worker_dict = {}
+    worker_dict["recording"] = recording
+    worker_dict["wf_array_info"] = wf_array_info
+    worker_dict["spikes"] = spikes
+    worker_dict["nbefore"] = nbefore
+    worker_dict["nafter"] = nafter
+    worker_dict["return_scaled"] = return_scaled
+    worker_dict["sparsity_mask"] = sparsity_mask
+    worker_dict["mode"] = mode
 
     if mode == "memmap":
         filename = wf_array_info["filename"]
         all_waveforms = np.load(str(filename), mmap_mode="r+")
-        worker_ctx["all_waveforms"] = all_waveforms
+        worker_dict["all_waveforms"] = all_waveforms
     elif mode == "shared_memory":
         from multiprocessing.shared_memory import SharedMemory
 
         shm_name, dtype, shape = wf_array_info["shm_name"], wf_array_info["dtype"], wf_array_info["shape"]
         shm = SharedMemory(shm_name)
         all_waveforms = np.ndarray(shape=shape, dtype=dtype, buffer=shm.buf)
-        worker_ctx["shm"] = shm
-        worker_ctx["all_waveforms"] = all_waveforms
+        worker_dict["shm"] = shm
+        worker_dict["all_waveforms"] = all_waveforms
 
     # prepare segment slices
     segment_slices = []
     for segment_index in range(recording.get_num_segments()):
         s0, s1 = np.searchsorted(spikes["segment_index"], [segment_index, segment_index + 1])
         segment_slices.append((s0, s1))
-    worker_ctx["segment_slices"] = segment_slices
+    worker_dict["segment_slices"] = segment_slices
 
-    return worker_ctx
+    return worker_dict
 
 
 # used by ChunkRecordingExecutor
-def _worker_distribute_single_buffer(segment_index, start_frame, end_frame, worker_ctx):
+def _worker_distribute_single_buffer(segment_index, start_frame, end_frame, worker_dict):
     # recover variables of the worker
-    recording = worker_ctx["recording"]
-    segment_slices = worker_ctx["segment_slices"]
-    spikes = worker_ctx["spikes"]
-    nbefore = worker_ctx["nbefore"]
-    nafter = worker_ctx["nafter"]
-    return_scaled = worker_ctx["return_scaled"]
-    sparsity_mask = worker_ctx["sparsity_mask"]
-    all_waveforms = worker_ctx["all_waveforms"]
+    recording = worker_dict["recording"]
+    segment_slices = worker_dict["segment_slices"]
+    spikes = worker_dict["spikes"]
+    nbefore = worker_dict["nbefore"]
+    nafter = worker_dict["nafter"]
+    return_scaled = worker_dict["return_scaled"]
+    sparsity_mask = worker_dict["sparsity_mask"]
+    all_waveforms = worker_dict["all_waveforms"]
 
     seg_size = recording.get_num_samples(segment_index=segment_index)
 
@@ -630,7 +630,7 @@ def _worker_distribute_single_buffer(segment_index, start_frame, end_frame, work
                 wf = wf[:, mask]
                 all_waveforms[spike_index, :, : wf.shape[1]] = wf
 
-        if worker_ctx["mode"] == "memmap":
+        if worker_dict["mode"] == "memmap":
             all_waveforms.flush()
 
 
@@ -843,12 +843,6 @@ def estimate_templates_with_accumulator(
         waveform_squared_accumulator_per_worker = None
         shm_squared_name = None
 
-    # trick to get the work_index given pid arrays
-    lock = multiprocessing.Lock()
-    array_pid = multiprocessing.Array("i", num_worker)
-    for i in range(num_worker):
-        array_pid[i] = -1
-
     func = _worker_estimate_templates
     init_func = _init_worker_estimate_templates
 
@@ -862,14 +856,12 @@ def estimate_templates_with_accumulator(
         nbefore,
         nafter,
         return_scaled,
-        lock,
-        array_pid,
     )
 
     if job_name is None:
         job_name = "estimate_templates_with_accumulator"
     processor = ChunkRecordingExecutor(
-        recording, func, init_func, init_args, job_name=job_name, verbose=verbose, **job_kwargs
+        recording, func, init_func, init_args, job_name=job_name, verbose=verbose, need_worker_index=True, **job_kwargs
     )
     processor.run()
 
@@ -920,15 +912,13 @@ def _init_worker_estimate_templates(
     nbefore,
     nafter,
     return_scaled,
-    lock,
-    array_pid,
 ):
-    worker_ctx = {}
-    worker_ctx["recording"] = recording
-    worker_ctx["spikes"] = spikes
-    worker_ctx["nbefore"] = nbefore
-    worker_ctx["nafter"] = nafter
-    worker_ctx["return_scaled"] = return_scaled
+    worker_dict = {}
+    worker_dict["recording"] = recording
+    worker_dict["spikes"] = spikes
+    worker_dict["nbefore"] = nbefore
+    worker_dict["nafter"] = nafter
+    worker_dict["return_scaled"] = return_scaled
 
     from multiprocessing.shared_memory import SharedMemory
     import multiprocessing
@@ -936,48 +926,36 @@ def _init_worker_estimate_templates(
     shm = SharedMemory(shm_name)
     waveform_accumulator_per_worker = np.ndarray(shape=shape, dtype=dtype, buffer=shm.buf)
 
-    worker_ctx["shm"] = shm
-    worker_ctx["waveform_accumulator_per_worker"] = waveform_accumulator_per_worker
+    worker_dict["shm"] = shm
+    worker_dict["waveform_accumulator_per_worker"] = waveform_accumulator_per_worker
     if shm_squared_name is not None:
         shm_squared = SharedMemory(shm_squared_name)
         waveform_squared_accumulator_per_worker = np.ndarray(shape=shape, dtype=dtype, buffer=shm_squared.buf)
-        worker_ctx["shm_squared"] = shm_squared
-        worker_ctx["waveform_squared_accumulator_per_worker"] = waveform_squared_accumulator_per_worker
+        worker_dict["shm_squared"] = shm_squared
+        worker_dict["waveform_squared_accumulator_per_worker"] = waveform_squared_accumulator_per_worker
 
     # prepare segment slices
     segment_slices = []
     for segment_index in range(recording.get_num_segments()):
         s0, s1 = np.searchsorted(spikes["segment_index"], [segment_index, segment_index + 1])
         segment_slices.append((s0, s1))
-    worker_ctx["segment_slices"] = segment_slices
-
-    child_process = multiprocessing.current_process()
-
-    lock.acquire()
-    num_worker = None
-    for i in range(len(array_pid)):
-        if array_pid[i] == -1:
-            num_worker = i
-            array_pid[i] = child_process.ident
-            break
-    worker_ctx["worker_index"] = num_worker
-    lock.release()
+    worker_dict["segment_slices"] = segment_slices
 
-    return worker_ctx
+    return worker_dict
 
 
 # used by ChunkRecordingExecutor
-def _worker_estimate_templates(segment_index, start_frame, end_frame, worker_ctx):
+def _worker_estimate_templates(segment_index, start_frame, end_frame, worker_dict):
     # recover variables of the worker
-    recording = worker_ctx["recording"]
-    segment_slices = worker_ctx["segment_slices"]
-    spikes = worker_ctx["spikes"]
-    nbefore = worker_ctx["nbefore"]
-    nafter = worker_ctx["nafter"]
-    waveform_accumulator_per_worker = worker_ctx["waveform_accumulator_per_worker"]
-    waveform_squared_accumulator_per_worker = worker_ctx.get("waveform_squared_accumulator_per_worker", None)
-    worker_index = worker_ctx["worker_index"]
-    return_scaled = worker_ctx["return_scaled"]
+    recording = worker_dict["recording"]
+    segment_slices = worker_dict["segment_slices"]
+    spikes = worker_dict["spikes"]
+    nbefore = worker_dict["nbefore"]
+    nafter = worker_dict["nafter"]
+    waveform_accumulator_per_worker = worker_dict["waveform_accumulator_per_worker"]
+    waveform_squared_accumulator_per_worker = worker_dict.get("waveform_squared_accumulator_per_worker", None)
+    worker_index = worker_dict["worker_index"]
+    return_scaled = worker_dict["return_scaled"]
 
     seg_size = recording.get_num_samples(segment_index=segment_index)
 

From e929820b06c0c2bf881742cb4e459e88e96be4cf Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 20 Nov 2024 14:19:35 +0100
Subject: [PATCH 221/344] change max_threads_per_process to
 max_threads_per_worker

---
 doc/get_started/quickstart.rst                |  2 +-
 src/spikeinterface/core/globals.py            |  2 +-
 src/spikeinterface/core/job_tools.py          | 52 ++++++++++++-------
 src/spikeinterface/core/tests/test_globals.py |  6 +--
 .../core/tests/test_job_tools.py              |  4 +-
 .../postprocessing/principal_component.py     | 16 +++---
 .../tests/test_principal_component.py         |  2 +-
 .../qualitymetrics/pca_metrics.py             | 10 ++--
 .../qualitymetrics/tests/test_pca_metrics.py  |  6 +--
 .../sortingcomponents/clustering/merge.py     | 12 ++---
 .../sortingcomponents/clustering/split.py     | 10 ++--
 11 files changed, 67 insertions(+), 55 deletions(-)

diff --git a/doc/get_started/quickstart.rst b/doc/get_started/quickstart.rst
index 3d45606a78..d1bf311340 100644
--- a/doc/get_started/quickstart.rst
+++ b/doc/get_started/quickstart.rst
@@ -287,7 +287,7 @@ available parameters are dictionaries and can be accessed with:
      'detect_threshold': 5,
      'freq_max': 5000.0,
      'freq_min': 400.0,
-     'max_threads_per_process': 1,
+     'max_threads_per_worker': 1,
      'mp_context': None,
      'n_jobs': 20,
      'nested_params': None,
diff --git a/src/spikeinterface/core/globals.py b/src/spikeinterface/core/globals.py
index 38f39c5481..195440c061 100644
--- a/src/spikeinterface/core/globals.py
+++ b/src/spikeinterface/core/globals.py
@@ -97,7 +97,7 @@ def is_set_global_dataset_folder() -> bool:
 
 
 ########################################
-_default_job_kwargs = dict(n_jobs=1, chunk_duration="1s", progress_bar=True, mp_context=None, max_threads_per_process=1)
+_default_job_kwargs = dict(pool_engine="thread", n_jobs=1, chunk_duration="1s", progress_bar=True, mp_context=None, max_threads_per_worker=1)
 
 global global_job_kwargs
 global_job_kwargs = _default_job_kwargs.copy()
diff --git a/src/spikeinterface/core/job_tools.py b/src/spikeinterface/core/job_tools.py
index 2a4af1288c..b37c9b7d69 100644
--- a/src/spikeinterface/core/job_tools.py
+++ b/src/spikeinterface/core/job_tools.py
@@ -48,7 +48,7 @@
     "chunk_duration",
     "progress_bar",
     "mp_context",
-    "max_threads_per_process",
+    "max_threads_per_worker",
 )
 
 # theses key are the same and should not be in th final dict
@@ -65,6 +65,17 @@ def fix_job_kwargs(runtime_job_kwargs):
 
     job_kwargs = get_global_job_kwargs()
 
+    # deprecation with backward compatibility
+    # this can be removed in 0.104.0
+    if "max_threads_per_process" in runtime_job_kwargs:
+        runtime_job_kwargs = runtime_job_kwargs.copy()
+        runtime_job_kwargs["max_threads_per_worker"] = runtime_job_kwargs.pop("max_threads_per_process")
+        warnings.warn(
+            "job_kwargs: max_threads_per_worker was changed to max_threads_per_worker",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
     for k in runtime_job_kwargs:
         assert k in job_keys, (
             f"{k} is not a valid job keyword argument. " f"Available keyword arguments are: {list(job_keys)}"
@@ -311,7 +322,7 @@ class ChunkRecordingExecutor:
     mp_context : "fork" | "spawn" | None, default: None
         "fork" or "spawn". If None, the context is taken by the recording.get_preferred_mp_context().
         "fork" is only safely available on LINUX systems.
-    max_threads_per_process : int or None, default: None
+    max_threads_per_worker : int or None, default: None
         Limit the number of thread per process using threadpoolctl modules.
         This used only when n_jobs>1
         If None, no limits.
@@ -342,7 +353,7 @@ def __init__(
         chunk_duration=None,
         mp_context=None,
         job_name="",
-        max_threads_per_process=1,
+        max_threads_per_worker=1,
         need_worker_index=False,
     ):
         self.recording = recording
@@ -375,7 +386,7 @@ def __init__(
             n_jobs=self.n_jobs,
         )
         self.job_name = job_name
-        self.max_threads_per_process = max_threads_per_process
+        self.max_threads_per_worker = max_threads_per_worker
 
         self.pool_engine = pool_engine
 
@@ -446,7 +457,7 @@ def run(self, recording_slices=None):
                     max_workers=n_jobs,
                     initializer=process_worker_initializer,
                     mp_context=multiprocessing.get_context(self.mp_context),
-                    initargs=(self.func, self.init_func, self.init_args, self.max_threads_per_process, self.need_worker_index, lock, array_pid),
+                    initargs=(self.func, self.init_func, self.init_args, self.max_threads_per_worker, self.need_worker_index, lock, array_pid),
                 ) as executor:
                     results = executor.map(process_function_wrapper, recording_slices)
 
@@ -473,12 +484,13 @@ def run(self, recording_slices=None):
                 
                 if self.need_worker_index:
                     lock = threading.Lock()
-                    thread_started = 0
+                else:
+                    lock = None
 
                 with ThreadPoolExecutor(
                     max_workers=n_jobs,
                     initializer=thread_worker_initializer,
-                    initargs=(self.func, self.init_func, self.init_args, self.max_threads_per_process, thread_local_data, self.need_worker_index, lock),
+                    initargs=(self.func, self.init_func, self.init_args, self.max_threads_per_worker, thread_local_data, self.need_worker_index, lock),
                 ) as executor:
 
 
@@ -507,19 +519,19 @@ class WorkerFuncWrapper:
     """
     small wraper that handle:
       * local worker_dict
-      *  max_threads_per_process
+      *  max_threads_per_worker
     """
-    def __init__(self, func, worker_dict, max_threads_per_process):
+    def __init__(self, func, worker_dict, max_threads_per_worker):
         self.func = func
         self.worker_dict = worker_dict
-        self.max_threads_per_process = max_threads_per_process
+        self.max_threads_per_worker = max_threads_per_worker
     
     def __call__(self, args):
         segment_index, start_frame, end_frame = args
-        if self.max_threads_per_process is None:
+        if self.max_threads_per_worker is None:
             return self.func(segment_index, start_frame, end_frame, self.worker_dict)
         else:
-            with threadpool_limits(limits=self.max_threads_per_process):
+            with threadpool_limits(limits=self.max_threads_per_worker):
                 return self.func(segment_index, start_frame, end_frame, self.worker_dict)
 
 # see
@@ -531,12 +543,12 @@ def __call__(self, args):
 global _process_func_wrapper
 
 
-def process_worker_initializer(func, init_func, init_args, max_threads_per_process, need_worker_index, lock, array_pid):
+def process_worker_initializer(func, init_func, init_args, max_threads_per_worker, need_worker_index, lock, array_pid):
     global _process_func_wrapper
-    if max_threads_per_process is None:
+    if max_threads_per_worker is None:
         worker_dict = init_func(*init_args)
     else:
-        with threadpool_limits(limits=max_threads_per_process):
+        with threadpool_limits(limits=max_threads_per_worker):
             worker_dict = init_func(*init_args)
 
     if need_worker_index:
@@ -551,7 +563,7 @@ def process_worker_initializer(func, init_func, init_args, max_threads_per_proce
         worker_dict["worker_index"] = worker_index
         lock.release()
 
-    _process_func_wrapper = WorkerFuncWrapper(func, worker_dict, max_threads_per_process)
+    _process_func_wrapper = WorkerFuncWrapper(func, worker_dict, max_threads_per_worker)
 
 def process_function_wrapper(args):
     global _process_func_wrapper
@@ -561,11 +573,11 @@ def process_function_wrapper(args):
 # use by thread at init
 global _thread_started
 
-def thread_worker_initializer(func, init_func, init_args, max_threads_per_process, thread_local_data, need_worker_index, lock):
-    if max_threads_per_process is None:
+def thread_worker_initializer(func, init_func, init_args, max_threads_per_worker, thread_local_data, need_worker_index, lock):
+    if max_threads_per_worker is None:
         worker_dict = init_func(*init_args)
     else:
-        with threadpool_limits(limits=max_threads_per_process):
+        with threadpool_limits(limits=max_threads_per_worker):
             worker_dict = init_func(*init_args)
 
     if need_worker_index:
@@ -576,7 +588,7 @@ def thread_worker_initializer(func, init_func, init_args, max_threads_per_proces
         worker_dict["worker_index"] = worker_index
         lock.release()
 
-    thread_local_data.func_wrapper = WorkerFuncWrapper(func, worker_dict, max_threads_per_process)
+    thread_local_data.func_wrapper = WorkerFuncWrapper(func, worker_dict, max_threads_per_worker)
 
 def thread_function_wrapper(args):
     thread_local_data = args[0]
diff --git a/src/spikeinterface/core/tests/test_globals.py b/src/spikeinterface/core/tests/test_globals.py
index 9677378fc5..2b21cd8978 100644
--- a/src/spikeinterface/core/tests/test_globals.py
+++ b/src/spikeinterface/core/tests/test_globals.py
@@ -36,7 +36,7 @@ def test_global_tmp_folder(create_cache_folder):
 
 
 def test_global_job_kwargs():
-    job_kwargs = dict(n_jobs=4, chunk_duration="1s", progress_bar=True, mp_context=None, max_threads_per_process=1)
+    job_kwargs = dict(n_jobs=4, chunk_duration="1s", progress_bar=True, mp_context=None, max_threads_per_worker=1)
     global_job_kwargs = get_global_job_kwargs()
 
     # test warning when not setting n_jobs and calling fix_job_kwargs
@@ -44,7 +44,7 @@ def test_global_job_kwargs():
         job_kwargs_split = fix_job_kwargs({})
 
     assert global_job_kwargs == dict(
-        n_jobs=1, chunk_duration="1s", progress_bar=True, mp_context=None, max_threads_per_process=1
+        n_jobs=1, chunk_duration="1s", progress_bar=True, mp_context=None, max_threads_per_worker=1
     )
     set_global_job_kwargs(**job_kwargs)
     assert get_global_job_kwargs() == job_kwargs
@@ -59,7 +59,7 @@ def test_global_job_kwargs():
     set_global_job_kwargs(**partial_job_kwargs)
     global_job_kwargs = get_global_job_kwargs()
     assert global_job_kwargs == dict(
-        n_jobs=2, chunk_duration="1s", progress_bar=True, mp_context=None, max_threads_per_process=1
+        n_jobs=2, chunk_duration="1s", progress_bar=True, mp_context=None, max_threads_per_worker=1
     )
     # test that fix_job_kwargs grabs global kwargs
     new_job_kwargs = dict(n_jobs=cpu_count())
diff --git a/src/spikeinterface/core/tests/test_job_tools.py b/src/spikeinterface/core/tests/test_job_tools.py
index 5a32898411..8872a259bf 100644
--- a/src/spikeinterface/core/tests/test_job_tools.py
+++ b/src/spikeinterface/core/tests/test_job_tools.py
@@ -281,7 +281,7 @@ def test_worker_index():
     # test_divide_segment_into_chunks()
     # test_ensure_n_jobs()
     # test_ensure_chunk_size()
-    # test_ChunkRecordingExecutor()
+    test_ChunkRecordingExecutor()
     # test_fix_job_kwargs()
     # test_split_job_kwargs()
-    test_worker_index()
+    # test_worker_index()
diff --git a/src/spikeinterface/postprocessing/principal_component.py b/src/spikeinterface/postprocessing/principal_component.py
index 809f2c5bba..84fbfc5965 100644
--- a/src/spikeinterface/postprocessing/principal_component.py
+++ b/src/spikeinterface/postprocessing/principal_component.py
@@ -316,13 +316,13 @@ def _run(self, verbose=False, **job_kwargs):
         job_kwargs = fix_job_kwargs(job_kwargs)
         n_jobs = job_kwargs["n_jobs"]
         progress_bar = job_kwargs["progress_bar"]
-        max_threads_per_process = job_kwargs["max_threads_per_process"]
+        max_threads_per_worker = job_kwargs["max_threads_per_worker"]
         mp_context = job_kwargs["mp_context"]
 
         # fit model/models
         # TODO : make parralel  for by_channel_global and concatenated
         if mode == "by_channel_local":
-            pca_models = self._fit_by_channel_local(n_jobs, progress_bar, max_threads_per_process, mp_context)
+            pca_models = self._fit_by_channel_local(n_jobs, progress_bar, max_threads_per_worker, mp_context)
             for chan_ind, chan_id in enumerate(self.sorting_analyzer.channel_ids):
                 self.data[f"pca_model_{mode}_{chan_id}"] = pca_models[chan_ind]
             pca_model = pca_models
@@ -415,7 +415,7 @@ def run_for_all_spikes(self, file_path=None, verbose=False, **job_kwargs):
         )
         processor.run()
 
-    def _fit_by_channel_local(self, n_jobs, progress_bar, max_threads_per_process, mp_context):
+    def _fit_by_channel_local(self, n_jobs, progress_bar, max_threads_per_worker, mp_context):
         from sklearn.decomposition import IncrementalPCA
 
         p = self.params
@@ -444,10 +444,10 @@ def _fit_by_channel_local(self, n_jobs, progress_bar, max_threads_per_process, m
                     pca = pca_models[chan_ind]
                     pca.partial_fit(wfs[:, :, wf_ind])
             else:
-                # create list of args to parallelize. For convenience, the max_threads_per_process is passed
+                # create list of args to parallelize. For convenience, the max_threads_per_worker is passed
                 # as last argument
                 items = [
-                    (chan_ind, pca_models[chan_ind], wfs[:, :, wf_ind], max_threads_per_process)
+                    (chan_ind, pca_models[chan_ind], wfs[:, :, wf_ind], max_threads_per_worker)
                     for wf_ind, chan_ind in enumerate(channel_inds)
                 ]
                 n_jobs = min(n_jobs, len(items))
@@ -687,12 +687,12 @@ def _init_work_all_pc_extractor(recording, sorting, all_pcs_args, nbefore, nafte
 
 
 def _partial_fit_one_channel(args):
-    chan_ind, pca_model, wf_chan, max_threads_per_process = args
+    chan_ind, pca_model, wf_chan, max_threads_per_worker = args
 
-    if max_threads_per_process is None:
+    if max_threads_per_worker is None:
         pca_model.partial_fit(wf_chan)
         return chan_ind, pca_model
     else:
-        with threadpool_limits(limits=int(max_threads_per_process)):
+        with threadpool_limits(limits=int(max_threads_per_worker)):
             pca_model.partial_fit(wf_chan)
             return chan_ind, pca_model
diff --git a/src/spikeinterface/postprocessing/tests/test_principal_component.py b/src/spikeinterface/postprocessing/tests/test_principal_component.py
index 7a509c410f..ecfc39f2c6 100644
--- a/src/spikeinterface/postprocessing/tests/test_principal_component.py
+++ b/src/spikeinterface/postprocessing/tests/test_principal_component.py
@@ -27,7 +27,7 @@ def test_multi_processing(self):
         )
         sorting_analyzer.compute("principal_components", mode="by_channel_local", n_jobs=2)
         sorting_analyzer.compute(
-            "principal_components", mode="by_channel_local", n_jobs=2, max_threads_per_process=4, mp_context="spawn"
+            "principal_components", mode="by_channel_local", n_jobs=2, max_threads_per_worker=4, mp_context="spawn"
         )
 
     def test_mode_concatenated(self):
diff --git a/src/spikeinterface/qualitymetrics/pca_metrics.py b/src/spikeinterface/qualitymetrics/pca_metrics.py
index 4c68dfea59..55f91fd87f 100644
--- a/src/spikeinterface/qualitymetrics/pca_metrics.py
+++ b/src/spikeinterface/qualitymetrics/pca_metrics.py
@@ -58,7 +58,7 @@ def compute_pc_metrics(
     n_jobs=1,
     progress_bar=False,
     mp_context=None,
-    max_threads_per_process=None,
+    max_threads_per_worker=None,
 ) -> dict:
     """
     Calculate principal component derived metrics.
@@ -147,7 +147,7 @@ def compute_pc_metrics(
         pcs = dense_projections[np.isin(all_labels, neighbor_unit_ids)][:, :, neighbor_channel_indices]
         pcs_flat = pcs.reshape(pcs.shape[0], -1)
 
-        func_args = (pcs_flat, labels, non_nn_metrics, unit_id, unit_ids, qm_params, max_threads_per_process)
+        func_args = (pcs_flat, labels, non_nn_metrics, unit_id, unit_ids, qm_params, max_threads_per_worker)
         items.append(func_args)
 
     if not run_in_parallel and non_nn_metrics:
@@ -977,12 +977,12 @@ def _compute_isolation(pcs_target_unit, pcs_other_unit, n_neighbors: int):
 
 
 def pca_metrics_one_unit(args):
-    (pcs_flat, labels, metric_names, unit_id, unit_ids, qm_params, max_threads_per_process) = args
+    (pcs_flat, labels, metric_names, unit_id, unit_ids, qm_params, max_threads_per_worker) = args
 
-    if max_threads_per_process is None:
+    if max_threads_per_worker is None:
         return _pca_metrics_one_unit(pcs_flat, labels, metric_names, unit_id, unit_ids, qm_params)
     else:
-        with threadpool_limits(limits=int(max_threads_per_process)):
+        with threadpool_limits(limits=int(max_threads_per_worker)):
             return _pca_metrics_one_unit(pcs_flat, labels, metric_names, unit_id, unit_ids, qm_params)
 
 
diff --git a/src/spikeinterface/qualitymetrics/tests/test_pca_metrics.py b/src/spikeinterface/qualitymetrics/tests/test_pca_metrics.py
index f2e912c6b4..ba8dae4619 100644
--- a/src/spikeinterface/qualitymetrics/tests/test_pca_metrics.py
+++ b/src/spikeinterface/qualitymetrics/tests/test_pca_metrics.py
@@ -31,13 +31,13 @@ def test_pca_metrics_multi_processing(small_sorting_analyzer):
 
     print(f"Computing PCA metrics with 1 thread per process")
     res1 = compute_pc_metrics(
-        sorting_analyzer, n_jobs=-1, metric_names=metric_names, max_threads_per_process=1, progress_bar=True
+        sorting_analyzer, n_jobs=-1, metric_names=metric_names, max_threads_per_worker=1, progress_bar=True
     )
     print(f"Computing PCA metrics with 2 thread per process")
     res2 = compute_pc_metrics(
-        sorting_analyzer, n_jobs=-1, metric_names=metric_names, max_threads_per_process=2, progress_bar=True
+        sorting_analyzer, n_jobs=-1, metric_names=metric_names, max_threads_per_worker=2, progress_bar=True
     )
     print("Computing PCA metrics with spawn context")
     res2 = compute_pc_metrics(
-        sorting_analyzer, n_jobs=-1, metric_names=metric_names, max_threads_per_process=2, progress_bar=True
+        sorting_analyzer, n_jobs=-1, metric_names=metric_names, max_threads_per_worker=2, progress_bar=True
     )
diff --git a/src/spikeinterface/sortingcomponents/clustering/merge.py b/src/spikeinterface/sortingcomponents/clustering/merge.py
index 4a7b722aea..e618cfbfb6 100644
--- a/src/spikeinterface/sortingcomponents/clustering/merge.py
+++ b/src/spikeinterface/sortingcomponents/clustering/merge.py
@@ -261,7 +261,7 @@ def find_merge_pairs(
     **job_kwargs,
     # n_jobs=1,
     # mp_context="fork",
-    # max_threads_per_process=1,
+    # max_threads_per_worker=1,
     # progress_bar=True,
 ):
     """
@@ -299,7 +299,7 @@ def find_merge_pairs(
 
     n_jobs = job_kwargs["n_jobs"]
     mp_context = job_kwargs.get("mp_context", None)
-    max_threads_per_process = job_kwargs.get("max_threads_per_process", 1)
+    max_threads_per_worker = job_kwargs.get("max_threads_per_worker", 1)
     progress_bar = job_kwargs["progress_bar"]
 
     Executor = get_poolexecutor(n_jobs)
@@ -316,7 +316,7 @@ def find_merge_pairs(
             templates,
             method,
             method_kwargs,
-            max_threads_per_process,
+            max_threads_per_worker,
         ),
     ) as pool:
         jobs = []
@@ -354,7 +354,7 @@ def find_pair_worker_init(
     templates,
     method,
     method_kwargs,
-    max_threads_per_process,
+    max_threads_per_worker,
 ):
     global _ctx
     _ctx = {}
@@ -366,7 +366,7 @@ def find_pair_worker_init(
     _ctx["method"] = method
     _ctx["method_kwargs"] = method_kwargs
     _ctx["method_class"] = find_pair_method_dict[method]
-    _ctx["max_threads_per_process"] = max_threads_per_process
+    _ctx["max_threads_per_worker"] = max_threads_per_worker
 
     # if isinstance(features_dict_or_folder, dict):
     #     _ctx["features"] = features_dict_or_folder
@@ -380,7 +380,7 @@ def find_pair_worker_init(
 
 def find_pair_function_wrapper(label0, label1):
     global _ctx
-    with threadpool_limits(limits=_ctx["max_threads_per_process"]):
+    with threadpool_limits(limits=_ctx["max_threads_per_worker"]):
         is_merge, label0, label1, shift, merge_value = _ctx["method_class"].merge(
             label0,
             label1,
diff --git a/src/spikeinterface/sortingcomponents/clustering/split.py b/src/spikeinterface/sortingcomponents/clustering/split.py
index 15917934a8..3c2e878c39 100644
--- a/src/spikeinterface/sortingcomponents/clustering/split.py
+++ b/src/spikeinterface/sortingcomponents/clustering/split.py
@@ -65,7 +65,7 @@ def split_clusters(
     n_jobs = job_kwargs["n_jobs"]
     mp_context = job_kwargs.get("mp_context", None)
     progress_bar = job_kwargs["progress_bar"]
-    max_threads_per_process = job_kwargs.get("max_threads_per_process", 1)
+    max_threads_per_worker = job_kwargs.get("max_threads_per_worker", 1)
 
     original_labels = peak_labels
     peak_labels = peak_labels.copy()
@@ -77,7 +77,7 @@ def split_clusters(
         max_workers=n_jobs,
         initializer=split_worker_init,
         mp_context=get_context(method=mp_context),
-        initargs=(recording, features_dict_or_folder, original_labels, method, method_kwargs, max_threads_per_process),
+        initargs=(recording, features_dict_or_folder, original_labels, method, method_kwargs, max_threads_per_worker),
     ) as pool:
         labels_set = np.setdiff1d(peak_labels, [-1])
         current_max_label = np.max(labels_set) + 1
@@ -133,7 +133,7 @@ def split_clusters(
 
 
 def split_worker_init(
-    recording, features_dict_or_folder, original_labels, method, method_kwargs, max_threads_per_process
+    recording, features_dict_or_folder, original_labels, method, method_kwargs, max_threads_per_worker
 ):
     global _ctx
     _ctx = {}
@@ -144,14 +144,14 @@ def split_worker_init(
     _ctx["method"] = method
     _ctx["method_kwargs"] = method_kwargs
     _ctx["method_class"] = split_methods_dict[method]
-    _ctx["max_threads_per_process"] = max_threads_per_process
+    _ctx["max_threads_per_worker"] = max_threads_per_worker
     _ctx["features"] = FeaturesLoader.from_dict_or_folder(features_dict_or_folder)
     _ctx["peaks"] = _ctx["features"]["peaks"]
 
 
 def split_function_wrapper(peak_indices, recursion_level):
     global _ctx
-    with threadpool_limits(limits=_ctx["max_threads_per_process"]):
+    with threadpool_limits(limits=_ctx["max_threads_per_worker"]):
         is_split, local_labels = _ctx["method_class"].split(
             peak_indices, _ctx["peaks"], _ctx["features"], recursion_level, **_ctx["method_kwargs"]
         )

From d4a6e95d1c9f6a7d5cb9d5f4ca017a2240c187ad Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 20 Nov 2024 14:35:06 +0100
Subject: [PATCH 222/344] implement get_best_job_kwargs()

---
 src/spikeinterface/core/__init__.py           |  2 +-
 src/spikeinterface/core/job_tools.py          | 39 +++++++++++++++++++
 .../core/tests/test_job_tools.py              |  9 ++++-
 3 files changed, 47 insertions(+), 3 deletions(-)

diff --git a/src/spikeinterface/core/__init__.py b/src/spikeinterface/core/__init__.py
index ead7007920..bea77decfc 100644
--- a/src/spikeinterface/core/__init__.py
+++ b/src/spikeinterface/core/__init__.py
@@ -90,7 +90,7 @@
     write_python,
     normal_pdf,
 )
-from .job_tools import ensure_n_jobs, ensure_chunk_size, ChunkRecordingExecutor, split_job_kwargs, fix_job_kwargs
+from .job_tools import get_best_job_kwargs, ensure_n_jobs, ensure_chunk_size, ChunkRecordingExecutor, split_job_kwargs, fix_job_kwargs
 from .recording_tools import (
     write_binary_recording,
     write_to_h5_dataset_format,
diff --git a/src/spikeinterface/core/job_tools.py b/src/spikeinterface/core/job_tools.py
index b37c9b7d69..b12ad7fc4d 100644
--- a/src/spikeinterface/core/job_tools.py
+++ b/src/spikeinterface/core/job_tools.py
@@ -59,6 +59,45 @@
     "chunk_duration",
 )
 
+def get_best_job_kwargs():
+    """
+    Given best possible job_kwargs for the platform.
+    """
+
+    n_cpu = os.cpu_count()
+
+    if platform.system() == "Linux":
+        # maybe we should test this more but with linux the fork is still faster than threading
+        pool_engine = "process"
+        mp_context = "fork"
+
+        # this is totally empiricat but this is a good start
+        if n_cpu <= 16:
+            # for small n_cpu lets make many process
+            n_jobs = n_cpu
+            max_threads_per_worker = 1
+        else:
+            # lets have less process with more thread each
+            n_cpu = int(n_cpu / 4)
+            max_threads_per_worker = 8
+
+    else: # windows and mac
+        # on windows and macos the fork is forbidden and process+spwan is super slow at startup
+        # so lets go to threads
+        pool_engine = "thread"
+        mp_context = None
+        n_jobs = n_cpu
+        max_threads_per_worker = 1
+
+    return dict(
+        pool_engine=pool_engine,
+        mp_context=mp_context,
+        n_jobs=n_jobs,
+        max_threads_per_worker=max_threads_per_worker,
+    )
+
+
+
 
 def fix_job_kwargs(runtime_job_kwargs):
     from .globals import get_global_job_kwargs, is_set_global_job_kwargs_set
diff --git a/src/spikeinterface/core/tests/test_job_tools.py b/src/spikeinterface/core/tests/test_job_tools.py
index 8872a259bf..3918fe8ec0 100644
--- a/src/spikeinterface/core/tests/test_job_tools.py
+++ b/src/spikeinterface/core/tests/test_job_tools.py
@@ -3,7 +3,7 @@
 
 import time
 
-from spikeinterface.core import generate_recording, set_global_job_kwargs, get_global_job_kwargs
+from spikeinterface.core import generate_recording, set_global_job_kwargs, get_global_job_kwargs, get_best_job_kwargs
 
 from spikeinterface.core.job_tools import (
     divide_segment_into_chunks,
@@ -277,11 +277,16 @@ def test_worker_index():
             assert 0 in res
             assert 1 in res
 
+def test_get_best_job_kwargs():
+    job_kwargs = get_best_job_kwargs()
+    print(job_kwargs)
+
 if __name__ == "__main__":
     # test_divide_segment_into_chunks()
     # test_ensure_n_jobs()
     # test_ensure_chunk_size()
-    test_ChunkRecordingExecutor()
+    # test_ChunkRecordingExecutor()
     # test_fix_job_kwargs()
     # test_split_job_kwargs()
     # test_worker_index()
+    test_get_best_job_kwargs()

From 423801b2d99d3a1cead66f9a9150c4b344568b04 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 20 Nov 2024 14:38:30 +0100
Subject: [PATCH 223/344] oups

---
 src/spikeinterface/core/tests/test_globals.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/spikeinterface/core/tests/test_globals.py b/src/spikeinterface/core/tests/test_globals.py
index 2b21cd8978..896b737c88 100644
--- a/src/spikeinterface/core/tests/test_globals.py
+++ b/src/spikeinterface/core/tests/test_globals.py
@@ -44,7 +44,7 @@ def test_global_job_kwargs():
         job_kwargs_split = fix_job_kwargs({})
 
     assert global_job_kwargs == dict(
-        n_jobs=1, chunk_duration="1s", progress_bar=True, mp_context=None, max_threads_per_worker=1
+        pool_engine="thread", n_jobs=1, chunk_duration="1s", progress_bar=True, mp_context=None, max_threads_per_worker=1
     )
     set_global_job_kwargs(**job_kwargs)
     assert get_global_job_kwargs() == job_kwargs
@@ -80,6 +80,6 @@ def test_global_job_kwargs():
 
 
 if __name__ == "__main__":
-    test_global_dataset_folder()
-    test_global_tmp_folder()
+    # test_global_dataset_folder()
+    # test_global_tmp_folder()
     test_global_job_kwargs()

From 1736b65ceb13adcae78eb161b7dbbc52ad666400 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 20 Nov 2024 14:41:02 +0100
Subject: [PATCH 224/344] oups

---
 src/spikeinterface/core/tests/test_globals.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/core/tests/test_globals.py b/src/spikeinterface/core/tests/test_globals.py
index 896b737c88..580287eb21 100644
--- a/src/spikeinterface/core/tests/test_globals.py
+++ b/src/spikeinterface/core/tests/test_globals.py
@@ -36,7 +36,7 @@ def test_global_tmp_folder(create_cache_folder):
 
 
 def test_global_job_kwargs():
-    job_kwargs = dict(n_jobs=4, chunk_duration="1s", progress_bar=True, mp_context=None, max_threads_per_worker=1)
+    job_kwargs = dict(pool_engine="thread", n_jobs=4, chunk_duration="1s", progress_bar=True, mp_context=None, max_threads_per_worker=1)
     global_job_kwargs = get_global_job_kwargs()
 
     # test warning when not setting n_jobs and calling fix_job_kwargs
@@ -59,7 +59,7 @@ def test_global_job_kwargs():
     set_global_job_kwargs(**partial_job_kwargs)
     global_job_kwargs = get_global_job_kwargs()
     assert global_job_kwargs == dict(
-        n_jobs=2, chunk_duration="1s", progress_bar=True, mp_context=None, max_threads_per_worker=1
+        pool_engine="thread", n_jobs=2, chunk_duration="1s", progress_bar=True, mp_context=None, max_threads_per_worker=1
     )
     # test that fix_job_kwargs grabs global kwargs
     new_job_kwargs = dict(n_jobs=cpu_count())

From 9b2875fd06782bd6da722fed1f524dfda4203f0a Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Thu, 21 Nov 2024 11:53:01 +0100
Subject: [PATCH 225/344] Add stream_mode as extra_requirements for NWB wghen
 streaming

---
 src/spikeinterface/extractors/nwbextractors.py | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/src/spikeinterface/extractors/nwbextractors.py b/src/spikeinterface/extractors/nwbextractors.py
index d797e64910..171992f6b1 100644
--- a/src/spikeinterface/extractors/nwbextractors.py
+++ b/src/spikeinterface/extractors/nwbextractors.py
@@ -599,6 +599,8 @@ def __init__(
         else:
             gains, offsets, locations, groups = self._fetch_main_properties_backend()
             self.extra_requirements.append("h5py")
+        if stream_mode is not None:
+            self.extra_requirements.append(stream_mode)
         self.set_channel_gains(gains)
         self.set_channel_offsets(offsets)
         if locations is not None:
@@ -1100,6 +1102,8 @@ def __init__(
             for property_name, property_values in properties.items():
                 values = [x.decode("utf-8") if isinstance(x, bytes) else x for x in property_values]
                 self.set_property(property_name, values)
+        if stream_mode is not None:
+            self.extra_requirements.append(stream_mode)
 
         if stream_mode is None and file_path is not None:
             file_path = str(Path(file_path).resolve())

From ad00beb182967ebe68f59ebfd7f1abad3002a10e Mon Sep 17 00:00:00 2001
From: Charlie Windolf <charliexwindolf@gmail.com>
Date: Thu, 21 Nov 2024 20:44:20 +0000
Subject: [PATCH 226/344] Update `interpolate_motion_on_traces` docstring

---
 .../sortingcomponents/motion/motion_interpolation.py           | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
index d207dced08..7c6f0ba71a 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
@@ -83,6 +83,9 @@ def interpolate_motion_on_traces(
     interpolation_time_bin_centers_s : None or np.array
         Manually specify the time bins which the interpolation happens
         in for this segment. If None, these are the motion estimate's time bins.
+    interpolation_time_bin_edges_s : None or np.array
+        If present, interpolation chunks will be the time bins defined by these edges
+        rather than interpolation_time_bin_centers_s or the motion's bins.
     spatial_interpolation_method : "idw" | "kriging", default: "kriging"
         The spatial interpolation method used to interpolate the channel locations:
             * idw : Inverse Distance Weighing

From 28527d2a8bcd03a3c6d9036ac9be180ad4dc6334 Mon Sep 17 00:00:00 2001
From: Charlie Windolf <charliexwindolf@gmail.com>
Date: Thu, 21 Nov 2024 20:46:30 +0000
Subject: [PATCH 227/344] Should be centers!

---
 .../sortingcomponents/motion/motion_interpolation.py            | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
index 7c6f0ba71a..f0fff5c039 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
@@ -126,7 +126,7 @@ def interpolate_motion_on_traces(
 
     # -- determine the blocks of frames that will land in the same interpolation time bin
     if interpolation_time_bin_centers_s is None and interpolation_time_bin_edges_s is None:
-        bin_centers_s = motion.temporal_bin_edges_s[segment_index]
+        bin_centers_s = motion.temporal_bin_centers_s[segment_index]
         bin_edges_s = motion.temporal_bin_edges_s[segment_index]
     else:
         bin_centers_s, bin_edges_s = ensure_time_bins(interpolation_time_bin_centers_s, interpolation_time_bin_edges_s)

From b3b3fcf5be7b67451f54cac753844cbb06b8d4a3 Mon Sep 17 00:00:00 2001
From: Charlie Windolf <charliexwindolf@gmail.com>
Date: Thu, 21 Nov 2024 20:47:34 +0000
Subject: [PATCH 228/344] Typo

---
 .../sortingcomponents/motion/motion_interpolation.py            | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
index f0fff5c039..9e32e189d9 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
@@ -132,7 +132,7 @@ def interpolate_motion_on_traces(
         bin_centers_s, bin_edges_s = ensure_time_bins(interpolation_time_bin_centers_s, interpolation_time_bin_edges_s)
 
     # nearest interpolation bin:
-    # seachsorted(b, t, side="right") == i means that b[i-1] <= t < b[i]
+    # searchsorted(b, t, side="right") == i means that b[i-1] <= t < b[i]
     # hence the -1. doing it with "left" is not as nice -- we want t==b[0]
     # to lead to i=1 (rounding down).
     # time_bins are bin centers, but we want to snap to the nearest center.

From b02860e463262a3b9522ebf9badc45c860cf8d29 Mon Sep 17 00:00:00 2001
From: Charlie Windolf <charliexwindolf@gmail.com>
Date: Thu, 21 Nov 2024 20:51:11 +0000
Subject: [PATCH 229/344] Clarify comments

---
 .../sortingcomponents/motion/motion_interpolation.py        | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
index 9e32e189d9..8f96579228 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
@@ -131,14 +131,10 @@ def interpolate_motion_on_traces(
     else:
         bin_centers_s, bin_edges_s = ensure_time_bins(interpolation_time_bin_centers_s, interpolation_time_bin_edges_s)
 
-    # nearest interpolation bin:
+    # bin the frame times according to the interpolation time bins.
     # searchsorted(b, t, side="right") == i means that b[i-1] <= t < b[i]
     # hence the -1. doing it with "left" is not as nice -- we want t==b[0]
     # to lead to i=1 (rounding down).
-    # time_bins are bin centers, but we want to snap to the nearest center.
-    # idea is to get the left bin edges and bin the interp times.
-    # this is like subtracting bin_dt_s/2, but allows non-equally-spaced bins.
-    # it's fine to use the first bin center for the first left edge
     bin_inds = np.searchsorted(bin_edges_s, times, side="right") - 1
 
     # the time bins may not cover the whole set of times in the recording,

From df2484002b562861f0f64bc053b5da619253e983 Mon Sep 17 00:00:00 2001
From: Charlie Windolf <charliexwindolf@gmail.com>
Date: Thu, 21 Nov 2024 20:57:08 +0000
Subject: [PATCH 230/344] Rename variables for clarity

---
 .../motion/motion_interpolation.py            | 25 ++++++++++---------
 1 file changed, 13 insertions(+), 12 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
index 8f96579228..2bd3493650 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
@@ -126,30 +126,30 @@ def interpolate_motion_on_traces(
 
     # -- determine the blocks of frames that will land in the same interpolation time bin
     if interpolation_time_bin_centers_s is None and interpolation_time_bin_edges_s is None:
-        bin_centers_s = motion.temporal_bin_centers_s[segment_index]
-        bin_edges_s = motion.temporal_bin_edges_s[segment_index]
+        interpolation_time_bin_centers_s = motion.temporal_bin_centers_s[segment_index]
+        interpolation_time_bin_edges_s = motion.temporal_bin_edges_s[segment_index]
     else:
-        bin_centers_s, bin_edges_s = ensure_time_bins(interpolation_time_bin_centers_s, interpolation_time_bin_edges_s)
+        interpolation_time_bin_centers_s, interpolation_time_bin_edges_s = ensure_time_bins(interpolation_time_bin_centers_s, interpolation_time_bin_edges_s)
 
     # bin the frame times according to the interpolation time bins.
     # searchsorted(b, t, side="right") == i means that b[i-1] <= t < b[i]
     # hence the -1. doing it with "left" is not as nice -- we want t==b[0]
     # to lead to i=1 (rounding down).
-    bin_inds = np.searchsorted(bin_edges_s, times, side="right") - 1
+    interpolation_bin_inds = np.searchsorted(interpolation_time_bin_edges_s, times, side="right") - 1
 
     # the time bins may not cover the whole set of times in the recording,
     # so we need to clip these indices to the valid range
-    n_bins = bin_edges_s.shape[0] - 1
-    np.clip(bin_inds, 0, n_bins - 1, out=bin_inds)
+    n_bins = interpolation_time_bin_edges_s.shape[0] - 1
+    np.clip(interpolation_bin_inds, 0, n_bins - 1, out=interpolation_bin_inds)
 
     # -- what are the possibilities here anyway?
-    bins_here = np.arange(bin_inds[0], bin_inds[-1] + 1)
+    interpolation_bins_here = np.arange(interpolation_bin_inds[0], interpolation_bin_inds[-1] + 1)
 
     # inperpolation kernel will be the same per temporal bin
     interp_times = np.empty(total_num_chans)
     current_start_index = 0
-    for bin_ind in bins_here:
-        bin_time = bin_centers_s[bin_ind]
+    for interp_bin_ind in interpolation_bins_here:
+        bin_time = bin_centers_s[interp_bin_ind]
         interp_times.fill(bin_time)
         channel_motions = motion.get_displacement_at_time_and_depth(
             interp_times,
@@ -177,16 +177,17 @@ def interpolate_motion_on_traces(
         # ax.set_title(f"bin_ind {bin_ind} - {bin_time}s - {spatial_interpolation_method}")
         # plt.show()
 
+        # quick search logic to find frames corresponding to this interpolation bin in the recording
         # quickly find the end of this bin, which is also the start of the next
         next_start_index = current_start_index + np.searchsorted(
-            bin_inds[current_start_index:], bin_ind + 1, side="left"
+            interpolation_bin_inds[current_start_index:], interp_bin_ind + 1, side="left"
         )
-        in_bin = slice(current_start_index, next_start_index)
+        frames_in_bin = slice(current_start_index, next_start_index)
 
         # here we use a simple np.matmul even if dirft_kernel can be super sparse.
         # because the speed for a sparse matmul is not so good when we disable multi threaad (due multi processing
         # in ChunkRecordingExecutor)
-        np.matmul(traces[in_bin], drift_kernel, out=traces_corrected[in_bin])
+        np.matmul(traces[frames_in_bin], drift_kernel, out=traces_corrected[frames_in_bin])
         current_start_index = next_start_index
 
     return traces_corrected

From 91fb7320eafbcdaa8fe728e36cbc7fa686f32ba8 Mon Sep 17 00:00:00 2001
From: Charlie Windolf <charliexwindolf@gmail.com>
Date: Thu, 21 Nov 2024 20:59:13 +0000
Subject: [PATCH 231/344] Note on clipping behavior

---
 .../sortingcomponents/motion/motion_interpolation.py        | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
index 2bd3493650..8aed8085bf 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
@@ -64,7 +64,11 @@ def interpolate_motion_on_traces(
     """
     Apply inverse motion with spatial interpolation on traces.
 
-    Traces can be full traces, but also waveforms snippets.
+    Traces can be full traces, but also waveforms snippets. Times used for looking up
+    displacements are controlled by interpolation_time_bin_edges_s or 
+    interpolation_time_bin_centers_s, or fall back to the Motion object's time bins
+    by default; times in the recording outside these time bins use the closest edge
+    bin's displacement value during interpolation.
 
     Parameters
     ----------

From b80bad71e2c1ee316048beb79a9169dd8f68c6ff Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Thu, 21 Nov 2024 21:01:47 +0000
Subject: [PATCH 232/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 .../sortingcomponents/motion/motion_interpolation.py        | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
index 8aed8085bf..14471f77fc 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
@@ -65,7 +65,7 @@ def interpolate_motion_on_traces(
     Apply inverse motion with spatial interpolation on traces.
 
     Traces can be full traces, but also waveforms snippets. Times used for looking up
-    displacements are controlled by interpolation_time_bin_edges_s or 
+    displacements are controlled by interpolation_time_bin_edges_s or
     interpolation_time_bin_centers_s, or fall back to the Motion object's time bins
     by default; times in the recording outside these time bins use the closest edge
     bin's displacement value during interpolation.
@@ -133,7 +133,9 @@ def interpolate_motion_on_traces(
         interpolation_time_bin_centers_s = motion.temporal_bin_centers_s[segment_index]
         interpolation_time_bin_edges_s = motion.temporal_bin_edges_s[segment_index]
     else:
-        interpolation_time_bin_centers_s, interpolation_time_bin_edges_s = ensure_time_bins(interpolation_time_bin_centers_s, interpolation_time_bin_edges_s)
+        interpolation_time_bin_centers_s, interpolation_time_bin_edges_s = ensure_time_bins(
+            interpolation_time_bin_centers_s, interpolation_time_bin_edges_s
+        )
 
     # bin the frame times according to the interpolation time bins.
     # searchsorted(b, t, side="right") == i means that b[i-1] <= t < b[i]

From c89060314e233b89e4e9112e74c7643545806d22 Mon Sep 17 00:00:00 2001
From: Charlie Windolf <charliexwindolf@gmail.com>
Date: Thu, 21 Nov 2024 16:09:45 -0500
Subject: [PATCH 233/344] Fix variable typo; add docstring

---
 .../motion/motion_interpolation.py               |  5 +++--
 .../sortingcomponents/motion/motion_utils.py     | 16 ++++++++++++++++
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
index 14471f77fc..e87f83751c 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
@@ -3,7 +3,8 @@
 import numpy as np
 from spikeinterface.core.core_tools import define_function_from_class
 from spikeinterface.preprocessing import get_spatial_interpolation_kernel
-from spikeinterface.preprocessing.basepreprocessor import BasePreprocessor, BasePreprocessorSegment
+from spikeinterface.preprocessing.basepreprocessor import (
+    BasePreprocessor, BasePreprocessorSegment)
 from spikeinterface.preprocessing.filter import fix_dtype
 
 from .motion_utils import ensure_time_bin_edges, ensure_time_bins
@@ -155,7 +156,7 @@ def interpolate_motion_on_traces(
     interp_times = np.empty(total_num_chans)
     current_start_index = 0
     for interp_bin_ind in interpolation_bins_here:
-        bin_time = bin_centers_s[interp_bin_ind]
+        bin_time = interpolation_time_bin_centers_s[interp_bin_ind]
         interp_times.fill(bin_time)
         channel_motions = motion.get_displacement_at_time_and_depth(
             interp_times,
diff --git a/src/spikeinterface/sortingcomponents/motion/motion_utils.py b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
index ec0a55a8f8..680d75f221 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_utils.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_utils.py
@@ -580,6 +580,22 @@ def make_3d_motion_histograms(
 
 
 def ensure_time_bins(time_bin_centers_s=None, time_bin_edges_s=None):
+    """Ensure that both bin edges and bin centers are present
+
+    If either of the inputs are None but not both, the missing is reconstructed
+    from the present. Going from edges to centers is done by taking midpoints.
+    Going from centers to edges is done by taking midpoints and padding with the
+    left and rightmost centers.
+
+    Parameters
+    ----------
+    time_bin_centers_s : None or np.array
+    time_bin_edges_s : None or np.array
+
+    Returns
+    -------
+    time_bin_centers_s, time_bin_edges_s
+    """
     if time_bin_centers_s is None and time_bin_edges_s is None:
         raise ValueError("Need at least one of time_bin_centers_s or time_bin_edges_s.")
 

From 6d2e47911a5e64737f2c98f9cdc199e9f6d306fc Mon Sep 17 00:00:00 2001
From: Charlie Windolf <charliexwindolf@gmail.com>
Date: Thu, 21 Nov 2024 16:14:00 -0500
Subject: [PATCH 234/344] Variable names in tests

---
 .../motion/tests/test_motion_interpolation.py | 45 +++++++++----------
 1 file changed, 21 insertions(+), 24 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/motion/tests/test_motion_interpolation.py b/src/spikeinterface/sortingcomponents/motion/tests/test_motion_interpolation.py
index 8542b62524..c97c8324ba 100644
--- a/src/spikeinterface/sortingcomponents/motion/tests/test_motion_interpolation.py
+++ b/src/spikeinterface/sortingcomponents/motion/tests/test_motion_interpolation.py
@@ -4,11 +4,8 @@
 import spikeinterface.core as sc
 from spikeinterface.sortingcomponents.motion import Motion
 from spikeinterface.sortingcomponents.motion.motion_interpolation import (
-    InterpolateMotionRecording,
-    correct_motion_on_peaks,
-    interpolate_motion,
-    interpolate_motion_on_traces,
-)
+    InterpolateMotionRecording, correct_motion_on_peaks, interpolate_motion,
+    interpolate_motion_on_traces)
 from spikeinterface.sortingcomponents.tests.common import make_dataset
 
 
@@ -84,26 +81,26 @@ def test_interpolate_motion_on_traces():
 def test_interpolation_simple():
     # a recording where a 1 moves at 1 chan per second. 30 chans 10 frames.
     # there will be 9 chans of drift, so we add 9 chans of padding to the bottom
-    nt = nc0 = 10  # these need to be the same for this test
-    nc1 = nc0 + nc0 - 1
-    traces = np.zeros((nt, nc1), dtype="float32")
-    traces[:, :nc0] = np.eye(nc0)
+    n_samples = num_chans_orig = 10  # these need to be the same for this test
+    num_chans_drifted = num_chans_orig + num_chans_orig - 1
+    traces = np.zeros((n_samples, num_chans_drifted), dtype="float32")
+    traces[:, :num_chans_orig] = np.eye(num_chans_orig)
     rec = sc.NumpyRecording(traces, sampling_frequency=1)
-    rec.set_dummy_probe_from_locations(np.c_[np.zeros(nc1), np.arange(nc1)])
+    rec.set_dummy_probe_from_locations(np.c_[np.zeros(num_chans_drifted), np.arange(num_chans_drifted)])
 
-    true_motion = Motion(np.arange(nt)[:, None], 0.5 + np.arange(nt), np.zeros(1))
+    true_motion = Motion(np.arange(n_samples)[:, None], 0.5 + np.arange(n_samples), np.zeros(1))
     rec_corrected = interpolate_motion(rec, true_motion, spatial_interpolation_method="nearest")
     traces_corrected = rec_corrected.get_traces()
-    assert traces_corrected.shape == (nc0, nc0)
-    assert np.array_equal(traces_corrected[:, 0], np.ones(nt))
-    assert np.array_equal(traces_corrected[:, 1:], np.zeros((nt, nc0 - 1)))
+    assert traces_corrected.shape == (num_chans_orig, num_chans_orig)
+    assert np.array_equal(traces_corrected[:, 0], np.ones(n_samples))
+    assert np.array_equal(traces_corrected[:, 1:], np.zeros((n_samples, num_chans_orig - 1)))
 
     # let's try a new version where we interpolate too slowly
     rec_corrected = interpolate_motion(
         rec, true_motion, spatial_interpolation_method="nearest", num_closest=2, interpolation_time_bin_size_s=2
     )
     traces_corrected = rec_corrected.get_traces()
-    assert traces_corrected.shape == (nc0, nc0)
+    assert traces_corrected.shape == (num_chans_orig, num_chans_orig)
     # what happens with nearest here?
     # well... due to rounding towards the nearest even number, the motion (which at
     # these time bin centers is 0.5, 2.5, 4.5, ...) flips the signal's nearest
@@ -131,8 +128,8 @@ def test_cross_band_interpolation():
     fs_ap = 300.0
     t_start = 10.0
     total_duration = 5.0
-    nt_lfp = int(fs_lfp * total_duration)
-    nt_ap = int(fs_ap * total_duration)
+    num_samples_lfp = int(fs_lfp * total_duration)
+    num_samples_ap = int(fs_ap * total_duration)
     t_switch = 3
 
     # because interpolation uses bin centers logic, there will be a half
@@ -140,18 +137,18 @@ def test_cross_band_interpolation():
     halfbin_ap_lfp = int(0.5 * (fs_ap / fs_lfp))
 
     # channel geometry
-    nc = 10
-    geom = np.c_[np.zeros(nc), np.arange(nc)]
+    num_chans = 10
+    geom = np.c_[np.zeros(num_chans), np.arange(num_chans)]
 
     # make an LFP recording which drifts a bit
-    traces_lfp = np.zeros((nt_lfp, nc))
+    traces_lfp = np.zeros((num_samples_lfp, num_chans))
     traces_lfp[: int(t_switch * fs_lfp), 5] = 1.0
     traces_lfp[int(t_switch * fs_lfp) :, 6] = 1.0
     rec_lfp = sc.NumpyRecording(traces_lfp, sampling_frequency=fs_lfp)
     rec_lfp.set_dummy_probe_from_locations(geom)
 
     # same for AP
-    traces_ap = np.zeros((nt_ap, nc))
+    traces_ap = np.zeros((num_samples_ap, num_chans))
     traces_ap[: int(t_switch * fs_ap) - halfbin_ap_lfp, 5] = 1.0
     traces_ap[int(t_switch * fs_ap) - halfbin_ap_lfp :, 6] = 1.0
     rec_ap = sc.NumpyRecording(traces_ap, sampling_frequency=fs_ap)
@@ -160,8 +157,8 @@ def test_cross_band_interpolation():
     # set times for both, and silence the warning
     with warnings.catch_warnings():
         warnings.simplefilter("ignore", category=UserWarning)
-        rec_lfp.set_times(t_start + np.arange(nt_lfp) / fs_lfp)
-        rec_ap.set_times(t_start + np.arange(nt_ap) / fs_ap)
+        rec_lfp.set_times(t_start + np.arange(num_samples_lfp) / fs_lfp)
+        rec_ap.set_times(t_start + np.arange(num_samples_ap) / fs_ap)
 
     # estimate motion
     motion = estimate_motion(rec_lfp, method="dredge_lfp", rigid=True)
@@ -169,7 +166,7 @@ def test_cross_band_interpolation():
     # nearest to keep it simple
     rec_corrected = interpolate_motion(rec_ap, motion, spatial_interpolation_method="nearest", num_closest=2)
     traces_corrected = rec_corrected.get_traces()
-    target = np.zeros((nt_ap, nc - 2))
+    target = np.zeros((num_samples_ap, num_chans - 2))
     target[:, 4] = 1
     ii, jj = np.nonzero(traces_corrected)
     assert np.array_equal(traces_corrected, target)

From b4c91a0d941e97be68908b11974d18f802ec74a5 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Thu, 21 Nov 2024 21:15:30 +0000
Subject: [PATCH 235/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 .../sortingcomponents/motion/motion_interpolation.py       | 3 +--
 .../motion/tests/test_motion_interpolation.py              | 7 +++++--
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
index e87f83751c..b3a4c9a207 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
@@ -3,8 +3,7 @@
 import numpy as np
 from spikeinterface.core.core_tools import define_function_from_class
 from spikeinterface.preprocessing import get_spatial_interpolation_kernel
-from spikeinterface.preprocessing.basepreprocessor import (
-    BasePreprocessor, BasePreprocessorSegment)
+from spikeinterface.preprocessing.basepreprocessor import BasePreprocessor, BasePreprocessorSegment
 from spikeinterface.preprocessing.filter import fix_dtype
 
 from .motion_utils import ensure_time_bin_edges, ensure_time_bins
diff --git a/src/spikeinterface/sortingcomponents/motion/tests/test_motion_interpolation.py b/src/spikeinterface/sortingcomponents/motion/tests/test_motion_interpolation.py
index c97c8324ba..e4ba870325 100644
--- a/src/spikeinterface/sortingcomponents/motion/tests/test_motion_interpolation.py
+++ b/src/spikeinterface/sortingcomponents/motion/tests/test_motion_interpolation.py
@@ -4,8 +4,11 @@
 import spikeinterface.core as sc
 from spikeinterface.sortingcomponents.motion import Motion
 from spikeinterface.sortingcomponents.motion.motion_interpolation import (
-    InterpolateMotionRecording, correct_motion_on_peaks, interpolate_motion,
-    interpolate_motion_on_traces)
+    InterpolateMotionRecording,
+    correct_motion_on_peaks,
+    interpolate_motion,
+    interpolate_motion_on_traces,
+)
 from spikeinterface.sortingcomponents.tests.common import make_dataset
 
 

From c9d02d884372e89109842a28f47e8dbf8b5a8f11 Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Fri, 22 Nov 2024 09:44:33 +0100
Subject: [PATCH 236/344] Tests

---
 src/spikeinterface/sorters/internal/spyking_circus2.py  | 3 ++-
 src/spikeinterface/sortingcomponents/clustering/main.py | 1 +
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/spikeinterface/sorters/internal/spyking_circus2.py b/src/spikeinterface/sorters/internal/spyking_circus2.py
index 5cce8b54f5..f74570806c 100644
--- a/src/spikeinterface/sorters/internal/spyking_circus2.py
+++ b/src/spikeinterface/sorters/internal/spyking_circus2.py
@@ -115,10 +115,10 @@ def _run_from_folder(cls, sorter_output_folder, params, verbose):
         from spikeinterface.sortingcomponents.matching import find_spikes_from_templates
         from spikeinterface.sortingcomponents.tools import remove_empty_templates
         from spikeinterface.sortingcomponents.tools import get_prototype_spike, check_probe_for_drift_correction
-        from spikeinterface.sortingcomponents.tools import get_prototype_spike
 
         job_kwargs = fix_job_kwargs(params["job_kwargs"])
         job_kwargs.update({"progress_bar": verbose})
+        print(job_kwargs)
 
         recording = cls.load_recording_from_folder(sorter_output_folder.parent, with_warnings=False)
 
@@ -231,6 +231,7 @@ def _run_from_folder(cls, sorter_output_folder, params, verbose):
             else:
                 clustering_method = "random_projections"
 
+            print('test')
             labels, peak_labels = find_cluster_from_peaks(
                 recording_w, selected_peaks, method=clustering_method, method_kwargs=clustering_params, **job_kwargs
             )
diff --git a/src/spikeinterface/sortingcomponents/clustering/main.py b/src/spikeinterface/sortingcomponents/clustering/main.py
index ba0fe6f9ac..fadcb07527 100644
--- a/src/spikeinterface/sortingcomponents/clustering/main.py
+++ b/src/spikeinterface/sortingcomponents/clustering/main.py
@@ -32,6 +32,7 @@ def find_cluster_from_peaks(recording, peaks, method="stupid", method_kwargs={},
         peak_labels.shape[0] == peaks.shape[0]
     """
     job_kwargs = fix_job_kwargs(job_kwargs)
+    print("toto", job_kwargs)
 
     assert (
         method in clustering_methods

From a1e97a54249b076768af8f790506bcc48e3b7fb8 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Fri, 22 Nov 2024 08:44:58 +0000
Subject: [PATCH 237/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/sorters/internal/spyking_circus2.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/sorters/internal/spyking_circus2.py b/src/spikeinterface/sorters/internal/spyking_circus2.py
index f74570806c..bb6306fe15 100644
--- a/src/spikeinterface/sorters/internal/spyking_circus2.py
+++ b/src/spikeinterface/sorters/internal/spyking_circus2.py
@@ -231,7 +231,7 @@ def _run_from_folder(cls, sorter_output_folder, params, verbose):
             else:
                 clustering_method = "random_projections"
 
-            print('test')
+            print("test")
             labels, peak_labels = find_cluster_from_peaks(
                 recording_w, selected_peaks, method=clustering_method, method_kwargs=clustering_params, **job_kwargs
             )

From d414c2d6561966ca1979d11ce0a16c9029011fab Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Fri, 22 Nov 2024 09:56:24 +0100
Subject: [PATCH 238/344] Remove prints

---
 src/spikeinterface/sorters/internal/spyking_circus2.py    | 2 --
 src/spikeinterface/sortingcomponents/clustering/circus.py | 2 +-
 src/spikeinterface/sortingcomponents/clustering/main.py   | 1 -
 3 files changed, 1 insertion(+), 4 deletions(-)

diff --git a/src/spikeinterface/sorters/internal/spyking_circus2.py b/src/spikeinterface/sorters/internal/spyking_circus2.py
index f74570806c..208d9f5bc6 100644
--- a/src/spikeinterface/sorters/internal/spyking_circus2.py
+++ b/src/spikeinterface/sorters/internal/spyking_circus2.py
@@ -118,7 +118,6 @@ def _run_from_folder(cls, sorter_output_folder, params, verbose):
 
         job_kwargs = fix_job_kwargs(params["job_kwargs"])
         job_kwargs.update({"progress_bar": verbose})
-        print(job_kwargs)
 
         recording = cls.load_recording_from_folder(sorter_output_folder.parent, with_warnings=False)
 
@@ -231,7 +230,6 @@ def _run_from_folder(cls, sorter_output_folder, params, verbose):
             else:
                 clustering_method = "random_projections"
 
-            print('test')
             labels, peak_labels = find_cluster_from_peaks(
                 recording_w, selected_peaks, method=clustering_method, method_kwargs=clustering_params, **job_kwargs
             )
diff --git a/src/spikeinterface/sortingcomponents/clustering/circus.py b/src/spikeinterface/sortingcomponents/clustering/circus.py
index 32fe69ee38..6a341047f4 100644
--- a/src/spikeinterface/sortingcomponents/clustering/circus.py
+++ b/src/spikeinterface/sortingcomponents/clustering/circus.py
@@ -184,7 +184,7 @@ def main_function(cls, recording, peaks, params, job_kwargs=dict()):
             sparse_mask = node1.neighbours_mask
             neighbours_mask = get_channel_distances(recording) <= radius_um
 
-            # np.save(features_folder / "sparse_mask.npy", sparse_mask)
+            # np.save(features_folder / "sparse_mask.npy", sparse_mask)
             np.save(features_folder / "peaks.npy", peaks)
 
             original_labels = peaks["channel_index"]
diff --git a/src/spikeinterface/sortingcomponents/clustering/main.py b/src/spikeinterface/sortingcomponents/clustering/main.py
index fadcb07527..ba0fe6f9ac 100644
--- a/src/spikeinterface/sortingcomponents/clustering/main.py
+++ b/src/spikeinterface/sortingcomponents/clustering/main.py
@@ -32,7 +32,6 @@ def find_cluster_from_peaks(recording, peaks, method="stupid", method_kwargs={},
         peak_labels.shape[0] == peaks.shape[0]
     """
     job_kwargs = fix_job_kwargs(job_kwargs)
-    print("toto", job_kwargs)
 
     assert (
         method in clustering_methods

From 4c20e0c588ade80025ed61ae67963581ab0e7ada Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Fri, 22 Nov 2024 08:58:32 +0000
Subject: [PATCH 239/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/sortingcomponents/clustering/circus.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/sortingcomponents/clustering/circus.py b/src/spikeinterface/sortingcomponents/clustering/circus.py
index 6a341047f4..32fe69ee38 100644
--- a/src/spikeinterface/sortingcomponents/clustering/circus.py
+++ b/src/spikeinterface/sortingcomponents/clustering/circus.py
@@ -184,7 +184,7 @@ def main_function(cls, recording, peaks, params, job_kwargs=dict()):
             sparse_mask = node1.neighbours_mask
             neighbours_mask = get_channel_distances(recording) <= radius_um
 
-            # np.save(features_folder / "sparse_mask.npy", sparse_mask)
+            # np.save(features_folder / "sparse_mask.npy", sparse_mask)
             np.save(features_folder / "peaks.npy", peaks)
 
             original_labels = peaks["channel_index"]

From f0ec139fdd52b43048becd9323d7475a6d41097e Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Fri, 22 Nov 2024 10:06:37 +0100
Subject: [PATCH 240/344] Feedback from Zach and Alessio better test for
 waveforms_tools

---
 src/spikeinterface/core/job_tools.py          | 25 ++++----
 .../core/tests/test_job_tools.py              |  1 -
 .../core/tests/test_waveform_tools.py         | 58 ++++++++++++-------
 3 files changed, 48 insertions(+), 36 deletions(-)

diff --git a/src/spikeinterface/core/job_tools.py b/src/spikeinterface/core/job_tools.py
index b12ad7fc4d..64a5c6cdbf 100644
--- a/src/spikeinterface/core/job_tools.py
+++ b/src/spikeinterface/core/job_tools.py
@@ -110,7 +110,7 @@ def fix_job_kwargs(runtime_job_kwargs):
         runtime_job_kwargs = runtime_job_kwargs.copy()
         runtime_job_kwargs["max_threads_per_worker"] = runtime_job_kwargs.pop("max_threads_per_process")
         warnings.warn(
-            "job_kwargs: max_threads_per_worker was changed to max_threads_per_worker",
+            "job_kwargs: max_threads_per_process was changed to max_threads_per_worker, max_threads_per_process will be removed in 0.104",
             DeprecationWarning,
             stacklevel=2,
         )
@@ -346,7 +346,7 @@ class ChunkRecordingExecutor:
     gather_func : None or callable, default: None
         Optional function that is called in the main thread and retrieves the results of each worker.
         This function can be used instead of `handle_returns` to implement custom storage on-the-fly.
-    pool_engine : "process" | "thread"
+    pool_engine : "process" | "thread", default: "thread"
         If n_jobs>1 then use ProcessPoolExecutor or ThreadPoolExecutor
     n_jobs : int, default: 1
         Number of jobs to be used. Use -1 to use as many jobs as number of cores
@@ -384,7 +384,7 @@ def __init__(
         progress_bar=False,
         handle_returns=False,
         gather_func=None,
-        pool_engine="process",
+        pool_engine="thread",
         n_jobs=1,
         total_memory=None,
         chunk_size=None,
@@ -400,12 +400,13 @@ def __init__(
         self.init_func = init_func
         self.init_args = init_args
 
-        if mp_context is None:
-            mp_context = recording.get_preferred_mp_context()
-        if mp_context is not None and platform.system() == "Windows":
-            assert mp_context != "fork", "'fork' mp_context not supported on Windows!"
-        elif mp_context == "fork" and platform.system() == "Darwin":
-            warnings.warn('As of Python 3.8 "fork" is no longer considered safe on macOS')
+        if pool_engine == "process":
+            if mp_context is None:
+                mp_context = recording.get_preferred_mp_context()
+            if mp_context is not None and platform.system() == "Windows":
+                assert mp_context != "fork", "'fork' mp_context not supported on Windows!"
+            elif mp_context == "fork" and platform.system() == "Darwin":
+                warnings.warn('As of Python 3.8 "fork" is no longer considered safe on macOS')
 
         self.mp_context = mp_context
 
@@ -572,13 +573,9 @@ def __call__(self, args):
         else:
             with threadpool_limits(limits=self.max_threads_per_worker):
                 return self.func(segment_index, start_frame, end_frame, self.worker_dict)
-
 # see
 # https://stackoverflow.com/questions/10117073/how-to-use-initializer-to-set-up-my-multiprocess-pool
-# the tricks is : thiw variables are global per worker
-# so they are not share in the same process
-# global _worker_ctx
-# global _func
+# the tricks is : this variable are global per worker (so not shared in the same process)
 global _process_func_wrapper
 
 
diff --git a/src/spikeinterface/core/tests/test_job_tools.py b/src/spikeinterface/core/tests/test_job_tools.py
index 3918fe8ec0..824532a11e 100644
--- a/src/spikeinterface/core/tests/test_job_tools.py
+++ b/src/spikeinterface/core/tests/test_job_tools.py
@@ -81,7 +81,6 @@ def test_ensure_chunk_size():
 
 def func(segment_index, start_frame, end_frame, worker_dict):
     import os
-    import time
 
     #  print('func', segment_index, start_frame, end_frame, worker_dict, os.getpid())
     time.sleep(0.010)
diff --git a/src/spikeinterface/core/tests/test_waveform_tools.py b/src/spikeinterface/core/tests/test_waveform_tools.py
index d0e9358164..ed27815758 100644
--- a/src/spikeinterface/core/tests/test_waveform_tools.py
+++ b/src/spikeinterface/core/tests/test_waveform_tools.py
@@ -173,29 +173,45 @@ def test_estimate_templates_with_accumulator():
 
     job_kwargs = dict(n_jobs=2, progress_bar=True, chunk_duration="1s")
 
-    templates = estimate_templates_with_accumulator(
-        recording, spikes, sorting.unit_ids, nbefore, nafter, return_scaled=True, **job_kwargs
-    )
-    # print(templates.shape)
-    assert templates.shape[0] == sorting.unit_ids.size
-    assert templates.shape[1] == nbefore + nafter
-    assert templates.shape[2] == recording.get_num_channels()
+    # here we compare the result with the same mechanism with with several worker pool size
+    # this means that that acumulator are splitted and then agglomerated back
+    # this should lead to very small diff
+    # n_jobs=1 is done in loop
+    templates_by_worker = []
+
+    if platform.system() == "Linux":
+        engine_loop = ["thread", "process"]
+    else:
+        engine_loop = ["thread"]
+
+    for pool_engine in engine_loop:
+        for n_jobs in (1, 2, 8):
+            job_kwargs = dict(pool_engine=pool_engine, n_jobs=n_jobs, progress_bar=True, chunk_duration="1s")
+            templates = estimate_templates_with_accumulator(
+                recording, spikes, sorting.unit_ids, nbefore, nafter, return_scaled=True, **job_kwargs
+            )
+            assert templates.shape[0] == sorting.unit_ids.size
+            assert templates.shape[1] == nbefore + nafter
+            assert templates.shape[2] == recording.get_num_channels()
+            assert np.any(templates != 0)
+
+            templates_by_worker.append(templates)
+            if len(templates_by_worker) > 1:
+                templates_loop = templates_by_worker[0]
+                np.testing.assert_almost_equal(templates, templates_loop, decimal=4)
+                
+                # import matplotlib.pyplot as plt
+                # fig, axs = plt.subplots(nrows=2, sharex=True)
+                # for unit_index, unit_id in enumerate(sorting.unit_ids):
+                #     ax = axs[0]
+                #     ax.set_title(f"{pool_engine} {n_jobs}")
+                #     ax.plot(templates[unit_index, :, :].T.flatten())
+                #     ax.plot(templates_loop[unit_index, :, :].T.flatten(), color="k", ls="--")
+                #     ax = axs[1]
+                #     ax.plot((templates - templates_loop)[unit_index, :, :].T.flatten(), color="k", ls="--")
+                # plt.show()
 
-    assert np.any(templates != 0)
 
-    job_kwargs = dict(n_jobs=1, progress_bar=True, chunk_duration="1s")
-    templates_loop = estimate_templates_with_accumulator(
-        recording, spikes, sorting.unit_ids, nbefore, nafter, return_scaled=True, **job_kwargs
-    )
-    np.testing.assert_almost_equal(templates, templates_loop, decimal=4)
-    
-    # import matplotlib.pyplot as plt
-    # fig, ax = plt.subplots()
-    # for unit_index, unit_id in enumerate(sorting.unit_ids):
-        # ax.plot(templates[unit_index, :, :].T.flatten())
-        # ax.plot(templates_loop[unit_index, :, :].T.flatten(), color="k", ls="--")
-        # ax.plot((templates - templates_loop)[unit_index, :, :].T.flatten(), color="k", ls="--")
-    # plt.show()
 
 
 def test_estimate_templates():

From 9cc1673f5c1c520636ee7654a067de2b0a68ef96 Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Fri, 22 Nov 2024 10:14:49 +0100
Subject: [PATCH 241/344] Cleaning imports. Need to test with mac

---
 .../sortingcomponents/clustering/circus.py               | 1 -
 .../sortingcomponents/clustering/random_projections.py   | 4 ++--
 .../sortingcomponents/clustering/sliding_hdbscan.py      | 2 +-
 src/spikeinterface/sortingcomponents/clustering/tdc.py   | 9 ++-------
 4 files changed, 5 insertions(+), 11 deletions(-)

diff --git a/src/spikeinterface/sortingcomponents/clustering/circus.py b/src/spikeinterface/sortingcomponents/clustering/circus.py
index 6a341047f4..c1ec3f1aab 100644
--- a/src/spikeinterface/sortingcomponents/clustering/circus.py
+++ b/src/spikeinterface/sortingcomponents/clustering/circus.py
@@ -18,7 +18,6 @@
 from spikeinterface.core.waveform_tools import estimate_templates
 from .clustering_tools import remove_duplicates_via_matching
 from spikeinterface.core.recording_tools import get_noise_levels, get_channel_distances
-from spikeinterface.core.job_tools import fix_job_kwargs
 from spikeinterface.sortingcomponents.peak_selection import select_peaks
 from spikeinterface.sortingcomponents.waveforms.temporal_pca import TemporalPCAProjection
 from spikeinterface.core.template import Templates
diff --git a/src/spikeinterface/sortingcomponents/clustering/random_projections.py b/src/spikeinterface/sortingcomponents/clustering/random_projections.py
index 40bb4ac987..484a7376c1 100644
--- a/src/spikeinterface/sortingcomponents/clustering/random_projections.py
+++ b/src/spikeinterface/sortingcomponents/clustering/random_projections.py
@@ -16,7 +16,7 @@
 from spikeinterface.core.basesorting import minimum_spike_dtype
 from spikeinterface.core.waveform_tools import estimate_templates
 from .clustering_tools import remove_duplicates_via_matching
-from spikeinterface.core.recording_tools import get_noise_levels, get_channel_distances
+from spikeinterface.core.recording_tools import get_noise_levels
 from spikeinterface.sortingcomponents.waveforms.savgol_denoiser import SavGolDenoiser
 from spikeinterface.sortingcomponents.features_from_peaks import RandomProjectionsFeature
 from spikeinterface.core.template import Templates
@@ -144,7 +144,7 @@ def main_function(cls, recording, peaks, params, job_kwargs=dict()):
             is_scaled=False,
         )
         if params["noise_levels"] is None:
-            params["noise_levels"] = get_noise_levels(recording, return_scaled=False)
+            params["noise_levels"] = get_noise_levels(recording, return_scaled=False, **job_kwargs)
         sparsity = compute_sparsity(templates, params["noise_levels"], **params["sparsity"])
         templates = templates.to_sparse(sparsity)
         templates = remove_empty_templates(templates)
diff --git a/src/spikeinterface/sortingcomponents/clustering/sliding_hdbscan.py b/src/spikeinterface/sortingcomponents/clustering/sliding_hdbscan.py
index 2ae810ae20..5f8ac99848 100644
--- a/src/spikeinterface/sortingcomponents/clustering/sliding_hdbscan.py
+++ b/src/spikeinterface/sortingcomponents/clustering/sliding_hdbscan.py
@@ -23,7 +23,7 @@
     get_random_data_chunks,
     extract_waveforms_to_buffers,
 )
-from .clustering_tools import auto_clean_clustering, auto_split_clustering
+from .clustering_tools import auto_clean_clustering
 
 
 class SlidingHdbscanClustering:
diff --git a/src/spikeinterface/sortingcomponents/clustering/tdc.py b/src/spikeinterface/sortingcomponents/clustering/tdc.py
index c6b94eaa48..6c361b0562 100644
--- a/src/spikeinterface/sortingcomponents/clustering/tdc.py
+++ b/src/spikeinterface/sortingcomponents/clustering/tdc.py
@@ -9,27 +9,22 @@
 
 from spikeinterface.core import (
     get_channel_distances,
-    Templates,
-    compute_sparsity,
     get_global_tmp_folder,
 )
 
 from spikeinterface.core.node_pipeline import (
     run_node_pipeline,
-    ExtractDenseWaveforms,
     ExtractSparseWaveforms,
     PeakRetriever,
 )
 
-from spikeinterface.sortingcomponents.tools import extract_waveform_at_max_channel, cache_preprocessing
-from spikeinterface.sortingcomponents.peak_detection import detect_peaks, DetectPeakLocallyExclusive
+from spikeinterface.sortingcomponents.tools import extract_waveform_at_max_channel
 from spikeinterface.sortingcomponents.peak_selection import select_peaks
-from spikeinterface.sortingcomponents.peak_localization import LocalizeCenterOfMass, LocalizeGridConvolution
 from spikeinterface.sortingcomponents.waveforms.temporal_pca import TemporalPCAProjection
 
 from spikeinterface.sortingcomponents.clustering.split import split_clusters
 from spikeinterface.sortingcomponents.clustering.merge import merge_clusters
-from spikeinterface.sortingcomponents.clustering.tools import compute_template_from_sparse
+
 
 
 class TdcClustering:

From 61351e7a60b7b2215cd3eea3374363e354c7fb1e Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Fri, 22 Nov 2024 09:18:47 +0000
Subject: [PATCH 242/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/sortingcomponents/clustering/tdc.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/spikeinterface/sortingcomponents/clustering/tdc.py b/src/spikeinterface/sortingcomponents/clustering/tdc.py
index 6c361b0562..59472d1374 100644
--- a/src/spikeinterface/sortingcomponents/clustering/tdc.py
+++ b/src/spikeinterface/sortingcomponents/clustering/tdc.py
@@ -26,7 +26,6 @@
 from spikeinterface.sortingcomponents.clustering.merge import merge_clusters
 
 
-
 class TdcClustering:
     """
     Here the implementation of clustering used by tridesclous2

From cc8b4c4a976d7f60dc7c70358f229e49f034dec8 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Fri, 22 Nov 2024 11:04:33 +0100
Subject: [PATCH 243/344] fix tests

---
 .../qualitymetrics/tests/conftest.py               |  7 +++++--
 .../qualitymetrics/tests/test_pca_metrics.py       | 14 +++++++++++++-
 2 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/src/spikeinterface/qualitymetrics/tests/conftest.py b/src/spikeinterface/qualitymetrics/tests/conftest.py
index 01fa16c8d7..9878adf142 100644
--- a/src/spikeinterface/qualitymetrics/tests/conftest.py
+++ b/src/spikeinterface/qualitymetrics/tests/conftest.py
@@ -8,8 +8,8 @@
 job_kwargs = dict(n_jobs=2, progress_bar=True, chunk_duration="1s")
 
 
-@pytest.fixture(scope="module")
-def small_sorting_analyzer():
+
+def make_small_analyzer():
     recording, sorting = generate_ground_truth_recording(
         durations=[2.0],
         num_units=10,
@@ -34,6 +34,9 @@ def small_sorting_analyzer():
 
     return sorting_analyzer
 
+@pytest.fixture(scope="module")
+def small_sorting_analyzer():
+    return make_small_analyzer()
 
 @pytest.fixture(scope="module")
 def sorting_analyzer_simple():
diff --git a/src/spikeinterface/qualitymetrics/tests/test_pca_metrics.py b/src/spikeinterface/qualitymetrics/tests/test_pca_metrics.py
index ba8dae4619..897c2837cc 100644
--- a/src/spikeinterface/qualitymetrics/tests/test_pca_metrics.py
+++ b/src/spikeinterface/qualitymetrics/tests/test_pca_metrics.py
@@ -19,7 +19,14 @@ def test_calculate_pc_metrics(small_sorting_analyzer):
             assert not np.all(np.isnan(res1[metric_name].values))
             assert not np.all(np.isnan(res2[metric_name].values))
 
-        assert np.array_equal(res1[metric_name].values, res2[metric_name].values)
+        # import matplotlib.pyplot as plt
+        # fig, ax = plt.subplots()
+        # ax.plot(res1[metric_name].values)
+        # ax.plot(res2[metric_name].values)
+        # ax.plot(res2[metric_name].values - res1[metric_name].values)
+        # plt.show()
+
+        np.testing.assert_almost_equal(res1[metric_name].values, res2[metric_name].values, decimal=4)
 
 
 def test_pca_metrics_multi_processing(small_sorting_analyzer):
@@ -41,3 +48,8 @@ def test_pca_metrics_multi_processing(small_sorting_analyzer):
     res2 = compute_pc_metrics(
         sorting_analyzer, n_jobs=-1, metric_names=metric_names, max_threads_per_worker=2, progress_bar=True
     )
+
+if __name__ == "__main__":
+    from spikeinterface.qualitymetrics.tests.conftest import make_small_analyzer
+    small_sorting_analyzer = make_small_analyzer()
+    test_calculate_pc_metrics(small_sorting_analyzer)
\ No newline at end of file

From c16ca722e057671a503c2a38a4d80a1b0cd6b7cd Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Fri, 22 Nov 2024 12:11:46 +0100
Subject: [PATCH 244/344] oups

---
 .../qualitymetrics/tests/test_pca_metrics.py  | 29 ++++++++++++-------
 1 file changed, 18 insertions(+), 11 deletions(-)

diff --git a/src/spikeinterface/qualitymetrics/tests/test_pca_metrics.py b/src/spikeinterface/qualitymetrics/tests/test_pca_metrics.py
index 897c2837cc..312c3949b3 100644
--- a/src/spikeinterface/qualitymetrics/tests/test_pca_metrics.py
+++ b/src/spikeinterface/qualitymetrics/tests/test_pca_metrics.py
@@ -15,18 +15,25 @@ def test_calculate_pc_metrics(small_sorting_analyzer):
     res2 = pd.DataFrame(res2)
 
     for metric_name in res1.columns:
-        if metric_name != "nn_unit_id":
-            assert not np.all(np.isnan(res1[metric_name].values))
-            assert not np.all(np.isnan(res2[metric_name].values))
-
-        # import matplotlib.pyplot as plt
-        # fig, ax = plt.subplots()
-        # ax.plot(res1[metric_name].values)
-        # ax.plot(res2[metric_name].values)
-        # ax.plot(res2[metric_name].values - res1[metric_name].values)
-        # plt.show()
+        values1 = res1[metric_name].values
+        values2 = res1[metric_name].values
 
-        np.testing.assert_almost_equal(res1[metric_name].values, res2[metric_name].values, decimal=4)
+        if metric_name != "nn_unit_id":
+            assert not np.all(np.isnan(values1))
+            assert not np.all(np.isnan(values2))
+
+        if values1.dtype.kind == "f":
+            np.testing.assert_almost_equal(values1, values2, decimal=4)
+            # import matplotlib.pyplot as plt
+            # fig, axs = plt.subplots(nrows=2, share=True)
+            # ax =a xs[0]
+            # ax.plot(res1[metric_name].values)
+            # ax.plot(res2[metric_name].values)
+            # ax =a xs[1]
+            # ax.plot(res2[metric_name].values - res1[metric_name].values)
+            # plt.show()
+        else:
+            assert np.array_equal(values1, values2)
 
 
 def test_pca_metrics_multi_processing(small_sorting_analyzer):

From de5ee687781eddfd8ebdde3b83e9f91d3ac81163 Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Fri, 22 Nov 2024 15:07:40 +0100
Subject: [PATCH 245/344] Less cores for mac ?

---
 src/spikeinterface/sorters/internal/spyking_circus2.py | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/src/spikeinterface/sorters/internal/spyking_circus2.py b/src/spikeinterface/sorters/internal/spyking_circus2.py
index 208d9f5bc6..6e84cc996f 100644
--- a/src/spikeinterface/sorters/internal/spyking_circus2.py
+++ b/src/spikeinterface/sorters/internal/spyking_circus2.py
@@ -52,7 +52,7 @@ class Spykingcircus2Sorter(ComponentsBasedSorter):
         "matched_filtering": True,
         "cache_preprocessing": {"mode": "memory", "memory_limit": 0.5, "delete_cache": True},
         "multi_units_only": False,
-        "job_kwargs": {"n_jobs": 0.8},
+        "job_kwargs": {"n_jobs": 0.5},
         "debug": False,
     }
 
@@ -282,11 +282,10 @@ def _run_from_folder(cls, sorter_output_folder, params, verbose):
             matching_method = params["matching"].pop("method")
             matching_params = params["matching"].copy()
             matching_params["templates"] = templates
-            matching_job_params = job_kwargs.copy()
 
             if matching_method is not None:
                 spikes = find_spikes_from_templates(
-                    recording_w, matching_method, method_kwargs=matching_params, **matching_job_params
+                    recording_w, matching_method, method_kwargs=matching_params, **job_kwargs
                 )
 
                 if params["debug"]:

From 38e0adac18c2c862f9193e5a5d643b394a6d3d52 Mon Sep 17 00:00:00 2001
From: Charlie Windolf <charliexwindolf@gmail.com>
Date: Fri, 22 Nov 2024 10:28:34 -0500
Subject: [PATCH 246/344] Typo

---
 .../sortingcomponents/motion/motion_interpolation.py            | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
index b3a4c9a207..fc8ccb788b 100644
--- a/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
+++ b/src/spikeinterface/sortingcomponents/motion/motion_interpolation.py
@@ -130,7 +130,7 @@ def interpolate_motion_on_traces(
 
     # -- determine the blocks of frames that will land in the same interpolation time bin
     if interpolation_time_bin_centers_s is None and interpolation_time_bin_edges_s is None:
-        interpolation_time_bin_centers_s = motion.temporal_bin_centers_s[segment_index]
+        interpolation_time_bin_centers_s = motion.temporal_bins_s[segment_index]
         interpolation_time_bin_edges_s = motion.temporal_bin_edges_s[segment_index]
     else:
         interpolation_time_bin_centers_s, interpolation_time_bin_edges_s = ensure_time_bins(

From e175bdc0323d4d0e4d6c7213bb5d27ee92b4febb Mon Sep 17 00:00:00 2001
From: zm711 <92116279+zm711@users.noreply.github.com>
Date: Fri, 22 Nov 2024 16:06:19 -0500
Subject: [PATCH 247/344] wip

---
 .../quality_metric_calculator.py              |  7 ++++
 .../qualitymetrics/quality_metric_list.py     | 38 ++++++++++++++++++-
 2 files changed, 44 insertions(+), 1 deletion(-)

diff --git a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
index bcea6ab612..aef3631438 100644
--- a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
+++ b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
@@ -16,6 +16,7 @@
     _misc_metric_name_to_func,
     _possible_pc_metric_names,
     compute_name_to_column_names,
+    column_name_to_column_dtype,
 )
 from .misc_metrics import _default_params as misc_metrics_params
 from .pca_metrics import _default_params as pca_metrics_params
@@ -225,6 +226,12 @@ def _compute_metrics(self, sorting_analyzer, unit_ids=None, verbose=False, metri
         # we use the convert_dtypes to convert the columns to the most appropriate dtype and avoid object columns
         # (in case of NaN values)
         metrics = metrics.convert_dtypes()
+
+        # we do this because the convert_dtypes infers the wrong types sometimes.
+        # the actual types for columns can be found in column_name_to_column_dtype dictionary.
+        for column in metrics.columns:
+            metrics[column] = metrics[column].astype(column_name_to_column_dtype[column])
+
         return metrics
 
     def _run(self, verbose=False, **job_kwargs):
diff --git a/src/spikeinterface/qualitymetrics/quality_metric_list.py b/src/spikeinterface/qualitymetrics/quality_metric_list.py
index 375dd320ae..8ad3bee44c 100644
--- a/src/spikeinterface/qualitymetrics/quality_metric_list.py
+++ b/src/spikeinterface/qualitymetrics/quality_metric_list.py
@@ -66,7 +66,11 @@
     "amplitude_cutoff": ["amplitude_cutoff"],
     "amplitude_median": ["amplitude_median"],
     "amplitude_cv": ["amplitude_cv_median", "amplitude_cv_range"],
-    "synchrony": ["sync_spike_2", "sync_spike_4", "sync_spike_8"],
+    "synchrony": [
+        "sync_spike_2",
+        "sync_spike_4",
+        "sync_spike_8",
+    ],  # we probably shouldn't hard code this. This is determined by the arguments in the function...
     "firing_range": ["firing_range"],
     "drift": ["drift_ptp", "drift_std", "drift_mad"],
     "sd_ratio": ["sd_ratio"],
@@ -79,3 +83,35 @@
     "silhouette": ["silhouette"],
     "silhouette_full": ["silhouette_full"],
 }
+
+column_name_to_column_dtype = {
+    "num_spikes": int,
+    "firing_rate": float,
+    "presence_ratio": float,
+    "snr": float,
+    "isi_violations_ratio": float,
+    "isi_violations_count": float,
+    "rp_violations": float,
+    "rp_contamination": float,
+    "sliding_rp_violation": float,
+    "amplitude_cutoff": float,
+    "amplitude_median": float,
+    "amplitude_cv_median": float,
+    "amplitude_cv_range": float,
+    "synch": float,
+    "firing_range": float,
+    "drift_ptp": float,
+    "drift_std": float,
+    "drift_mad": float,
+    "sd_ratio": float,
+    "isolation_distance": float,
+    "l_ratio": float,
+    "d_prime": float,
+    "nn_hit_rate": float,
+    "nn_miss_rate": float,
+    "nn_isolation": float,
+    "nn_unit_id": float,
+    "nn_noise_overlap": float,
+    "silhouette": float,
+    "silhouette_full": float,
+}

From bf96fe114b9e479a3db784f4e4de2aa02f65489e Mon Sep 17 00:00:00 2001
From: zm711 <92116279+zm711@users.noreply.github.com>
Date: Fri, 22 Nov 2024 16:13:20 -0500
Subject: [PATCH 248/344] fix synchrony

---
 .../qualitymetrics/quality_metric_calculator.py           | 8 +++++++-
 src/spikeinterface/qualitymetrics/quality_metric_list.py  | 3 ++-
 2 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
index aef3631438..5cefcaa75d 100644
--- a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
+++ b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
@@ -230,7 +230,13 @@ def _compute_metrics(self, sorting_analyzer, unit_ids=None, verbose=False, metri
         # we do this because the convert_dtypes infers the wrong types sometimes.
         # the actual types for columns can be found in column_name_to_column_dtype dictionary.
         for column in metrics.columns:
-            metrics[column] = metrics[column].astype(column_name_to_column_dtype[column])
+            # we have one issue where the name of the columns for synchrony are named based on
+            # what the user has input as arguments so we need a way to handle this separately
+            # everything else should be handled with the column name.
+            if "sync" in column:
+                metrics[column] = metrics[column].astype(column_name_to_column_dtype["sync"])
+            else:
+                metrics[column] = metrics[column].astype(column_name_to_column_dtype[column])
 
         return metrics
 
diff --git a/src/spikeinterface/qualitymetrics/quality_metric_list.py b/src/spikeinterface/qualitymetrics/quality_metric_list.py
index 8ad3bee44c..685aaddc83 100644
--- a/src/spikeinterface/qualitymetrics/quality_metric_list.py
+++ b/src/spikeinterface/qualitymetrics/quality_metric_list.py
@@ -84,6 +84,7 @@
     "silhouette_full": ["silhouette_full"],
 }
 
+# this dict allows us to ensure the appropriate dtype of metrics rather than allow Pandas to infer them
 column_name_to_column_dtype = {
     "num_spikes": int,
     "firing_rate": float,
@@ -98,7 +99,7 @@
     "amplitude_median": float,
     "amplitude_cv_median": float,
     "amplitude_cv_range": float,
-    "synch": float,
+    "sync": float,
     "firing_range": float,
     "drift_ptp": float,
     "drift_std": float,

From 5b77ba170788c18fcb9fb06413b8baf58caf73fb Mon Sep 17 00:00:00 2001
From: zm711 <92116279+zm711@users.noreply.github.com>
Date: Fri, 22 Nov 2024 16:29:44 -0500
Subject: [PATCH 249/344] fix nan and empty units

---
 .../qualitymetrics/quality_metric_calculator.py            | 3 +++
 .../qualitymetrics/tests/test_quality_metric_calculator.py | 7 ++++++-
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
index 5cefcaa75d..6fdc21bac2 100644
--- a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
+++ b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
@@ -222,6 +222,9 @@ def _compute_metrics(self, sorting_analyzer, unit_ids=None, verbose=False, metri
         # add NaN for empty units
         if len(empty_unit_ids) > 0:
             metrics.loc[empty_unit_ids] = np.nan
+            # num_spikes is an int and should be 0
+            if "num_spikes" in metrics.columns:
+                metrics.loc[empty_unit_ids, ["num_spikes"]] = 0
 
         # we use the convert_dtypes to convert the columns to the most appropriate dtype and avoid object columns
         # (in case of NaN values)
diff --git a/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py b/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py
index c4c1778cf2..56e3975210 100644
--- a/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py
+++ b/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py
@@ -133,10 +133,15 @@ def test_empty_units(sorting_analyzer_simple):
         seed=2205,
     )
 
+    # num_spikes are ints not nans so we confirm empty units are nans for everything except
+    # num_spikes which should be 0
+    nan_containing_columns = [column for column in metrics_empty.columns if column != "num_spikes"]
     for empty_unit_id in sorting_empty.get_empty_unit_ids():
         from pandas import isnull
 
-        assert np.all(isnull(metrics_empty.loc[empty_unit_id].values))
+        assert np.all(isnull(metrics_empty.loc[empty_unit_id, nan_containing_columns].values))
+        if "num_spikes" in metrics_empty.columns:
+            assert metrics_empty.loc[empty_unit_id, ["num_spikes"]] == 0
 
 
 # TODO @alessio all theses old test should be moved in test_metric_functions.py or test_pca_metrics()

From 807e771dfb9a2f6041a12f10baf28ac17ad0c0a0 Mon Sep 17 00:00:00 2001
From: zm711 <92116279+zm711@users.noreply.github.com>
Date: Fri, 22 Nov 2024 16:38:17 -0500
Subject: [PATCH 250/344] fix test

---
 .../qualitymetrics/tests/test_quality_metric_calculator.py  | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py b/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py
index 56e3975210..71569e7b2b 100644
--- a/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py
+++ b/src/spikeinterface/qualitymetrics/tests/test_quality_metric_calculator.py
@@ -136,12 +136,12 @@ def test_empty_units(sorting_analyzer_simple):
     # num_spikes are ints not nans so we confirm empty units are nans for everything except
     # num_spikes which should be 0
     nan_containing_columns = [column for column in metrics_empty.columns if column != "num_spikes"]
-    for empty_unit_id in sorting_empty.get_empty_unit_ids():
+    for empty_unit_ids in sorting_empty.get_empty_unit_ids():
         from pandas import isnull
 
-        assert np.all(isnull(metrics_empty.loc[empty_unit_id, nan_containing_columns].values))
+        assert np.all(isnull(metrics_empty.loc[empty_unit_ids, nan_containing_columns].values))
         if "num_spikes" in metrics_empty.columns:
-            assert metrics_empty.loc[empty_unit_id, ["num_spikes"]] == 0
+            assert sum(metrics_empty.loc[empty_unit_ids, ["num_spikes"]]) == 0
 
 
 # TODO @alessio all theses old test should be moved in test_metric_functions.py or test_pca_metrics()

From 155ab31b45f119a56a5318c3a0e030d17c36af07 Mon Sep 17 00:00:00 2001
From: Garcia Samuel <sam.garcia.die@gmail.com>
Date: Mon, 25 Nov 2024 08:35:12 +0100
Subject: [PATCH 251/344] merci zach

Co-authored-by: Zach McKenzie <92116279+zm711@users.noreply.github.com>
---
 src/spikeinterface/core/job_tools.py | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/src/spikeinterface/core/job_tools.py b/src/spikeinterface/core/job_tools.py
index 64a5c6cdbf..ce7eb05dbc 100644
--- a/src/spikeinterface/core/job_tools.py
+++ b/src/spikeinterface/core/job_tools.py
@@ -61,7 +61,8 @@
 
 def get_best_job_kwargs():
     """
-    Given best possible job_kwargs for the platform.
+    Gives best possible job_kwargs for the platform.
+    Currently this function  is from developer experience, but may be adapted in the future.
     """
 
     n_cpu = os.cpu_count()
@@ -71,19 +72,19 @@ def get_best_job_kwargs():
         pool_engine = "process"
         mp_context = "fork"
 
-        # this is totally empiricat but this is a good start
+        # this is totally empirical but this is a good start
         if n_cpu <= 16:
-            # for small n_cpu lets make many process
+            # for small n_cpu let's make many process
             n_jobs = n_cpu
             max_threads_per_worker = 1
         else:
-            # lets have less process with more thread each
+            # let's have fewer processes with more threads each
             n_cpu = int(n_cpu / 4)
             max_threads_per_worker = 8
 
     else: # windows and mac
         # on windows and macos the fork is forbidden and process+spwan is super slow at startup
-        # so lets go to threads
+        # so let's go to threads
         pool_engine = "thread"
         mp_context = None
         n_jobs = n_cpu
@@ -557,7 +558,7 @@ def run(self, recording_slices=None):
 
 class WorkerFuncWrapper:
     """
-    small wraper that handle:
+    small wrapper that handles:
       * local worker_dict
       *  max_threads_per_worker
     """
@@ -575,7 +576,7 @@ def __call__(self, args):
                 return self.func(segment_index, start_frame, end_frame, self.worker_dict)
 # see
 # https://stackoverflow.com/questions/10117073/how-to-use-initializer-to-set-up-my-multiprocess-pool
-# the tricks is : this variable are global per worker (so not shared in the same process)
+# the trick is : this variable is global per worker (so not shared in the same process)
 global _process_func_wrapper
 
 

From 2cff62babd7816c14fef9246152b53a2bb59d991 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 27 Nov 2024 14:36:53 +0100
Subject: [PATCH 252/344] plot drift with the scatter plot

---
 .../benchmark/benchmark_motion_estimation.py       | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/src/spikeinterface/benchmark/benchmark_motion_estimation.py b/src/spikeinterface/benchmark/benchmark_motion_estimation.py
index abb2a51bae..3a7d11fc35 100644
--- a/src/spikeinterface/benchmark/benchmark_motion_estimation.py
+++ b/src/spikeinterface/benchmark/benchmark_motion_estimation.py
@@ -109,6 +109,9 @@ def run(self, **job_kwargs):
             estimate_motion=t4 - t3,
         )
 
+
+        self.result["peaks"] = peaks
+        self.result["peak_locations"] = peak_locations
         self.result["step_run_times"] = step_run_times
         self.result["raw_motion"] = motion
 
@@ -131,6 +134,8 @@ def compute_result(self, **result_params):
         self.result["motion"] = motion
 
     _run_key_saved = [
+        ("peaks", "npy"),
+        ("peak_locations", "npy"),
         ("raw_motion", "Motion"),
         ("step_run_times", "pickle"),
     ]
@@ -161,7 +166,7 @@ def create_benchmark(self, key):
     def plot_true_drift(self, case_keys=None, scaling_probe=1.5, figsize=(8, 6)):
         self.plot_drift(case_keys=case_keys, tested_drift=False, scaling_probe=scaling_probe, figsize=figsize)
 
-    def plot_drift(self, case_keys=None, gt_drift=True, tested_drift=True, scaling_probe=1.0, figsize=(8, 6)):
+    def plot_drift(self, case_keys=None, gt_drift=True, tested_drift=True, raster=False, scaling_probe=1.0, figsize=(8, 6)):
         import matplotlib.pyplot as plt
 
         if case_keys is None:
@@ -195,6 +200,13 @@ def plot_drift(self, case_keys=None, gt_drift=True, tested_drift=True, scaling_p
 
             # for i in range(self.gt_unit_positions.shape[1]):
             #     ax.plot(temporal_bins_s, self.gt_unit_positions[:, i], alpha=0.5, ls="--", c="0.5")
+            if raster:
+                peaks = bench.result["peaks"]
+                peak_locations = bench.result["peak_locations"]
+                rec = bench.recording
+                x = peaks["sample_index"] / rec.sampling_frequency
+                y = peak_locations[bench.direction]
+                ax.scatter(x, y, alpha=.2, s=2,  c=np.abs(peaks["amplitude"]), cmap="inferno")
 
             for i in range(gt_motion.displacement[0].shape[1]):
                 depth = motion.spatial_bins_um[i]

From 22882ef66a8389fdfd7aac30ea4633151f1cdd16 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Wed, 27 Nov 2024 13:38:09 +0000
Subject: [PATCH 253/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 .../benchmark/benchmark_motion_estimation.py               | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/src/spikeinterface/benchmark/benchmark_motion_estimation.py b/src/spikeinterface/benchmark/benchmark_motion_estimation.py
index 3a7d11fc35..5a3c490d38 100644
--- a/src/spikeinterface/benchmark/benchmark_motion_estimation.py
+++ b/src/spikeinterface/benchmark/benchmark_motion_estimation.py
@@ -109,7 +109,6 @@ def run(self, **job_kwargs):
             estimate_motion=t4 - t3,
         )
 
-
         self.result["peaks"] = peaks
         self.result["peak_locations"] = peak_locations
         self.result["step_run_times"] = step_run_times
@@ -166,7 +165,9 @@ def create_benchmark(self, key):
     def plot_true_drift(self, case_keys=None, scaling_probe=1.5, figsize=(8, 6)):
         self.plot_drift(case_keys=case_keys, tested_drift=False, scaling_probe=scaling_probe, figsize=figsize)
 
-    def plot_drift(self, case_keys=None, gt_drift=True, tested_drift=True, raster=False, scaling_probe=1.0, figsize=(8, 6)):
+    def plot_drift(
+        self, case_keys=None, gt_drift=True, tested_drift=True, raster=False, scaling_probe=1.0, figsize=(8, 6)
+    ):
         import matplotlib.pyplot as plt
 
         if case_keys is None:
@@ -206,7 +207,7 @@ def plot_drift(self, case_keys=None, gt_drift=True, tested_drift=True, raster=Fa
                 rec = bench.recording
                 x = peaks["sample_index"] / rec.sampling_frequency
                 y = peak_locations[bench.direction]
-                ax.scatter(x, y, alpha=.2, s=2,  c=np.abs(peaks["amplitude"]), cmap="inferno")
+                ax.scatter(x, y, alpha=0.2, s=2, c=np.abs(peaks["amplitude"]), cmap="inferno")
 
             for i in range(gt_motion.displacement[0].shape[1]):
                 depth = motion.spatial_bins_um[i]

From 0c88b39a875e5068b0bfd4f63db7ff45f025e202 Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Fri, 29 Nov 2024 05:46:02 +0100
Subject: [PATCH 254/344] Patch to force remove sorters

---
 src/spikeinterface/benchmark/benchmark_base.py   | 5 +++--
 src/spikeinterface/benchmark/benchmark_sorter.py | 9 +++++++++
 src/spikeinterface/curation/auto_merge.py        | 2 +-
 3 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/src/spikeinterface/benchmark/benchmark_base.py b/src/spikeinterface/benchmark/benchmark_base.py
index b9cbf269c8..ddcf25f2ab 100644
--- a/src/spikeinterface/benchmark/benchmark_base.py
+++ b/src/spikeinterface/benchmark/benchmark_base.py
@@ -208,10 +208,11 @@ def run(self, case_keys=None, keep=True, verbose=False, **job_kwargs):
         for key in case_keys:
 
             result_folder = self.folder / "results" / self.key_to_str(key)
-
+            sorter_folder = self.folder / "sorters" / self.key_to_str(key)
+        
             if keep and result_folder.exists():
                 continue
-            elif not keep and result_folder.exists():
+            elif not keep and (result_folder.exists() or sorter_folder.exists()):
                 self.remove_benchmark(key)
             job_keys.append(key)
 
diff --git a/src/spikeinterface/benchmark/benchmark_sorter.py b/src/spikeinterface/benchmark/benchmark_sorter.py
index f9267c785a..8180c943be 100644
--- a/src/spikeinterface/benchmark/benchmark_sorter.py
+++ b/src/spikeinterface/benchmark/benchmark_sorter.py
@@ -56,6 +56,15 @@ def create_benchmark(self, key):
         benchmark = SorterBenchmark(recording, gt_sorting, params, sorter_folder)
         return benchmark
 
+    def remove_benchmark(self, key):
+        BenchmarkStudy.remove_benchmark(self, key)
+
+        sorter_folder = self.folder / "sorters" / self.key_to_str(key)
+        import shutil
+        if sorter_folder.exists():
+            shutil.rmtree(sorter_folder)
+        
+
     def get_performance_by_unit(self, case_keys=None):
         import pandas as pd
 
diff --git a/src/spikeinterface/curation/auto_merge.py b/src/spikeinterface/curation/auto_merge.py
index 4f4cff144e..89c24565c2 100644
--- a/src/spikeinterface/curation/auto_merge.py
+++ b/src/spikeinterface/curation/auto_merge.py
@@ -231,7 +231,7 @@ def compute_merge_unit_groups(
         params = _default_step_params.get(step).copy()
         if steps_params is not None and step in steps_params:
             params.update(steps_params[step])
-
+    
         # STEP : remove units with too few spikes
         if step == "num_spikes":
 

From 32c74d43085848008e0a497342f4b3eb2d917020 Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Fri, 29 Nov 2024 05:46:58 +0100
Subject: [PATCH 255/344] Spaces

---
 src/spikeinterface/curation/auto_merge.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/curation/auto_merge.py b/src/spikeinterface/curation/auto_merge.py
index 89c24565c2..4f4cff144e 100644
--- a/src/spikeinterface/curation/auto_merge.py
+++ b/src/spikeinterface/curation/auto_merge.py
@@ -231,7 +231,7 @@ def compute_merge_unit_groups(
         params = _default_step_params.get(step).copy()
         if steps_params is not None and step in steps_params:
             params.update(steps_params[step])
-    
+
         # STEP : remove units with too few spikes
         if step == "num_spikes":
 

From c35a706632065af280300330ba25f76326906590 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Fri, 29 Nov 2024 04:49:39 +0000
Subject: [PATCH 256/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/benchmark/benchmark_base.py   | 2 +-
 src/spikeinterface/benchmark/benchmark_sorter.py | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/benchmark/benchmark_base.py b/src/spikeinterface/benchmark/benchmark_base.py
index ddcf25f2ab..fc1b136d2d 100644
--- a/src/spikeinterface/benchmark/benchmark_base.py
+++ b/src/spikeinterface/benchmark/benchmark_base.py
@@ -209,7 +209,7 @@ def run(self, case_keys=None, keep=True, verbose=False, **job_kwargs):
 
             result_folder = self.folder / "results" / self.key_to_str(key)
             sorter_folder = self.folder / "sorters" / self.key_to_str(key)
-        
+
             if keep and result_folder.exists():
                 continue
             elif not keep and (result_folder.exists() or sorter_folder.exists()):
diff --git a/src/spikeinterface/benchmark/benchmark_sorter.py b/src/spikeinterface/benchmark/benchmark_sorter.py
index 8180c943be..3cf6dca04f 100644
--- a/src/spikeinterface/benchmark/benchmark_sorter.py
+++ b/src/spikeinterface/benchmark/benchmark_sorter.py
@@ -61,9 +61,9 @@ def remove_benchmark(self, key):
 
         sorter_folder = self.folder / "sorters" / self.key_to_str(key)
         import shutil
+
         if sorter_folder.exists():
             shutil.rmtree(sorter_folder)
-        
 
     def get_performance_by_unit(self, case_keys=None):
         import pandas as pd

From b0e7b1c60086fd818759b8df0f617d5441f4ff40 Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Fri, 29 Nov 2024 06:04:48 +0100
Subject: [PATCH 257/344] Fix kwargs in silence periods

---
 src/spikeinterface/preprocessing/silence_periods.py | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/src/spikeinterface/preprocessing/silence_periods.py b/src/spikeinterface/preprocessing/silence_periods.py
index 85169011d8..a188f5d8db 100644
--- a/src/spikeinterface/preprocessing/silence_periods.py
+++ b/src/spikeinterface/preprocessing/silence_periods.py
@@ -97,7 +97,12 @@ def __init__(self, recording, list_periods, mode="zeros", noise_levels=None, see
             rec_segment = SilencedPeriodsRecordingSegment(parent_segment, periods, mode, noise_generator, seg_index)
             self.add_recording_segment(rec_segment)
 
-        self._kwargs = dict(recording=recording, list_periods=list_periods, mode=mode, noise_generator=noise_generator)
+        self._kwargs = dict(recording=recording,
+                            list_periods=list_periods,
+                            mode=mode,
+                            noise_levels=noise_levels,
+                            seed=seed,
+                            random_chunk_kwargs=random_chunk_kwargs)
 
 
 class SilencedPeriodsRecordingSegment(BasePreprocessorSegment):

From 60d7ad53b59fac5b47bd976905d64efc62b3daeb Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Fri, 29 Nov 2024 06:10:02 +0100
Subject: [PATCH 258/344] Fix

---
 src/spikeinterface/preprocessing/silence_periods.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/spikeinterface/preprocessing/silence_periods.py b/src/spikeinterface/preprocessing/silence_periods.py
index a188f5d8db..5e410d51d5 100644
--- a/src/spikeinterface/preprocessing/silence_periods.py
+++ b/src/spikeinterface/preprocessing/silence_periods.py
@@ -100,7 +100,6 @@ def __init__(self, recording, list_periods, mode="zeros", noise_levels=None, see
         self._kwargs = dict(recording=recording,
                             list_periods=list_periods,
                             mode=mode,
-                            noise_levels=noise_levels,
                             seed=seed,
                             random_chunk_kwargs=random_chunk_kwargs)
 

From 01ae85cbb3ebcfd6f9e20eb191d92a278bbcb5e4 Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Fri, 29 Nov 2024 06:14:16 +0100
Subject: [PATCH 259/344] WIP

---
 src/spikeinterface/preprocessing/silence_periods.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/preprocessing/silence_periods.py b/src/spikeinterface/preprocessing/silence_periods.py
index 5e410d51d5..7c518d02a0 100644
--- a/src/spikeinterface/preprocessing/silence_periods.py
+++ b/src/spikeinterface/preprocessing/silence_periods.py
@@ -100,8 +100,8 @@ def __init__(self, recording, list_periods, mode="zeros", noise_levels=None, see
         self._kwargs = dict(recording=recording,
                             list_periods=list_periods,
                             mode=mode,
-                            seed=seed,
-                            random_chunk_kwargs=random_chunk_kwargs)
+                            seed=seed)
+        self._kwargs.update(random_chunk_kwargs)
 
 
 class SilencedPeriodsRecordingSegment(BasePreprocessorSegment):

From db2b4d5130a095500637c06f9d74aa2f03d41b73 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Fri, 29 Nov 2024 05:15:54 +0000
Subject: [PATCH 260/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/preprocessing/silence_periods.py | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/src/spikeinterface/preprocessing/silence_periods.py b/src/spikeinterface/preprocessing/silence_periods.py
index 7c518d02a0..00d9a1a407 100644
--- a/src/spikeinterface/preprocessing/silence_periods.py
+++ b/src/spikeinterface/preprocessing/silence_periods.py
@@ -97,10 +97,7 @@ def __init__(self, recording, list_periods, mode="zeros", noise_levels=None, see
             rec_segment = SilencedPeriodsRecordingSegment(parent_segment, periods, mode, noise_generator, seg_index)
             self.add_recording_segment(rec_segment)
 
-        self._kwargs = dict(recording=recording,
-                            list_periods=list_periods,
-                            mode=mode,
-                            seed=seed)
+        self._kwargs = dict(recording=recording, list_periods=list_periods, mode=mode, seed=seed)
         self._kwargs.update(random_chunk_kwargs)
 
 

From 5af4f858268c18421c8d1e7a3cbaca3c9957491e Mon Sep 17 00:00:00 2001
From: chrishalcrow <57948917+chrishalcrow@users.noreply.github.com>
Date: Mon, 2 Dec 2024 09:19:15 +0000
Subject: [PATCH 261/344] Hard code synchony_size for users, but leave flexible
 code underneathe

---
 doc/get_started/quickstart.rst                |  2 +-
 doc/modules/qualitymetrics/synchrony.rst      |  4 +-
 .../qualitymetrics/misc_metrics.py            | 27 ++++++-------
 .../tests/test_metrics_functions.py           | 39 ++++++++-----------
 4 files changed, 30 insertions(+), 42 deletions(-)

diff --git a/doc/get_started/quickstart.rst b/doc/get_started/quickstart.rst
index 3d45606a78..1349802ce5 100644
--- a/doc/get_started/quickstart.rst
+++ b/doc/get_started/quickstart.rst
@@ -673,7 +673,7 @@ compute quality metrics (some quality metrics require certain extensions
                               'min_spikes': 0,
                               'window_size_s': 1},
      'snr': {'peak_mode': 'extremum', 'peak_sign': 'neg'},
-     'synchrony': {'synchrony_sizes': (2, 4, 8)}}
+     'synchrony': {}
 
 
 Since the recording is very short, let’s change some parameters to
diff --git a/doc/modules/qualitymetrics/synchrony.rst b/doc/modules/qualitymetrics/synchrony.rst
index d244fd0c0f..696dacbd3c 100644
--- a/doc/modules/qualitymetrics/synchrony.rst
+++ b/doc/modules/qualitymetrics/synchrony.rst
@@ -12,7 +12,7 @@ trains. This way synchronous events can be found both in multi-unit and single-u
 Complexity is calculated by counting the number of spikes (i.e. non-empty bins) that occur at the same sample index,
 within and across spike trains.
 
-Synchrony metrics can be computed for different synchrony sizes (>1), defining the number of simultaneous spikes to count.
+Synchrony metrics are computed for 2, 4 and 8 synchronous spikes.
 
 
 
@@ -29,7 +29,7 @@ Example code
 
     import spikeinterface.qualitymetrics as sqm
     # Combine a sorting and recording into a sorting_analyzer
-    synchrony = sqm.compute_synchrony_metrics(sorting_analyzer=sorting_analyzer synchrony_sizes=(2, 4, 8))
+    synchrony = sqm.compute_synchrony_metrics(sorting_analyzer=sorting_analyzer)
     # synchrony is a tuple of dicts with the synchrony metrics for each unit
 
 
diff --git a/src/spikeinterface/qualitymetrics/misc_metrics.py b/src/spikeinterface/qualitymetrics/misc_metrics.py
index 8dfd41cf88..b0e0a0ad19 100644
--- a/src/spikeinterface/qualitymetrics/misc_metrics.py
+++ b/src/spikeinterface/qualitymetrics/misc_metrics.py
@@ -520,7 +520,7 @@ def compute_sliding_rp_violations(
 )
 
 
-def get_synchrony_counts(spikes, synchrony_sizes, all_unit_ids):
+def _get_synchrony_counts(spikes, all_unit_ids, synchrony_sizes=np.array([2, 4, 8])):
     """
     Compute synchrony counts, the number of simultaneous spikes with sizes `synchrony_sizes`.
 
@@ -528,10 +528,10 @@ def get_synchrony_counts(spikes, synchrony_sizes, all_unit_ids):
     ----------
     spikes : np.array
         Structured numpy array with fields ("sample_index", "unit_index", "segment_index").
-    synchrony_sizes : numpy array
-        The synchrony sizes to compute. Should be pre-sorted.
     all_unit_ids : list or None, default: None
         List of unit ids to compute the synchrony metrics. Expecting all units.
+    synchrony_sizes : numpy array
+        The synchrony sizes to compute. Should be pre-sorted.
 
     Returns
     -------
@@ -565,17 +565,15 @@ def get_synchrony_counts(spikes, synchrony_sizes, all_unit_ids):
     return synchrony_counts
 
 
-def compute_synchrony_metrics(sorting_analyzer, synchrony_sizes=(2, 4, 8), unit_ids=None):
+def compute_synchrony_metrics(sorting_analyzer, unit_ids=None):
     """
     Compute synchrony metrics. Synchrony metrics represent the rate of occurrences of
-    "synchrony_size" spikes at the exact same sample index.
+    spikes at the exact same sample index, with synchrony sizes 2, 4 and 8.
 
     Parameters
     ----------
     sorting_analyzer : SortingAnalyzer
         A SortingAnalyzer object.
-    synchrony_sizes : list or tuple, default: (2, 4, 8)
-        The synchrony sizes to compute.
     unit_ids : list or None, default: None
         List of unit ids to compute the synchrony metrics. If None, all units are used.
 
@@ -583,19 +581,16 @@ def compute_synchrony_metrics(sorting_analyzer, synchrony_sizes=(2, 4, 8), unit_
     -------
     sync_spike_{X} : dict
         The synchrony metric for synchrony size X.
-        Returns are as many as synchrony_sizes.
 
     References
     ----------
     Based on concepts described in [Grün]_
     This code was adapted from `Elephant - Electrophysiology Analysis Toolkit <https://github.com/NeuralEnsemble/elephant/blob/master/elephant/spike_train_synchrony.py#L245>`_
     """
-    assert min(synchrony_sizes) > 1, "Synchrony sizes must be greater than 1"
-    # Sort the synchrony times so we can slice numpy arrays, instead of using dicts
-    synchrony_sizes_np = np.array(synchrony_sizes, dtype=np.int16)
-    synchrony_sizes_np.sort()
 
-    res = namedtuple("synchrony_metrics", [f"sync_spike_{size}" for size in synchrony_sizes_np])
+    synchrony_sizes = np.array([2, 4, 8])
+
+    res = namedtuple("synchrony_metrics", [f"sync_spike_{size}" for size in synchrony_sizes])
 
     sorting = sorting_analyzer.sorting
 
@@ -606,10 +601,10 @@ def compute_synchrony_metrics(sorting_analyzer, synchrony_sizes=(2, 4, 8), unit_
 
     spikes = sorting.to_spike_vector()
     all_unit_ids = sorting.unit_ids
-    synchrony_counts = get_synchrony_counts(spikes, synchrony_sizes_np, all_unit_ids)
+    synchrony_counts = _get_synchrony_counts(spikes, all_unit_ids, synchrony_sizes=synchrony_sizes)
 
     synchrony_metrics_dict = {}
-    for sync_idx, synchrony_size in enumerate(synchrony_sizes_np):
+    for sync_idx, synchrony_size in enumerate(synchrony_sizes):
         sync_id_metrics_dict = {}
         for i, unit_id in enumerate(all_unit_ids):
             if unit_id not in unit_ids:
@@ -623,7 +618,7 @@ def compute_synchrony_metrics(sorting_analyzer, synchrony_sizes=(2, 4, 8), unit_
     return res(**synchrony_metrics_dict)
 
 
-_default_params["synchrony"] = dict(synchrony_sizes=(2, 4, 8))
+_default_params["synchrony"] = dict()
 
 
 def compute_firing_ranges(sorting_analyzer, bin_size_s=5, percentiles=(5, 95), unit_ids=None):
diff --git a/src/spikeinterface/qualitymetrics/tests/test_metrics_functions.py b/src/spikeinterface/qualitymetrics/tests/test_metrics_functions.py
index 4c0890b62b..f51dc3e884 100644
--- a/src/spikeinterface/qualitymetrics/tests/test_metrics_functions.py
+++ b/src/spikeinterface/qualitymetrics/tests/test_metrics_functions.py
@@ -39,7 +39,7 @@
     compute_firing_ranges,
     compute_amplitude_cv_metrics,
     compute_sd_ratio,
-    get_synchrony_counts,
+    _get_synchrony_counts,
     compute_quality_metrics,
 )
 
@@ -352,7 +352,7 @@ def test_synchrony_counts_no_sync():
     one_spike["sample_index"] = spike_times
     one_spike["unit_index"] = spike_units
 
-    sync_count = get_synchrony_counts(one_spike, np.array((2)), [0])
+    sync_count = _get_synchrony_counts(one_spike, [0])
 
     assert np.all(sync_count[0] == np.array([0]))
 
@@ -372,7 +372,7 @@ def test_synchrony_counts_one_sync():
     two_spikes["sample_index"] = np.concatenate((spike_indices, added_spikes_indices))
     two_spikes["unit_index"] = np.concatenate((spike_labels, added_spikes_labels))
 
-    sync_count = get_synchrony_counts(two_spikes, np.array((2)), [0, 1])
+    sync_count = _get_synchrony_counts(two_spikes, [0, 1])
 
     assert np.all(sync_count[0] == np.array([1, 1]))
 
@@ -392,7 +392,7 @@ def test_synchrony_counts_one_quad_sync():
     four_spikes["sample_index"] = np.concatenate((spike_indices, added_spikes_indices))
     four_spikes["unit_index"] = np.concatenate((spike_labels, added_spikes_labels))
 
-    sync_count = get_synchrony_counts(four_spikes, np.array((2, 4)), [0, 1, 2, 3])
+    sync_count = _get_synchrony_counts(four_spikes, [0, 1, 2, 3])
 
     assert np.all(sync_count[0] == np.array([1, 1, 1, 1]))
     assert np.all(sync_count[1] == np.array([1, 1, 1, 1]))
@@ -409,7 +409,7 @@ def test_synchrony_counts_not_all_units():
     three_spikes["sample_index"] = np.concatenate((spike_indices, added_spikes_indices))
     three_spikes["unit_index"] = np.concatenate((spike_labels, added_spikes_labels))
 
-    sync_count = get_synchrony_counts(three_spikes, np.array((2)), [0, 1, 2])
+    sync_count = _get_synchrony_counts(three_spikes, [0, 1, 2])
 
     assert np.all(sync_count[0] == np.array([0, 1, 1]))
 
@@ -610,9 +610,9 @@ def test_calculate_rp_violations(sorting_analyzer_violations):
 def test_synchrony_metrics(sorting_analyzer_simple):
     sorting_analyzer = sorting_analyzer_simple
     sorting = sorting_analyzer.sorting
-    synchrony_sizes = (2, 3, 4)
-    synchrony_metrics = compute_synchrony_metrics(sorting_analyzer, synchrony_sizes=synchrony_sizes)
-    print(synchrony_metrics)
+    synchrony_metrics = compute_synchrony_metrics(sorting_analyzer)
+
+    synchrony_sizes = np.array([2, 4, 8])
 
     # check returns
     for size in synchrony_sizes:
@@ -625,10 +625,8 @@ def test_synchrony_metrics(sorting_analyzer_simple):
         sorting_sync = add_synchrony_to_sorting(sorting, sync_event_ratio=sync_level)
         sorting_analyzer_sync = create_sorting_analyzer(sorting_sync, sorting_analyzer.recording, format="memory")
 
-        previous_synchrony_metrics = compute_synchrony_metrics(
-            previous_sorting_analyzer, synchrony_sizes=synchrony_sizes
-        )
-        current_synchrony_metrics = compute_synchrony_metrics(sorting_analyzer_sync, synchrony_sizes=synchrony_sizes)
+        previous_synchrony_metrics = compute_synchrony_metrics(previous_sorting_analyzer)
+        current_synchrony_metrics = compute_synchrony_metrics(sorting_analyzer_sync)
         print(current_synchrony_metrics)
         # check that all values increased
         for i, col in enumerate(previous_synchrony_metrics._fields):
@@ -647,22 +645,17 @@ def test_synchrony_metrics_unit_id_subset(sorting_analyzer_simple):
 
     unit_ids_subset = [3, 7]
 
-    synchrony_sizes = (2,)
-    (synchrony_metrics,) = compute_synchrony_metrics(
-        sorting_analyzer_simple, synchrony_sizes=synchrony_sizes, unit_ids=unit_ids_subset
-    )
+    synchrony_metrics = compute_synchrony_metrics(sorting_analyzer_simple, unit_ids=unit_ids_subset)
 
-    assert list(synchrony_metrics.keys()) == [3, 7]
+    assert list(synchrony_metrics.sync_spike_2.keys()) == [3, 7]
+    assert list(synchrony_metrics.sync_spike_4.keys()) == [3, 7]
+    assert list(synchrony_metrics.sync_spike_8.keys()) == [3, 7]
 
 
 def test_synchrony_metrics_no_unit_ids(sorting_analyzer_simple):
 
-    # all_unit_ids = sorting_analyzer_simple.sorting.unit_ids
-
-    synchrony_sizes = (2,)
-    (synchrony_metrics,) = compute_synchrony_metrics(sorting_analyzer_simple, synchrony_sizes=synchrony_sizes)
-
-    assert np.all(list(synchrony_metrics.keys()) == sorting_analyzer_simple.unit_ids)
+    synchrony_metrics = compute_synchrony_metrics(sorting_analyzer_simple)
+    assert np.all(list(synchrony_metrics.sync_spike_2.keys()) == sorting_analyzer_simple.unit_ids)
 
 
 @pytest.mark.sortingcomponents

From 45eb5b74e58061ee04dcb2a4bba10dbcf2a2c892 Mon Sep 17 00:00:00 2001
From: chrishalcrow <57948917+chrishalcrow@users.noreply.github.com>
Date: Mon, 2 Dec 2024 09:31:23 +0000
Subject: [PATCH 262/344] Add warning and ability to pass synchrony_sizes

---
 src/spikeinterface/qualitymetrics/__init__.py     | 2 +-
 src/spikeinterface/qualitymetrics/misc_metrics.py | 6 +++++-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/qualitymetrics/__init__.py b/src/spikeinterface/qualitymetrics/__init__.py
index 9d604f6ae2..754c82d8e3 100644
--- a/src/spikeinterface/qualitymetrics/__init__.py
+++ b/src/spikeinterface/qualitymetrics/__init__.py
@@ -6,4 +6,4 @@
     get_default_qm_params,
 )
 from .pca_metrics import get_quality_pca_metric_list
-from .misc_metrics import get_synchrony_counts
+from .misc_metrics import _get_synchrony_counts
diff --git a/src/spikeinterface/qualitymetrics/misc_metrics.py b/src/spikeinterface/qualitymetrics/misc_metrics.py
index b0e0a0ad19..2f178c46f3 100644
--- a/src/spikeinterface/qualitymetrics/misc_metrics.py
+++ b/src/spikeinterface/qualitymetrics/misc_metrics.py
@@ -565,7 +565,7 @@ def _get_synchrony_counts(spikes, all_unit_ids, synchrony_sizes=np.array([2, 4,
     return synchrony_counts
 
 
-def compute_synchrony_metrics(sorting_analyzer, unit_ids=None):
+def compute_synchrony_metrics(sorting_analyzer, unit_ids=None, synchrony_sizes=None):
     """
     Compute synchrony metrics. Synchrony metrics represent the rate of occurrences of
     spikes at the exact same sample index, with synchrony sizes 2, 4 and 8.
@@ -588,6 +588,10 @@ def compute_synchrony_metrics(sorting_analyzer, unit_ids=None):
     This code was adapted from `Elephant - Electrophysiology Analysis Toolkit <https://github.com/NeuralEnsemble/elephant/blob/master/elephant/spike_train_synchrony.py#L245>`_
     """
 
+    if synchrony_sizes is not None:
+        warning_message = "Custom `synchrony_sizes` is deprecated; the `synchrony_metrics` will be computed using `synchrony_sizes = [2,4,8]`"
+        warnings.warn(warning_message)
+
     synchrony_sizes = np.array([2, 4, 8])
 
     res = namedtuple("synchrony_metrics", [f"sync_spike_{size}" for size in synchrony_sizes])

From 039b408a59ce965b91908de82d0bc55114f8655e Mon Sep 17 00:00:00 2001
From: chrishalcrow <57948917+chrishalcrow@users.noreply.github.com>
Date: Mon, 2 Dec 2024 13:43:39 +0000
Subject: [PATCH 263/344] move backwards compat to
 `_handle_backward_compatibility_on_load`

---
 .../postprocessing/template_metrics.py        | 25 ++++++++++---------
 .../quality_metric_calculator.py              | 14 +++++------
 2 files changed, 20 insertions(+), 19 deletions(-)

diff --git a/src/spikeinterface/postprocessing/template_metrics.py b/src/spikeinterface/postprocessing/template_metrics.py
index 477ad04440..7de6e8766a 100644
--- a/src/spikeinterface/postprocessing/template_metrics.py
+++ b/src/spikeinterface/postprocessing/template_metrics.py
@@ -88,9 +88,22 @@ class ComputeTemplateMetrics(AnalyzerExtension):
     need_recording = False
     use_nodepipeline = False
     need_job_kwargs = False
+    need_backward_compatibility_on_load = True
 
     min_channels_for_multi_channel_warning = 10
 
+    def _handle_backward_compatibility_on_load(self):
+
+        # For backwards compatibility - this reformats metrics_kwargs as metric_params
+        if (metrics_kwargs := self.params.get("metrics_kwargs")) is not None:
+
+            metric_params = {}
+            for metric_name in self.params["metric_names"]:
+                metric_params[metric_name] = deepcopy(metrics_kwargs)
+            self.params["metric_params"] = metric_params
+
+            del self.params["metrics_kwargs"]
+
     def _set_params(
         self,
         metric_names=None,
@@ -344,18 +357,6 @@ def _run(self, verbose=False):
     def _get_data(self):
         return self.data["metrics"]
 
-    def load_params(self):
-        AnalyzerExtension.load_params(self)
-        # For backwards compatibility - this reformats metrics_kwargs as metric_params
-        if (metrics_kwargs := self.params.get("metrics_kwargs")) is not None:
-
-            metric_params = {}
-            for metric_name in self.params["metric_names"]:
-                metric_params[metric_name] = deepcopy(metrics_kwargs)
-            self.params["metric_params"] = metric_params
-
-            del self.params["metrics_kwargs"]
-
 
 register_result_extension(ComputeTemplateMetrics)
 compute_template_metrics = ComputeTemplateMetrics.function_factory()
diff --git a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
index e7e7c244ea..d71450853f 100644
--- a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
+++ b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
@@ -55,6 +55,13 @@ class ComputeQualityMetrics(AnalyzerExtension):
     need_recording = False
     use_nodepipeline = False
     need_job_kwargs = True
+    need_backward_compatibility_on_load = True
+
+    def _handle_backward_compatibility_on_load(self):
+        # For backwards compatibility - this renames qm_params as metric_params
+        if (qm_params := self.params.get("qm_params")) is not None:
+            self.params["metric_params"] = qm_params
+            del self.params["qm_params"]
 
     def _set_params(
         self,
@@ -262,13 +269,6 @@ def _run(self, verbose=False, **job_kwargs):
     def _get_data(self):
         return self.data["metrics"]
 
-    def load_params(self):
-        AnalyzerExtension.load_params(self)
-        # For backwards compatibility - this renames qm_params as metric_params
-        if (qm_params := self.params.get("qm_params")) is not None:
-            self.params["metric_params"] = qm_params
-            del self.params["qm_params"]
-
 
 register_result_extension(ComputeQualityMetrics)
 compute_quality_metrics = ComputeQualityMetrics.function_factory()

From 771de98c6ddd07e064cb28d6e2450e599d54d2a6 Mon Sep 17 00:00:00 2001
From: chrishalcrow <57948917+chrishalcrow@users.noreply.github.com>
Date: Tue, 3 Dec 2024 09:51:28 +0000
Subject: [PATCH 264/344] Respond to z-man

---
 src/spikeinterface/postprocessing/template_metrics.py | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/src/spikeinterface/postprocessing/template_metrics.py b/src/spikeinterface/postprocessing/template_metrics.py
index 7de6e8766a..da917e673c 100644
--- a/src/spikeinterface/postprocessing/template_metrics.py
+++ b/src/spikeinterface/postprocessing/template_metrics.py
@@ -64,8 +64,7 @@ class ComputeTemplateMetrics(AnalyzerExtension):
         Whether to compute multi-channel metrics
     delete_existing_metrics : bool, default: False
         If True, any template metrics attached to the `sorting_analyzer` are deleted. If False, any metrics which were previously calculated but are not included in `metric_names` are kept, provided the `metric_params` are unchanged.
-    metric_params : dict of dicts
-        metric_params : dict of dicts or None
+    metric_params : dict of dicts or None, default: None
         Dictionary with parameters for template metrics calculation.
         Default parameters can be obtained with: `si.postprocessing.template_metrics.get_default_tm_params()`
 
@@ -138,7 +137,7 @@ def _set_params(
 
         if metrics_kwargs is not None and metric_params is None:
             deprecation_msg = "`metrics_kwargs` is deprecated and will be removed in version 0.104.0. Please use metric_params instead"
-            warnings.warn(deprecation_msg, category=DeprecationWarning)
+            deprecation_msg = "`metrics_kwargs` is deprecated and will be removed in version 0.104.0. Please use `metric_params` instead"
 
             metric_params = {}
             for metric_name in metric_names:

From de7210a43135c1164ee2f214e117543441935375 Mon Sep 17 00:00:00 2001
From: chrishalcrow <57948917+chrishalcrow@users.noreply.github.com>
Date: Tue, 3 Dec 2024 09:52:16 +0000
Subject: [PATCH 265/344] oups

---
 src/spikeinterface/postprocessing/template_metrics.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/postprocessing/template_metrics.py b/src/spikeinterface/postprocessing/template_metrics.py
index da917e673c..1969480503 100644
--- a/src/spikeinterface/postprocessing/template_metrics.py
+++ b/src/spikeinterface/postprocessing/template_metrics.py
@@ -136,7 +136,7 @@ def _set_params(
             metric_names += get_multi_channel_template_metric_names()
 
         if metrics_kwargs is not None and metric_params is None:
-            deprecation_msg = "`metrics_kwargs` is deprecated and will be removed in version 0.104.0. Please use metric_params instead"
+            deprecation_msg = "`metrics_kwargs` is deprecated and will be removed in version 0.104.0. Please use `metric_params` instead"
             deprecation_msg = "`metrics_kwargs` is deprecated and will be removed in version 0.104.0. Please use `metric_params` instead"
 
             metric_params = {}

From 2081916e33d467145223a7c3099aca556f6e3864 Mon Sep 17 00:00:00 2001
From: chrishalcrow <57948917+chrishalcrow@users.noreply.github.com>
Date: Tue, 3 Dec 2024 14:18:15 +0000
Subject: [PATCH 266/344] respond to review

---
 src/spikeinterface/qualitymetrics/misc_metrics.py      | 10 ++++++----
 .../qualitymetrics/tests/test_metrics_functions.py     |  8 ++++----
 2 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/src/spikeinterface/qualitymetrics/misc_metrics.py b/src/spikeinterface/qualitymetrics/misc_metrics.py
index 2f178c46f3..6007de379c 100644
--- a/src/spikeinterface/qualitymetrics/misc_metrics.py
+++ b/src/spikeinterface/qualitymetrics/misc_metrics.py
@@ -520,7 +520,7 @@ def compute_sliding_rp_violations(
 )
 
 
-def _get_synchrony_counts(spikes, all_unit_ids, synchrony_sizes=np.array([2, 4, 8])):
+def _get_synchrony_counts(spikes, synchrony_sizes, all_unit_ids):
     """
     Compute synchrony counts, the number of simultaneous spikes with sizes `synchrony_sizes`.
 
@@ -530,7 +530,7 @@ def _get_synchrony_counts(spikes, all_unit_ids, synchrony_sizes=np.array([2, 4,
         Structured numpy array with fields ("sample_index", "unit_index", "segment_index").
     all_unit_ids : list or None, default: None
         List of unit ids to compute the synchrony metrics. Expecting all units.
-    synchrony_sizes : numpy array
+    synchrony_sizes : None or np.array, default: None
         The synchrony sizes to compute. Should be pre-sorted.
 
     Returns
@@ -576,6 +576,8 @@ def compute_synchrony_metrics(sorting_analyzer, unit_ids=None, synchrony_sizes=N
         A SortingAnalyzer object.
     unit_ids : list or None, default: None
         List of unit ids to compute the synchrony metrics. If None, all units are used.
+    synchrony_sizes: None, default: None
+        Deprecated argument. Please use private `_get_synchrony_counts` if you need finer control over number of synchronous spikes.
 
     Returns
     -------
@@ -590,7 +592,7 @@ def compute_synchrony_metrics(sorting_analyzer, unit_ids=None, synchrony_sizes=N
 
     if synchrony_sizes is not None:
         warning_message = "Custom `synchrony_sizes` is deprecated; the `synchrony_metrics` will be computed using `synchrony_sizes = [2,4,8]`"
-        warnings.warn(warning_message)
+        warnings.warn(warning_message, DeprecationWarning, stacklevel=2)
 
     synchrony_sizes = np.array([2, 4, 8])
 
@@ -605,7 +607,7 @@ def compute_synchrony_metrics(sorting_analyzer, unit_ids=None, synchrony_sizes=N
 
     spikes = sorting.to_spike_vector()
     all_unit_ids = sorting.unit_ids
-    synchrony_counts = _get_synchrony_counts(spikes, all_unit_ids, synchrony_sizes=synchrony_sizes)
+    synchrony_counts = _get_synchrony_counts(spikes, synchrony_sizes, all_unit_ids)
 
     synchrony_metrics_dict = {}
     for sync_idx, synchrony_size in enumerate(synchrony_sizes):
diff --git a/src/spikeinterface/qualitymetrics/tests/test_metrics_functions.py b/src/spikeinterface/qualitymetrics/tests/test_metrics_functions.py
index f51dc3e884..ae4c7ab62d 100644
--- a/src/spikeinterface/qualitymetrics/tests/test_metrics_functions.py
+++ b/src/spikeinterface/qualitymetrics/tests/test_metrics_functions.py
@@ -352,7 +352,7 @@ def test_synchrony_counts_no_sync():
     one_spike["sample_index"] = spike_times
     one_spike["unit_index"] = spike_units
 
-    sync_count = _get_synchrony_counts(one_spike, [0])
+    sync_count = _get_synchrony_counts(one_spike, np.array([2, 4, 8]), [0])
 
     assert np.all(sync_count[0] == np.array([0]))
 
@@ -372,7 +372,7 @@ def test_synchrony_counts_one_sync():
     two_spikes["sample_index"] = np.concatenate((spike_indices, added_spikes_indices))
     two_spikes["unit_index"] = np.concatenate((spike_labels, added_spikes_labels))
 
-    sync_count = _get_synchrony_counts(two_spikes, [0, 1])
+    sync_count = _get_synchrony_counts(two_spikes, np.array([2, 4, 8]), [0, 1])
 
     assert np.all(sync_count[0] == np.array([1, 1]))
 
@@ -392,7 +392,7 @@ def test_synchrony_counts_one_quad_sync():
     four_spikes["sample_index"] = np.concatenate((spike_indices, added_spikes_indices))
     four_spikes["unit_index"] = np.concatenate((spike_labels, added_spikes_labels))
 
-    sync_count = _get_synchrony_counts(four_spikes, [0, 1, 2, 3])
+    sync_count = _get_synchrony_counts(four_spikes, np.array([2, 4, 8]), [0, 1, 2, 3])
 
     assert np.all(sync_count[0] == np.array([1, 1, 1, 1]))
     assert np.all(sync_count[1] == np.array([1, 1, 1, 1]))
@@ -409,7 +409,7 @@ def test_synchrony_counts_not_all_units():
     three_spikes["sample_index"] = np.concatenate((spike_indices, added_spikes_indices))
     three_spikes["unit_index"] = np.concatenate((spike_labels, added_spikes_labels))
 
-    sync_count = _get_synchrony_counts(three_spikes, [0, 1, 2])
+    sync_count = _get_synchrony_counts(three_spikes, np.array([2, 4, 8]), [0, 1, 2])
 
     assert np.all(sync_count[0] == np.array([0, 1, 1]))
 

From 09ff624817b53d30d35f1e4f9060edabab45a308 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Wed, 4 Dec 2024 10:33:40 +0100
Subject: [PATCH 267/344] Remove venv in full-tests-with-codecov

---
 .../actions/build-test-environment/action.yml | 36 +++++++------------
 .github/workflows/all-tests.yml               |  2 +-
 2 files changed, 14 insertions(+), 24 deletions(-)

diff --git a/.github/actions/build-test-environment/action.yml b/.github/actions/build-test-environment/action.yml
index 723e8a702f..a212bd64d5 100644
--- a/.github/actions/build-test-environment/action.yml
+++ b/.github/actions/build-test-environment/action.yml
@@ -1,41 +1,20 @@
 name: Install packages
 description: This action installs the package and its dependencies for testing
 
-inputs:
-  python-version:
-    description: 'Python version to set up'
-    required: false
-  os:
-    description: 'Operating system to set up'
-    required: false
-
 runs:
   using: "composite"
   steps:
     - name: Install dependencies
       run: |
-        sudo apt install git
         git config --global user.email "CI@example.com"
         git config --global user.name "CI Almighty"
-        python -m venv ${{ github.workspace }}/test_env # Environment used in the caching step
-        python -m pip install -U pip  # Official recommended way
-        source ${{ github.workspace }}/test_env/bin/activate
         pip install tabulate  # This produces summaries at the end
         pip install -e .[test,extractors,streaming_extractors,test_extractors,full]
       shell: bash
-    - name: Force installation of latest dev from key-packages when running dev (not release)
-      run: |
-        source ${{ github.workspace }}/test_env/bin/activate
-        spikeinterface_is_dev_version=$(python -c "import spikeinterface; print(spikeinterface.DEV_MODE)")
-        if [ $spikeinterface_is_dev_version = "True" ]; then
-          echo "Running spikeinterface dev version"
-          pip install --no-cache-dir git+https://github.com/NeuralEnsemble/python-neo
-          pip install --no-cache-dir git+https://github.com/SpikeInterface/probeinterface
-        fi
-          echo "Running tests for release, using pyproject.toml versions of neo and probeinterface"
+    - name: Install git-annex
       shell: bash
-    - name: git-annex install
       run: |
+        pip install datalad-installer
         wget https://downloads.kitenet.net/git-annex/linux/current/git-annex-standalone-amd64.tar.gz
         mkdir /home/runner/work/installation
         mv git-annex-standalone-amd64.tar.gz /home/runner/work/installation/
@@ -44,4 +23,15 @@ runs:
         tar xvzf git-annex-standalone-amd64.tar.gz
         echo "$(pwd)/git-annex.linux" >> $GITHUB_PATH
         cd $workdir
+        git config --global filter.annex.process "git-annex filter-process"  # recommended for efficiency
+    - name: Force installation of latest dev from key-packages when running dev (not release)
+      run: |
+        source ${{ github.workspace }}/test_env/bin/activate
+        spikeinterface_is_dev_version=$(python -c "import spikeinterface; print(spikeinterface.DEV_MODE)")
+        if [ $spikeinterface_is_dev_version = "True" ]; then
+          echo "Running spikeinterface dev version"
+          pip install --no-cache-dir git+https://github.com/NeuralEnsemble/python-neo
+          pip install --no-cache-dir git+https://github.com/SpikeInterface/probeinterface
+        fi
+          echo "Running tests for release, using pyproject.toml versions of neo and probeinterface"
       shell: bash
diff --git a/.github/workflows/all-tests.yml b/.github/workflows/all-tests.yml
index dcaec8b272..a9c840d5d5 100644
--- a/.github/workflows/all-tests.yml
+++ b/.github/workflows/all-tests.yml
@@ -47,7 +47,7 @@ jobs:
             echo "$file was changed"
           done
 
-      - name: Set testing environment  # This decides which tests are run and whether to install especial dependencies
+      - name: Set testing environment  # This decides which tests are run and whether to install special dependencies
         shell: bash
         run: |
           changed_files="${{ steps.changed-files.outputs.all_changed_files }}"

From 8500b9d0f4488794dcc6d6b71afec2ebf4697b1d Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Wed, 4 Dec 2024 10:48:11 +0100
Subject: [PATCH 268/344] Oups

---
 .github/actions/build-test-environment/action.yml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/.github/actions/build-test-environment/action.yml b/.github/actions/build-test-environment/action.yml
index a212bd64d5..c2524d2c16 100644
--- a/.github/actions/build-test-environment/action.yml
+++ b/.github/actions/build-test-environment/action.yml
@@ -26,7 +26,6 @@ runs:
         git config --global filter.annex.process "git-annex filter-process"  # recommended for efficiency
     - name: Force installation of latest dev from key-packages when running dev (not release)
       run: |
-        source ${{ github.workspace }}/test_env/bin/activate
         spikeinterface_is_dev_version=$(python -c "import spikeinterface; print(spikeinterface.DEV_MODE)")
         if [ $spikeinterface_is_dev_version = "True" ]; then
           echo "Running spikeinterface dev version"

From 922606b6d4d279da103b7e7edde3ecb79a76e3c8 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Wed, 4 Dec 2024 11:16:01 +0100
Subject: [PATCH 269/344] Oups 2

---
 .github/workflows/full-test-with-codecov.yml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/.github/workflows/full-test-with-codecov.yml b/.github/workflows/full-test-with-codecov.yml
index 407c614ebf..f8ed2aa7a9 100644
--- a/.github/workflows/full-test-with-codecov.yml
+++ b/.github/workflows/full-test-with-codecov.yml
@@ -45,7 +45,6 @@ jobs:
         env:
           HDF5_PLUGIN_PATH: ${{ github.workspace }}/hdf5_plugin_path_maxwell
         run: |
-          source ${{ github.workspace }}/test_env/bin/activate
           pytest -m "not sorters_external" --cov=./ --cov-report xml:./coverage.xml -vv -ra --durations=0 | tee report_full.txt; test ${PIPESTATUS[0]} -eq 0 || exit 1
           echo "# Timing profile of full tests" >> $GITHUB_STEP_SUMMARY
           python ./.github/scripts/build_job_summary.py report_full.txt >> $GITHUB_STEP_SUMMARY

From 986a74a30c94a49ed2a2dd6183e8ddc078105b85 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Thu, 5 Dec 2024 09:02:31 +0100
Subject: [PATCH 270/344] Pin ONE-API version

---
 pyproject.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pyproject.toml b/pyproject.toml
index fc09ad9198..22fbdc7f22 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -73,7 +73,7 @@ extractors = [
 ]
 
 streaming_extractors = [
-    "ONE-api>=2.7.0", # alf sorter and streaming IBL
+    "ONE-api>=2.7.0,<2.10.0", # alf sorter and streaming IBL
     "ibllib>=2.36.0", # streaming IBL
     # Following dependencies are for streaming with nwb files
     "pynwb>=2.6.0",

From 96da22f7ac509bfc83a2a90eed06d58e3f71f990 Mon Sep 17 00:00:00 2001
From: chrishalcrow <57948917+chrishalcrow@users.noreply.github.com>
Date: Thu, 5 Dec 2024 10:00:30 +0000
Subject: [PATCH 271/344] Correct method default in docstring

---
 src/spikeinterface/postprocessing/unit_locations.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/postprocessing/unit_locations.py b/src/spikeinterface/postprocessing/unit_locations.py
index 3f6dd47eec..bea06fd8f5 100644
--- a/src/spikeinterface/postprocessing/unit_locations.py
+++ b/src/spikeinterface/postprocessing/unit_locations.py
@@ -26,7 +26,7 @@ class ComputeUnitLocations(AnalyzerExtension):
     ----------
     sorting_analyzer : SortingAnalyzer
         A SortingAnalyzer object
-    method : "center_of_mass" | "monopolar_triangulation" | "grid_convolution", default: "center_of_mass"
+    method : "monopolar_triangulation" or  "center_of_mass" or "grid_convolution", default: "monopolar_triangulation"
         The method to use for localization
     **method_kwargs : dict, default: {}
         Kwargs which are passed to the method function. These can be found in the docstrings of `compute_center_of_mass`, `compute_grid_convolution` and `compute_monopolar_triangulation`.

From 10d459f3d45315cee3079e3b14428222487ef9c6 Mon Sep 17 00:00:00 2001
From: chrishalcrow <57948917+chrishalcrow@users.noreply.github.com>
Date: Thu, 5 Dec 2024 15:18:59 +0000
Subject: [PATCH 272/344] change or to | in docstring

---
 src/spikeinterface/postprocessing/unit_locations.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/postprocessing/unit_locations.py b/src/spikeinterface/postprocessing/unit_locations.py
index bea06fd8f5..df19458316 100644
--- a/src/spikeinterface/postprocessing/unit_locations.py
+++ b/src/spikeinterface/postprocessing/unit_locations.py
@@ -26,7 +26,7 @@ class ComputeUnitLocations(AnalyzerExtension):
     ----------
     sorting_analyzer : SortingAnalyzer
         A SortingAnalyzer object
-    method : "monopolar_triangulation" or  "center_of_mass" or "grid_convolution", default: "monopolar_triangulation"
+    method : "monopolar_triangulation" |  "center_of_mass" | "grid_convolution", default: "monopolar_triangulation"
         The method to use for localization
     **method_kwargs : dict, default: {}
         Kwargs which are passed to the method function. These can be found in the docstrings of `compute_center_of_mass`, `compute_grid_convolution` and `compute_monopolar_triangulation`.

From 4c7b6a5be65af4aa4ce6461e84956455f970942f Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Wed, 11 Dec 2024 09:53:59 +0100
Subject: [PATCH 273/344] Patch

---
 src/spikeinterface/widgets/unit_waveforms.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/widgets/unit_waveforms.py b/src/spikeinterface/widgets/unit_waveforms.py
index c593836061..3b31eacee5 100644
--- a/src/spikeinterface/widgets/unit_waveforms.py
+++ b/src/spikeinterface/widgets/unit_waveforms.py
@@ -565,7 +565,7 @@ def _update_plot(self, change):
             channel_locations = self.sorting_analyzer.get_channel_locations()
         else:
             unit_indices = [list(self.templates.unit_ids).index(unit_id) for unit_id in unit_ids]
-            templates = self.templates.templates_array[unit_indices]
+            templates = self.templates.get_dense_templates()[unit_indices]
             templates_shadings = None
             channel_locations = self.templates.get_channel_locations()
 

From 0bf2b08248b836c6323524c1f54cf3690cd6c5f8 Mon Sep 17 00:00:00 2001
From: Heberto Mayorquin <h.mayorquin@gmail.com>
Date: Tue, 17 Dec 2024 11:14:08 -0600
Subject: [PATCH 274/344] use strings as ids in generators

---
 src/spikeinterface/core/generate.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/spikeinterface/core/generate.py b/src/spikeinterface/core/generate.py
index 0316b3bab1..d03c08b480 100644
--- a/src/spikeinterface/core/generate.py
+++ b/src/spikeinterface/core/generate.py
@@ -134,7 +134,7 @@ def generate_sorting(
     seed = _ensure_seed(seed)
     rng = np.random.default_rng(seed)
     num_segments = len(durations)
-    unit_ids = np.arange(num_units)
+    unit_ids = [str(id) for id in np.arange(num_units)]
 
     spikes = []
     for segment_index in range(num_segments):
@@ -1111,7 +1111,7 @@ def __init__(
 
         """
 
-        unit_ids = np.arange(num_units)
+        unit_ids = [str(id) for id in np.arange(num_units)]
         super().__init__(sampling_frequency, unit_ids)
 
         self.num_units = num_units
@@ -1280,7 +1280,7 @@ def __init__(
         noise_block_size: int = 30000,
     ):
 
-        channel_ids = np.arange(num_channels)
+        channel_ids = [str(id) for id in np.arange(num_channels)]
         dtype = np.dtype(dtype).name  # Cast to string for serialization
         if dtype not in ("float32", "float64"):
             raise ValueError(f"'dtype' must be 'float32' or 'float64' but is {dtype}")

From 212a974ea7fa17eacb91f37495c764dc2eb8f828 Mon Sep 17 00:00:00 2001
From: Heberto Mayorquin <h.mayorquin@gmail.com>
Date: Tue, 17 Dec 2024 12:16:16 -0600
Subject: [PATCH 275/344] change to strings

---
 src/spikeinterface/core/basesorting.py        |  2 +-
 src/spikeinterface/core/generate.py           |  7 ++++--
 .../core/tests/test_basesnippets.py           | 10 ++++-----
 .../test_channelsaggregationrecording.py      |  6 +++--
 .../core/tests/test_sortinganalyzer.py        | 14 ++++++------
 .../core/tests/test_unitsselectionsorting.py  | 22 +++++++++++--------
 6 files changed, 35 insertions(+), 26 deletions(-)

diff --git a/src/spikeinterface/core/basesorting.py b/src/spikeinterface/core/basesorting.py
index 2af48407a3..9a0e242d62 100644
--- a/src/spikeinterface/core/basesorting.py
+++ b/src/spikeinterface/core/basesorting.py
@@ -135,7 +135,7 @@ def get_total_duration(self) -> float:
 
     def get_unit_spike_train(
         self,
-        unit_id,
+        unit_id: str | int,
         segment_index: Union[int, None] = None,
         start_frame: Union[int, None] = None,
         end_frame: Union[int, None] = None,
diff --git a/src/spikeinterface/core/generate.py b/src/spikeinterface/core/generate.py
index d03c08b480..5824a75ab8 100644
--- a/src/spikeinterface/core/generate.py
+++ b/src/spikeinterface/core/generate.py
@@ -2,7 +2,7 @@
 import math
 import warnings
 import numpy as np
-from typing import Literal
+from typing import Literal, Optional
 from math import ceil
 
 from .basesorting import SpikeVectorSortingSegment
@@ -1138,6 +1138,7 @@ def __init__(
                 firing_rates=firing_rates,
                 refractory_period_seconds=self.refractory_period_seconds,
                 seed=segment_seed,
+                unit_ids=unit_ids,
                 t_start=None,
             )
             self.add_sorting_segment(segment)
@@ -1161,6 +1162,7 @@ def __init__(
         firing_rates: float | np.ndarray,
         refractory_period_seconds: float | np.ndarray,
         seed: int,
+        unit_ids: list[str],
         t_start: Optional[float] = None,
     ):
         self.num_units = num_units
@@ -1177,7 +1179,8 @@ def __init__(
             self.refractory_period_seconds = np.full(num_units, self.refractory_period_seconds, dtype="float64")
 
         self.segment_seed = seed
-        self.units_seed = {unit_id: self.segment_seed + hash(unit_id) for unit_id in range(num_units)}
+        self.units_seed = {unit_id: abs(self.segment_seed + hash(unit_id)) for unit_id in unit_ids}
+
         self.num_samples = math.ceil(sampling_frequency * duration)
         super().__init__(t_start)
 
diff --git a/src/spikeinterface/core/tests/test_basesnippets.py b/src/spikeinterface/core/tests/test_basesnippets.py
index 64f7f76819..f243dd9d9f 100644
--- a/src/spikeinterface/core/tests/test_basesnippets.py
+++ b/src/spikeinterface/core/tests/test_basesnippets.py
@@ -41,8 +41,8 @@ def test_BaseSnippets(create_cache_folder):
     assert snippets.get_num_segments() == len(duration)
     assert snippets.get_num_channels() == num_channels
 
-    assert np.all(snippets.ids_to_indices([0, 1, 2]) == [0, 1, 2])
-    assert np.all(snippets.ids_to_indices([0, 1, 2], prefer_slice=True) == slice(0, 3, None))
+    assert np.all(snippets.ids_to_indices(["0", "1", "2"]) == [0, 1, 2])
+    assert np.all(snippets.ids_to_indices(["0", "1", "2"], prefer_slice=True) == slice(0, 3, None))
 
     # annotations / properties
     snippets.annotate(gre="ta")
@@ -60,7 +60,7 @@ def test_BaseSnippets(create_cache_folder):
     )
 
     # missing property
-    snippets.set_property("string_property", ["ciao", "bello"], ids=[0, 1])
+    snippets.set_property("string_property", ["ciao", "bello"], ids=["0", "1"])
     values = snippets.get_property("string_property")
     assert values[2] == ""
 
@@ -70,14 +70,14 @@ def test_BaseSnippets(create_cache_folder):
         snippets.set_property,
         key="string_property_nan",
         values=["hola", "chabon"],
-        ids=[0, 1],
+        ids=["0", "1"],
         missing_value=np.nan,
     )
 
     # int properties without missing values raise an error
     assert_raises(Exception, snippets.set_property, key="int_property", values=[5, 6], ids=[1, 2])
 
-    snippets.set_property("int_property", [5, 6], ids=[1, 2], missing_value=200)
+    snippets.set_property("int_property", [5, 6], ids=["1", "2"], missing_value=200)
     values = snippets.get_property("int_property")
     assert values.dtype.kind == "i"
 
diff --git a/src/spikeinterface/core/tests/test_channelsaggregationrecording.py b/src/spikeinterface/core/tests/test_channelsaggregationrecording.py
index 118b6092a9..99d6890dfd 100644
--- a/src/spikeinterface/core/tests/test_channelsaggregationrecording.py
+++ b/src/spikeinterface/core/tests/test_channelsaggregationrecording.py
@@ -38,10 +38,12 @@ def test_channelsaggregationrecording():
 
         assert np.allclose(traces1_1, recording_agg.get_traces(channel_ids=[str(channel_ids[1])], segment_index=seg))
         assert np.allclose(
-            traces2_0, recording_agg.get_traces(channel_ids=[str(num_channels + channel_ids[0])], segment_index=seg)
+            traces2_0,
+            recording_agg.get_traces(channel_ids=[str(num_channels + int(channel_ids[0]))], segment_index=seg),
         )
         assert np.allclose(
-            traces3_2, recording_agg.get_traces(channel_ids=[str(2 * num_channels + channel_ids[2])], segment_index=seg)
+            traces3_2,
+            recording_agg.get_traces(channel_ids=[str(2 * num_channels + int(channel_ids[2]))], segment_index=seg),
         )
         # all traces
         traces1 = recording1.get_traces(segment_index=seg)
diff --git a/src/spikeinterface/core/tests/test_sortinganalyzer.py b/src/spikeinterface/core/tests/test_sortinganalyzer.py
index 35ab18b5f2..899993d840 100644
--- a/src/spikeinterface/core/tests/test_sortinganalyzer.py
+++ b/src/spikeinterface/core/tests/test_sortinganalyzer.py
@@ -76,8 +76,8 @@ def test_SortingAnalyzer_binary_folder(tmp_path, dataset):
 
     # test select_units see https://github.com/SpikeInterface/spikeinterface/issues/3041
     # this bug requires that we have an info.json file so we calculate templates above
-    select_units_sorting_analyer = sorting_analyzer.select_units(unit_ids=[1])
-    assert len(select_units_sorting_analyer.unit_ids) == 1
+    select_units_sorting_analyer = sorting_analyzer.select_units(unit_ids=["1"])
+    assert len(select_units_sorting_analyer.unit_ids) == "1"
 
     folder = tmp_path / "test_SortingAnalyzer_binary_folder"
     if folder.exists():
@@ -121,11 +121,11 @@ def test_SortingAnalyzer_zarr(tmp_path, dataset):
 
     # test select_units see https://github.com/SpikeInterface/spikeinterface/issues/3041
     # this bug requires that we have an info.json file so we calculate templates above
-    select_units_sorting_analyer = sorting_analyzer.select_units(unit_ids=[1])
-    assert len(select_units_sorting_analyer.unit_ids) == 1
-    remove_units_sorting_analyer = sorting_analyzer.remove_units(remove_unit_ids=[1])
+    select_units_sorting_analyer = sorting_analyzer.select_units(unit_ids=["1"])
+    assert len(select_units_sorting_analyer.unit_ids) == "1"
+    remove_units_sorting_analyer = sorting_analyzer.remove_units(remove_unit_ids=["1"])
     assert len(remove_units_sorting_analyer.unit_ids) == len(sorting_analyzer.unit_ids) - 1
-    assert 1 not in remove_units_sorting_analyer.unit_ids
+    assert "1" not in remove_units_sorting_analyer.unit_ids
 
     # test no compression
     sorting_analyzer_no_compression = create_sorting_analyzer(
@@ -358,7 +358,7 @@ def _check_sorting_analyzers(sorting_analyzer, original_sorting, cache_folder):
                 shutil.rmtree(folder)
         else:
             folder = None
-        sorting_analyzer4 = sorting_analyzer.merge_units(merge_unit_groups=[[0, 1]], format=format, folder=folder)
+        sorting_analyzer4 = sorting_analyzer.merge_units(merge_unit_groups=[["0", "1"]], format=format, folder=folder)
 
         if format != "memory":
             if format == "zarr":
diff --git a/src/spikeinterface/core/tests/test_unitsselectionsorting.py b/src/spikeinterface/core/tests/test_unitsselectionsorting.py
index 1e72b0ab28..3ecb702aa2 100644
--- a/src/spikeinterface/core/tests/test_unitsselectionsorting.py
+++ b/src/spikeinterface/core/tests/test_unitsselectionsorting.py
@@ -10,25 +10,29 @@
 def test_basic_functions():
     sorting = generate_sorting(num_units=3, durations=[0.100, 0.100], sampling_frequency=30000.0)
 
-    sorting2 = UnitsSelectionSorting(sorting, unit_ids=[0, 2])
-    assert np.array_equal(sorting2.unit_ids, [0, 2])
+    sorting2 = UnitsSelectionSorting(sorting, unit_ids=["0", "2"])
+    assert np.array_equal(sorting2.unit_ids, ["0", "2"])
     assert sorting2.get_parent() == sorting
 
-    sorting3 = UnitsSelectionSorting(sorting, unit_ids=[0, 2], renamed_unit_ids=["a", "b"])
+    sorting3 = UnitsSelectionSorting(sorting, unit_ids=["0", "2"], renamed_unit_ids=["a", "b"])
     assert np.array_equal(sorting3.unit_ids, ["a", "b"])
 
     assert np.array_equal(
-        sorting.get_unit_spike_train(0, segment_index=0), sorting2.get_unit_spike_train(0, segment_index=0)
+        sorting.get_unit_spike_train(unit_id="0", segment_index=0),
+        sorting2.get_unit_spike_train(unit_id="0", segment_index=0),
     )
     assert np.array_equal(
-        sorting.get_unit_spike_train(0, segment_index=0), sorting3.get_unit_spike_train("a", segment_index=0)
+        sorting.get_unit_spike_train(unit_id="0", segment_index=0),
+        sorting3.get_unit_spike_train(unit_id="a", segment_index=0),
     )
 
     assert np.array_equal(
-        sorting.get_unit_spike_train(2, segment_index=0), sorting2.get_unit_spike_train(2, segment_index=0)
+        sorting.get_unit_spike_train(unit_id="2", segment_index=0),
+        sorting2.get_unit_spike_train(unit_id="2", segment_index=0),
     )
     assert np.array_equal(
-        sorting.get_unit_spike_train(2, segment_index=0), sorting3.get_unit_spike_train("b", segment_index=0)
+        sorting.get_unit_spike_train(unit_id="2", segment_index=0),
+        sorting3.get_unit_spike_train(unit_id="b", segment_index=0),
     )
 
 
@@ -36,13 +40,13 @@ def test_failure_with_non_unique_unit_ids():
     seed = 10
     sorting = generate_sorting(num_units=3, durations=[0.100], sampling_frequency=30000.0, seed=seed)
     with pytest.raises(AssertionError):
-        sorting2 = UnitsSelectionSorting(sorting, unit_ids=[0, 2], renamed_unit_ids=["a", "a"])
+        sorting2 = UnitsSelectionSorting(sorting, unit_ids=["0", "2"], renamed_unit_ids=["a", "a"])
 
 
 def test_custom_cache_spike_vector():
     sorting = generate_sorting(num_units=3, durations=[0.100, 0.100], sampling_frequency=30000.0)
 
-    sub_sorting = UnitsSelectionSorting(sorting, unit_ids=[2, 0], renamed_unit_ids=["b", "a"])
+    sub_sorting = UnitsSelectionSorting(sorting, unit_ids=["2", "0"], renamed_unit_ids=["b", "a"])
     cached_spike_vector = sub_sorting.to_spike_vector(use_cache=True)
     computed_spike_vector = sub_sorting.to_spike_vector(use_cache=False)
     assert np.all(cached_spike_vector == computed_spike_vector)

From c36e49e6c5057496cd59ab74f23c805732bf708c Mon Sep 17 00:00:00 2001
From: Heberto Mayorquin <h.mayorquin@gmail.com>
Date: Tue, 17 Dec 2024 12:24:41 -0600
Subject: [PATCH 276/344] keep sorting analyzer tests as they were

---
 src/spikeinterface/core/tests/test_sortinganalyzer.py | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/src/spikeinterface/core/tests/test_sortinganalyzer.py b/src/spikeinterface/core/tests/test_sortinganalyzer.py
index 899993d840..8d8beaa491 100644
--- a/src/spikeinterface/core/tests/test_sortinganalyzer.py
+++ b/src/spikeinterface/core/tests/test_sortinganalyzer.py
@@ -31,6 +31,14 @@ def get_dataset():
         noise_kwargs=dict(noise_levels=5.0, strategy="tile_pregenerated"),
         seed=2205,
     )
+
+    # TODO: the tests or the sorting analyzer make assumptions about the ids being integers
+    # So keeping this the way it was
+    integer_channel_ids = [int(id) for id in recording.get_channel_ids()]
+    integer_unit_ids = [int(id) for id in sorting.get_unit_ids()]
+
+    recording = recording.rename_channels(new_channel_ids=integer_channel_ids)
+    sorting = sorting.rename_units(new_unit_ids=integer_unit_ids)
     return recording, sorting
 
 
@@ -358,7 +366,7 @@ def _check_sorting_analyzers(sorting_analyzer, original_sorting, cache_folder):
                 shutil.rmtree(folder)
         else:
             folder = None
-        sorting_analyzer4 = sorting_analyzer.merge_units(merge_unit_groups=[["0", "1"]], format=format, folder=folder)
+        sorting_analyzer4 = sorting_analyzer.merge_units(merge_unit_groups=[[0, 1]], format=format, folder=folder)
 
         if format != "memory":
             if format == "zarr":

From 3dd6b359daa86252878e480dddbe9dc719e98c2b Mon Sep 17 00:00:00 2001
From: Heberto Mayorquin <h.mayorquin@gmail.com>
Date: Tue, 17 Dec 2024 12:27:04 -0600
Subject: [PATCH 277/344] fully restore sorting anlayzer

---
 .../core/tests/test_sortinganalyzer.py               | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/spikeinterface/core/tests/test_sortinganalyzer.py b/src/spikeinterface/core/tests/test_sortinganalyzer.py
index 8d8beaa491..15f089f784 100644
--- a/src/spikeinterface/core/tests/test_sortinganalyzer.py
+++ b/src/spikeinterface/core/tests/test_sortinganalyzer.py
@@ -84,8 +84,8 @@ def test_SortingAnalyzer_binary_folder(tmp_path, dataset):
 
     # test select_units see https://github.com/SpikeInterface/spikeinterface/issues/3041
     # this bug requires that we have an info.json file so we calculate templates above
-    select_units_sorting_analyer = sorting_analyzer.select_units(unit_ids=["1"])
-    assert len(select_units_sorting_analyer.unit_ids) == "1"
+    select_units_sorting_analyer = sorting_analyzer.select_units(unit_ids=[1])
+    assert len(select_units_sorting_analyer.unit_ids) == 1
 
     folder = tmp_path / "test_SortingAnalyzer_binary_folder"
     if folder.exists():
@@ -129,11 +129,11 @@ def test_SortingAnalyzer_zarr(tmp_path, dataset):
 
     # test select_units see https://github.com/SpikeInterface/spikeinterface/issues/3041
     # this bug requires that we have an info.json file so we calculate templates above
-    select_units_sorting_analyer = sorting_analyzer.select_units(unit_ids=["1"])
-    assert len(select_units_sorting_analyer.unit_ids) == "1"
-    remove_units_sorting_analyer = sorting_analyzer.remove_units(remove_unit_ids=["1"])
+    select_units_sorting_analyer = sorting_analyzer.select_units(unit_ids=[1])
+    assert len(select_units_sorting_analyer.unit_ids) == 1
+    remove_units_sorting_analyer = sorting_analyzer.remove_units(remove_unit_ids=[1])
     assert len(remove_units_sorting_analyer.unit_ids) == len(sorting_analyzer.unit_ids) - 1
-    assert "1" not in remove_units_sorting_analyer.unit_ids
+    assert 1 not in remove_units_sorting_analyer.unit_ids
 
     # test no compression
     sorting_analyzer_no_compression = create_sorting_analyzer(

From 61f40187cb372f64a2752136c6df461bbad89705 Mon Sep 17 00:00:00 2001
From: Heberto Mayorquin <h.mayorquin@gmail.com>
Date: Tue, 17 Dec 2024 12:41:22 -0600
Subject: [PATCH 278/344] fix mda extractor

---
 src/spikeinterface/extractors/tests/test_mdaextractors.py | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/src/spikeinterface/extractors/tests/test_mdaextractors.py b/src/spikeinterface/extractors/tests/test_mdaextractors.py
index 0ef6697c6c..78e6afb65e 100644
--- a/src/spikeinterface/extractors/tests/test_mdaextractors.py
+++ b/src/spikeinterface/extractors/tests/test_mdaextractors.py
@@ -9,6 +9,12 @@ def test_mda_extractors(create_cache_folder):
     cache_folder = create_cache_folder
     rec, sort = generate_ground_truth_recording(durations=[10.0], num_units=10)
 
+    ids_as_integers = [id for id in range(rec.get_num_channels())]
+    rec = rec.rename_channels(new_channel_ids=ids_as_integers)
+
+    ids_as_integers = [id for id in range(sort.get_num_units())]
+    sort = sort.rename_units(new_unit_ids=ids_as_integers)
+
     MdaRecordingExtractor.write_recording(rec, cache_folder / "mdatest")
     rec_mda = MdaRecordingExtractor(cache_folder / "mdatest")
     probe = rec_mda.get_probe()

From 0429152bfa7141b4c1428fc960833d9141da2168 Mon Sep 17 00:00:00 2001
From: Heberto Mayorquin <h.mayorquin@gmail.com>
Date: Tue, 17 Dec 2024 13:11:51 -0600
Subject: [PATCH 279/344] fix preprocessing

---
 src/spikeinterface/preprocessing/tests/test_clip.py       | 8 ++++----
 .../preprocessing/tests/test_interpolate_bad_channels.py  | 4 +++-
 .../preprocessing/tests/test_normalize_scale.py           | 2 +-
 src/spikeinterface/preprocessing/tests/test_rectify.py    | 2 +-
 4 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/src/spikeinterface/preprocessing/tests/test_clip.py b/src/spikeinterface/preprocessing/tests/test_clip.py
index 724ba2c963..c18c7d37af 100644
--- a/src/spikeinterface/preprocessing/tests/test_clip.py
+++ b/src/spikeinterface/preprocessing/tests/test_clip.py
@@ -14,12 +14,12 @@ def test_clip():
     rec1 = clip(rec, a_min=-1.5)
     rec1.save(verbose=False)
 
-    traces0 = rec0.get_traces(segment_index=0, channel_ids=[1])
+    traces0 = rec0.get_traces(segment_index=0, channel_ids=["1"])
     assert traces0.shape[1] == 1
 
     assert np.all(-2 <= traces0[0] <= 3)
 
-    traces1 = rec1.get_traces(segment_index=0, channel_ids=[0, 1])
+    traces1 = rec1.get_traces(segment_index=0, channel_ids=["0", "1"])
     assert traces1.shape[1] == 2
 
     assert np.all(-1.5 <= traces1[1])
@@ -34,11 +34,11 @@ def test_blank_staturation():
     rec1 = blank_staturation(rec, quantile_threshold=0.01, direction="both", chunk_size=10000)
     rec1.save(verbose=False)
 
-    traces0 = rec0.get_traces(segment_index=0, channel_ids=[1])
+    traces0 = rec0.get_traces(segment_index=0, channel_ids=["1"])
     assert traces0.shape[1] == 1
     assert np.all(traces0 < 3.0)
 
-    traces1 = rec1.get_traces(segment_index=0, channel_ids=[0])
+    traces1 = rec1.get_traces(segment_index=0, channel_ids=["0"])
     assert traces1.shape[1] == 1
     # use a smaller value to be sure
     a_min = rec1._recording_segments[0].a_min
diff --git a/src/spikeinterface/preprocessing/tests/test_interpolate_bad_channels.py b/src/spikeinterface/preprocessing/tests/test_interpolate_bad_channels.py
index 1189f04f7d..06bde4e3d1 100644
--- a/src/spikeinterface/preprocessing/tests/test_interpolate_bad_channels.py
+++ b/src/spikeinterface/preprocessing/tests/test_interpolate_bad_channels.py
@@ -163,7 +163,9 @@ def test_output_values():
     expected_weights = np.r_[np.tile(np.exp(-2), 3), np.exp(-4)]
     expected_weights /= np.sum(expected_weights)
 
-    si_interpolated_recording = spre.interpolate_bad_channels(recording, bad_channel_indexes, sigma_um=1, p=1)
+    si_interpolated_recording = spre.interpolate_bad_channels(
+        recording, bad_channel_ids=bad_channel_ids, sigma_um=1, p=1
+    )
     si_interpolated = si_interpolated_recording.get_traces()
 
     expected_ts = si_interpolated[:, 1:] @ expected_weights
diff --git a/src/spikeinterface/preprocessing/tests/test_normalize_scale.py b/src/spikeinterface/preprocessing/tests/test_normalize_scale.py
index 576b570832..151752e0e6 100644
--- a/src/spikeinterface/preprocessing/tests/test_normalize_scale.py
+++ b/src/spikeinterface/preprocessing/tests/test_normalize_scale.py
@@ -15,7 +15,7 @@ def test_normalize_by_quantile():
     rec2 = normalize_by_quantile(rec, mode="by_channel")
     rec2.save(verbose=False)
 
-    traces = rec2.get_traces(segment_index=0, channel_ids=[1])
+    traces = rec2.get_traces(segment_index=0, channel_ids=["1"])
     assert traces.shape[1] == 1
 
     rec2 = normalize_by_quantile(rec, mode="pool_channel")
diff --git a/src/spikeinterface/preprocessing/tests/test_rectify.py b/src/spikeinterface/preprocessing/tests/test_rectify.py
index b8bb31015e..a2a06e7a1f 100644
--- a/src/spikeinterface/preprocessing/tests/test_rectify.py
+++ b/src/spikeinterface/preprocessing/tests/test_rectify.py
@@ -15,7 +15,7 @@ def test_rectify():
     rec2 = rectify(rec)
     rec2.save(verbose=False)
 
-    traces = rec2.get_traces(segment_index=0, channel_ids=[1])
+    traces = rec2.get_traces(segment_index=0, channel_ids=["1"])
     assert traces.shape[1] == 1
 
     # import matplotlib.pyplot as plt

From 6d70a154426a2391e6712fb38b27dcf0fbd95a05 Mon Sep 17 00:00:00 2001
From: Heberto Mayorquin <h.mayorquin@gmail.com>
Date: Tue, 17 Dec 2024 13:18:20 -0600
Subject: [PATCH 280/344] fix quality metrics

---
 src/spikeinterface/qualitymetrics/tests/conftest.py | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/src/spikeinterface/qualitymetrics/tests/conftest.py b/src/spikeinterface/qualitymetrics/tests/conftest.py
index 01fa16c8d7..ac1789a375 100644
--- a/src/spikeinterface/qualitymetrics/tests/conftest.py
+++ b/src/spikeinterface/qualitymetrics/tests/conftest.py
@@ -16,6 +16,11 @@ def small_sorting_analyzer():
         seed=1205,
     )
 
+    channel_ids_as_integers = [id for id in range(recording.get_num_channels())]
+    unit_ids_as_integers = [id for id in range(sorting.get_num_units())]
+    recording = recording.rename_channels(new_channel_ids=channel_ids_as_integers)
+    sorting = sorting.rename_units(new_unit_ids=unit_ids_as_integers)
+
     sorting = sorting.select_units([2, 7, 0], ["#3", "#9", "#4"])
 
     sorting_analyzer = create_sorting_analyzer(recording=recording, sorting=sorting, format="memory")
@@ -60,6 +65,11 @@ def sorting_analyzer_simple():
         seed=1205,
     )
 
+    channel_ids_as_integers = [id for id in range(recording.get_num_channels())]
+    unit_ids_as_integers = [id for id in range(sorting.get_num_units())]
+    recording = recording.rename_channels(new_channel_ids=channel_ids_as_integers)
+    sorting = sorting.rename_units(new_unit_ids=unit_ids_as_integers)
+
     sorting_analyzer = create_sorting_analyzer(sorting, recording, format="memory", sparse=True)
 
     sorting_analyzer.compute("random_spikes", max_spikes_per_unit=300, seed=1205)

From d94ccf1e56bf1c8cd0d89b71bbba42817c59106f Mon Sep 17 00:00:00 2001
From: Heberto Mayorquin <h.mayorquin@gmail.com>
Date: Tue, 17 Dec 2024 13:45:55 -0600
Subject: [PATCH 281/344] fix post processing

---
 .../postprocessing/tests/test_multi_extensions.py            | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/src/spikeinterface/postprocessing/tests/test_multi_extensions.py b/src/spikeinterface/postprocessing/tests/test_multi_extensions.py
index bf0000135c..be0070d94a 100644
--- a/src/spikeinterface/postprocessing/tests/test_multi_extensions.py
+++ b/src/spikeinterface/postprocessing/tests/test_multi_extensions.py
@@ -23,6 +23,11 @@ def get_dataset():
         seed=2205,
     )
 
+    channel_ids_as_integers = [id for id in range(recording.get_num_channels())]
+    unit_ids_as_integers = [id for id in range(sorting.get_num_units())]
+    recording = recording.rename_channels(new_channel_ids=channel_ids_as_integers)
+    sorting = sorting.rename_units(new_unit_ids=unit_ids_as_integers)
+
     # since templates are going to be averaged and this might be a problem for amplitude scaling
     # we select the 3 units with the largest templates to split
     analyzer_raw = create_sorting_analyzer(sorting, recording, format="memory", sparse=False)

From 7f461db713a377725ea51888859930401d224a98 Mon Sep 17 00:00:00 2001
From: Heberto Mayorquin <h.mayorquin@gmail.com>
Date: Tue, 17 Dec 2024 13:48:07 -0600
Subject: [PATCH 282/344] fix motion

---
 src/spikeinterface/sortingcomponents/tests/common.py | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/src/spikeinterface/sortingcomponents/tests/common.py b/src/spikeinterface/sortingcomponents/tests/common.py
index 01e4445a13..d5e5b6be1b 100644
--- a/src/spikeinterface/sortingcomponents/tests/common.py
+++ b/src/spikeinterface/sortingcomponents/tests/common.py
@@ -21,4 +21,10 @@ def make_dataset():
         noise_kwargs=dict(noise_levels=5.0, strategy="on_the_fly"),
         seed=2205,
     )
+
+    channel_ids_as_integers = [id for id in range(recording.get_num_channels())]
+    unit_ids_as_integers = [id for id in range(sorting.get_num_units())]
+    recording = recording.rename_channels(new_channel_ids=channel_ids_as_integers)
+    sorting = sorting.rename_units(new_unit_ids=unit_ids_as_integers)
+
     return recording, sorting

From 33359cc1f1646545d7beb2a16bad8528e019d428 Mon Sep 17 00:00:00 2001
From: Heberto Mayorquin <h.mayorquin@gmail.com>
Date: Tue, 17 Dec 2024 14:21:07 -0600
Subject: [PATCH 283/344] fix curation

---
 src/spikeinterface/curation/tests/common.py              | 5 +++++
 .../curation/tests/test_sortingview_curation.py          | 9 +++++++++
 2 files changed, 14 insertions(+)

diff --git a/src/spikeinterface/curation/tests/common.py b/src/spikeinterface/curation/tests/common.py
index 9cd20f4bfc..e9c4c4a463 100644
--- a/src/spikeinterface/curation/tests/common.py
+++ b/src/spikeinterface/curation/tests/common.py
@@ -19,6 +19,11 @@ def make_sorting_analyzer(sparse=True):
         seed=2205,
     )
 
+    channel_ids_as_integers = [id for id in range(recording.get_num_channels())]
+    unit_ids_as_integers = [id for id in range(sorting.get_num_units())]
+    recording = recording.rename_channels(new_channel_ids=channel_ids_as_integers)
+    sorting = sorting.rename_units(new_unit_ids=unit_ids_as_integers)
+
     sorting_analyzer = create_sorting_analyzer(sorting=sorting, recording=recording, format="memory", sparse=sparse)
     sorting_analyzer.compute("random_spikes")
     sorting_analyzer.compute("waveforms", **job_kwargs)
diff --git a/src/spikeinterface/curation/tests/test_sortingview_curation.py b/src/spikeinterface/curation/tests/test_sortingview_curation.py
index 945aca7937..ff80be365d 100644
--- a/src/spikeinterface/curation/tests/test_sortingview_curation.py
+++ b/src/spikeinterface/curation/tests/test_sortingview_curation.py
@@ -49,6 +49,9 @@ def test_gh_curation():
     Test curation using GitHub URI.
     """
     sorting = generate_sorting(num_units=10)
+    unit_ids_as_int = [id for id in range(sorting.get_num_units())]
+    sorting = sorting.rename_units(new_unit_ids=unit_ids_as_int)
+
     # curated link:
     # https://figurl.org/f?v=npm://@fi-sci/figurl-sortingview@12/dist&d=sha1://058ab901610aa9d29df565595a3cc2a81a1b08e5
     gh_uri = "gh://SpikeInterface/spikeinterface/main/src/spikeinterface/curation/tests/sv-sorting-curation.json"
@@ -76,6 +79,8 @@ def test_sha1_curation():
     Test curation using SHA1 URI.
     """
     sorting = generate_sorting(num_units=10)
+    unit_ids_as_int = [id for id in range(sorting.get_num_units())]
+    sorting = sorting.rename_units(new_unit_ids=unit_ids_as_int)
 
     # from SHA1
     # curated link:
@@ -105,6 +110,8 @@ def test_json_curation():
     Test curation using a JSON file.
     """
     sorting = generate_sorting(num_units=10)
+    unit_ids_as_int = [id for id in range(sorting.get_num_units())]
+    sorting = sorting.rename_units(new_unit_ids=unit_ids_as_int)
 
     # from curation.json
     json_file = parent_folder / "sv-sorting-curation.json"
@@ -248,6 +255,8 @@ def test_json_no_merge_curation():
     Test curation with no merges using a JSON file.
     """
     sorting = generate_sorting(num_units=10)
+    unit_ids_as_int = [id for id in range(sorting.get_num_units())]
+    sorting = sorting.rename_units(new_unit_ids=unit_ids_as_int)
 
     json_file = parent_folder / "sv-sorting-curation-no-merge.json"
     sorting_curated = apply_sortingview_curation(sorting, uri_or_json=json_file)

From bb48b63a05e6e933bce31e380f97f83cfb3cddb9 Mon Sep 17 00:00:00 2001
From: Heberto Mayorquin <h.mayorquin@gmail.com>
Date: Thu, 19 Dec 2024 11:03:57 -0600
Subject: [PATCH 284/344] Update src/spikeinterface/core/generate.py

Co-authored-by: Alessio Buccino <alejoe9187@gmail.com>
---
 src/spikeinterface/core/generate.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/core/generate.py b/src/spikeinterface/core/generate.py
index 5824a75ab8..118ce384f3 100644
--- a/src/spikeinterface/core/generate.py
+++ b/src/spikeinterface/core/generate.py
@@ -1111,7 +1111,7 @@ def __init__(
 
         """
 
-        unit_ids = [str(id) for id in np.arange(num_units)]
+        unit_ids = [str(idx) for idx in np.arange(num_units)]
         super().__init__(sampling_frequency, unit_ids)
 
         self.num_units = num_units

From 2f26983798026145f9455cacb5e312f11efc4bf3 Mon Sep 17 00:00:00 2001
From: Heberto Mayorquin <h.mayorquin@gmail.com>
Date: Thu, 19 Dec 2024 11:04:03 -0600
Subject: [PATCH 285/344] Update src/spikeinterface/core/generate.py

Co-authored-by: Alessio Buccino <alejoe9187@gmail.com>
---
 src/spikeinterface/core/generate.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/core/generate.py b/src/spikeinterface/core/generate.py
index 118ce384f3..fb10f26a2e 100644
--- a/src/spikeinterface/core/generate.py
+++ b/src/spikeinterface/core/generate.py
@@ -134,7 +134,7 @@ def generate_sorting(
     seed = _ensure_seed(seed)
     rng = np.random.default_rng(seed)
     num_segments = len(durations)
-    unit_ids = [str(id) for id in np.arange(num_units)]
+    unit_ids = [str(idx) for idx in np.arange(num_units)]
 
     spikes = []
     for segment_index in range(num_segments):

From edbe09635ad3eb377857819eb38fc795d4b83ccb Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Tue, 7 Jan 2025 11:33:37 +0100
Subject: [PATCH 286/344] Update zarr version

---
 pyproject.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pyproject.toml b/pyproject.toml
index 22fbdc7f22..51949f6dbf 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -23,7 +23,7 @@ dependencies = [
     "numpy>=1.20, <2.0",  # 1.20 np.ptp, 1.26 might be necessary for avoiding pickling errors when numpy >2.0
     "threadpoolctl>=3.0.0",
     "tqdm",
-    "zarr>=2.16,<2.18",
+    "zarr>=2.18.4,<3",
     "neo>=0.13.0",
     "probeinterface>=0.2.23",
     "packaging",

From 7dea3b2b39568c1a9fb8dd95e1a3fa1de8ed01a4 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Tue, 7 Jan 2025 11:35:15 +0100
Subject: [PATCH 287/344] Update src/spikeinterface/core/generate.py

---
 src/spikeinterface/core/generate.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/core/generate.py b/src/spikeinterface/core/generate.py
index fb10f26a2e..aa69fe585b 100644
--- a/src/spikeinterface/core/generate.py
+++ b/src/spikeinterface/core/generate.py
@@ -1283,7 +1283,7 @@ def __init__(
         noise_block_size: int = 30000,
     ):
 
-        channel_ids = [str(id) for id in np.arange(num_channels)]
+        channel_ids = [str(idx) for idx in np.arange(num_channels)]
         dtype = np.dtype(dtype).name  # Cast to string for serialization
         if dtype not in ("float32", "float64"):
             raise ValueError(f"'dtype' must be 'float32' or 'float64' but is {dtype}")

From bfc65dda92e216732bb074b5a298b084e164da90 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Tue, 7 Jan 2025 11:42:51 +0100
Subject: [PATCH 288/344] Allow 2.16 for older python versions

---
 pyproject.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pyproject.toml b/pyproject.toml
index 51949f6dbf..5b694cd93c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -23,7 +23,7 @@ dependencies = [
     "numpy>=1.20, <2.0",  # 1.20 np.ptp, 1.26 might be necessary for avoiding pickling errors when numpy >2.0
     "threadpoolctl>=3.0.0",
     "tqdm",
-    "zarr>=2.18.4,<3",
+    "zarr>=2.16,<3",
     "neo>=0.13.0",
     "probeinterface>=0.2.23",
     "packaging",

From 919a65e2146e8db439f4db4035be1b3fca977432 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Tue, 7 Jan 2025 11:45:12 +0100
Subject: [PATCH 289/344] Allow 2.18.0 for older python versions

---
 pyproject.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pyproject.toml b/pyproject.toml
index 5b694cd93c..f6a0a5cf3b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -23,7 +23,7 @@ dependencies = [
     "numpy>=1.20, <2.0",  # 1.20 np.ptp, 1.26 might be necessary for avoiding pickling errors when numpy >2.0
     "threadpoolctl>=3.0.0",
     "tqdm",
-    "zarr>=2.16,<3",
+    "zarr>=2.18,<3",
     "neo>=0.13.0",
     "probeinterface>=0.2.23",
     "packaging",

From 6ecbb014ec9a83fa1c867c06f5f8572a83194d5f Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 8 Jan 2025 08:44:36 +0100
Subject: [PATCH 290/344] quick benchmark

---
 .../core/tests/test_job_tools.py              | 44 +++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/src/spikeinterface/core/tests/test_job_tools.py b/src/spikeinterface/core/tests/test_job_tools.py
index 824532a11e..552fe7b00b 100644
--- a/src/spikeinterface/core/tests/test_job_tools.py
+++ b/src/spikeinterface/core/tests/test_job_tools.py
@@ -280,6 +280,48 @@ def test_get_best_job_kwargs():
     job_kwargs = get_best_job_kwargs()
     print(job_kwargs)
 
+
+# def quick_becnhmark():
+#     # keep this commented do not remove
+
+
+#     from spikeinterface.generation import generate_drifting_recording
+#     from spikeinterface.sortingcomponents.peak_detection import detect_peaks
+#     from spikeinterface import get_noise_levels
+#     import time
+
+#     all_job_kwargs = [
+#         dict(pool_engine="process", n_jobs=2, mp_context="spawn", max_threads_per_worker=2),
+#         dict(pool_engine="process", n_jobs=4, mp_context="spawn", max_threads_per_worker=1),
+#         dict(pool_engine="thread", n_jobs=4, mp_context=None, max_threads_per_worker=1),
+#         dict(pool_engine="thread", n_jobs=2, mp_context=None, max_threads_per_worker=2),
+#         dict(n_jobs=1),
+#     ]
+
+    
+
+#     rec, _, sorting = generate_drifting_recording(
+#         num_units=50,
+#         duration=120.0,
+#         sampling_frequency=30000.0,
+#         probe_name="Neuropixel-128",
+
+#     )
+#     # print(rec)
+
+#     noise_levels = get_noise_levels(rec, return_scaled=False)
+#     for job_kwargs in all_job_kwargs:
+#         print()
+#         print(job_kwargs)
+#         t0 = time.perf_counter()
+#         peaks = detect_peaks(rec, method="locally_exclusive", noise_levels=noise_levels, **job_kwargs)
+#         t1 = time.perf_counter()
+#         print("time included the spawn:", t1-t0)
+
+
+
+
+
 if __name__ == "__main__":
     # test_divide_segment_into_chunks()
     # test_ensure_n_jobs()
@@ -289,3 +331,5 @@ def test_get_best_job_kwargs():
     # test_split_job_kwargs()
     # test_worker_index()
     test_get_best_job_kwargs()
+
+    # quick_becnhmark()

From 9329243e87c8634ca60b2fd0cd7e189d9096cc29 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 8 Jan 2025 08:56:51 +0100
Subject: [PATCH 291/344] Pierre suggestion

---
 src/spikeinterface/core/job_tools.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/core/job_tools.py b/src/spikeinterface/core/job_tools.py
index ce7eb05dbc..b8970eaf59 100644
--- a/src/spikeinterface/core/job_tools.py
+++ b/src/spikeinterface/core/job_tools.py
@@ -535,7 +535,7 @@ def run(self, recording_slices=None):
                 ) as executor:
 
 
-                    recording_slices2 = [(thread_local_data, ) + args for args in recording_slices]
+                    recording_slices2 = [(thread_local_data, ) + tuple(args) for args in recording_slices]
                     results = executor.map(thread_function_wrapper, recording_slices2)
 
                     for res in results:

From 61f8509d4c0cb082dc574390d8fb6e64d71890d0 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Wed, 8 Jan 2025 08:19:20 +0000
Subject: [PATCH 292/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/core/__init__.py           |  9 +++-
 src/spikeinterface/core/globals.py            |  4 +-
 src/spikeinterface/core/job_tools.py          | 48 +++++++++++++------
 src/spikeinterface/core/tests/test_globals.py | 23 +++++++--
 .../core/tests/test_job_tools.py              |  9 +---
 .../core/tests/test_waveform_tools.py         |  4 +-
 .../qualitymetrics/tests/conftest.py          |  3 +-
 .../qualitymetrics/tests/test_pca_metrics.py  |  4 +-
 8 files changed, 73 insertions(+), 31 deletions(-)

diff --git a/src/spikeinterface/core/__init__.py b/src/spikeinterface/core/__init__.py
index bea77decfc..f68b70b895 100644
--- a/src/spikeinterface/core/__init__.py
+++ b/src/spikeinterface/core/__init__.py
@@ -90,7 +90,14 @@
     write_python,
     normal_pdf,
 )
-from .job_tools import get_best_job_kwargs, ensure_n_jobs, ensure_chunk_size, ChunkRecordingExecutor, split_job_kwargs, fix_job_kwargs
+from .job_tools import (
+    get_best_job_kwargs,
+    ensure_n_jobs,
+    ensure_chunk_size,
+    ChunkRecordingExecutor,
+    split_job_kwargs,
+    fix_job_kwargs,
+)
 from .recording_tools import (
     write_binary_recording,
     write_to_h5_dataset_format,
diff --git a/src/spikeinterface/core/globals.py b/src/spikeinterface/core/globals.py
index 195440c061..e9974adff7 100644
--- a/src/spikeinterface/core/globals.py
+++ b/src/spikeinterface/core/globals.py
@@ -97,7 +97,9 @@ def is_set_global_dataset_folder() -> bool:
 
 
 ########################################
-_default_job_kwargs = dict(pool_engine="thread", n_jobs=1, chunk_duration="1s", progress_bar=True, mp_context=None, max_threads_per_worker=1)
+_default_job_kwargs = dict(
+    pool_engine="thread", n_jobs=1, chunk_duration="1s", progress_bar=True, mp_context=None, max_threads_per_worker=1
+)
 
 global global_job_kwargs
 global_job_kwargs = _default_job_kwargs.copy()
diff --git a/src/spikeinterface/core/job_tools.py b/src/spikeinterface/core/job_tools.py
index b8970eaf59..ed8a26683c 100644
--- a/src/spikeinterface/core/job_tools.py
+++ b/src/spikeinterface/core/job_tools.py
@@ -59,6 +59,7 @@
     "chunk_duration",
 )
 
+
 def get_best_job_kwargs():
     """
     Gives best possible job_kwargs for the platform.
@@ -82,7 +83,7 @@ def get_best_job_kwargs():
             n_cpu = int(n_cpu / 4)
             max_threads_per_worker = 8
 
-    else: # windows and mac
+    else:  # windows and mac
         # on windows and macos the fork is forbidden and process+spwan is super slow at startup
         # so let's go to threads
         pool_engine = "thread"
@@ -98,8 +99,6 @@ def get_best_job_kwargs():
     )
 
 
-
-
 def fix_job_kwargs(runtime_job_kwargs):
     from .globals import get_global_job_kwargs, is_set_global_job_kwargs_set
 
@@ -498,7 +497,15 @@ def run(self, recording_slices=None):
                     max_workers=n_jobs,
                     initializer=process_worker_initializer,
                     mp_context=multiprocessing.get_context(self.mp_context),
-                    initargs=(self.func, self.init_func, self.init_args, self.max_threads_per_worker, self.need_worker_index, lock, array_pid),
+                    initargs=(
+                        self.func,
+                        self.init_func,
+                        self.init_args,
+                        self.max_threads_per_worker,
+                        self.need_worker_index,
+                        lock,
+                        array_pid,
+                    ),
                 ) as executor:
                     results = executor.map(process_function_wrapper, recording_slices)
 
@@ -510,7 +517,7 @@ def run(self, recording_slices=None):
                             returns.append(res)
                         if self.gather_func is not None:
                             self.gather_func(res)
-            
+
             elif self.pool_engine == "thread":
                 # this is need to create a per worker local dict where the initializer will push the func wrapper
                 thread_local_data = threading.local()
@@ -522,7 +529,7 @@ def run(self, recording_slices=None):
                     # here the tqdm threading do not work (maybe collision) so we need to create a pbar
                     # before thread spawning
                     pbar = tqdm(desc=self.job_name, total=len(recording_slices))
-                
+
                 if self.need_worker_index:
                     lock = threading.Lock()
                 else:
@@ -531,11 +538,18 @@ def run(self, recording_slices=None):
                 with ThreadPoolExecutor(
                     max_workers=n_jobs,
                     initializer=thread_worker_initializer,
-                    initargs=(self.func, self.init_func, self.init_args, self.max_threads_per_worker, thread_local_data, self.need_worker_index, lock),
+                    initargs=(
+                        self.func,
+                        self.init_func,
+                        self.init_args,
+                        self.max_threads_per_worker,
+                        thread_local_data,
+                        self.need_worker_index,
+                        lock,
+                    ),
                 ) as executor:
 
-
-                    recording_slices2 = [(thread_local_data, ) + tuple(args) for args in recording_slices]
+                    recording_slices2 = [(thread_local_data,) + tuple(args) for args in recording_slices]
                     results = executor.map(thread_function_wrapper, recording_slices2)
 
                     for res in results:
@@ -551,9 +565,8 @@ def run(self, recording_slices=None):
 
             else:
                 raise ValueError("If n_jobs>1 pool_engine must be 'process' or 'thread'")
-            
-        return returns
 
+        return returns
 
 
 class WorkerFuncWrapper:
@@ -562,11 +575,12 @@ class WorkerFuncWrapper:
       * local worker_dict
       *  max_threads_per_worker
     """
+
     def __init__(self, func, worker_dict, max_threads_per_worker):
         self.func = func
         self.worker_dict = worker_dict
         self.max_threads_per_worker = max_threads_per_worker
-    
+
     def __call__(self, args):
         segment_index, start_frame, end_frame = args
         if self.max_threads_per_worker is None:
@@ -574,6 +588,8 @@ def __call__(self, args):
         else:
             with threadpool_limits(limits=self.max_threads_per_worker):
                 return self.func(segment_index, start_frame, end_frame, self.worker_dict)
+
+
 # see
 # https://stackoverflow.com/questions/10117073/how-to-use-initializer-to-set-up-my-multiprocess-pool
 # the trick is : this variable is global per worker (so not shared in the same process)
@@ -602,6 +618,7 @@ def process_worker_initializer(func, init_func, init_args, max_threads_per_worke
 
     _process_func_wrapper = WorkerFuncWrapper(func, worker_dict, max_threads_per_worker)
 
+
 def process_function_wrapper(args):
     global _process_func_wrapper
     return _process_func_wrapper(args)
@@ -610,7 +627,10 @@ def process_function_wrapper(args):
 # use by thread at init
 global _thread_started
 
-def thread_worker_initializer(func, init_func, init_args, max_threads_per_worker, thread_local_data, need_worker_index, lock):
+
+def thread_worker_initializer(
+    func, init_func, init_args, max_threads_per_worker, thread_local_data, need_worker_index, lock
+):
     if max_threads_per_worker is None:
         worker_dict = init_func(*init_args)
     else:
@@ -627,13 +647,13 @@ def thread_worker_initializer(func, init_func, init_args, max_threads_per_worker
 
     thread_local_data.func_wrapper = WorkerFuncWrapper(func, worker_dict, max_threads_per_worker)
 
+
 def thread_function_wrapper(args):
     thread_local_data = args[0]
     args = args[1:]
     return thread_local_data.func_wrapper(args)
 
 
-
 # Here some utils copy/paste from DART (Charlie Windolf)
 
 
diff --git a/src/spikeinterface/core/tests/test_globals.py b/src/spikeinterface/core/tests/test_globals.py
index 580287eb21..3f86558303 100644
--- a/src/spikeinterface/core/tests/test_globals.py
+++ b/src/spikeinterface/core/tests/test_globals.py
@@ -36,7 +36,14 @@ def test_global_tmp_folder(create_cache_folder):
 
 
 def test_global_job_kwargs():
-    job_kwargs = dict(pool_engine="thread", n_jobs=4, chunk_duration="1s", progress_bar=True, mp_context=None, max_threads_per_worker=1)
+    job_kwargs = dict(
+        pool_engine="thread",
+        n_jobs=4,
+        chunk_duration="1s",
+        progress_bar=True,
+        mp_context=None,
+        max_threads_per_worker=1,
+    )
     global_job_kwargs = get_global_job_kwargs()
 
     # test warning when not setting n_jobs and calling fix_job_kwargs
@@ -44,7 +51,12 @@ def test_global_job_kwargs():
         job_kwargs_split = fix_job_kwargs({})
 
     assert global_job_kwargs == dict(
-        pool_engine="thread", n_jobs=1, chunk_duration="1s", progress_bar=True, mp_context=None, max_threads_per_worker=1
+        pool_engine="thread",
+        n_jobs=1,
+        chunk_duration="1s",
+        progress_bar=True,
+        mp_context=None,
+        max_threads_per_worker=1,
     )
     set_global_job_kwargs(**job_kwargs)
     assert get_global_job_kwargs() == job_kwargs
@@ -59,7 +71,12 @@ def test_global_job_kwargs():
     set_global_job_kwargs(**partial_job_kwargs)
     global_job_kwargs = get_global_job_kwargs()
     assert global_job_kwargs == dict(
-        pool_engine="thread", n_jobs=2, chunk_duration="1s", progress_bar=True, mp_context=None, max_threads_per_worker=1
+        pool_engine="thread",
+        n_jobs=2,
+        chunk_duration="1s",
+        progress_bar=True,
+        mp_context=None,
+        max_threads_per_worker=1,
     )
     # test that fix_job_kwargs grabs global kwargs
     new_job_kwargs = dict(n_jobs=cpu_count())
diff --git a/src/spikeinterface/core/tests/test_job_tools.py b/src/spikeinterface/core/tests/test_job_tools.py
index 552fe7b00b..88d52ebb1f 100644
--- a/src/spikeinterface/core/tests/test_job_tools.py
+++ b/src/spikeinterface/core/tests/test_job_tools.py
@@ -236,8 +236,6 @@ def test_split_job_kwargs():
     assert "other_param" not in job_kwargs and "n_jobs" in job_kwargs and "progress_bar" in job_kwargs
 
 
-
-
 def func2(segment_index, start_frame, end_frame, worker_dict):
     time.sleep(0.010)
     # print(os.getpid(), worker_dict["worker_index"])
@@ -269,13 +267,14 @@ def test_worker_index():
                 n_jobs=2,
                 handle_returns=True,
                 chunk_duration="200ms",
-                need_worker_index=True
+                need_worker_index=True,
             )
             res = processor.run()
             # we should have a mix of 0 and 1
             assert 0 in res
             assert 1 in res
 
+
 def test_get_best_job_kwargs():
     job_kwargs = get_best_job_kwargs()
     print(job_kwargs)
@@ -298,7 +297,6 @@ def test_get_best_job_kwargs():
 #         dict(n_jobs=1),
 #     ]
 
-    
 
 #     rec, _, sorting = generate_drifting_recording(
 #         num_units=50,
@@ -319,9 +317,6 @@ def test_get_best_job_kwargs():
 #         print("time included the spawn:", t1-t0)
 
 
-
-
-
 if __name__ == "__main__":
     # test_divide_segment_into_chunks()
     # test_ensure_n_jobs()
diff --git a/src/spikeinterface/core/tests/test_waveform_tools.py b/src/spikeinterface/core/tests/test_waveform_tools.py
index ed27815758..a516e6d42b 100644
--- a/src/spikeinterface/core/tests/test_waveform_tools.py
+++ b/src/spikeinterface/core/tests/test_waveform_tools.py
@@ -199,7 +199,7 @@ def test_estimate_templates_with_accumulator():
             if len(templates_by_worker) > 1:
                 templates_loop = templates_by_worker[0]
                 np.testing.assert_almost_equal(templates, templates_loop, decimal=4)
-                
+
                 # import matplotlib.pyplot as plt
                 # fig, axs = plt.subplots(nrows=2, sharex=True)
                 # for unit_index, unit_id in enumerate(sorting.unit_ids):
@@ -212,8 +212,6 @@ def test_estimate_templates_with_accumulator():
                 # plt.show()
 
 
-
-
 def test_estimate_templates():
     recording, sorting = get_dataset()
 
diff --git a/src/spikeinterface/qualitymetrics/tests/conftest.py b/src/spikeinterface/qualitymetrics/tests/conftest.py
index fb65338a1b..39bc62ae12 100644
--- a/src/spikeinterface/qualitymetrics/tests/conftest.py
+++ b/src/spikeinterface/qualitymetrics/tests/conftest.py
@@ -8,7 +8,6 @@
 job_kwargs = dict(n_jobs=2, progress_bar=True, chunk_duration="1s")
 
 
-
 def make_small_analyzer():
     recording, sorting = generate_ground_truth_recording(
         durations=[2.0],
@@ -39,10 +38,12 @@ def make_small_analyzer():
 
     return sorting_analyzer
 
+
 @pytest.fixture(scope="module")
 def small_sorting_analyzer():
     return make_small_analyzer()
 
+
 @pytest.fixture(scope="module")
 def sorting_analyzer_simple():
     # we need high firing rate for amplitude_cutoff
diff --git a/src/spikeinterface/qualitymetrics/tests/test_pca_metrics.py b/src/spikeinterface/qualitymetrics/tests/test_pca_metrics.py
index 312c3949b3..287439a4f7 100644
--- a/src/spikeinterface/qualitymetrics/tests/test_pca_metrics.py
+++ b/src/spikeinterface/qualitymetrics/tests/test_pca_metrics.py
@@ -56,7 +56,9 @@ def test_pca_metrics_multi_processing(small_sorting_analyzer):
         sorting_analyzer, n_jobs=-1, metric_names=metric_names, max_threads_per_worker=2, progress_bar=True
     )
 
+
 if __name__ == "__main__":
     from spikeinterface.qualitymetrics.tests.conftest import make_small_analyzer
+
     small_sorting_analyzer = make_small_analyzer()
-    test_calculate_pc_metrics(small_sorting_analyzer)
\ No newline at end of file
+    test_calculate_pc_metrics(small_sorting_analyzer)

From e74aa00e2c8ee5d6e94f79da491a565fcef322c8 Mon Sep 17 00:00:00 2001
From: chrishalcrow <57948917+chrishalcrow@users.noreply.github.com>
Date: Wed, 8 Jan 2025 15:21:52 +0000
Subject: [PATCH 293/344] string-ify unit_ids in plot_2_sort_gallery

---
 examples/tutorials/widgets/plot_2_sort_gallery.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/examples/tutorials/widgets/plot_2_sort_gallery.py b/examples/tutorials/widgets/plot_2_sort_gallery.py
index da5c611ce4..056b5e3a8d 100644
--- a/examples/tutorials/widgets/plot_2_sort_gallery.py
+++ b/examples/tutorials/widgets/plot_2_sort_gallery.py
@@ -31,14 +31,14 @@
 # plot_autocorrelograms()
 # ~~~~~~~~~~~~~~~~~~~~~~~~
 
-w_ach = sw.plot_autocorrelograms(sorting, window_ms=150.0, bin_ms=5.0, unit_ids=[1, 2, 5])
+w_ach = sw.plot_autocorrelograms(sorting, window_ms=150.0, bin_ms=5.0, unit_ids=['1', '2', '5'])
 
 ##############################################################################
 # plot_crosscorrelograms()
 # ~~~~~~~~~~~~~~~~~~~~~~~~
 
 
-w_cch = sw.plot_crosscorrelograms(sorting, window_ms=150.0, bin_ms=5.0, unit_ids=[1, 2, 5])
+w_cch = sw.plot_crosscorrelograms(sorting, window_ms=150.0, bin_ms=5.0, unit_ids=['1', '2', '5'])
 
 plt.show()
 

From 0deac0364d8962aff9036f5412eb956cca7039e6 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 8 Jan 2025 16:49:55 +0100
Subject: [PATCH 294/344] Small fixes in curation format and apply_curation()

---
 src/spikeinterface/curation/curation_format.py | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/src/spikeinterface/curation/curation_format.py b/src/spikeinterface/curation/curation_format.py
index 5f85538b08..f51b782572 100644
--- a/src/spikeinterface/curation/curation_format.py
+++ b/src/spikeinterface/curation/curation_format.py
@@ -45,12 +45,16 @@ def validate_curation_dict(curation_dict):
         if not removed_units_set.issubset(unit_set):
             raise ValueError("Curation format: some removed units are not in the unit list")
 
+    for group in curation_dict["merge_unit_groups"]:
+        if len(group) < 2:
+            raise ValueError("Curation format: 'merge_unit_groups' must be list of list with at least 2 elements")
+
     all_merging_groups = [set(group) for group in curation_dict["merge_unit_groups"]]
     for gp_1, gp_2 in combinations(all_merging_groups, 2):
         if len(gp_1.intersection(gp_2)) != 0:
-            raise ValueError("Some units belong to multiple merge groups")
+            raise ValueError("Curation format: some units belong to multiple merge groups")
     if len(removed_units_set.intersection(merged_units_set)) != 0:
-        raise ValueError("Some units were merged and deleted")
+        raise ValueError("Curation format: some units were merged and deleted")
 
     # Check the labels exclusivity
     for lbl in curation_dict["manual_labels"]:
@@ -253,7 +257,7 @@ def apply_curation_labels(sorting, new_unit_ids, curation_dict):
                         group_values.append(value)
                 if len(set(group_values)) == 1:
                     # all group has the same label or empty
-                    sorting.set_property(key, values=group_values, ids=[new_unit_id])
+                    sorting.set_property(key, values=group_values[:1], ids=[new_unit_id])
             else:
 
                 for key in label_def["label_options"]:

From 7a5e75fc65008f4eafee48db8ebf69c043c5df65 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 8 Jan 2025 21:52:54 +0100
Subject: [PATCH 295/344] Start changes to improve sigui API

---
 src/spikeinterface/widgets/sorting_summary.py | 25 +++++++++++++++++--
 1 file changed, 23 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/widgets/sorting_summary.py b/src/spikeinterface/widgets/sorting_summary.py
index a113298851..6b8e9b7d44 100644
--- a/src/spikeinterface/widgets/sorting_summary.py
+++ b/src/spikeinterface/widgets/sorting_summary.py
@@ -50,8 +50,16 @@ class SortingSummaryWidget(BaseWidget):
         analyzer.get_extension("quality_metrics").get_data().columns and
         analyzer.get_extension("template_metrics").get_data().columns.
         (sortingview backend)
+    curation_dict : dict or None
+        When curation is True, optionaly the viewer can get a previous 'curation_dict'
+        to continue/check  previous curations on this analyzer.
+        In this case label_definitions must be None beacuse it is already included in the curation_dict.
+        (spikeinterface_gui backend)
+    label_definitions : dict or None
+        When curation is True, optionaly the user can provide a label_definitions dict.
+        This replaces the label_choices in the curation_format.
+        (spikeinterface_gui backend)
     """
-
     def __init__(
         self,
         sorting_analyzer: SortingAnalyzer,
@@ -62,6 +70,8 @@ def __init__(
         curation=False,
         unit_table_properties=None,
         label_choices=None,
+        curation_dict=None,
+        label_definitions=None,
         backend=None,
         **backend_kwargs,
     ):
@@ -74,6 +84,9 @@ def __init__(
         if unit_ids is None:
             unit_ids = sorting.get_unit_ids()
 
+        if curation_dict is not None and label_definitions is not None:
+            raise ValueError("curation_dict and label_definitions are mutualy exclusive, they cannot be not None both")
+
         plot_data = dict(
             sorting_analyzer=sorting_analyzer,
             unit_ids=unit_ids,
@@ -83,6 +96,8 @@ def __init__(
             curation=curation,
             label_choices=label_choices,
             max_amplitudes_per_unit=max_amplitudes_per_unit,
+            curation_dict=curation_dict,
+            label_definitions=label_definitions,
         )
 
         BaseWidget.__init__(self, plot_data, backend=backend, **backend_kwargs)
@@ -193,6 +208,12 @@ def plot_spikeinterface_gui(self, data_plot, **backend_kwargs):
         import spikeinterface_gui
 
         app = spikeinterface_gui.mkQApp()
-        win = spikeinterface_gui.MainWindow(sorting_analyzer, curation=data_plot["curation"])
+        win = spikeinterface_gui.MainWindow(
+            sorting_analyzer,
+            curation=data_plot["curation"]
+            curation_data=data_plot["curation_dict"],
+            label_definitions=data_plot["label_definitions"],
+            more_units_properties=data_plot["unit_table_properties"],
+        )
         win.show()
         app.exec_()

From ac46fb5d4c88ba9dcaa8370dc937882cf6e473c5 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Wed, 8 Jan 2025 21:36:58 +0000
Subject: [PATCH 296/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/qualitymetrics/quality_metric_calculator.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
index 1f79acaa8b..6410647371 100644
--- a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
+++ b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
@@ -18,7 +18,6 @@
     _possible_pc_metric_names,
     compute_name_to_column_names,
     column_name_to_column_dtype,
-
 )
 from .misc_metrics import _default_params as misc_metrics_params
 from .pca_metrics import _default_params as pca_metrics_params

From e1c401dd62d014d0f69996e9592b708b8eb0460f Mon Sep 17 00:00:00 2001
From: Zach McKenzie <92116279+zm711@users.noreply.github.com>
Date: Wed, 8 Jan 2025 16:39:24 -0500
Subject: [PATCH 297/344] oops

---
 src/spikeinterface/qualitymetrics/quality_metric_calculator.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
index 6410647371..4aad25e928 100644
--- a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
+++ b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
@@ -16,7 +16,6 @@
     compute_pc_metrics,
     _misc_metric_name_to_func,
     _possible_pc_metric_names,
-    compute_name_to_column_names,
     column_name_to_column_dtype,
 )
 from .misc_metrics import _default_params as misc_metrics_params

From cdc1b2a34f8f0fc6a15a7b6a573c8ed8ce4c2a77 Mon Sep 17 00:00:00 2001
From: zm711 <92116279+zm711@users.noreply.github.com>
Date: Thu, 9 Jan 2025 12:12:32 -0500
Subject: [PATCH 298/344] add back in list

---
 src/spikeinterface/qualitymetrics/quality_metric_calculator.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
index 4aad25e928..834c8a9974 100644
--- a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
+++ b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
@@ -16,6 +16,7 @@
     compute_pc_metrics,
     _misc_metric_name_to_func,
     _possible_pc_metric_names,
+    qm_compute_name_to_column_names,
     column_name_to_column_dtype,
 )
 from .misc_metrics import _default_params as misc_metrics_params

From e45a9f85d49474d625bb4728b971b8357368e643 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Fri, 10 Jan 2025 11:52:40 +0100
Subject: [PATCH 299/344] Exploit hard-coded sync sizes

---
 .../qualitymetrics/quality_metric_calculator.py             | 5 +----
 src/spikeinterface/qualitymetrics/quality_metric_list.py    | 6 ++++--
 2 files changed, 5 insertions(+), 6 deletions(-)

diff --git a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
index 834c8a9974..02409ffdbb 100644
--- a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
+++ b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
@@ -251,10 +251,7 @@ def _compute_metrics(self, sorting_analyzer, unit_ids=None, verbose=False, metri
             # we have one issue where the name of the columns for synchrony are named based on
             # what the user has input as arguments so we need a way to handle this separately
             # everything else should be handled with the column name.
-            if "sync" in column:
-                metrics[column] = metrics[column].astype(column_name_to_column_dtype["sync"])
-            else:
-                metrics[column] = metrics[column].astype(column_name_to_column_dtype[column])
+            metrics[column] = metrics[column].astype(column_name_to_column_dtype[column])
 
         return metrics
 
diff --git a/src/spikeinterface/qualitymetrics/quality_metric_list.py b/src/spikeinterface/qualitymetrics/quality_metric_list.py
index fc7ae906e7..23b781eb9d 100644
--- a/src/spikeinterface/qualitymetrics/quality_metric_list.py
+++ b/src/spikeinterface/qualitymetrics/quality_metric_list.py
@@ -70,7 +70,7 @@
         "sync_spike_2",
         "sync_spike_4",
         "sync_spike_8",
-    ],  # we probably shouldn't hard code this. This is determined by the arguments in the function...
+    ],
     "firing_range": ["firing_range"],
     "drift": ["drift_ptp", "drift_std", "drift_mad"],
     "sd_ratio": ["sd_ratio"],
@@ -99,7 +99,9 @@
     "amplitude_median": float,
     "amplitude_cv_median": float,
     "amplitude_cv_range": float,
-    "sync": float,
+    "sync_spike_2": float,
+    "sync_spike_4": float,
+    "sync_spike_8": float,
     "firing_range": float,
     "drift_ptp": float,
     "drift_std": float,

From 8353160e7804dff75bcb4dde07c07ef4650d7244 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Fri, 10 Jan 2025 11:53:48 +0100
Subject: [PATCH 300/344] Remove comment

---
 src/spikeinterface/qualitymetrics/quality_metric_calculator.py | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
index 02409ffdbb..2f92f50ef0 100644
--- a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
+++ b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
@@ -248,9 +248,6 @@ def _compute_metrics(self, sorting_analyzer, unit_ids=None, verbose=False, metri
         # we do this because the convert_dtypes infers the wrong types sometimes.
         # the actual types for columns can be found in column_name_to_column_dtype dictionary.
         for column in metrics.columns:
-            # we have one issue where the name of the columns for synchrony are named based on
-            # what the user has input as arguments so we need a way to handle this separately
-            # everything else should be handled with the column name.
             metrics[column] = metrics[column].astype(column_name_to_column_dtype[column])
 
         return metrics

From 33feca3a65416ba8c214e8a384e24a55aec1bd5c Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Fri, 10 Jan 2025 11:58:17 +0100
Subject: [PATCH 301/344] Protect dtype casting only when column is in
 column_name_to_column_dtype

---
 src/spikeinterface/qualitymetrics/quality_metric_calculator.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
index 2f92f50ef0..11ce3d0160 100644
--- a/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
+++ b/src/spikeinterface/qualitymetrics/quality_metric_calculator.py
@@ -248,7 +248,8 @@ def _compute_metrics(self, sorting_analyzer, unit_ids=None, verbose=False, metri
         # we do this because the convert_dtypes infers the wrong types sometimes.
         # the actual types for columns can be found in column_name_to_column_dtype dictionary.
         for column in metrics.columns:
-            metrics[column] = metrics[column].astype(column_name_to_column_dtype[column])
+            if column in column_name_to_column_dtype:
+                metrics[column] = metrics[column].astype(column_name_to_column_dtype[column])
 
         return metrics
 

From 9ff3070d6bc59a50645df6b22336dd8a03c22c86 Mon Sep 17 00:00:00 2001
From: Anoushka Jain <jain.anoushka3@gmail.com>
Date: Fri, 10 Jan 2025 15:48:53 +0100
Subject: [PATCH 302/344] Automatic curation with metrics  (#2918)

Co-authored-by: Robyn Greene <pepper9611@gmail.com>
Co-authored-by: jakeswann1 <jake.swann.22@ucl.ac.uk>
Co-authored-by: Jake Swann <66915197+jakeswann1@users.noreply.github.com>
Co-authored-by: Chris Halcrow <57948917+chrishalcrow@users.noreply.github.com>
Co-authored-by: Alessio Buccino <alejoe9187@gmail.com>
---
 doc/api.rst                                   |   3 +
 doc/conf.py                                   |   1 +
 doc/how_to/auto_curation_prediction.rst       |  43 +
 doc/how_to/auto_curation_training.rst         |  58 ++
 doc/how_to/index.rst                          |   2 +
 doc/images/files_screen.png                   | Bin 0 -> 99254 bytes
 doc/images/hf-logo.svg                        |   8 +
 doc/images/initial_model_screen.png           | Bin 0 -> 34596 bytes
 doc/tutorials_custom_index.rst                |  37 +-
 examples/tutorials/curation/README.rst        |   5 +
 .../curation/plot_1_automated_curation.py     | 287 ++++++
 .../curation/plot_2_train_a_model.py          | 168 ++++
 .../curation/plot_3_upload_a_model.py         | 139 +++
 ...y_mertics.py => plot_3_quality_metrics.py} |   0
 pyproject.toml                                |   8 +
 src/spikeinterface/curation/__init__.py       |   4 +
 .../curation/model_based_curation.py          | 435 +++++++++
 .../tests/test_model_based_curation.py        | 167 ++++
 .../tests/test_train_manual_curation.py       | 285 ++++++
 .../tests/trained_pipeline/best_model.skops   | Bin 0 -> 34009 bytes
 .../tests/trained_pipeline/labels.csv         |  21 +
 .../trained_pipeline/model_accuracies.csv     |   2 +
 .../tests/trained_pipeline/model_info.json    |  60 ++
 .../tests/trained_pipeline/training_data.csv  |  21 +
 .../curation/train_manual_curation.py         | 843 ++++++++++++++++++
 .../qualitymetrics/pca_metrics.py             |   3 +
 26 files changed, 2598 insertions(+), 2 deletions(-)
 create mode 100644 doc/how_to/auto_curation_prediction.rst
 create mode 100644 doc/how_to/auto_curation_training.rst
 create mode 100644 doc/images/files_screen.png
 create mode 100644 doc/images/hf-logo.svg
 create mode 100644 doc/images/initial_model_screen.png
 create mode 100644 examples/tutorials/curation/README.rst
 create mode 100644 examples/tutorials/curation/plot_1_automated_curation.py
 create mode 100644 examples/tutorials/curation/plot_2_train_a_model.py
 create mode 100644 examples/tutorials/curation/plot_3_upload_a_model.py
 rename examples/tutorials/qualitymetrics/{plot_3_quality_mertics.py => plot_3_quality_metrics.py} (100%)
 create mode 100644 src/spikeinterface/curation/model_based_curation.py
 create mode 100644 src/spikeinterface/curation/tests/test_model_based_curation.py
 create mode 100644 src/spikeinterface/curation/tests/test_train_manual_curation.py
 create mode 100644 src/spikeinterface/curation/tests/trained_pipeline/best_model.skops
 create mode 100644 src/spikeinterface/curation/tests/trained_pipeline/labels.csv
 create mode 100644 src/spikeinterface/curation/tests/trained_pipeline/model_accuracies.csv
 create mode 100644 src/spikeinterface/curation/tests/trained_pipeline/model_info.json
 create mode 100644 src/spikeinterface/curation/tests/trained_pipeline/training_data.csv
 create mode 100644 src/spikeinterface/curation/train_manual_curation.py

diff --git a/doc/api.rst b/doc/api.rst
index 6bb9b39091..eb9a61eb9c 100644
--- a/doc/api.rst
+++ b/doc/api.rst
@@ -346,6 +346,9 @@ spikeinterface.curation
     .. autofunction:: remove_redundant_units
     .. autofunction:: remove_duplicated_spikes
     .. autofunction:: remove_excess_spikes
+    .. autofunction:: load_model
+    .. autofunction:: auto_label_units
+    .. autofunction:: train_model
 
 Deprecated
 ~~~~~~~~~~
diff --git a/doc/conf.py b/doc/conf.py
index e3d58ca8f2..41659d2e84 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -125,6 +125,7 @@
     'subsection_order': ExplicitOrder([
                                        '../examples/tutorials/core',
                                        '../examples/tutorials/extractors',
+                                       '../examples/tutorials/curation',
                                        '../examples/tutorials/qualitymetrics',
                                        '../examples/tutorials/comparison',
                                        '../examples/tutorials/widgets',
diff --git a/doc/how_to/auto_curation_prediction.rst b/doc/how_to/auto_curation_prediction.rst
new file mode 100644
index 0000000000..9b1612ec12
--- /dev/null
+++ b/doc/how_to/auto_curation_prediction.rst
@@ -0,0 +1,43 @@
+How to use a trained model to predict the curation labels
+=========================================================
+
+For a more detailed guide to using trained models, `read our tutorial here
+<https://spikeinterface.readthedocs.io/en/latest/tutorials/curation/plot_1_automated_curation.html>`_).
+
+There is a Collection of models for automated curation available on the
+`SpikeInterface HuggingFace page <https://huggingface.co/SpikeInterface>`_.
+
+We'll apply the model ``toy_tetrode_model`` from ``SpikeInterface`` on a SortingAnalyzer
+called ``sorting_analyzer``. We assume that the quality and template metrics have
+already been computed.
+
+We need to pass the ``sorting_analyzer``, the ``repo_id`` (which is just the part of the
+repo's URL after huggingface.co/) and that we trust the model.
+
+.. code::
+
+    from spikeinterface.curation import auto_label_units
+
+    labels_and_probabilities = auto_label_units(
+        sorting_analyzer = sorting_analyzer,
+        repo_id = "SpikeInterface/toy_tetrode_model",
+        trust_model = True
+    )
+
+If you have a local directory containing the model in a ``skops`` file you can use this to
+create the labels:
+
+.. code::
+
+    labels_and_probabilities = si.auto_label_units(
+        sorting_analyzer = sorting_analyzer,
+        model_folder = "my_folder_with_a_model_in_it",
+    )
+
+The returned labels are a dictionary of model's predictions and it's confidence. These
+are also saved as a property of your ``sorting_analyzer`` and can be accessed like so:
+
+.. code::
+
+    labels = sorting_analyzer.sorting.get_property("classifier_label")
+    probabilities = sorting_analyzer.sorting.get_property("classifier_probability")
diff --git a/doc/how_to/auto_curation_training.rst b/doc/how_to/auto_curation_training.rst
new file mode 100644
index 0000000000..20ab57d284
--- /dev/null
+++ b/doc/how_to/auto_curation_training.rst
@@ -0,0 +1,58 @@
+How to train a model to predict curation labels
+===============================================
+
+A full tutorial for model-based curation can be found `here <https://spikeinterface.readthedocs.io/en/latest/tutorials/curation/plot_2_train_a_model.html>`_.
+
+Here, we assume that you have:
+
+* Two SortingAnalyzers called ``analyzer_1`` and
+  ``analyzer_2``, and have calculated some template and quality metrics for both
+* Manually curated labels for the units in each analyzer, in lists called
+  ``analyzer_1_labels`` and ``analyzer_2_labels``. If you have used phy, the lists can
+  be accessed using ``curated_labels = analyzer.sorting.get_property("quality")``.
+
+With these objects calculated, you can train a model as follows
+
+.. code::
+
+    from spikeinterface.curation import train_model
+
+    analyzer_list = [analyzer_1, analyzer_2]
+    labels_list = [analyzer_1_labels, analyzer_2_labels]
+    output_folder = "/path/to/output_folder"
+
+    trainer = train_model(
+        mode="analyzers",
+        labels=labels_list,
+        analyzers=analyzer_list,
+        output_folder=output_folder,
+        metric_names=None, # Set if you want to use a subset of metrics, defaults to all calculated quality and template metrics
+        imputation_strategies=None, # Default is all available imputation strategies
+        scaling_techniques=None, # Default is all available scaling techniques
+        classifiers=None, # Defaults to Random Forest classifier only - we usually find this gives the best results, but a range of classifiers is available
+        seed=None, # Set a seed for reproducibility
+    )
+
+
+The trainer tries several models and chooses the most accurate one. This model and
+some metadata are stored in the ``output_folder``, which can later be loaded using the
+``load_model`` function (`more details <https://spikeinterface.readthedocs.io/en/latest/tutorials/curation/plot_1_automated_curation.html#download-a-pretrained-model>`_).
+We can also access the model, which is an sklearn ``Pipeline``, from the trainer object
+
+.. code::
+
+    best_model = trainer.best_pipeline
+
+
+The training function can also be run in “csv” mode, if you prefer to
+store metrics in as .csv files. If the target labels are stored as a column in
+the file, you can point to these with the ``target_label`` parameter
+
+.. code::
+
+    trainer = train_model(
+        mode="csv",
+        metrics_paths = ["/path/to/csv_file_1", "/path/to/csv_file_2"],
+        target_label = "my_label",
+        output_folder=output_folder,
+    )
diff --git a/doc/how_to/index.rst b/doc/how_to/index.rst
index 5d7eae9003..7f79156a3b 100644
--- a/doc/how_to/index.rst
+++ b/doc/how_to/index.rst
@@ -15,3 +15,5 @@ Guides on how to solve specific, short problems in SpikeInterface. Learn how to.
     load_your_data_into_sorting
     benchmark_with_hybrid_recordings
     drift_with_lfp
+    auto_curation_training
+    auto_curation_prediction
diff --git a/doc/images/files_screen.png b/doc/images/files_screen.png
new file mode 100644
index 0000000000000000000000000000000000000000..ef2b5b08736cded355de3473c31075f2f04430f5
GIT binary patch
literal 99254
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
YYbom`MfE5f2Kc+9d{3!D!94iC09w~e^Z)<=

literal 0
HcmV?d00001

diff --git a/doc/images/hf-logo.svg b/doc/images/hf-logo.svg
new file mode 100644
index 0000000000..ab959d165f
--- /dev/null
+++ b/doc/images/hf-logo.svg
@@ -0,0 +1,8 @@
+<svg width="256" height="256" viewBox="0 0 256 256" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M230.721 172.7C230.183 170.673 229.313 168.75 228.146 167.008C228.396 166.091 228.587 165.159 228.714 164.217C229.543 158.241 227.471 152.77 223.567 148.537C221.452 146.225 219.185 144.698 216.784 143.761C218.36 137.018 219.157 130.117 219.161 123.193C219.161 120.03 218.982 116.932 218.682 113.88C218.526 112.356 218.337 110.836 218.115 109.32C217.428 104.847 216.408 100.431 215.064 96.11C214.183 93.2707 213.164 90.476 212.01 87.736C210.281 83.6782 208.262 79.75 205.969 75.982C204.465 73.475 202.827 71.0508 201.062 68.72C200.197 67.543 199.296 66.3938 198.358 65.274C195.58 61.898 192.561 58.7277 189.325 55.788C188.25 54.7997 187.145 53.8453 186.01 52.926C184.893 51.9943 183.751 51.0927 182.586 50.222C180.241 48.4766 177.818 46.8392 175.324 45.315C161.543 36.945 145.382 32.145 128.109 32.145C77.817 32.145 37.057 72.907 37.057 123.196C37.055 130.208 37.867 137.196 39.477 144.02C37.317 144.958 35.247 146.42 33.327 148.535C29.424 152.766 27.351 158.217 28.18 164.193C28.306 165.142 28.495 166.082 28.747 167.006C27.5811 168.749 26.7117 170.673 26.174 172.7C24.974 177.261 25.369 181.374 26.894 184.978C25.236 189.688 25.65 194.704 27.809 199.065C29.379 202.25 31.626 204.714 34.396 206.916C37.689 209.534 41.811 211.758 46.783 213.892C52.715 216.422 59.956 218.799 63.249 219.671C71.755 221.873 79.911 223.269 88.177 223.337C99.954 223.446 110.096 220.677 117.357 213.59C120.924 214.027 124.515 214.246 128.109 214.244C131.906 214.236 135.699 213.997 139.467 213.529C146.711 220.661 156.892 223.455 168.712 223.343C176.977 223.277 185.133 221.881 193.617 219.676C196.932 218.804 204.17 216.427 210.105 213.897C215.077 211.76 219.199 209.536 222.514 206.922C225.263 204.719 227.508 202.256 229.079 199.071C231.26 194.709 231.652 189.693 230.017 184.983C231.527 181.379 231.92 177.257 230.721 172.7ZM222.281 184.673C223.952 187.844 224.059 191.427 222.585 194.764C220.349 199.821 214.795 203.805 204.008 208.082C197.3 210.742 191.158 212.443 191.104 212.458C182.232 214.759 174.208 215.928 167.262 215.928C155.76 215.928 147.201 212.754 141.773 206.486C132.594 208.05 123.222 208.103 114.026 206.644C108.591 212.808 100.081 215.928 88.676 215.928C81.729 215.928 73.706 214.759 64.833 212.458C64.779 212.443 58.639 210.742 51.929 208.082C41.143 203.805 35.587 199.824 33.352 194.764C31.878 191.427 31.985 187.844 33.656 184.673C33.81 184.378 33.976 184.091 34.153 183.813C33.1516 182.309 32.4799 180.61 32.182 178.827C31.8842 177.045 31.967 175.22 32.425 173.472C33.089 170.949 34.46 168.851 36.322 167.344C35.425 165.87 34.8365 164.23 34.592 162.522C34.056 158.808 35.289 155.1 38.062 152.076C40.222 149.723 43.275 148.428 46.655 148.428H46.745C44.1965 140.259 42.9044 131.75 42.913 123.193C42.913 76.522 80.749 38.683 127.427 38.683C174.104 38.683 211.94 76.518 211.94 123.193C211.947 131.773 210.646 140.304 208.081 148.492C208.489 148.452 208.889 148.432 209.282 148.431C212.662 148.431 215.716 149.726 217.874 152.079C220.647 155.1 221.881 158.811 221.344 162.525C221.1 164.233 220.511 165.873 219.615 167.347C221.477 168.854 222.849 170.952 223.512 173.475C223.97 175.223 224.053 177.048 223.755 178.831C223.458 180.613 222.786 182.312 221.784 183.816C221.961 184.091 222.129 184.378 222.281 184.673Z" fill="white"/>
+<path d="M221.784 183.816C222.786 182.312 223.458 180.613 223.756 178.831C224.053 177.048 223.97 175.223 223.512 173.475C222.848 170.952 221.476 168.854 219.615 167.347C220.512 165.873 221.1 164.233 221.344 162.525C221.881 158.811 220.648 155.103 217.874 152.079C215.716 149.726 212.662 148.431 209.282 148.431C208.889 148.431 208.489 148.452 208.081 148.492C210.643 140.304 211.942 131.774 211.933 123.195C211.933 76.5231 174.097 38.6851 127.424 38.6851C80.75 38.6851 42.9099 76.5191 42.9099 123.195C42.9015 131.752 44.1936 140.261 46.742 148.43H46.6519C43.2719 148.43 40.219 149.724 38.06 152.077C35.287 155.098 34.0529 158.81 34.5899 162.523C34.8346 164.231 35.4231 165.872 36.3199 167.346C34.4579 168.852 33.086 170.95 32.422 173.473C31.9642 175.222 31.8817 177.047 32.1799 178.83C32.4781 180.612 33.1501 182.312 34.1519 183.816C33.9739 184.094 33.8099 184.381 33.6549 184.676C31.9849 187.847 31.877 191.43 33.352 194.767C35.588 199.824 41.1419 203.808 51.9289 208.085C58.6359 210.745 64.779 212.446 64.833 212.461C73.705 214.762 81.729 215.931 88.675 215.931C100.081 215.931 108.591 212.811 114.026 206.647C123.222 208.106 132.594 208.052 141.773 206.489C147.201 212.757 155.76 215.931 167.262 215.931C174.208 215.931 182.232 214.762 191.103 212.461C191.158 212.446 197.298 210.745 204.008 208.085C214.795 203.808 220.35 199.824 222.585 194.767C224.059 191.43 223.952 187.847 222.281 184.676C222.129 184.379 221.961 184.091 221.784 183.816ZM110.137 196.997C109.669 197.815 109.168 198.614 108.635 199.391C107.23 201.448 105.382 203.02 103.237 204.188C99.1369 206.424 93.947 207.205 88.675 207.205C80.346 207.205 71.808 205.256 67.023 204.015C66.787 203.954 37.689 195.735 41.373 188.739C41.993 187.562 43.0129 187.092 44.2979 187.092C49.4849 187.092 58.9299 194.816 62.9889 194.816C63.8959 194.816 64.5359 194.43 64.7969 193.488C66.5269 187.284 38.5039 184.676 40.8639 175.692C41.2799 174.102 42.41 173.456 43.998 173.456C50.856 173.455 66.248 185.516 69.467 185.516C69.714 185.516 69.8909 185.443 69.9869 185.291C70.0009 185.268 70.015 185.246 70.028 185.222C71.539 182.727 70.6719 180.913 60.3209 174.573L59.3269 173.968C47.9359 167.074 39.9409 162.925 44.4879 157.975C45.0109 157.404 45.7529 157.151 46.6539 157.151C47.7219 157.151 49.0149 157.508 50.4389 158.108C56.4549 160.645 64.793 167.564 68.276 170.581C68.8239 171.057 69.3683 171.538 69.9089 172.022C69.9089 172.022 74.319 176.608 76.985 176.608C77.599 176.608 78.1199 176.366 78.4729 175.768C80.364 172.58 60.9099 157.838 59.8129 151.755C59.0689 147.634 60.3349 145.546 62.6749 145.546C63.7879 145.546 65.1459 146.02 66.6449 146.971C71.2949 149.922 80.2729 165.35 83.5599 171.352C84.6619 173.363 86.5429 174.213 88.2379 174.213C91.6009 174.213 94.2299 170.87 88.5459 166.622C80.0029 160.23 83.001 149.782 87.078 149.139C87.252 149.111 87.4279 149.097 87.6029 149.097C91.3109 149.097 92.9459 155.486 92.9459 155.486C92.9459 155.486 97.7399 167.524 105.975 175.753C113.447 183.222 114.491 189.351 110.137 196.997ZM136.766 198.407L136.339 198.458L135.611 198.541C135.228 198.581 134.844 198.619 134.459 198.654L134.084 198.688L133.741 198.717L133.255 198.756L132.718 198.795L132.182 198.83L132.063 198.838C131.923 198.846 131.783 198.855 131.641 198.862L131.462 198.872C131.296 198.881 131.13 198.889 130.962 198.896L130.381 198.921L129.854 198.939L129.502 198.949H129.323C129.213 198.949 129.104 198.955 128.994 198.956H128.82C128.71 198.956 128.601 198.956 128.491 198.961L128.043 198.967H127.418C126.927 198.967 126.437 198.962 125.949 198.952L125.553 198.943C125.44 198.943 125.327 198.938 125.216 198.934L124.796 198.922L124.275 198.902L123.805 198.881L123.684 198.876L123.237 198.853C123.112 198.846 122.989 198.84 122.865 198.831L122.576 198.814C122.213 198.791 121.85 198.766 121.487 198.738L121.107 198.707C120.947 198.695 120.787 198.68 120.628 198.666C120.441 198.65 120.254 198.632 120.067 198.614C119.754 198.585 119.441 198.553 119.128 198.519H119.113C123.683 188.324 121.372 178.802 112.137 169.575C106.08 163.526 102.051 154.594 101.215 152.633C99.5229 146.828 95.045 140.375 87.608 140.375C86.979 140.375 86.351 140.425 85.73 140.523C82.472 141.036 79.624 142.911 77.592 145.733C75.396 143.002 73.262 140.831 71.332 139.605C68.422 137.76 65.5179 136.824 62.6889 136.824C59.1579 136.824 56.0019 138.274 53.8019 140.904L53.7459 140.971C53.7039 140.798 53.6639 140.625 53.6229 140.451L53.6179 140.428C53.1992 138.638 52.8477 136.833 52.5639 135.016C52.5639 135.004 52.5639 134.992 52.5579 134.98C52.5359 134.843 52.5159 134.705 52.4949 134.568C52.4334 134.162 52.3757 133.755 52.3219 133.348C52.2979 133.163 52.2719 132.978 52.2489 132.793L52.1809 132.238C52.1589 132.053 52.1409 131.885 52.1209 131.709L52.115 131.665C52.0351 130.945 51.9651 130.225 51.9049 129.503L51.8829 129.226L51.8479 128.754C51.8379 128.625 51.8279 128.495 51.8209 128.365C51.8209 128.334 51.8159 128.304 51.8149 128.275C51.7895 127.913 51.7678 127.55 51.7499 127.187C51.7399 126.998 51.7299 126.81 51.7219 126.62L51.7019 126.124L51.6969 125.974L51.6809 125.517L51.6709 125.128C51.6709 124.973 51.6629 124.818 51.6609 124.663C51.6579 124.508 51.6539 124.338 51.6529 124.174C51.6509 124.01 51.6529 123.848 51.6479 123.685C51.6439 123.521 51.6479 123.358 51.6479 123.195C51.6479 81.3421 85.5789 47.4111 127.436 47.4111C169.292 47.4111 203.222 81.3411 203.222 123.195V124.174C203.222 124.337 203.217 124.501 203.214 124.663C203.214 124.798 203.208 124.931 203.204 125.068C203.204 125.188 203.199 125.309 203.195 125.425C203.195 125.578 203.186 125.731 203.181 125.884V125.896L203.16 126.427C203.153 126.582 203.147 126.738 203.139 126.893L203.134 127.003L203.107 127.499C203.048 128.562 202.967 129.623 202.866 130.683V130.696C202.849 130.87 202.832 131.044 202.813 131.218L202.768 131.629L202.679 132.433L202.628 132.84L202.565 133.319C202.542 133.493 202.519 133.668 202.493 133.841C202.467 134.036 202.438 134.23 202.409 134.424L202.34 134.883L202.258 135.403C202.23 135.576 202.2 135.748 202.168 135.92C202.135 136.093 202.109 136.265 202.079 136.437C202.019 136.781 201.956 137.125 201.89 137.468C201.789 137.981 201.686 138.493 201.58 139.005L201.47 139.512C201.434 139.681 201.395 139.851 201.357 140.02C199.224 137.947 196.399 136.818 193.284 136.818C190.457 136.818 187.55 137.753 184.641 139.598C182.711 140.824 180.578 142.996 178.381 145.726C176.346 142.904 173.498 141.029 170.242 140.516C169.621 140.418 168.993 140.368 168.364 140.368C160.925 140.368 156.45 146.821 154.757 152.626C153.917 154.587 149.887 163.519 143.825 169.577C134.596 178.775 132.268 188.254 136.766 198.407ZM215.007 177.998L214.977 178.087C214.901 178.288 214.813 178.484 214.714 178.674C214.639 178.814 214.558 178.95 214.47 179.082C214.303 179.331 214.12 179.569 213.921 179.793C213.875 179.845 213.831 179.897 213.779 179.948C213.707 180.025 213.634 180.101 213.559 180.175C212.213 181.509 210.161 182.679 207.841 183.752C207.578 183.871 207.311 183.99 207.042 184.11L206.774 184.229C206.595 184.308 206.416 184.386 206.228 184.463C206.049 184.541 205.863 184.619 205.677 184.695L205.119 184.925C203.814 185.462 202.477 185.974 201.173 186.479L200.615 186.696L200.064 186.912C199.697 187.055 199.335 187.198 198.979 187.341L198.448 187.555L197.926 187.768L197.67 187.876C197.499 187.947 197.332 188.018 197.165 188.089C193.328 189.736 190.567 191.411 191.147 193.489C191.163 193.548 191.181 193.604 191.201 193.659C191.253 193.813 191.324 193.958 191.413 194.095C191.465 194.176 191.525 194.253 191.592 194.323C192.274 195.032 193.515 194.92 195.08 194.357C195.3 194.276 195.519 194.192 195.736 194.104L195.872 194.048C196.23 193.896 196.609 193.726 196.996 193.542C197.093 193.496 197.191 193.452 197.289 193.401C199.203 192.465 201.372 191.205 203.524 190.058C204.385 189.593 205.258 189.152 206.142 188.733C208.18 187.774 210.096 187.094 211.636 187.094C212.359 187.094 212.997 187.242 213.529 187.582L213.618 187.641C213.952 187.876 214.232 188.178 214.441 188.528C214.482 188.595 214.522 188.666 214.561 188.739C215.322 190.184 214.685 191.68 213.194 193.147C211.763 194.556 209.537 195.937 207.007 197.215C206.819 197.31 206.631 197.405 206.44 197.498C198.91 201.196 189.049 203.981 188.912 204.016C186.284 204.697 182.526 205.591 178.292 206.26L177.666 206.358L177.563 206.373C177.089 206.445 176.614 206.512 176.138 206.574C175.655 206.639 175.167 206.698 174.676 206.753L174.586 206.763C172.806 206.968 171.019 207.104 169.228 207.169H169.202C168.554 207.192 167.907 207.204 167.259 207.204H166.512C165.524 207.191 164.538 207.146 163.553 207.07C163.53 207.07 163.505 207.07 163.482 207.064C163.129 207.037 162.777 207.004 162.425 206.965C162.06 206.926 161.696 206.882 161.333 206.833C161.094 206.801 160.856 206.765 160.618 206.726C160.376 206.687 160.134 206.647 159.893 206.605L159.564 206.543L159.539 206.538C159.192 206.472 158.847 206.399 158.503 206.319C158.303 206.274 158.104 206.23 157.907 206.176L157.788 206.146C157.69 206.122 157.595 206.096 157.498 206.07L157.445 206.056L157.137 205.966C157.025 205.935 156.913 205.901 156.801 205.868L156.762 205.857L156.471 205.768C156.361 205.734 156.251 205.698 156.142 205.662L155.874 205.573L155.677 205.504C155.487 205.437 155.298 205.368 155.111 205.296L154.933 205.226L154.786 205.168C154.502 205.054 154.22 204.935 153.941 204.81L153.756 204.72L153.725 204.706C153.659 204.675 153.594 204.644 153.528 204.617C153.399 204.555 153.271 204.491 153.144 204.426L153.105 204.407L152.921 204.31C152.594 204.139 152.274 203.957 151.96 203.764L151.788 203.658C151.702 203.605 151.616 203.55 151.532 203.494L151.308 203.346L151.067 203.18L150.923 203.077C150.771 202.969 150.622 202.857 150.476 202.742L150.243 202.563C150.15 202.488 150.058 202.412 149.967 202.335C149.89 202.272 149.815 202.206 149.74 202.14L149.734 202.135C149.653 202.064 149.574 201.993 149.495 201.92C149.417 201.849 149.339 201.777 149.263 201.704L149.254 201.695C149.174 201.619 149.096 201.542 149.019 201.463C148.942 201.385 148.863 201.307 148.788 201.227C148.713 201.148 148.636 201.067 148.562 200.984C148.488 200.902 148.42 200.827 148.35 200.746L148.327 200.719C148.259 200.641 148.192 200.562 148.126 200.481C147.983 200.31 147.844 200.135 147.71 199.956C147.575 199.776 147.443 199.592 147.314 199.405L147.191 199.221C147.027 198.981 146.867 198.739 146.712 198.493C146.596 198.316 146.483 198.138 146.373 197.957C146.302 197.844 146.234 197.73 146.166 197.618L146.138 197.572C146.073 197.462 146.009 197.354 145.947 197.245C145.911 197.186 145.877 197.127 145.845 197.066C145.812 197.004 145.774 196.941 145.739 196.878L145.682 196.779L145.647 196.715C145.58 196.595 145.514 196.474 145.45 196.352C145.42 196.298 145.391 196.244 145.36 196.192L145.271 196.019L145.181 195.848C144.956 195.398 144.743 194.942 144.543 194.48L144.472 194.311C144.426 194.198 144.383 194.086 144.337 193.975C144.315 193.921 144.293 193.868 144.274 193.814C144.167 193.537 144.067 193.257 143.975 192.975C143.942 192.874 143.91 192.775 143.88 192.675C143.808 192.448 143.743 192.219 143.685 191.988C143.614 191.719 143.551 191.448 143.498 191.175C143.487 191.12 143.476 191.065 143.467 191.012C143.415 190.745 143.373 190.476 143.34 190.206C143.332 190.153 143.326 190.1 143.32 190.047L143.303 189.885C143.281 189.673 143.264 189.46 143.254 189.247C143.254 189.193 143.249 189.139 143.247 189.087C143.242 188.981 143.24 188.875 143.239 188.769C143.183 184.496 145.345 180.388 149.968 175.767C158.203 167.54 162.997 155.501 162.997 155.501C162.997 155.501 163.126 154.996 163.394 154.269C163.431 154.168 163.47 154.064 163.514 153.955C163.67 153.548 163.846 153.148 164.041 152.758L164.08 152.683C164.246 152.351 164.428 152.027 164.624 151.712C164.67 151.639 164.714 151.567 164.765 151.494C164.912 151.277 165.067 151.065 165.23 150.86C165.319 150.749 165.416 150.639 165.513 150.532C165.552 150.49 165.59 150.448 165.631 150.408C166.108 149.915 166.653 149.513 167.27 149.299L167.348 149.273C167.4 149.256 167.452 149.24 167.505 149.225C167.566 149.209 167.627 149.195 167.69 149.182L167.719 149.176C167.849 149.15 167.981 149.133 168.114 149.124H168.125C168.194 149.124 168.264 149.117 168.335 149.117C168.424 149.117 168.507 149.117 168.594 149.126C168.684 149.134 168.773 149.144 168.863 149.158C169.605 149.276 170.311 149.718 170.919 150.4C171.15 150.66 171.358 150.94 171.54 151.236C171.66 151.428 171.773 151.631 171.88 151.845C171.923 151.934 171.964 152.016 172.004 152.104C172.108 152.33 172.202 152.56 172.284 152.795C172.479 153.345 172.626 153.911 172.723 154.487C172.807 154.992 172.857 155.502 172.873 156.013C172.881 156.286 172.881 156.563 172.873 156.842C172.819 158.14 172.553 159.421 172.086 160.634C172.044 160.745 171.997 160.857 171.952 160.969C171.86 161.195 171.759 161.417 171.65 161.634C171.569 161.799 171.484 161.965 171.392 162.13C171.332 162.24 171.269 162.35 171.206 162.46C171.045 162.734 170.871 163.006 170.684 163.277L170.571 163.439C170.129 164.055 169.637 164.633 169.099 165.167C168.569 165.698 168.001 166.189 167.4 166.637C166.798 167.083 166.233 167.577 165.711 168.114C164.208 169.691 163.858 171.083 164.196 172.138C164.25 172.304 164.321 172.465 164.407 172.617C164.508 172.791 164.628 172.951 164.764 173.097L164.817 173.152L164.871 173.206C164.925 173.258 164.982 173.309 165.043 173.359L165.103 173.407C165.248 173.519 165.402 173.619 165.563 173.707C165.61 173.732 165.652 173.757 165.705 173.781C165.879 173.866 166.058 173.939 166.242 173.998C166.293 174.015 166.344 174.03 166.396 174.046L166.461 174.063L166.551 174.087L166.628 174.106L166.712 174.124L166.795 174.141L166.874 174.154C166.932 174.164 166.992 174.174 167.052 174.181L167.109 174.19L167.213 174.2L167.277 174.207L167.382 174.214H167.444L167.554 174.22H167.9L167.999 174.214L168.113 174.207L168.252 174.194L168.382 174.179C168.412 174.179 168.442 174.171 168.472 174.165C168.872 174.107 169.264 174.001 169.639 173.849L169.798 173.782C169.887 173.743 169.977 173.702 170.059 173.658C170.235 173.57 170.406 173.47 170.57 173.361C170.799 173.211 171.015 173.043 171.217 172.858C171.265 172.815 171.312 172.769 171.358 172.725C171.381 172.703 171.403 172.682 171.425 172.658C171.469 172.613 171.514 172.569 171.558 172.52C171.878 172.168 172.155 171.78 172.383 171.363C174.34 167.804 176.391 164.298 178.534 160.849L178.828 160.378L179.125 159.907C179.273 159.668 179.423 159.433 179.572 159.199L179.722 158.965C180.22 158.185 180.726 157.41 181.241 156.641L181.546 156.185C182.158 155.278 182.768 154.396 183.373 153.558L183.674 153.143C184.332 152.236 185.017 151.348 185.728 150.482L186.01 150.144C186.057 150.088 186.1 150.032 186.151 149.978C186.244 149.868 186.337 149.761 186.428 149.657C186.474 149.604 186.517 149.552 186.566 149.5L186.834 149.198L186.968 149.051C187.103 148.906 187.235 148.767 187.365 148.634C187.455 148.544 187.538 148.455 187.624 148.371C188.131 147.853 188.69 147.388 189.293 146.985L189.433 146.895C189.567 146.805 189.706 146.721 189.848 146.645C192.212 145.303 194.169 145.204 195.296 146.331C195.978 147.013 196.356 148.144 196.335 149.718C196.335 149.787 196.335 149.857 196.33 149.929V150.006C196.33 150.078 196.324 150.15 196.318 150.223C196.318 150.313 196.308 150.402 196.299 150.492C196.29 150.581 196.285 150.649 196.276 150.729C196.276 150.751 196.272 150.774 196.268 150.798C196.262 150.867 196.253 150.938 196.243 151.009C196.243 151.03 196.243 151.052 196.235 151.074C196.224 151.169 196.21 151.263 196.194 151.357C196.183 151.447 196.168 151.531 196.152 151.619L196.126 151.768C196.1 151.91 196.067 152.05 196.026 152.188C195.948 152.447 195.854 152.7 195.743 152.946C195.588 153.284 195.417 153.613 195.229 153.933C195.125 154.111 195.018 154.286 194.907 154.459C194.793 154.638 194.673 154.819 194.549 155.002C194.233 155.454 193.905 155.897 193.564 156.33L193.408 156.527C192.852 157.22 192.278 157.899 191.686 158.562L191.499 158.772C191.247 159.053 190.991 159.336 190.729 159.62L190.532 159.834C190.401 159.977 190.264 160.12 190.132 160.264C190.001 160.407 189.864 160.552 189.726 160.697L189.315 161.13L188.898 161.566L188.478 162.002C188.196 162.294 187.913 162.586 187.628 162.878C183.573 167.037 179.301 171.182 177.855 173.766C177.758 173.934 177.671 174.108 177.593 174.285C177.387 174.755 177.301 175.157 177.36 175.482C177.379 175.589 177.416 175.691 177.471 175.785C177.552 175.926 177.651 176.056 177.766 176.172C177.819 176.224 177.875 176.272 177.934 176.316C178.232 176.528 178.591 176.637 178.957 176.627H179.071L179.188 176.618L179.305 176.605L179.402 176.591C179.415 176.589 179.429 176.587 179.442 176.583L179.531 176.566L179.554 176.561L179.653 176.54L179.688 176.531C179.723 176.522 179.757 176.513 179.792 176.503C179.827 176.493 179.875 176.48 179.917 176.466C180.093 176.413 180.265 176.35 180.434 176.278C180.523 176.242 180.61 176.203 180.696 176.161C180.741 176.141 180.786 176.12 180.828 176.098L180.962 176.032C181.282 175.866 181.594 175.685 181.898 175.491L182.031 175.401C182.076 175.373 182.121 175.344 182.164 175.312L182.297 175.223L182.368 175.174L182.56 175.039C182.739 174.916 182.906 174.789 183.075 174.66L183.09 174.648L183.359 174.44C183.726 174.15 184.074 173.858 184.39 173.583L184.6 173.399L184.619 173.381L184.729 173.284C184.987 173.052 185.217 172.836 185.408 172.658L185.487 172.581C185.556 172.516 185.619 172.455 185.676 172.403L185.788 172.292L185.828 172.253L185.839 172.242L185.956 172.125L186.03 172.048L186.039 172.041L186.074 172.009L186.118 171.969L186.132 171.956L186.169 171.922L186.373 171.743L186.487 171.641C186.548 171.588 186.607 171.534 186.666 171.479L186.802 171.358C186.827 171.338 186.851 171.316 186.876 171.294L187.019 171.169L187.229 170.984L187.341 170.887C187.776 170.509 188.305 170.052 188.913 169.537L189.162 169.326L189.573 168.981L189.994 168.63C190.544 168.173 191.136 167.688 191.762 167.185L192.173 166.855C192.523 166.576 192.882 166.292 193.246 166.006C193.393 165.891 193.542 165.776 193.694 165.662C194.066 165.373 194.44 165.086 194.817 164.803C195.675 164.155 196.56 163.506 197.456 162.874L197.84 162.606C198.109 162.421 198.377 162.235 198.645 162.054L198.888 161.89C199.367 161.565 199.853 161.248 200.343 160.939L200.586 160.786L200.827 160.636C201.069 160.486 201.309 160.339 201.548 160.196L201.787 160.053L202.265 159.775L202.734 159.506L202.829 159.454L203.2 159.25C203.355 159.166 203.509 159.085 203.663 159.006L203.892 158.888L204.115 158.776C204.193 158.739 204.27 158.7 204.346 158.663C204.848 158.415 205.36 158.187 205.88 157.979C206.021 157.919 206.161 157.865 206.3 157.818L206.71 157.674C206.833 157.633 206.953 157.594 207.068 157.559L207.108 157.547C207.17 157.527 207.232 157.509 207.293 157.493L207.311 157.488C207.439 157.451 207.566 157.419 207.691 157.389H207.7C208.054 157.304 208.414 157.243 208.777 157.206C208.944 157.189 209.111 157.18 209.279 157.181H209.363C209.475 157.181 209.583 157.188 209.69 157.199C209.739 157.199 209.788 157.209 209.836 157.215H209.856C209.904 157.221 209.952 157.228 210 157.239C210.047 157.248 210.095 157.256 210.141 157.267H210.156C210.203 157.277 210.245 157.289 210.294 157.303C210.548 157.374 210.79 157.484 211.012 157.628C211.121 157.699 211.223 157.779 211.317 157.868L211.344 157.894C211.362 157.91 211.379 157.927 211.395 157.944L211.444 157.997C211.846 158.418 212.178 158.901 212.428 159.427L212.466 159.517C212.551 159.717 212.618 159.924 212.666 160.135C212.808 160.781 212.753 161.455 212.508 162.07C212.415 162.318 212.302 162.557 212.169 162.785C211.858 163.309 211.489 163.796 211.07 164.237L210.981 164.332C210.848 164.472 210.71 164.612 210.565 164.752C210.501 164.815 210.434 164.877 210.367 164.94L210.162 165.129L210.055 165.224C209.797 165.454 209.532 165.677 209.263 165.893C209.1 166.025 208.936 166.154 208.77 166.281C208.184 166.729 207.587 167.161 206.979 167.578C206.612 167.83 206.242 168.077 205.869 168.321C204.95 168.924 204.021 169.512 203.083 170.084C201.115 171.294 198.934 172.588 196.609 173.995L196.007 174.36C195.348 174.762 194.726 175.146 194.14 175.512L193.845 175.697L193.287 176.055C192.917 176.292 192.548 176.531 192.179 176.77L191.882 176.966C191.737 177.06 191.593 177.156 191.449 177.252L191.308 177.342L190.876 177.633L190.647 177.79L190.379 177.976L190.13 178.149C189.713 178.444 189.325 178.725 188.968 178.992L188.834 179.094C188.624 179.253 188.416 179.415 188.211 179.58C187.902 179.829 187.62 180.067 187.367 180.296L187.243 180.409C187.172 180.474 187.102 180.539 187.035 180.603C186.989 180.648 186.946 180.693 186.898 180.736L186.834 180.8C186.691 180.944 186.551 181.091 186.416 181.242L186.35 181.318C186.203 181.488 186.075 181.651 185.963 181.81L185.913 181.881C185.825 182.009 185.744 182.141 185.671 182.277C185.652 182.311 185.635 182.345 185.618 182.379L185.569 182.481L185.536 182.555L185.515 182.605L185.498 182.65L185.475 182.711C185.413 182.88 185.37 183.056 185.345 183.234L185.337 183.296L185.331 183.354V183.669C185.331 183.695 185.331 183.721 185.338 183.749L185.343 183.797C185.343 183.823 185.349 183.848 185.353 183.876C185.357 183.902 185.364 183.949 185.372 183.986V183.991C185.379 184.026 185.386 184.06 185.395 184.095C185.404 184.13 185.413 184.17 185.424 184.206C185.443 184.277 185.467 184.347 185.492 184.417C185.508 184.459 185.523 184.5 185.54 184.541C185.54 184.549 185.546 184.558 185.55 184.566L185.586 184.647L185.636 184.758C185.69 184.873 185.749 184.985 185.813 185.094L185.879 185.208L185.947 185.322C185.959 185.341 185.973 185.359 185.988 185.376L186.01 185.399L186.035 185.422L186.061 185.442C186.099 185.469 186.14 185.49 186.183 185.505C186.206 185.513 186.23 185.519 186.254 185.525C186.831 185.655 188.017 185.178 189.593 184.346C189.682 184.298 189.78 184.248 189.875 184.196L190.355 183.934L190.589 183.804C190.756 183.715 190.926 183.614 191.1 183.515L191.417 183.336C193.5 182.137 195.988 180.597 198.56 179.093C198.801 178.952 199.043 178.811 199.285 178.672L199.771 178.361C200.335 178.038 200.902 177.719 201.471 177.404C202.188 177.01 202.91 176.626 203.639 176.254L204.115 176.013C204.431 175.857 204.744 175.705 205.053 175.557C205.651 175.273 206.256 175.003 206.868 174.748L207.203 174.612L207.243 174.596C209.018 173.893 210.627 173.459 211.929 173.459C212.21 173.456 212.492 173.48 212.769 173.528H212.778C212.867 173.544 212.948 173.562 213.031 173.582H213.046C213.259 173.636 213.466 173.713 213.662 173.812C213.937 173.954 214.184 174.143 214.393 174.371C214.489 174.477 214.574 174.592 214.649 174.714C214.789 174.929 214.899 175.162 214.978 175.406C215.01 175.501 215.038 175.594 215.067 175.693C215.278 176.45 215.257 177.253 215.007 177.998Z" fill="#FF9D00"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M203.21 123.685V123.194C203.21 81.34 169.292 47.411 127.435 47.411C85.5791 47.411 51.648 81.342 51.648 123.194V123.358C51.646 123.467 51.645 123.576 51.648 123.685C51.6529 123.848 51.6546 124.011 51.653 124.174L51.6581 124.534L51.661 124.663C51.661 124.723 51.6631 124.782 51.6651 124.842C51.6681 124.937 51.67 125.033 51.67 125.128L51.681 125.517L51.697 125.974L51.702 126.124L51.722 126.597V126.62C51.73 126.805 51.7401 126.989 51.7491 127.173L51.75 127.187C51.76 127.375 51.7701 127.564 51.7821 127.753C51.7921 127.927 51.802 128.101 51.815 128.275L51.8171 128.306C51.8258 128.455 51.8358 128.605 51.847 128.754L51.85 128.794L51.883 129.226L51.8861 129.254C51.8921 129.338 51.898 129.422 51.906 129.503C51.9658 130.224 52.0355 130.945 52.1151 131.664L52.12 131.709L52.181 132.238L52.2491 132.793L52.299 133.17L52.322 133.347C52.3753 133.755 52.433 134.162 52.495 134.568L52.4991 134.595L52.558 134.979C52.8435 136.808 53.1971 138.626 53.618 140.429L53.6231 140.451L53.655 140.586L53.746 140.971L53.802 140.904C56.002 138.274 59.158 136.824 62.689 136.824C65.519 136.824 68.4221 137.76 71.3321 139.605C73.2621 140.831 75.3961 143.002 77.5921 145.733C79.6241 142.911 82.4721 141.035 85.7301 140.523C86.3513 140.425 86.9792 140.376 87.6081 140.375C95.0441 140.375 99.523 146.828 101.215 152.633C102.051 154.594 106.08 163.526 112.156 169.568C121.392 178.795 123.703 188.316 119.132 198.511H119.148C119.459 198.546 119.772 198.578 120.087 198.607C120.274 198.625 120.46 198.643 120.648 198.659L120.714 198.665L121.127 198.7L121.507 198.73C121.869 198.758 122.232 198.784 122.596 198.807L122.885 198.824L123.114 198.838L123.256 198.846L123.703 198.869L123.825 198.874L124.294 198.895L124.816 198.915L125.235 198.927L125.305 198.929C125.394 198.933 125.483 198.936 125.572 198.936L125.668 198.939C126.258 198.953 126.847 198.96 127.437 198.959H128.063L128.51 198.954C128.62 198.949 128.729 198.949 128.84 198.949H129.014L129.165 198.945C129.224 198.943 129.283 198.941 129.343 198.941H129.522L129.873 198.932L130.401 198.914L130.982 198.888C131.15 198.882 131.316 198.873 131.482 198.865L131.661 198.854L131.927 198.84L132.083 198.831L132.201 198.823L132.738 198.788L133.274 198.749L133.761 198.71L134.103 198.681L134.479 198.647C135.107 198.591 135.733 198.525 136.359 198.45L136.786 198.399C132.287 188.247 134.616 178.767 143.813 169.577C149.876 163.519 153.905 154.587 154.745 152.625C156.438 146.821 160.914 140.368 168.352 140.368C168.981 140.368 169.61 140.418 170.231 140.516C173.486 141.028 176.334 142.904 178.369 145.726C180.566 142.996 182.699 140.823 184.63 139.597C187.539 137.753 190.445 136.817 193.272 136.817C196.388 136.817 199.212 137.947 201.345 140.02C201.384 139.851 201.422 139.682 201.459 139.512L201.568 139.006C201.607 138.821 201.646 138.636 201.683 138.451C201.749 138.124 201.815 137.797 201.878 137.467C201.944 137.125 202.007 136.781 202.067 136.437L202.098 136.251C202.117 136.141 202.135 136.031 202.156 135.92C202.19 135.748 202.218 135.576 202.246 135.402L202.257 135.336L202.328 134.883L202.398 134.424V134.42C202.449 134.081 202.497 133.742 202.542 133.403L202.553 133.319L202.616 132.841L202.667 132.433L202.757 131.629L202.792 131.306L202.801 131.218C202.82 131.044 202.838 130.87 202.854 130.696V130.682C202.867 130.544 202.881 130.405 202.893 130.266C202.964 129.478 203.024 128.686 203.072 127.891C203.081 127.761 203.088 127.63 203.096 127.499V127.493L203.122 127.002L203.128 126.892C203.144 126.56 203.158 126.228 203.169 125.896V125.884L203.174 125.754C203.179 125.645 203.183 125.535 203.183 125.425L203.185 125.381C203.189 125.278 203.193 125.172 203.193 125.067L203.196 124.977C203.199 124.872 203.202 124.768 203.202 124.663L203.204 124.574C203.207 124.441 203.21 124.307 203.21 124.174V123.685ZM108.638 199.391C114.64 190.59 114.214 183.984 105.98 175.754C97.7441 167.523 92.951 155.487 92.951 155.487C92.951 155.487 91.1621 148.496 87.0821 149.138C83.0021 149.78 80.0091 160.227 88.5521 166.622C97.0941 173.017 86.8521 177.353 83.5641 171.352C80.2761 165.35 71.299 149.923 66.645 146.972C61.991 144.021 58.718 145.675 59.815 151.757C60.36 154.776 65.4281 159.929 70.1631 164.743C74.9671 169.627 79.428 174.163 78.474 175.768C76.581 178.955 69.9141 172.023 69.9141 172.023C69.9141 172.023 49.038 153.025 44.494 157.976C40.304 162.539 46.765 166.418 56.7211 172.397C57.5671 172.905 58.4391 173.429 59.3321 173.969C70.7231 180.865 71.609 182.684 69.992 185.293C69.395 186.257 65.582 183.968 60.892 181.153C52.897 176.352 42.3551 170.023 40.8661 175.688C39.5781 180.591 47.334 183.595 54.368 186.32C60.228 188.59 65.5881 190.666 64.7991 193.484C63.9821 196.406 59.5531 193.969 54.7121 191.305C49.2771 188.314 43.3221 185.038 41.3731 188.735C37.6901 195.725 66.7831 203.954 67.0231 204.015C76.4231 206.453 100.295 211.619 108.638 199.391ZM147.303 199.391C141.301 190.59 141.727 183.984 149.962 175.754C158.197 167.523 162.99 155.487 162.99 155.487C162.99 155.487 164.779 148.496 168.859 149.138C172.939 149.78 175.932 160.227 167.39 166.622C158.847 173.017 169.089 177.353 172.377 171.352C175.666 165.35 184.637 149.923 189.291 146.972C193.945 144.021 197.22 145.675 196.122 151.757C195.578 154.776 190.509 159.929 185.774 164.744C180.97 169.628 176.509 174.163 177.462 175.768C179.355 178.955 186.027 172.019 186.027 172.019C186.027 172.019 206.902 153.022 211.448 157.973C215.637 162.535 209.176 166.415 199.219 172.394C198.348 172.917 197.478 173.441 196.609 173.966C185.218 180.862 184.332 182.681 185.948 185.289C186.546 186.254 190.359 183.964 195.048 181.149C203.044 176.349 213.586 170.019 215.075 175.685C216.364 180.588 208.607 183.592 201.573 186.317C195.713 188.587 190.353 190.663 191.141 193.481C191.957 196.402 196.385 193.965 201.225 191.301C206.66 188.31 212.616 185.032 214.564 188.732C218.248 195.726 189.15 203.947 188.915 204.007C179.515 206.453 155.643 211.619 147.303 199.391Z" fill="#FFD21E"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M152.047 102.567C153.229 102.985 154.108 104.257 154.944 105.468C156.074 107.104 157.126 108.627 158.74 107.769C160.644 106.756 162.205 105.202 163.225 103.302C164.246 101.402 164.681 99.2427 164.475 97.096C164.321 95.4908 163.813 93.9398 162.987 92.5548C162.161 91.1697 161.038 89.985 159.7 89.0862C158.361 88.1874 156.839 87.5968 155.245 87.3569C153.65 87.117 152.022 87.2339 150.478 87.699C148.934 88.1639 147.513 88.9653 146.316 90.0455C145.119 91.1257 144.176 92.4578 143.556 93.946C142.936 95.4342 142.653 97.0415 142.728 98.652C142.804 100.263 143.235 101.836 143.992 103.26C144.74 104.667 146.4 104.003 148.152 103.302C149.525 102.753 150.956 102.181 152.047 102.567ZM100.672 102.567C99.49 102.985 98.611 104.258 97.775 105.468C96.645 107.105 95.592 108.627 93.979 107.769C91.5845 106.501 89.7482 104.386 88.8278 101.838C87.9075 99.2895 87.9692 96.4896 89.0008 93.9841C90.0324 91.4786 91.9601 89.4471 94.408 88.2855C96.856 87.1239 99.6488 86.9156 102.242 87.701C104.307 88.3228 106.141 89.5427 107.513 91.2065C108.885 92.8704 109.732 94.9035 109.949 97.049C110.165 99.1945 109.74 101.356 108.728 103.26C107.979 104.667 106.319 104.003 104.567 103.303C103.193 102.753 101.764 102.181 100.672 102.567ZM144.099 149.318C152.242 142.903 155.233 132.429 155.233 125.977C155.233 120.877 151.802 122.482 146.309 125.202L145.999 125.355C140.957 127.852 134.245 131.177 126.877 131.177C119.508 131.177 112.796 127.852 107.755 125.354C102.084 122.545 98.527 120.783 98.527 125.978C98.527 132.634 101.709 143.563 110.443 149.912C111.596 147.573 113.219 145.497 115.211 143.813C117.202 142.129 119.52 140.874 122.018 140.126C122.89 139.866 123.788 141.367 124.707 142.904C125.594 144.386 126.501 145.902 127.423 145.902C128.406 145.902 129.371 144.408 130.314 142.95C131.299 141.425 132.26 139.94 133.189 140.237C137.864 141.738 141.775 144.993 144.099 149.318Z" fill="#32343D"/>
+<path d="M144.097 149.317C139.856 152.659 134.219 154.9 126.878 154.9C119.981 154.9 114.587 152.922 110.443 149.911C111.596 147.572 113.219 145.495 115.211 143.812C117.202 142.128 119.52 140.873 122.018 140.125C123.73 139.614 125.545 145.901 127.423 145.901C129.433 145.901 131.37 139.655 133.189 140.236C137.863 141.738 141.773 144.993 144.097 149.317Z" fill="#FF323D"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M81.2 111.64C80.2312 112.288 79.1173 112.687 77.9572 112.801C76.7971 112.916 75.6267 112.742 74.55 112.295C73.6893 111.94 72.9072 111.418 72.2488 110.759C71.5903 110.101 71.0684 109.319 70.713 108.458C70.267 107.381 70.0935 106.211 70.2082 105.051C70.3228 103.891 70.7219 102.777 71.37 101.808C72.1488 100.642 73.2558 99.7333 74.5512 99.1967C75.8466 98.6601 77.272 98.5197 78.6471 98.7935C80.0223 99.0672 81.2853 99.7427 82.2764 100.734C83.2675 101.726 83.9422 102.99 84.215 104.365C84.4883 105.74 84.3477 107.165 83.8113 108.46C83.2748 109.755 82.3654 110.861 81.2 111.64ZM182.613 111.64C181.644 112.288 180.53 112.687 179.37 112.801C178.209 112.916 177.039 112.742 175.962 112.295C175.101 111.939 174.319 111.418 173.661 110.759C173.003 110.101 172.481 109.319 172.125 108.458C171.68 107.381 171.507 106.211 171.621 105.051C171.736 103.891 172.135 102.777 172.782 101.808C173.364 100.936 174.133 100.205 175.032 99.6658C175.931 99.1269 176.938 98.7942 177.981 98.6917C179.025 98.5891 180.078 98.7193 181.064 99.0728C182.051 99.4264 182.947 99.9944 183.688 100.736C184.68 101.727 185.355 102.99 185.628 104.365C185.902 105.74 185.761 107.165 185.224 108.46C184.687 109.755 183.779 110.861 182.613 111.64Z" fill="#FFAD03"/>
+</svg>
diff --git a/doc/images/initial_model_screen.png b/doc/images/initial_model_screen.png
new file mode 100644
index 0000000000000000000000000000000000000000..b01c4248a6915a5253fbec778477bf3b1498f5cc
GIT binary patch
literal 34596
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
S1L$ksU{Yf8qSe9%0sjvo9p`%h

literal 0
HcmV?d00001

diff --git a/doc/tutorials_custom_index.rst b/doc/tutorials_custom_index.rst
index 4c7625d811..82f2c06eed 100644
--- a/doc/tutorials_custom_index.rst
+++ b/doc/tutorials_custom_index.rst
@@ -119,8 +119,8 @@ The :code:`spikeinterface.qualitymetrics` module allows users to compute various
 
    .. grid-item-card:: Quality Metrics
       :link-type: ref
-      :link: sphx_glr_tutorials_qualitymetrics_plot_3_quality_mertics.py
-      :img-top: /tutorials/qualitymetrics/images/thumb/sphx_glr_plot_3_quality_mertics_thumb.png
+      :link: sphx_glr_tutorials_qualitymetrics_plot_3_quality_metrics.py
+      :img-top: /tutorials/qualitymetrics/images/thumb/sphx_glr_plot_3_quality_metrics_thumb.png
       :img-alt: Quality Metrics
       :class-card: gallery-card
       :text-align: center
@@ -133,6 +133,39 @@ The :code:`spikeinterface.qualitymetrics` module allows users to compute various
       :class-card: gallery-card
       :text-align: center
 
+Automated curation tutorials
+----------------------------
+
+Learn how to curate your units using a trained machine learning model. Or how to create
+and share your own model.
+
+.. grid:: 1 2 2 3
+   :gutter: 2
+
+   .. grid-item-card:: Model-based curation
+      :link-type: ref
+      :link: sphx_glr_tutorials_curation_plot_1_automated_curation.py
+      :img-top: /tutorials/curation/images/sphx_glr_plot_1_automated_curation_002.png
+      :img-alt: Model-based curation
+      :class-card: gallery-card
+      :text-align: center
+
+   .. grid-item-card:: Train your own model
+      :link-type: ref
+      :link: sphx_glr_tutorials_curation_plot_2_train_a_model.py
+      :img-top: /tutorials/curation/images/thumb/sphx_glr_plot_2_train_a_model_thumb.png
+      :img-alt: Train your own model
+      :class-card: gallery-card
+      :text-align: center
+
+   .. grid-item-card:: Upload your model to HuggingFaceHub
+      :link-type: ref
+      :link: sphx_glr_tutorials_curation_plot_3_upload_a_model.py
+      :img-top: /images/hf-logo.svg
+      :img-alt: Upload your model
+      :class-card: gallery-card
+      :text-align: center
+
 Comparison tutorial
 -------------------
 
diff --git a/examples/tutorials/curation/README.rst b/examples/tutorials/curation/README.rst
new file mode 100644
index 0000000000..0f64179e65
--- /dev/null
+++ b/examples/tutorials/curation/README.rst
@@ -0,0 +1,5 @@
+Curation tutorials
+------------------
+
+Learn how to use models to automatically curated your sorted data, or generate models
+based on your own curation.
diff --git a/examples/tutorials/curation/plot_1_automated_curation.py b/examples/tutorials/curation/plot_1_automated_curation.py
new file mode 100644
index 0000000000..e88b0973df
--- /dev/null
+++ b/examples/tutorials/curation/plot_1_automated_curation.py
@@ -0,0 +1,287 @@
+"""
+Model-based curation tutorial
+=============================
+
+Sorters are not perfect. They output excellent units, as well as noisy ones, and ones that
+should be split or merged. Hence one should curate the generated units. Historically, this
+has been done using laborious manual curation. An alternative is to use automated methods
+based on metrics which quantify features of the units. In spikeinterface these are the
+quality metrics and the template metrics. A simple approach is to use thresholding:
+only accept units whose metrics pass a certain quality threshold. Another approach is to
+take one (or more) manually labelled sortings, whose metrics have been computed, and train
+a machine learning model to predict labels.
+
+This notebook provides a step-by-step guide on how to take a machine learning model that
+someone else has trained and use it to curate your own spike sorted output. SpikeInterface
+also provides the tools to train your own model,
+`which you can learn about here <https://spikeinterface.readthedocs.io/en/latest/tutorials/curation/plot_2_train_a_model.html>`_.
+
+We'll download a toy model and use it to label our sorted data. We start by importing some packages
+"""
+
+import warnings
+warnings.filterwarnings("ignore")
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+
+import spikeinterface.core as si
+import spikeinterface.curation as sc
+import spikeinterface.widgets as sw
+
+# note: you can use more cores using e.g.
+# si.set_global_jobs_kwargs(n_jobs = 8)
+
+##############################################################################
+# Download a pretrained model
+# ---------------------------
+#
+# Let's download a pretrained model from `Hugging Face <https://huggingface.co/>`_ (HF),
+# a model sharing platform focused on AI and ML models and datasets. The
+# ``load_model`` function allows us to download directly from HF, or use a model in a local
+# folder. The function downloads the model and saves it in a temporary folder and returns a
+# model and some metadata about the model.
+
+model, model_info = sc.load_model(
+    repo_id = "SpikeInterface/toy_tetrode_model",
+    trusted = ['numpy.dtype']
+)
+
+
+##############################################################################
+# This model was trained on artifically generated tetrode data. There are also models trained
+# on real data, like the one discussed `below <#A-model-trained-on-real-Neuropixels-data>`_.
+# Each model object has a nice html representation, which will appear if you're using a Jupyter notebook.
+
+model
+
+##############################################################################
+# This tells us more information about the model. The one we've just downloaded was trained used
+# a ``RandomForestClassifier```. You can also discover this information by running
+# ``model.get_params()``. The model object (an `sklearn Pipeline <https://scikit-learn.org/1.5/modules/generated/sklearn.pipeline.Pipeline.html>`_) also contains information
+# about which metrics were used to compute the model. We can access it from the model (or from the model_info)
+
+print(model.feature_names_in_)
+
+##############################################################################
+# Hence, to use this model we need to create a ``sorting_analyzer`` with all these metrics computed.
+# We'll do this by generating a recording and sorting, creating a sorting analyzer and computing a
+# bunch of extensions. Follow these links for more info on `recordings <https://spikeinterface.readthedocs.io/en/latest/modules/extractors.html>`_, `sortings <https://spikeinterface.readthedocs.io/en/latest/modules/sorters.html>`_, `sorting analyzers <https://spikeinterface.readthedocs.io/en/latest/tutorials/core/plot_4_sorting_analyzer.html#sphx-glr-tutorials-core-plot-4-sorting-analyzer-py>`_
+# and `extensions <https://spikeinterface.readthedocs.io/en/latest/modules/postprocessing.html>`_.
+
+recording, sorting = si.generate_ground_truth_recording(num_channels=4, seed=4, num_units=10)
+sorting_analyzer = si.create_sorting_analyzer(sorting=sorting, recording=recording)
+sorting_analyzer.compute(['noise_levels','random_spikes','waveforms','templates','spike_locations','spike_amplitudes','correlograms','principal_components','quality_metrics','template_metrics'])
+sorting_analyzer.compute('template_metrics', include_multi_channel_metrics=True)
+
+##############################################################################
+# This sorting_analyzer now contains the required quality metrics and template metrics.
+# We can check that this is true by accessing the extension data.
+
+all_metric_names = list(sorting_analyzer.get_extension('quality_metrics').get_data().keys()) + list(sorting_analyzer.get_extension('template_metrics').get_data().keys())
+print(set(all_metric_names) == set(model.feature_names_in_))
+
+##############################################################################
+# Great! We can now use the model to predict labels. Here, we pass the HF repo id directly
+# to the ``auto_label_units`` function. This returns a dictionary containing a label and
+# a confidence for each unit contained in the ``sorting_analyzer``.
+
+labels = sc.auto_label_units(
+    sorting_analyzer = sorting_analyzer,
+    repo_id = "SpikeInterface/toy_tetrode_model",
+    trusted = ['numpy.dtype']
+)
+
+print(labels)
+
+
+##############################################################################
+# The model has labelled one unit as bad. Let's look at that one, and also the 'good' unit
+# with the highest confidence of being 'good'.
+
+sw.plot_unit_templates(sorting_analyzer, unit_ids=['7','9'])
+
+##############################################################################
+# Nice! Unit 9 looks more like an expected action potential waveform while unit 7 doesn't,
+# and it seems reasonable that unit 7 is labelled as `bad`. However, for certain experiments
+# or brain areas, unit 7 might be a great small-amplitude unit. This example highlights that
+# you should be careful applying models trained on one dataset to your own dataset. You can
+# explore the currently available models on the `spikeinterface hugging face hub <https://huggingface.co/SpikeInterface>`_
+# page, or `train your own one <https://spikeinterface.readthedocs.io/en/latest/tutorials/curation/plot_2_train_a_model.html>`_.
+#
+# Assess the model performance
+# ----------------------------
+#
+# To assess the performance of the model relative to labels assigned by a human creator, we can load or generate some
+# "human labels", and plot a confusion matrix of predicted vs human labels for all clusters. Here
+# we'll be a conservative human, who has labelled several units with small amplitudes as 'bad'.
+
+human_labels = ['bad', 'good', 'good', 'bad', 'good', 'bad', 'good', 'bad', 'good', 'good']
+
+# Note: if you labelled using phy, you can load the labels using:
+# human_labels = sorting_analyzer.sorting.get_property('quality')
+# We need to load in the `label_conversion` dictionary, which converts integers such
+# as '0' and '1' to readable labels such as 'good' and 'bad'. This is stored as
+# in `model_info`, which we loaded earlier.
+
+from sklearn.metrics import confusion_matrix, balanced_accuracy_score
+
+label_conversion = model_info['label_conversion']
+predictions = labels['prediction']
+
+conf_matrix = confusion_matrix(human_labels, predictions)
+
+# Calculate balanced accuracy for the confusion matrix
+balanced_accuracy = balanced_accuracy_score(human_labels, predictions)
+
+plt.imshow(conf_matrix)
+for (index, value) in np.ndenumerate(conf_matrix):
+    plt.annotate( str(value), xy=index, color="white", fontsize="15")
+plt.xlabel('Predicted Label')
+plt.ylabel('Human Label')
+plt.xticks(ticks = [0, 1], labels = list(label_conversion.values()))
+plt.yticks(ticks = [0, 1], labels = list(label_conversion.values()))
+plt.title('Predicted vs Human Label')
+plt.suptitle(f"Balanced Accuracy: {balanced_accuracy}")
+plt.show()
+
+
+##############################################################################
+# Here, there are several false positives (if we consider the human labels to be "the truth").
+#
+# Next, we can also see how the model's confidence relates to the probability that the model
+# label matches the human label.
+#
+# This could be used to help decide which units should be auto-curated and which need further
+# manual creation. For example, we might accept any unit as 'good' that the model predicts
+# as 'good' with confidence over a threshold, say 80%. If the confidence is lower we might decide to take a
+# look at this unit manually. Below, we will create a plot that shows how the agreement
+# between human and model labels changes as we increase the confidence threshold. We see that
+# the agreement increases as the confidence does. So the model gets more accurate with a
+# higher confidence threshold, as expceted.
+
+
+def calculate_moving_avg(label_df, confidence_label, window_size):
+
+    label_df[f'{confidence_label}_decile'] = pd.cut(label_df[confidence_label], 10, labels=False, duplicates='drop')
+    # Group by decile and calculate the proportion of correct labels (agreement)
+    p_label_grouped = label_df.groupby(f'{confidence_label}_decile')['model_x_human_agreement'].mean()
+    # Convert decile to range 0-1
+    p_label_grouped.index = p_label_grouped.index / 10
+    # Sort the DataFrame by confidence scores
+    label_df_sorted = label_df.sort_values(by=confidence_label)
+
+    p_label_moving_avg = label_df_sorted['model_x_human_agreement'].rolling(window=window_size).mean()
+
+    return label_df_sorted[confidence_label], p_label_moving_avg
+
+confidences = labels['probability']
+
+# Make dataframe of human label, model label, and confidence
+label_df = pd.DataFrame(data = {
+    'human_label': human_labels,
+    'decoder_label': predictions,
+    'confidence': confidences},
+    index = sorting_analyzer.sorting.get_unit_ids())
+
+# Calculate the proportion of agreed labels by confidence decile
+label_df['model_x_human_agreement'] = label_df['human_label'] == label_df['decoder_label']
+
+p_agreement_sorted, p_agreement_moving_avg = calculate_moving_avg(label_df, 'confidence', 3)
+
+# Plot the moving average of agreement
+plt.figure(figsize=(6, 6))
+plt.plot(p_agreement_sorted, p_agreement_moving_avg, label = 'Moving Average')
+plt.axhline(y=1/len(np.unique(predictions)), color='black', linestyle='--', label='Chance')
+plt.xlabel('Confidence'); #plt.xlim(0.5, 1)
+plt.ylabel('Proportion Agreement with Human Label'); plt.ylim(0, 1)
+plt.title('Agreement vs Confidence (Moving Average)')
+plt.legend(); plt.grid(True); plt.show()
+
+##############################################################################
+# In this case, you might decide to only trust labels which had confidence over above 0.88,
+# and manually labels the ones the model isn't so confident about.
+#
+# A model trained on real Neuropixels data
+# ----------------------------------------
+#
+# Above, we used a toy model trained on generated data. There are also models on HuggingFace
+# trained on real data.
+#
+# For example, the following classifiers are trained on Neuropixels data from 11 mice recorded in
+# V1,SC and ALM: https://huggingface.co/AnoushkaJain3/noise_neural_classifier/ and
+# https://huggingface.co/AnoushkaJain3/sua_mua_classifier/ . One will classify units into
+# `noise` or `not-noise` and the other will classify the `not-noise` units into single
+# unit activity (sua) units and multi-unit activity (mua) units.
+#
+# There is more information about the model on the model's HuggingFace page. Take a look!
+# The idea here is to first apply the noise/not-noise classifier, then the sua/mua one.
+# We can do so as follows:
+#
+
+# Apply the noise/not-noise model
+noise_neuron_labels = sc.auto_label_units(
+    sorting_analyzer = sorting_analyzer,
+    repo_id = "AnoushkaJain3/noise_neural_classifier",
+    trust_model=True,
+)
+
+noise_units = noise_neuron_labels[noise_neuron_labels['prediction']=='noise']
+analyzer_neural = sorting_analyzer.remove_units(noise_units.index)
+
+# Apply the sua/mua model
+sua_mua_labels = sc.auto_label_units(
+    sorting_analyzer = analyzer_neural,
+    repo_id = "AnoushkaJain3/sua_mua_classifier",
+    trust_model=True,
+)
+
+all_labels = pd.concat([sua_mua_labels, noise_units]).sort_index()
+print(all_labels)
+
+##############################################################################
+# If you run this without the ``trust_model=True`` parameter, you will receive an error:
+#
+# .. code-block::
+#
+#     UntrustedTypesFoundException: Untrusted types found in the file: ['sklearn.metrics._classification.balanced_accuracy_score', 'sklearn.metrics._scorer._Scorer', 'sklearn.model_selection._search_successive_halving.HalvingGridSearchCV', 'sklearn.model_selection._split.StratifiedKFold']
+#
+# This is a security warning, which can be overcome by passing the trusted types list
+# ``trusted = ['sklearn.metrics._classification.balanced_accuracy_score', 'sklearn.metrics._scorer._Scorer', 'sklearn.model_selection._search_successive_halving.HalvingGridSearchCV', 'sklearn.model_selection._split.StratifiedKFold']``
+# or by passing the ``trust_model=True``` keyword.
+#
+# .. dropdown:: More about security
+#
+#   Sharing models, with are Python objects, is complicated.
+#   We have chosen to use the `skops format <https://skops.readthedocs.io/en/stable/>`_, instead
+#   of the common but insecure ``.pkl`` format (read about ``pickle`` security issues
+#   `here <https://lwn.net/Articles/964392/>`_). While unpacking the ``.skops`` file, each function
+#   is checked. Ideally, skops should recognise all `sklearn`, `numpy` and `scipy` functions and
+#   allow the object to be loaded if it only contains these (and no unkown malicious code). But
+#   when ``skops`` it's not sure, it raises an error. Here, it doesn't recognise
+#   ``['sklearn.metrics._classification.balanced_accuracy_score', 'sklearn.metrics._scorer._Scorer',
+#   'sklearn.model_selection._search_successive_halving.HalvingGridSearchCV',
+#   'sklearn.model_selection._split.StratifiedKFold']``. Taking a look, these are all functions
+#   from `sklearn`, and we can happily add them to the ``trusted`` functions to load.
+#
+#    In general, you should be cautious when downloading ``.skops`` files and ``.pkl`` files from repos,
+#    especially from unknown sources.
+#
+# Directly applying a sklearn Pipeline
+# ------------------------------------
+#
+# Instead of using ``HuggingFace`` and ``skops``, someone might have given you a model
+# in differet way: perhaps by e-mail or a download. If you have the model in a
+# folder, you can apply it in a very similar way:
+#
+# .. code-block::
+#
+#    labels = sc.auto_label_units(
+#        sorting_analyzer = sorting_analyzer,
+#        model_folder = "path/to/model/folder",
+#    )
+
+##############################################################################
+# Using this, you lose the advantages of the model metadata: the quality metric parameters
+# are not checked and the labels are not converted their original human readable names (like
+# 'good' and 'bad'). Hence we advise using the methods discussed above, when possible.
diff --git a/examples/tutorials/curation/plot_2_train_a_model.py b/examples/tutorials/curation/plot_2_train_a_model.py
new file mode 100644
index 0000000000..1a38836527
--- /dev/null
+++ b/examples/tutorials/curation/plot_2_train_a_model.py
@@ -0,0 +1,168 @@
+"""
+Training a model for automated curation
+=============================
+
+If the pretrained models do not give satisfactory performance on your data, it is easy to train your own classifier using SpikeInterface.
+"""
+
+
+##############################################################################
+# Step 1: Generate and label data
+# -------------------------------
+#
+# First we will import our dependencies
+import warnings
+warnings.filterwarnings("ignore")
+from pathlib import Path
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+
+import spikeinterface.core as si
+import spikeinterface.curation as sc
+import spikeinterface.widgets as sw
+
+# Note, you can set the number of cores you use using e.g.
+# si.set_global_job_kwargs(n_jobs = 8)
+
+##############################################################################
+# For this tutorial, we will use simulated data to create ``recording`` and ``sorting`` objects. We'll
+# create two sorting objects: :code:`sorting_1` is coupled to the real recording, so the spike times of the sorter will
+# perfectly match the spikes in the recording. Hence this will contain good units. However, we've
+# uncoupled :code:`sorting_2` to the recording and the spike times will not be matched with the spikes in the recording.
+# Hence these units will mostly be random noise. We'll combine the "good" and "noise" sortings into one sorting
+# object using :code:`si.aggregate_units`.
+#
+# (When making your own model, you should
+# `load your own recording <https://spikeinterface.readthedocs.io/en/latest/modules/extractors.html>`_
+# and `do a sorting <https://spikeinterface.readthedocs.io/en/latest/modules/sorters.html>`_ on your data.)
+
+recording, sorting_1 = si.generate_ground_truth_recording(num_channels=4, seed=1, num_units=5)
+_, sorting_2 =si.generate_ground_truth_recording(num_channels=4, seed=2, num_units=5)
+
+both_sortings = si.aggregate_units([sorting_1, sorting_2])
+
+##############################################################################
+# To do some visualisation and postprocessing, we need to create a sorting analyzer, and
+# compute some extensions:
+
+analyzer = si.create_sorting_analyzer(sorting = both_sortings, recording=recording)
+analyzer.compute(['noise_levels','random_spikes','waveforms','templates'])
+
+##############################################################################
+# Now we can plot the templates for the first and fifth units. The first (unit id 0) belongs to
+# :code:`sorting_1` so should look like a real unit; the sixth (unit id 5) belongs to :code:`sorting_2`
+# so should look like noise.
+
+sw.plot_unit_templates(analyzer, unit_ids=["0", "5"])
+
+##############################################################################
+# This is as expected: great! (Find out more about plotting using widgets `here <https://spikeinterface.readthedocs.io/en/latest/modules/widgets.html>`_.)
+# We've set up our system so that the first five units are 'good' and the next five are 'bad'.
+# So we can make a list of labels which contain this information. For real data, you could
+# use a manual curation tool to make your own list.
+
+labels = ['good', 'good', 'good', 'good', 'good', 'bad', 'bad', 'bad', 'bad', 'bad']
+
+##############################################################################
+# Step 2: Train our model
+# -----------------------
+#
+# We'll now train a model, based on our labelled data. The model will be trained using properties
+# of the units, and then be applied to units from other sortings. The properties we use are the
+# `quality metrics <https://spikeinterface.readthedocs.io/en/latest/modules/qualitymetrics.html>`_
+# and `template metrics <https://spikeinterface.readthedocs.io/en/latest/modules/postprocessing.html#template-metrics>`_.
+# Hence we need to compute these, using some ``sorting_analyzer``` extensions.
+
+analyzer.compute(['spike_locations','spike_amplitudes','correlograms','principal_components','quality_metrics','template_metrics'])
+
+##############################################################################
+# Now that we have metrics and labels, we're ready to train the model using the
+# ``train_model``` function. The trainer will try several classifiers, imputation strategies and
+# scaling techniques then save the most accurate. To save time in this tutorial,
+# we'll only try one classifier (Random Forest), imputation strategy (median) and scaling
+# technique (standard scaler).
+#
+# We will use a list of one analyzer here, so the model is trained on a single
+# session. In reality, we would usually train a model using multiple analyzers from an
+# experiment, which should make the model more robust. To do this, you can simply pass
+# a list of analyzers and a list of manually curated labels for each
+# of these analyzers. Then the model would use all of these data as input.
+
+trainer = sc.train_model(
+    mode = "analyzers", # You can supply a labelled csv file instead of an analyzer
+    labels = [labels],
+    analyzers = [analyzer],
+    folder = "my_folder", # Where to save the model and model_info.json file
+    metric_names = None, # Specify which metrics to use for training: by default uses those already calculted
+    imputation_strategies = ["median"], # Defaults to all
+    scaling_techniques = ["standard_scaler"], # Defaults to all
+    classifiers = None, # Default to Random Forest only. Other classifiers you can try [ "AdaBoostClassifier","GradientBoostingClassifier","LogisticRegression","MLPClassifier"]
+    overwrite = True, # Whether or not to overwrite `folder` if it already exists. Default is False.
+    search_kwargs = {'cv': 3} # Parameters used during the model hyperparameter search
+)
+
+best_model = trainer.best_pipeline
+
+##############################################################################
+#
+# You can pass many sklearn `classifiers <https://scikit-learn.org/1.5/api/sklearn.impute.html>`_
+# `imputation strategies <https://scikit-learn.org/1.5/api/sklearn.impute.html>`_ and
+# `scalers <https://scikit-learn.org/1.5/api/sklearn.preprocessing.html>`_, although the
+# documentation is quite overwhelming. You can find the classifiers we've tried out
+# using the ``sc.get_default_classifier_search_spaces`` function.
+#
+# The above code saves the model in ``model.skops``, some metadata in
+# ``model_info.json`` and the model accuracies in ``model_accuracies.csv``
+# in the specified ``folder`` (in this case ``'my_folder'``).
+#
+# (``skops`` is a file format: you can think of it as a more-secure pkl file. `Read more <https://skops.readthedocs.io/en/stable/index.html>`_.)
+#
+# The ``model_accuracies.csv`` file contains the accuracy, precision and recall of the
+# tested models. Let's take a look:
+
+accuracies = pd.read_csv(Path("my_folder") / "model_accuracies.csv", index_col = 0)
+accuracies.head()
+
+##############################################################################
+# Our model is perfect!! This is because the task was *very* easy. We had 10 units; where
+# half were pure noise and half were not.
+#
+# The model also contains some more information, such as which features are "important",
+# as defined by sklearn (learn about feature importance of a Random Forest Classifier
+# `here <https://scikit-learn.org/1.5/auto_examples/ensemble/plot_forest_importances.html>`_.)
+# We can plot these:
+
+# Plot feature importances
+importances = best_model.named_steps['classifier'].feature_importances_
+indices = np.argsort(importances)[::-1]
+
+# The sklearn importances are not computed for inputs whose values are all `nan`.
+# Hence, we need to pick out the non-`nan` columns of our metrics
+features = best_model.feature_names_in_
+n_features = best_model.n_features_in_
+
+metrics = pd.concat([analyzer.get_extension('quality_metrics').get_data(), analyzer.get_extension('template_metrics').get_data()], axis=1)
+non_null_metrics = ~(metrics.isnull().all()).values
+
+features = features[non_null_metrics]
+n_features = len(features)
+
+plt.figure(figsize=(12, 7))
+plt.title("Feature Importances")
+plt.bar(range(n_features), importances[indices], align="center")
+plt.xticks(range(n_features), features[indices], rotation=90)
+plt.xlim([-1, n_features])
+plt.subplots_adjust(bottom=0.3)
+plt.show()
+
+##############################################################################
+# Roughly, this means the model is using metrics such as "nn_hit_rate" and "l_ratio"
+# but is not using "sync_spike_4" and "rp_contanimation". This is a toy model, so don't
+# take these results seriously. But using this information, you could retrain another,
+# simpler model using a subset of the metrics, by passing, e.g.,
+# ``metric_names = ['nn_hit_rate', 'l_ratio',...]`` to the ``train_model`` function.
+#
+# Now that you have a model, you can `apply it to another sorting
+# <https://spikeinterface.readthedocs.io/en/latest/tutorials/curation/plot_1_automated_curation.html>`_
+# or `upload it to HuggingFaceHub <https://spikeinterface.readthedocs.io/en/latest/tutorials/curation/plot_3_upload_a_model.html>`_.
diff --git a/examples/tutorials/curation/plot_3_upload_a_model.py b/examples/tutorials/curation/plot_3_upload_a_model.py
new file mode 100644
index 0000000000..0a9ea402db
--- /dev/null
+++ b/examples/tutorials/curation/plot_3_upload_a_model.py
@@ -0,0 +1,139 @@
+"""
+Upload a pipeline to Hugging Face Hub
+=====================================
+"""
+##############################################################################
+# In this tutorial we will upload a pipeline, trained in SpikeInterface, to the
+# `Hugging Face Hub <https://huggingface.co/>`_ (HFH).
+#
+# To do this, you first need to train a model. `Learn how here! <https://spikeinterface.readthedocs.io/en/latest/tutorials/curation/plot_2_train_a_model.html>`_
+#
+# Hugging Face Hub?
+# -----------------
+# Hugging Face Hub (HFH) is a model sharing platform focused on AI and ML models and datasets.
+# To upload your own model to HFH, you need to make an account with them.
+# If you do not want to make an account, you can simply share the model folder with colleagues.
+# There are also several ways to interaction with HFH: the way we propose here doesn't use
+# many of the tools ``skops`` and hugging face have developed such as the ``Card`` and
+# ``hub_utils``. Feel free to check those out `here <https://skops.readthedocs.io/en/stable/examples.html>`_.
+#
+# Prepare your model
+# ------------------
+#
+# The plan is to make a folder with the following file structure
+#
+# .. code-block::
+#
+#     my_model_folder/
+#         my_model_name.skops
+#         model_info.json
+#         training_data.csv
+#         labels.csv
+#         metadata.json
+#
+# SpikeInterface and HFH don't require you to keep this folder structure, we just advise it as
+# best practice.
+#
+# If you've used SpikeInterface to train your model, the ``train_model`` function auto-generates
+# most of this data. The only thing missing is the the ``metadata.json`` file. The purpose of this
+# file is to detail how the model was trained, which can help prospective users decide if it
+# is relevant for them. For example, taking
+# a model trained on mouse data and applying it to a primate is likely a bad idea (or a
+# great research paper!). And a model trained using tetrode data might have limited application
+# on a silcone high-density probes. Hence we suggest saving at least the species, brain areas
+# and probe information, as is done in the dictionary below. Note that we format the metadata
+# so that the information
+# in common with the NWB data format is consistent with it. Since the models can be trained
+# on several curations, all the metadata fields are lists:
+#
+# .. code-block::
+#
+#     import json
+#
+#     model_metadata = {
+#         "subject_species": ["Mus musculus"],
+#         "brain_areas": ["CA1"],
+#         "probes":
+#             [{
+#              "manufacturer": "IMEc",
+#              "name": "Neuropixels 2.0"
+#             }]
+#         }
+#     with open("my_model_folder/metadata.json", "w") as file:
+#         json.dump(model_metadata, file)
+#
+# Upload to HuggingFaceHub
+# ------------------------
+#
+# We'll now upload this folder to HFH using the web interface.
+#
+# First, go to https://huggingface.co/ and make an account. Once you've logged in, press
+# ``+`` then ``New model`` or find ``+ New Model`` in the user menu. You will be asked
+# to enter a model name, to choose a license for the model and whether the model should
+# be public or private. After you have made these choices, press ``Create Model``.
+#
+# You should be on your model's landing page, whose header looks something like
+#
+# .. image:: ../../images/initial_model_screen.png
+#     :width: 550
+#     :align: center
+#     :alt: The page shown on HuggingFaceHub when a user first initialises a model
+#
+# Click Files, then ``+ Add file`` then ``Upload file(s)``. You can then add your files to the repository. Upload these by pressing ``Commit changes to main``.
+#
+# You are returned to the Files page, which should look similar to
+#
+# .. image:: ../../images/files_screen.png
+#     :width: 700
+#     :align: center
+#     :alt: The file list for a model HuggingFaceHub.
+#
+# Let's add some information about the model for users to see when they go on your model's
+# page. Click on ``Model card`` then ``Edit model card``. Here is a sample model card for
+# For a model based on synthetically generated tetrode data,
+#
+# .. code-block::
+#
+#     ---
+#     license: mit
+#     ---
+#
+#     ## Model description
+#
+#     A toy model, trained on toy data generated from spikeinterface.
+#
+#     # Intended use
+#
+#     Used to try out automated curation in SpikeInterface.
+#
+#     # How to Get Started with the Model
+#
+#     This can be used to automatically label a sorting in spikeinterface. Provided you have a `sorting_analyzer`, it is used as follows
+#
+#     ` ` ` python (NOTE: you should remove the spaces between each backtick. This is just formatting for the notebook you are reading)
+#
+#         from spikeinterface.curation import auto_label_units
+#         labels = auto_label_units(
+#             sorting_analyzer = sorting_analyzer,
+#             repo_id = "SpikeInterface/toy_tetrode_model",
+#             trust_model=True
+#         )
+#     ` ` `
+#
+#     or you can download the entire repositry to `a_folder_for_a_model`, and use
+#
+#     ` ` ` python
+#         from spikeinterface.curation import auto_label_units
+#
+#         labels = auto_label_units(
+#             sorting_analyzer = sorting_analyzer,
+#             model_folder = "path/to/a_folder_for_a_model",
+#             trusted = ['numpy.dtype']
+#         )
+#     ` ` `
+#
+#     # Authors
+#
+#     Chris Halcrow
+#
+# You can see the repo with this Model card `here <https://huggingface.co/SpikeInterface/toy_tetrode_model>`_.
diff --git a/examples/tutorials/qualitymetrics/plot_3_quality_mertics.py b/examples/tutorials/qualitymetrics/plot_3_quality_metrics.py
similarity index 100%
rename from examples/tutorials/qualitymetrics/plot_3_quality_mertics.py
rename to examples/tutorials/qualitymetrics/plot_3_quality_metrics.py
diff --git a/pyproject.toml b/pyproject.toml
index 22fbdc7f22..0b2f06049f 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -101,6 +101,8 @@ full = [
     "matplotlib>=3.6", # matplotlib.colormaps
     "cuda-python; platform_system != 'Darwin'",
     "numba",
+    "skops",
+    "huggingface_hub"
 ]
 
 widgets = [
@@ -171,6 +173,10 @@ test = [
     "torch",
     "pynndescent",
 
+    # curation
+    "skops",
+    "huggingface_hub",
+
     # for github test : probeinterface and neo from master
     # for release we need pypi, so this need to be commented
     "probeinterface @ git+https://github.com/SpikeInterface/probeinterface.git",
@@ -192,6 +198,8 @@ docs = [
     "hdbscan>=0.8.33",   # For sorters spykingcircus2 + tridesclous
     "numba", # For many postprocessing functions
     "networkx",
+    "skops", # For auotmated curation
+    "scikit-learn", # For auotmated curation
     # Download data
     "pooch>=1.8.2",
     "datalad>=1.0.2",
diff --git a/src/spikeinterface/curation/__init__.py b/src/spikeinterface/curation/__init__.py
index 0302ffe5b7..975f2fe22f 100644
--- a/src/spikeinterface/curation/__init__.py
+++ b/src/spikeinterface/curation/__init__.py
@@ -15,3 +15,7 @@
 from .curation_format import validate_curation_dict, curation_label_to_dataframe, apply_curation
 
 from .sortingview_curation import apply_sortingview_curation
+
+# automated curation
+from .model_based_curation import auto_label_units, load_model
+from .train_manual_curation import train_model, get_default_classifier_search_spaces
diff --git a/src/spikeinterface/curation/model_based_curation.py b/src/spikeinterface/curation/model_based_curation.py
new file mode 100644
index 0000000000..93ad03734c
--- /dev/null
+++ b/src/spikeinterface/curation/model_based_curation.py
@@ -0,0 +1,435 @@
+import numpy as np
+from pathlib import Path
+import json
+import warnings
+import re
+
+from spikeinterface.core import SortingAnalyzer
+from spikeinterface.curation.train_manual_curation import (
+    try_to_get_metrics_from_analyzer,
+    _get_computed_metrics,
+    _format_metric_dataframe,
+)
+from copy import deepcopy
+
+
+class ModelBasedClassification:
+    """
+    Class for performing model-based classification on spike sorting data.
+
+    Parameters
+    ----------
+    sorting_analyzer : SortingAnalyzer
+        The sorting analyzer object containing the spike sorting data.
+    pipeline : Pipeline
+        The pipeline object representing the trained classification model.
+
+    Attributes
+    ----------
+    sorting_analyzer : SortingAnalyzer
+        The sorting analyzer object containing the spike sorting data.
+    pipeline : Pipeline
+        The pipeline object representing the trained classification model.
+    required_metrics : Sequence[str]
+        The list of required metrics for classification, extracted from the pipeline.
+
+    Methods
+    -------
+    predict_labels()
+        Predicts the labels for the spike sorting data using the trained model.
+    """
+
+    def __init__(self, sorting_analyzer: SortingAnalyzer, pipeline):
+        from sklearn.pipeline import Pipeline
+
+        if not isinstance(pipeline, Pipeline):
+            raise ValueError("The `pipeline` must be an instance of sklearn.pipeline.Pipeline")
+
+        self.sorting_analyzer = sorting_analyzer
+        self.pipeline = pipeline
+        self.required_metrics = pipeline.feature_names_in_
+
+    def predict_labels(
+        self, label_conversion=None, input_data=None, export_to_phy=False, model_info=None, enforce_metric_params=False
+    ):
+        """
+        Predicts the labels for the spike sorting data using the trained model.
+        Populates the sorting object with the predicted labels and probabilities as unit properties
+
+        Parameters
+        ----------
+        model_info : dict or None, default: None
+            Model info, generated with model, used to check metric parameters used to train it.
+        label_conversion : dict or None, default: None
+            A dictionary for converting the predicted labels (which are integers) to custom labels. If None,
+            tries to find in `model_info` file. The dictionary should have the format {old_label: new_label}.
+        input_data : pandas.DataFrame or None, default: None
+            The input data for classification. If not provided, the method will extract metrics stored in the sorting analyzer.
+        export_to_phy : bool, default: False.
+            Whether to export the classified units to Phy format. Default is False.
+        enforce_metric_params : bool, default: False
+            If True and the parameters used to compute the metrics in `sorting_analyzer` are different than the parmeters
+            used to compute the metrics used to train the model, this function will raise an error. Otherwise, a warning is raised.
+
+        Returns
+        -------
+        pd.DataFrame
+            A dataframe containing the classified units and their corresponding predictions and probabilities,
+            indexed by their `unit_ids`.
+        """
+        import pandas as pd
+
+        # Get metrics DataFrame for classification
+        if input_data is None:
+            input_data = _get_computed_metrics(self.sorting_analyzer)
+        else:
+            if not isinstance(input_data, pd.DataFrame):
+                raise ValueError("Input data must be a pandas DataFrame")
+
+        input_data = self._check_required_metrics_are_present(input_data)
+
+        if model_info is not None:
+            self._check_params_for_classification(enforce_metric_params, model_info=model_info)
+
+        if model_info is not None and label_conversion is None:
+            try:
+                string_label_conversion = model_info["label_conversion"]
+                # json keys are strings; we convert these to ints
+                label_conversion = {}
+                for key, value in string_label_conversion.items():
+                    label_conversion[int(key)] = value
+            except:
+                warnings.warn("Could not find `label_conversion` key in `model_info.json` file")
+
+        input_data = _format_metric_dataframe(input_data)
+
+        # Apply classifier
+        predictions = self.pipeline.predict(input_data)
+        probabilities = self.pipeline.predict_proba(input_data)
+        probabilities = np.max(probabilities, axis=1)
+
+        if isinstance(label_conversion, dict):
+
+            if set(predictions).issubset(set(label_conversion.keys())) is False:
+                raise ValueError("Labels in predictions do not match those in label_conversion")
+            predictions = [label_conversion[label] for label in predictions]
+
+        classified_units = pd.DataFrame(
+            zip(predictions, probabilities), columns=["prediction", "probability"], index=self.sorting_analyzer.unit_ids
+        )
+
+        # Set predictions and probability as sorting properties
+        self.sorting_analyzer.sorting.set_property("classifier_label", predictions)
+        self.sorting_analyzer.sorting.set_property("classifier_probability", probabilities)
+
+        if export_to_phy:
+            self._export_to_phy(classified_units)
+
+        return classified_units
+
+    def _check_required_metrics_are_present(self, calculated_metrics):
+
+        # Check all the required metrics have been calculated
+        required_metrics = set(self.required_metrics)
+        if required_metrics.issubset(set(calculated_metrics)):
+            input_data = calculated_metrics[self.required_metrics]
+        else:
+            raise ValueError(
+                "Input data does not contain all required metrics for classification",
+                f"Missing metrics: {required_metrics.difference(calculated_metrics)}",
+            )
+
+        return input_data
+
+    def _check_params_for_classification(self, enforce_metric_params=False, model_info=None):
+        """
+        Check that quality and template metrics parameters match those used to train the model
+
+        Parameters
+        ----------
+        enforce_metric_params : bool, default: False
+            If True and the parameters used to compute the metrics in `sorting_analyzer` are different than the parmeters
+            used to compute the metrics used to train the model, this function will raise an error. Otherwise, a warning is raised.
+        model_info : dict, default: None
+            Dictionary of model info containing provenance of the model.
+        """
+
+        extension_names = ["quality_metrics", "template_metrics"]
+
+        metric_extensions = [self.sorting_analyzer.get_extension(extension_name) for extension_name in extension_names]
+
+        for metric_extension, extension_name in zip(metric_extensions, extension_names):
+
+            # remove the 's' at the end of the extension name
+            extension_name = extension_name[:-1]
+            model_extension_params = model_info["metric_params"].get(extension_name + "_params")
+
+            if metric_extension is not None and model_extension_params is not None:
+
+                metric_params = metric_extension.params["metric_params"]
+
+                inconsistent_metrics = []
+                for metric in model_extension_params["metric_names"]:
+                    model_metric_params = model_extension_params.get("metric_params")
+                    if model_metric_params is None or metric not in model_metric_params:
+                        inconsistent_metrics.append(metric)
+                    else:
+                        if metric_params[metric] != model_metric_params[metric]:
+                            warning_message = f"{extension_name} params for {metric} do not match those used to train the model. Parameters can be found in the 'model_info.json' file."
+                            if enforce_metric_params is True:
+                                raise Exception(warning_message)
+                            else:
+                                warnings.warn(warning_message)
+
+                if len(inconsistent_metrics) > 0:
+                    warning_message = f"Parameters used to compute metrics {inconsistent_metrics}, used to train this model, are unknown."
+                    if enforce_metric_params is True:
+                        raise Exception(warning_message)
+                    else:
+                        warnings.warn(warning_message)
+
+    def _export_to_phy(self, classified_units):
+        """Export the classified units to Phy as cluster_prediction.tsv file"""
+
+        import pandas as pd
+
+        # Create a new DataFrame with unit_id, prediction, and probability columns from dict {unit_id: (prediction, probability)}
+        classified_df = pd.DataFrame.from_dict(classified_units, orient="index", columns=["prediction", "probability"])
+
+        # Export to Phy format
+        try:
+            sorting_path = self.sorting_analyzer.sorting.get_annotation("phy_folder")
+            assert sorting_path is not None
+            assert Path(sorting_path).is_dir()
+        except AssertionError:
+            raise ValueError("Phy folder not found in sorting annotations, or is not a directory")
+
+        classified_df.to_csv(f"{sorting_path}/cluster_prediction.tsv", sep="\t", index_label="cluster_id")
+
+
+def auto_label_units(
+    sorting_analyzer: SortingAnalyzer,
+    model_folder=None,
+    model_name=None,
+    repo_id=None,
+    label_conversion=None,
+    trust_model=False,
+    trusted=None,
+    export_to_phy=False,
+    enforce_metric_params=False,
+):
+    """
+    Automatically labels units based on a model-based classification, either from a model
+    hosted on HuggingFaceHub or one available in a local folder.
+
+    This function returns the predicted labels and the prediction probabilities, and populates
+    the sorting object with the predicted labels and probabilities in the 'classifier_label' and
+    'classifier_probability' properties.
+
+    Parameters
+    ----------
+    sorting_analyzer : SortingAnalyzer
+        The sorting analyzer object containing the spike sorting results.
+    model_folder : str or Path, defualt: None
+        The path to the folder containing the model
+    repo_id : str | Path, default: None
+        Hugging face repo id which contains the model e.g. 'username/model'
+    model_name: str | Path, default: None
+        Filename of model e.g. 'my_model.skops'. If None, uses first model found.
+    label_conversion : dic | None, default: None
+        A dictionary for converting the predicted labels (which are integers) to custom labels. If None,
+        tries to extract from `model_info.json` file. The dictionary should have the format {old_label: new_label}.
+    export_to_phy : bool, default: False
+        Whether to export the results to Phy format. Default is False.
+    trust_model : bool, default: False
+        Whether to trust the model. If True, the `trusted` parameter that is passed to `skops.load` to load the model will be
+        automatically inferred. If False, the `trusted` parameter must be provided to indicate the trusted objects.
+    trusted : list of str, default: None
+        Passed to skops.load. The object will be loaded only if there are only trusted objects and objects of types listed in trusted in the dumped file.
+    enforce_metric_params : bool, default: False
+            If True and the parameters used to compute the metrics in `sorting_analyzer` are different than the parmeters
+            used to compute the metrics used to train the model, this function will raise an error. Otherwise, a warning is raised.
+
+
+    Returns
+    -------
+    classified_units : pd.DataFrame
+        A dataframe containing the classified units, indexed by the `unit_ids`, containing the predicted label
+        and confidence probability of each labelled unit.
+
+    Raises
+    ------
+    ValueError
+        If the pipeline is not an instance of sklearn.pipeline.Pipeline.
+
+    """
+    from sklearn.pipeline import Pipeline
+
+    model, model_info = load_model(
+        model_folder=model_folder, repo_id=repo_id, model_name=model_name, trust_model=trust_model, trusted=trusted
+    )
+
+    if not isinstance(model, Pipeline):
+        raise ValueError("The model must be an instance of sklearn.pipeline.Pipeline")
+
+    model_based_classification = ModelBasedClassification(sorting_analyzer, model)
+
+    classified_units = model_based_classification.predict_labels(
+        label_conversion=label_conversion,
+        export_to_phy=export_to_phy,
+        model_info=model_info,
+        enforce_metric_params=enforce_metric_params,
+    )
+
+    return classified_units
+
+
+def load_model(model_folder=None, repo_id=None, model_name=None, trust_model=False, trusted=None):
+    """
+    Loads a model and model_info from a HuggingFaceHub repo or a local folder.
+
+    Parameters
+    ----------
+    model_folder : str or Path, defualt: None
+        The path to the folder containing the model
+    repo_id : str | Path, default: None
+        Hugging face repo id which contains the model e.g. 'username/model'
+    model_name: str | Path, default: None
+        Filename of model e.g. 'my_model.skops'. If None, uses first model found.
+    trust_model : bool, default: False
+        Whether to trust the model. If True, the `trusted` parameter that is passed to `skops.load` to load the model will be
+        automatically inferred. If False, the `trusted` parameter must be provided to indicate the trusted objects.
+    trusted : list of str, default: None
+        Passed to skops.load. The object will be loaded only if there are only trusted objects and objects of types listed in trusted in the dumped file.
+
+
+    Returns
+    -------
+    model, model_info
+        A model and metadata about the model
+    """
+
+    if model_folder is None and repo_id is None:
+        raise ValueError("Please provide a 'model_folder' or a 'repo_id'.")
+    elif model_folder is not None and repo_id is not None:
+        raise ValueError("Please only provide one of 'model_folder' or 'repo_id'.")
+    elif model_folder is not None:
+        model, model_info = _load_model_from_folder(
+            model_folder=model_folder, model_name=model_name, trust_model=trust_model, trusted=trusted
+        )
+    else:
+        model, model_info = _load_model_from_huggingface(
+            repo_id=repo_id, model_name=model_name, trust_model=trust_model, trusted=trusted
+        )
+
+    return model, model_info
+
+
+def _load_model_from_huggingface(repo_id=None, model_name=None, trust_model=False, trusted=None):
+    """
+    Loads a model from a huggingface repo
+
+    Returns
+    -------
+    model, model_info
+        A model and metadata about the model
+    """
+
+    from huggingface_hub import list_repo_files
+    from huggingface_hub import hf_hub_download
+
+    # get repo filenames
+    repo_filenames = list_repo_files(repo_id=repo_id)
+
+    # download all skops and json files to temp directory
+    for filename in repo_filenames:
+        if Path(filename).suffix in [".skops", ".json"]:
+            full_path = hf_hub_download(repo_id=repo_id, filename=filename)
+            model_folder = Path(full_path).parent
+
+    model, model_info = _load_model_from_folder(
+        model_folder=model_folder, model_name=model_name, trust_model=trust_model, trusted=trusted
+    )
+
+    return model, model_info
+
+
+def _load_model_from_folder(model_folder=None, model_name=None, trust_model=False, trusted=None):
+    """
+    Loads a model and model_info from a folder
+
+    Returns
+    -------
+    model, model_info
+        A model and metadata about the model
+    """
+
+    import skops.io as skio
+    from skops.io.exceptions import UntrustedTypesFoundException
+
+    folder = Path(model_folder)
+    assert folder.is_dir(), f"The folder {folder}, does not exist."
+
+    # look for any .skops files
+    skops_files = list(folder.glob("*.skops"))
+    assert len(skops_files) > 0, f"There are no '.skops' files in the folder {folder}"
+
+    if len(skops_files) > 1:
+        if model_name is None:
+            model_names = [f.name for f in skops_files]
+            raise ValueError(
+                f"There are more than 1 '.skops' file in folder {folder}. You have to specify "
+                f"the file using the 'model_name' argument. Available files:\n{model_names}"
+            )
+        else:
+            skops_file = folder / Path(model_name)
+            assert skops_file.is_file(), f"Model file {skops_file} not found."
+    elif len(skops_files) == 1:
+        skops_file = skops_files[0]
+
+    if trust_model and trusted is None:
+        try:
+            model = skio.load(skops_file)
+        except UntrustedTypesFoundException as e:
+            exception_msg = str(e)
+            # the exception message contains the list of untrusted objects. The following
+            #  search assumes it is the only list in the message.
+            string_list = re.search(r"\[(.*?)\]", exception_msg).group()
+            trusted = [list_item for list_item in string_list.split("'") if len(list_item) > 2]
+
+    model = skio.load(skops_file, trusted=trusted)
+
+    model_info_path = folder / "model_info.json"
+    if not model_info_path.is_file():
+        warnings.warn("No 'model_info.json' file found in folder. No metadata can be checked.")
+        model_info = None
+    else:
+        model_info = json.load(open(model_info_path))
+
+    model_info = handle_backwards_compatibility_metric_params(model_info)
+
+    return model, model_info
+
+
+def handle_backwards_compatibility_metric_params(model_info):
+
+    if (
+        model_info.get("metric_params") is not None
+        and model_info.get("metric_params").get("quality_metric_params") is not None
+    ):
+        if (qm_params := model_info["metric_params"]["quality_metric_params"].get("qm_params")) is not None:
+            model_info["metric_params"]["quality_metric_params"]["metric_params"] = qm_params
+            del model_info["metric_params"]["quality_metric_params"]["qm_params"]
+
+    if (
+        model_info.get("metric_params") is not None
+        and model_info.get("metric_params").get("template_metric_params") is not None
+    ):
+        if (tm_params := model_info["metric_params"]["template_metric_params"].get("metrics_kwargs")) is not None:
+            metric_params = {}
+            for metric_name in model_info["metric_params"]["template_metric_params"].get("metric_names"):
+                metric_params[metric_name] = deepcopy(tm_params)
+            model_info["metric_params"]["template_metric_params"]["metric_params"] = metric_params
+            del model_info["metric_params"]["template_metric_params"]["metrics_kwargs"]
+
+    return model_info
diff --git a/src/spikeinterface/curation/tests/test_model_based_curation.py b/src/spikeinterface/curation/tests/test_model_based_curation.py
new file mode 100644
index 0000000000..3683b417df
--- /dev/null
+++ b/src/spikeinterface/curation/tests/test_model_based_curation.py
@@ -0,0 +1,167 @@
+import pytest
+from pathlib import Path
+from spikeinterface.curation.tests.common import make_sorting_analyzer, sorting_analyzer_for_curation
+from spikeinterface.curation.model_based_curation import ModelBasedClassification
+from spikeinterface.curation import auto_label_units, load_model
+from spikeinterface.curation.train_manual_curation import _get_computed_metrics
+
+import numpy as np
+
+if hasattr(pytest, "global_test_folder"):
+    cache_folder = pytest.global_test_folder / "curation"
+else:
+    cache_folder = Path("cache_folder") / "curation"
+
+
+@pytest.fixture
+def model():
+    """A toy model, created using the `sorting_analyzer_for_curation` from `spikeinterface.curation.tests.common`.
+    It has been trained locally and, when applied to `sorting_analyzer_for_curation` will label its 5 units with
+    the following labels: [1,0,1,0,1]."""
+
+    model = load_model(Path(__file__).parent / "trained_pipeline/", trusted=["numpy.dtype"])
+    return model
+
+
+@pytest.fixture
+def required_metrics():
+    """These are the metrics which `model` are trained on."""
+    return ["num_spikes", "snr", "half_width"]
+
+
+def test_model_based_classification_init(sorting_analyzer_for_curation, model):
+    """Test that the ModelBasedClassification attributes are correctly initialised"""
+
+    model_based_classification = ModelBasedClassification(sorting_analyzer_for_curation, model[0])
+    assert model_based_classification.sorting_analyzer == sorting_analyzer_for_curation
+    assert model_based_classification.pipeline == model[0]
+    assert np.all(model_based_classification.required_metrics == model_based_classification.pipeline.feature_names_in_)
+
+
+def test_metric_ordering_independence(sorting_analyzer_for_curation, model):
+    """The function `auto_label_units` needs the correct metrics to have been computed. However,
+    it should be independent of the order of computation. We test this here."""
+
+    sorting_analyzer_for_curation.compute("template_metrics", metric_names=["half_width"])
+    sorting_analyzer_for_curation.compute("quality_metrics", metric_names=["num_spikes", "snr"])
+
+    model_folder = Path(__file__).parent / Path("trained_pipeline")
+
+    prediction_prob_dataframe_1 = auto_label_units(
+        sorting_analyzer=sorting_analyzer_for_curation,
+        model_folder=model_folder,
+        trusted=["numpy.dtype"],
+    )
+
+    sorting_analyzer_for_curation.compute("quality_metrics", metric_names=["snr", "num_spikes"])
+
+    prediction_prob_dataframe_2 = auto_label_units(
+        sorting_analyzer=sorting_analyzer_for_curation,
+        model_folder=model_folder,
+        trusted=["numpy.dtype"],
+    )
+
+    assert prediction_prob_dataframe_1.equals(prediction_prob_dataframe_2)
+
+
+def test_model_based_classification_get_metrics_for_classification(
+    sorting_analyzer_for_curation, model, required_metrics
+):
+    """If the user has not computed the required metrics, an error should be returned.
+    This test checks that an error occurs when the required metrics have not been computed,
+    and that no error is returned when the required metrics have been computed.
+    """
+
+    sorting_analyzer_for_curation.delete_extension("quality_metrics")
+    sorting_analyzer_for_curation.delete_extension("template_metrics")
+
+    model_based_classification = ModelBasedClassification(sorting_analyzer_for_curation, model[0])
+
+    # Check that ValueError is returned when no metrics are present in sorting_analyzer
+    with pytest.raises(ValueError):
+        computed_metrics = _get_computed_metrics(sorting_analyzer_for_curation)
+
+    # Compute some (but not all) of the required metrics in sorting_analyzer, should still error
+    sorting_analyzer_for_curation.compute("quality_metrics", metric_names=[required_metrics[0]])
+    computed_metrics = _get_computed_metrics(sorting_analyzer_for_curation)
+    with pytest.raises(ValueError):
+        model_based_classification._check_required_metrics_are_present(computed_metrics)
+
+    # Compute all of the required metrics in sorting_analyzer, no more error
+    sorting_analyzer_for_curation.compute("quality_metrics", metric_names=required_metrics[0:2])
+    sorting_analyzer_for_curation.compute("template_metrics", metric_names=[required_metrics[2]])
+
+    metrics_data = _get_computed_metrics(sorting_analyzer_for_curation)
+    assert metrics_data.shape[0] == len(sorting_analyzer_for_curation.sorting.get_unit_ids())
+    assert set(metrics_data.columns.to_list()) == set(required_metrics)
+
+
+def test_model_based_classification_export_to_phy(sorting_analyzer_for_curation, model):
+    # Test the _export_to_phy() method of ModelBasedClassification
+    model_based_classification = ModelBasedClassification(sorting_analyzer_for_curation, model[0])
+    classified_units = {0: (1, 0.5), 1: (0, 0.5), 2: (1, 0.5), 3: (0, 0.5), 4: (1, 0.5)}
+    # Function should fail here
+    with pytest.raises(ValueError):
+        model_based_classification._export_to_phy(classified_units)
+    # Make temp output folder and set as phy_folder
+    phy_folder = cache_folder / "phy_folder"
+    phy_folder.mkdir(parents=True, exist_ok=True)
+
+    model_based_classification.sorting_analyzer.sorting.annotate(phy_folder=phy_folder)
+    model_based_classification._export_to_phy(classified_units)
+    assert (phy_folder / "cluster_prediction.tsv").exists()
+
+
+def test_model_based_classification_predict_labels(sorting_analyzer_for_curation, model):
+    """The model `model` has been trained on the `sorting_analyzer` used in this test with
+    the labels `[1, 0, 1, 0, 1]`. Hence if we apply the model to this `sorting_analyzer`
+    we expect these labels to be outputted. The test checks this, and also checks
+    that label conversion works as expected."""
+
+    sorting_analyzer_for_curation.compute("template_metrics", metric_names=["half_width"])
+    sorting_analyzer_for_curation.compute("quality_metrics", metric_names=["num_spikes", "snr"])
+
+    # Test the predict_labels() method of ModelBasedClassification
+    model_based_classification = ModelBasedClassification(sorting_analyzer_for_curation, model[0])
+    classified_units = model_based_classification.predict_labels()
+    predictions = classified_units["prediction"].values
+
+    assert np.all(predictions == np.array([1, 0, 1, 0, 1]))
+
+    conversion = {0: "noise", 1: "good"}
+    classified_units_labelled = model_based_classification.predict_labels(label_conversion=conversion)
+    predictions_labelled = classified_units_labelled["prediction"]
+    assert np.all(predictions_labelled == ["good", "noise", "good", "noise", "good"])
+
+
+def test_exception_raised_when_metricparams_not_equal(sorting_analyzer_for_curation):
+    """We track whether the metric parameters used to compute the metrics used to train
+    a model are the same as the parameters used to compute the metrics in the sorting
+    analyzer which is being curated. If they are different, an error or warning will
+    be raised depending on the `enforce_metric_params` kwarg. This behaviour is tested here."""
+
+    sorting_analyzer_for_curation.compute(
+        "quality_metrics", metric_names=["num_spikes", "snr"], metric_params={"snr": {"peak_mode": "peak_to_peak"}}
+    )
+    sorting_analyzer_for_curation.compute("template_metrics", metric_names=["half_width"])
+
+    model_folder = Path(__file__).parent / Path("trained_pipeline")
+
+    model, model_info = load_model(model_folder=model_folder, trusted=["numpy.dtype"])
+    model_based_classification = ModelBasedClassification(sorting_analyzer_for_curation, model)
+
+    # an error should be raised if `enforce_metric_params` is True
+    with pytest.raises(Exception):
+        model_based_classification._check_params_for_classification(enforce_metric_params=True, model_info=model_info)
+
+    # but only a warning if `enforce_metric_params` is False
+    with pytest.warns(UserWarning):
+        model_based_classification._check_params_for_classification(enforce_metric_params=False, model_info=model_info)
+
+    # Now test the positive case. Recompute using the default parameters
+    sorting_analyzer_for_curation.compute("quality_metrics", metric_names=["num_spikes", "snr"], metric_params={})
+    sorting_analyzer_for_curation.compute("template_metrics", metric_names=["half_width"])
+
+    model, model_info = load_model(model_folder=model_folder, trusted=["numpy.dtype"])
+    model_based_classification = ModelBasedClassification(sorting_analyzer_for_curation, model)
+    model_based_classification._check_params_for_classification(enforce_metric_params=True, model_info=model_info)
diff --git a/src/spikeinterface/curation/tests/test_train_manual_curation.py b/src/spikeinterface/curation/tests/test_train_manual_curation.py
new file mode 100644
index 0000000000..f455fbdb9c
--- /dev/null
+++ b/src/spikeinterface/curation/tests/test_train_manual_curation.py
@@ -0,0 +1,285 @@
+import pytest
+import numpy as np
+import tempfile, csv
+from pathlib import Path
+
+from spikeinterface.curation.tests.common import make_sorting_analyzer
+from spikeinterface.curation.train_manual_curation import CurationModelTrainer, train_model
+
+
+@pytest.fixture
+def trainer():
+    """A simple CurationModelTrainer object is created, which can later by used to
+    train models using data from `sorting_analyzer`s."""
+
+    folder = tempfile.mkdtemp()  # Create a temporary output folder
+    imputation_strategies = ["median"]
+    scaling_techniques = ["standard_scaler"]
+    classifiers = ["LogisticRegression"]
+    metric_names = ["metric1", "metric2", "metric3"]
+    search_kwargs = {"cv": 3}
+    return CurationModelTrainer(
+        labels=[[0, 1, 0, 1, 0, 1, 0, 1, 0, 1]],
+        folder=folder,
+        metric_names=metric_names,
+        imputation_strategies=imputation_strategies,
+        scaling_techniques=scaling_techniques,
+        classifiers=classifiers,
+        search_kwargs=search_kwargs,
+    )
+
+
+def make_temp_training_csv():
+    """Create a temporary CSV file with artificially generated quality metrics.
+    The data is designed to be easy to dicern between units. Even units metric
+    values are all `0`, while odd units metric values are all `1`.
+    """
+    with tempfile.NamedTemporaryFile(mode="w", delete=False) as temp_file:
+        writer = csv.writer(temp_file)
+        writer.writerow(["unit_id", "metric1", "metric2", "metric3"])
+        for i in range(5):
+            writer.writerow([i * 2, 0, 0, 0])
+            writer.writerow([i * 2 + 1, 1, 1, 1])
+    return temp_file.name
+
+
+def test_load_and_preprocess_full(trainer):
+    """Check that we load and preprocess the csv file from `make_temp_training_csv`
+    correctly."""
+    temp_file_path = make_temp_training_csv()
+
+    # Load and preprocess the data from the temporary CSV file
+    trainer.load_and_preprocess_csv([temp_file_path])
+
+    # Assert that the data is loaded and preprocessed correctly
+    for a, row in trainer.X.iterrows():
+        assert np.all(row.values == [float(a % 2)] * 3)
+    for a, label in enumerate(trainer.y.values):
+        assert label == a % 2
+    for a, row in trainer.testing_metrics.iterrows():
+        assert np.all(row.values == [a % 2] * 3)
+        assert row.name == a
+
+
+def test_apply_scaling_imputation(trainer):
+    """Take a simple training and test set and check that they are corrected scaled,
+    using a standard scaler which rescales the training distribution to have mean 0
+    and variance 1. Length between each row is 3, so if x0 is the first value in the
+    column, all other values are scaled as x -> 2/3(x - x0) - 1. The y (labled) values
+    do not get scaled."""
+
+    from sklearn.impute._knn import KNNImputer
+    from sklearn.preprocessing._data import StandardScaler
+
+    imputation_strategy = "knn"
+    scaling_technique = "standard_scaler"
+    X_train = np.array([[1, 2, 3], [4, 5, 6]])
+    X_test = np.array([[7, 8, 9], [10, 11, 12]])
+    y_train = np.array([0, 1])
+    y_test = np.array([2, 3])
+
+    X_train_scaled, X_test_scaled, y_train_scaled, y_test_scaled, imputer, scaler = trainer.apply_scaling_imputation(
+        imputation_strategy, scaling_technique, X_train, X_test, y_train, y_test
+    )
+
+    first_row_elements = X_train[0]
+    for a, row in enumerate(X_train):
+        assert np.all(2 / 3 * (row - first_row_elements) - 1.0 == X_train_scaled[a])
+    for a, row in enumerate(X_test):
+        assert np.all(2 / 3 * (row - first_row_elements) - 1.0 == X_test_scaled[a])
+
+    assert np.all(y_train == y_train_scaled)
+    assert np.all(y_test == y_test_scaled)
+
+    assert isinstance(imputer, KNNImputer)
+    assert isinstance(scaler, StandardScaler)
+
+
+def test_get_classifier_search_space(trainer):
+    """For each classifier, there is a hyperparameter space we search over to find its
+    most accurate incarnation. Here, we check that we do indeed load the approprirate
+    dict of hyperparameter possibilities"""
+
+    from sklearn.linear_model._logistic import LogisticRegression
+
+    classifier = "LogisticRegression"
+    model, param_space = trainer.get_classifier_search_space(classifier)
+
+    assert isinstance(model, LogisticRegression)
+    assert len(param_space) > 0
+    assert isinstance(param_space, dict)
+
+
+def test_get_custom_classifier_search_space():
+    """Check that if a user passes a custom hyperparameter search space, that this is
+    passed correctly to the trainer."""
+
+    classifier = {
+        "LogisticRegression": {
+            "C": [0.1, 8.0],
+            "solver": ["lbfgs"],
+            "max_iter": [100, 400],
+        }
+    }
+    trainer = CurationModelTrainer(classifiers=classifier, labels=[[0, 1, 0, 1, 0, 1, 0, 1, 0, 1]])
+
+    model, param_space = trainer.get_classifier_search_space(list(classifier.keys())[0])
+    assert param_space == classifier["LogisticRegression"]
+
+
+def test_saved_files(trainer):
+    """During the trainer's creation, the following files should be created:
+        - best_model.skops
+        - labels.csv
+        - model_accuracies.csv
+        - model_info.json
+        - training_data.csv
+    This test checks that these exist, and checks some properties of the files."""
+
+    import pandas as pd
+    import json
+
+    trainer.X = np.random.rand(10, 3)
+    trainer.y = np.append(np.ones(5), np.zeros(5))
+
+    trainer.evaluate_model_config()
+    trainer_folder = Path(trainer.folder)
+
+    assert trainer_folder.is_dir()
+
+    best_model_path = trainer_folder / "best_model.skops"
+    model_accuracies_path = trainer_folder / "model_accuracies.csv"
+    training_data_path = trainer_folder / "training_data.csv"
+    labels_path = trainer_folder / "labels.csv"
+    model_info_path = trainer_folder / "model_info.json"
+
+    assert (best_model_path).is_file()
+
+    model_accuracies = pd.read_csv(model_accuracies_path)
+    model_accuracies["classifier name"].values[0] == "LogisticRegression"
+    assert len(model_accuracies) == 1
+
+    training_data = pd.read_csv(training_data_path)
+    assert np.all(np.isclose(training_data.values[:, 1:4], trainer.X, rtol=1e-10))
+
+    labels = pd.read_csv(labels_path)
+    assert np.all(labels.values[:, 1] == trainer.y.astype("float"))
+
+    model_info = pd.read_json(model_info_path)
+
+    with open(model_info_path) as f:
+        model_info = json.load(f)
+
+    assert set(model_info.keys()) == set(["metric_params", "requirements", "label_conversion"])
+
+
+def test_train_model():
+    """A simple function test to check that `train_model` doesn't fail with one csv inputs"""
+
+    metrics_path = make_temp_training_csv()
+    folder = tempfile.mkdtemp()
+    metric_names = ["metric1", "metric2", "metric3"]
+    trainer = train_model(
+        mode="csv",
+        metrics_paths=[metrics_path],
+        folder=folder,
+        labels=[[0, 1, 0, 1, 0, 1, 0, 1, 0, 1]],
+        metric_names=metric_names,
+        imputation_strategies=["median"],
+        scaling_techniques=["standard_scaler"],
+        classifiers=["LogisticRegression"],
+        overwrite=True,
+        search_kwargs={"cv": 3, "scoring": "balanced_accuracy", "n_iter": 1},
+    )
+    assert isinstance(trainer, CurationModelTrainer)
+
+
+def test_train_model_using_two_csvs():
+    """Models can be trained using more than one set of training data. This test checks
+    that `train_model` works with two inputs, from csv files."""
+
+    metrics_path_1 = make_temp_training_csv()
+    metrics_path_2 = make_temp_training_csv()
+
+    folder = tempfile.mkdtemp()
+    metric_names = ["metric1", "metric2", "metric3"]
+
+    trainer = train_model(
+        mode="csv",
+        metrics_paths=[metrics_path_1, metrics_path_2],
+        folder=folder,
+        labels=[[0, 1, 0, 1, 0, 1, 0, 1, 0, 1], [0, 1, 0, 1, 0, 1, 0, 1, 0, 1]],
+        metric_names=metric_names,
+        imputation_strategies=["median"],
+        scaling_techniques=["standard_scaler"],
+        classifiers=["LogisticRegression"],
+        overwrite=True,
+    )
+    assert isinstance(trainer, CurationModelTrainer)
+
+
+def test_train_using_two_sorting_analyzers():
+    """Models can be trained using more than one set of training data. This test checks
+    that `train_model` works with two inputs, from sorting analzyers. It also checks that
+    an error is raised if the sorting_analyzers have different sets of metrics computed."""
+
+    sorting_analyzer_1 = make_sorting_analyzer()
+    sorting_analyzer_1.compute({"quality_metrics": {"metric_names": ["num_spikes", "snr"]}})
+
+    sorting_analyzer_2 = make_sorting_analyzer()
+    sorting_analyzer_2.compute({"quality_metrics": {"metric_names": ["num_spikes", "snr"]}})
+
+    labels_1 = [0, 1, 1, 1, 1]
+    labels_2 = [1, 1, 0, 1, 1]
+
+    folder = tempfile.mkdtemp()
+    trainer = train_model(
+        analyzers=[sorting_analyzer_1, sorting_analyzer_2],
+        folder=folder,
+        labels=[labels_1, labels_2],
+        imputation_strategies=["median"],
+        scaling_techniques=["standard_scaler"],
+        classifiers=["LogisticRegression"],
+        overwrite=True,
+    )
+
+    assert isinstance(trainer, CurationModelTrainer)
+
+    # Check that there is an error raised if the metric names are different
+    sorting_analyzer_2 = make_sorting_analyzer()
+    sorting_analyzer_2.compute({"quality_metrics": {"metric_names": ["num_spikes"], "delete_existing_metrics": True}})
+
+    with pytest.raises(Exception):
+        trainer = train_model(
+            analyzers=[sorting_analyzer_1, sorting_analyzer_2],
+            folder=folder,
+            labels=[labels_1, labels_2],
+            imputation_strategies=["median"],
+            scaling_techniques=["standard_scaler"],
+            classifiers=["LogisticRegression"],
+            overwrite=True,
+        )
+
+    # Now check that there is an error raised if we demand the same metric params, but don't have them
+
+    sorting_analyzer_2.compute(
+        {
+            "quality_metrics": {
+                "metric_names": ["num_spikes", "snr"],
+                "metric_params": {"snr": {"peak_mode": "at_index"}},
+            }
+        }
+    )
+
+    with pytest.raises(Exception):
+        train_model(
+            analyzers=[sorting_analyzer_1, sorting_analyzer_2],
+            folder=folder,
+            labels=[labels_1, labels_2],
+            imputation_strategies=["median"],
+            scaling_techniques=["standard_scaler"],
+            classifiers=["LogisticRegression"],
+            search_kwargs={"cv": 3, "scoring": "balanced_accuracy", "n_iter": 1},
+            overwrite=True,
+            enforce_metric_params=True,
+        )
diff --git a/src/spikeinterface/curation/tests/trained_pipeline/best_model.skops b/src/spikeinterface/curation/tests/trained_pipeline/best_model.skops
new file mode 100644
index 0000000000000000000000000000000000000000..362405f917e2f4c3dc41eca4160f2d8be69b1c32
GIT binary patch
literal 34009
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
BV7dSR

literal 0
HcmV?d00001

diff --git a/src/spikeinterface/curation/tests/trained_pipeline/labels.csv b/src/spikeinterface/curation/tests/trained_pipeline/labels.csv
new file mode 100644
index 0000000000..46680a9e89
--- /dev/null
+++ b/src/spikeinterface/curation/tests/trained_pipeline/labels.csv
@@ -0,0 +1,21 @@
+unit_index,0
+0,1
+1,0
+2,1
+3,0
+4,1
+0,1
+1,0
+2,1
+3,0
+4,1
+0,1
+1,0
+2,1
+3,0
+4,1
+0,1
+1,0
+2,1
+3,0
+4,1
diff --git a/src/spikeinterface/curation/tests/trained_pipeline/model_accuracies.csv b/src/spikeinterface/curation/tests/trained_pipeline/model_accuracies.csv
new file mode 100644
index 0000000000..7f015c380b
--- /dev/null
+++ b/src/spikeinterface/curation/tests/trained_pipeline/model_accuracies.csv
@@ -0,0 +1,2 @@
+,classifier name,imputation_strategy,scaling_strategy,accuracy,precision,recall,model_id,best_params
+0,LogisticRegression,median,StandardScaler(),1.0000,1.0000,1.0000,0,"OrderedDict([('C', 4.811707275233983), ('max_iter', 384), ('solver', 'saga')])"
diff --git a/src/spikeinterface/curation/tests/trained_pipeline/model_info.json b/src/spikeinterface/curation/tests/trained_pipeline/model_info.json
new file mode 100644
index 0000000000..75ced28486
--- /dev/null
+++ b/src/spikeinterface/curation/tests/trained_pipeline/model_info.json
@@ -0,0 +1,60 @@
+{
+    "metric_params": {
+        "quality_metric_params": {
+            "metric_names": [
+                "snr",
+                "num_spikes"
+            ],
+            "peak_sign": null,
+            "seed": null,
+            "metric_params": {
+                "num_spikes": {},
+                "snr": {
+                    "peak_sign": "neg",
+                    "peak_mode": "extremum"
+                }
+            },
+            "skip_pc_metrics": false,
+            "delete_existing_metrics": false,
+            "metrics_to_compute": [
+                "snr",
+                "num_spikes"
+            ]
+        },
+        "template_metric_params": {
+            "metric_names": [
+                "half_width"
+            ],
+            "sparsity": null,
+            "peak_sign": "neg",
+            "upsampling_factor": 10,
+            "metric_params": {
+                "half_width": {
+                    "recovery_window_ms": 0.7,
+                    "peak_relative_threshold": 0.2,
+                    "peak_width_ms": 0.1,
+                    "depth_direction": "y",
+                    "min_channels_for_velocity": 5,
+                    "min_r2_velocity": 0.5,
+                    "exp_peak_function": "ptp",
+                    "min_r2_exp_decay": 0.5,
+                    "spread_threshold": 0.2,
+                    "spread_smooth_um": 20,
+                    "column_range": null
+                }
+            },
+            "delete_existing_metrics": false,
+            "metrics_to_compute": [
+                "half_width"
+            ]
+        }
+    },
+    "requirements": {
+        "spikeinterface": "0.101.1",
+        "scikit-learn": "1.3.2"
+    },
+    "label_conversion": {
+        "1": 1,
+        "0": 0
+    }
+}
diff --git a/src/spikeinterface/curation/tests/trained_pipeline/training_data.csv b/src/spikeinterface/curation/tests/trained_pipeline/training_data.csv
new file mode 100644
index 0000000000..c9efca17ad
--- /dev/null
+++ b/src/spikeinterface/curation/tests/trained_pipeline/training_data.csv
@@ -0,0 +1,21 @@
+unit_id,snr,num_spikes,half_width
+0,21.026926,5968.0,0.00027333334
+1,34.64474,5928.0,0.00023666666
+2,6.986315,5954.0,0.00026666667
+3,8.223127,6032.0,0.00020333333
+4,2.7464194,6002.0,0.00026666667
+0,21.026926,5968.0,0.00027333334
+1,34.64474,5928.0,0.00023666666
+2,6.986315,5954.0,0.00026666667
+3,8.223127,6032.0,0.00020333333
+4,2.7464194,6002.0,0.00026666667
+0,21.026926,5968.0,0.00027333334
+1,34.64474,5928.0,0.00023666666
+2,6.986315,5954.0,0.00026666667
+3,8.223127,6032.0,0.00020333333
+4,2.7464194,6002.0,0.00026666667
+0,21.026926,5968.0,0.00027333334
+1,34.64474,5928.0,0.00023666666
+2,6.986315,5954.0,0.00026666667
+3,8.223127,6032.0,0.00020333333
+4,2.7464194,6002.0,0.00026666667
diff --git a/src/spikeinterface/curation/train_manual_curation.py b/src/spikeinterface/curation/train_manual_curation.py
new file mode 100644
index 0000000000..7b315b0fba
--- /dev/null
+++ b/src/spikeinterface/curation/train_manual_curation.py
@@ -0,0 +1,843 @@
+import os
+import warnings
+import numpy as np
+import json
+import spikeinterface
+from spikeinterface.core.job_tools import fix_job_kwargs
+from spikeinterface.qualitymetrics import (
+    get_quality_metric_list,
+    get_quality_pca_metric_list,
+    qm_compute_name_to_column_names,
+)
+from spikeinterface.postprocessing import get_template_metric_names
+from spikeinterface.postprocessing.template_metrics import tm_compute_name_to_column_names
+from pathlib import Path
+from copy import deepcopy
+
+
+def get_default_classifier_search_spaces():
+
+    from scipy.stats import uniform, randint
+
+    default_classifier_search_spaces = {
+        "RandomForestClassifier": {
+            "n_estimators": [100, 150],
+            "criterion": ["gini", "entropy"],
+            "min_samples_split": [2, 4],
+            "min_samples_leaf": [2, 4],
+            "class_weight": ["balanced", "balanced_subsample"],
+        },
+        "AdaBoostClassifier": {
+            "learning_rate": [1, 2],
+            "n_estimators": [50, 100],
+            "algorithm": ["SAMME", "SAMME.R"],
+        },
+        "GradientBoostingClassifier": {
+            "learning_rate": uniform(0.05, 0.1),
+            "n_estimators": randint(100, 150),
+            "max_depth": [2, 4],
+            "min_samples_split": [2, 4],
+            "min_samples_leaf": [2, 4],
+        },
+        "SVC": {
+            "C": uniform(0.001, 10.0),
+            "kernel": ["sigmoid", "rbf"],
+            "gamma": uniform(0.001, 10.0),
+            "probability": [True],
+        },
+        "LogisticRegression": {
+            "C": uniform(0.001, 10.0),
+            "solver": ["newton-cg", "lbfgs", "liblinear", "sag", "saga"],
+            "max_iter": [100],
+        },
+        "XGBClassifier": {
+            "max_depth": [2, 4],
+            "eta": uniform(0.2, 0.5),
+            "sampling_method": ["uniform"],
+            "grow_policy": ["depthwise", "lossguide"],
+        },
+        "CatBoostClassifier": {"depth": [2, 4], "learning_rate": uniform(0.05, 0.15), "n_estimators": [100, 150]},
+        "LGBMClassifier": {"learning_rate": uniform(0.05, 0.15), "n_estimators": randint(100, 150)},
+        "MLPClassifier": {
+            "activation": ["tanh", "relu"],
+            "solver": ["adam"],
+            "alpha": uniform(1e-7, 1e-1),
+            "learning_rate": ["constant", "adaptive"],
+            "n_iter_no_change": [32],
+        },
+    }
+
+    return default_classifier_search_spaces
+
+
+class CurationModelTrainer:
+    """
+    Used to train and evaluate machine learning models for spike sorting curation.
+
+    Parameters
+    ----------
+    labels : list of lists, default: None
+        List of curated labels for each unit; must be in the same order as the metrics data.
+    folder : str, default: None
+        The folder where outputs such as models and evaluation metrics will be saved, if specified. Requires the skops library. If None, output will not be saved on file system.
+    metric_names : list of str, default: None
+        A list of metrics to use for training. If None, default metrics will be used.
+    imputation_strategies : list of str | None, default: None
+        A list of imputation strategies to try. Can be "knn”, "iterative" or any allowed
+        strategy passable to the sklearn `SimpleImputer`. If None, the default strategies
+        `["median", "most_frequent", "knn", "iterative"]` will be used.
+    scaling_techniques : list of str | None, default: None
+        A list of scaling techniques to try. Can be "standard_scaler", "min_max_scaler",
+        or "robust_scaler", If None, all techniques will be used.
+    classifiers : list of str or dict, default: None
+        A list of classifiers to evaluate. Optionally, a dictionary of classifiers and their hyperparameter search spaces can be provided. If None, default classifiers will be used. Check the `get_classifier_search_space` method for the default search spaces & format for custom spaces.
+    test_size : float, default: 0.2
+        Proportion of the dataset to include in the test split, passed to `train_test_split` from `sklear`.
+    seed : int, default: None
+        Random seed for reproducibility. If None, a random seed will be generated.
+    smote : bool, default: False
+        Whether to apply SMOTE for class imbalance. Default is False. Requires imbalanced-learn package.
+    verbose : bool, default: True
+        If True, useful information is printed during training.
+    search_kwargs : dict or None, default: None
+        Keyword arguments passed to `BayesSearchCV` or `RandomizedSearchCV` from `sklearn`. If None, use
+        `search_kwargs = {'cv': 3, 'scoring': 'balanced_accuracy', 'n_iter': 25}`.
+
+    Attributes
+    ----------
+    folder : str
+        The folder where outputs such as models and evaluation metrics will be saved. Requires the skops library.
+    labels : list of lists, default: None
+        List of curated labels for each `sorting_analyzer` and each unit; must be in the same order as the metrics data.
+    imputation_strategies : list of str | None, default: None
+        A list of imputation strategies to try. Can be "knn”, "iterative" or any allowed
+        strategy passable to the sklearn `SimpleImputer`. If None, the default strategies
+        `["median", "most_frequent", "knn", "iterative"]` will be used.
+    scaling_techniques : list of str | None, default: None
+        A list of scaling techniques to try. Can be "standard_scaler", "min_max_scaler",
+        or "robust_scaler", If None, all techniques will be used.
+    classifiers : list of str
+        The list of classifiers to evaluate.
+    classifier_search_space : dict or None
+        Dictionary of classifiers and their hyperparameter search spaces, if provided. If None, default search spaces are used.
+    seed : int
+        Random seed for reproducibility.
+    metrics_list : list of str
+        The list of metrics to use for training.
+    X : pandas.DataFrame or None
+        The feature matrix after preprocessing.
+    y : pandas.Series or None
+        The target vector after preprocessing.
+    testing_metrics : dict or None
+        Dictionary to hold testing metrics data.
+    label_conversion : dict or None
+        Dictionary to map string labels to integer codes if target column contains string labels.
+
+    Methods
+    -------
+    get_default_metrics_list()
+        Returns the default list of metrics.
+    load_and_preprocess_full(path)
+        Loads and preprocesses the data from the given path.
+    load_data_file(path)
+        Loads the data file from the given path.
+    process_test_data_for_classification()
+        Processes the test data for classification.
+    apply_scaling_imputation(imputation_strategy, scaling_technique, X_train, X_val, y_train, y_val)
+        Applies the specified imputation and scaling techniques to the data.
+    get_classifier_instance(classifier_name)
+        Returns an instance of the specified classifier.
+    get_classifier_search_space(classifier_name)
+        Returns the search space for hyperparameter tuning for the specified classifier.
+    get_classifier_search_space()
+        Returns the default search spaces for hyperparameter tuning for the classifiers.
+    evaluate_model_config(imputation_strategies, scaling_techniques, classifiers)
+        Evaluates the model configurations with the given imputation strategies, scaling techniques, and classifiers.
+    """
+
+    def __init__(
+        self,
+        labels=None,
+        folder=None,
+        metric_names=None,
+        imputation_strategies=None,
+        scaling_techniques=None,
+        classifiers=None,
+        test_size=0.2,
+        seed=None,
+        smote=False,
+        verbose=True,
+        search_kwargs=None,
+        **job_kwargs,
+    ):
+
+        import pandas as pd
+
+        if imputation_strategies is None:
+            imputation_strategies = ["median", "most_frequent", "knn", "iterative"]
+
+        if scaling_techniques is None:
+            scaling_techniques = [
+                "standard_scaler",
+                "min_max_scaler",
+                "robust_scaler",
+            ]
+
+        if classifiers is None:
+            self.classifiers = ["RandomForestClassifier"]
+            self.classifier_search_space = None
+        elif isinstance(classifiers, dict):
+            self.classifiers = list(classifiers.keys())
+            self.classifier_search_space = classifiers
+        elif isinstance(classifiers, list):
+            self.classifiers = classifiers
+            self.classifier_search_space = None
+        else:
+            raise ValueError("classifiers must be a list or dictionary")
+
+        # check if labels is a list of lists
+        if not all(isinstance(label, list) or isinstance(label, np.ndarray) for label in labels):
+            raise ValueError("labels must be a list of lists")
+
+        self.folder = Path(folder) if folder is not None else None
+        self.imputation_strategies = imputation_strategies
+        self.scaling_techniques = scaling_techniques
+        self.test_size = test_size
+        self.seed = seed if seed is not None else np.random.default_rng(seed=None).integers(0, 2**31)
+        self.metrics_params = {}
+        self.smote = smote
+        self.label_conversion = None
+        self.verbose = verbose
+        self.search_kwargs = search_kwargs
+
+        self.X = None
+        self.testing_metrics = None
+
+        self.requirements = {"spikeinterface": spikeinterface.__version__}
+
+        self.y = pd.concat([pd.DataFrame(one_labels)[0] for one_labels in labels])
+
+        self.metric_names = metric_names
+
+        if self.folder is not None and not self.folder.is_dir():
+            self.folder.mkdir(parents=True, exist_ok=True)
+
+        # update job_kwargs with global ones
+        job_kwargs = fix_job_kwargs(job_kwargs)
+        self.n_jobs = job_kwargs["n_jobs"]
+
+    def get_default_metrics_list(self):
+        """Returns the default list of metrics."""
+        return get_quality_metric_list() + get_quality_pca_metric_list() + get_template_metric_names()
+
+    def load_and_preprocess_analyzers(self, analyzers, enforce_metric_params):
+        """
+        Loads and preprocesses the quality metrics and labels from the given list of SortingAnalyzer objects.
+        """
+        import pandas as pd
+
+        metrics_for_each_analyzer = [_get_computed_metrics(an) for an in analyzers]
+        check_metric_names_are_the_same(metrics_for_each_analyzer)
+
+        self.testing_metrics = pd.concat(metrics_for_each_analyzer, axis=0)
+
+        # Set metric names to those calculated if not provided
+        if self.metric_names is None:
+            warnings.warn("No metric_names provided, using all metrics calculated by the analyzers")
+            self.metric_names = self.testing_metrics.columns.tolist()
+
+        conflicting_metrics = self._check_metrics_parameters(analyzers, enforce_metric_params)
+
+        self.metrics_params = {}
+
+        extension_names = ["quality_metrics", "template_metrics"]
+        metric_extensions = [analyzers[0].get_extension(extension_name) for extension_name in extension_names]
+
+        for metric_extension, extension_name in zip(metric_extensions, extension_names):
+
+            # remove the 's' at the end of the extension name
+            extension_name = extension_name[:-1]
+            if metric_extension is not None:
+                self.metrics_params[extension_name + "_params"] = metric_extension.params
+
+                # Only save metric params which are 1) consistent and 2) exist in metric_names
+                metric_names = metric_extension.params["metric_names"]
+                consistent_metrics = list(set(metric_names).difference(set(conflicting_metrics)))
+                consistent_metric_params = {
+                    metric: metric_extension.params["metric_params"][metric] for metric in consistent_metrics
+                }
+                self.metrics_params[extension_name + "_params"]["metric_params"] = consistent_metric_params
+
+        self.process_test_data_for_classification()
+
+    def _check_metrics_parameters(self, analyzers, enforce_metric_params):
+        """Checks that the metrics of each analyzer have been calcualted using the same parameters"""
+
+        extension_names = ["quality_metrics", "template_metrics"]
+
+        conflicting_metrics = []
+        for analyzer_index_1, analyzer_1 in enumerate(analyzers):
+            for analyzer_index_2, analyzer_2 in enumerate(analyzers):
+
+                if analyzer_index_1 <= analyzer_index_2:
+                    continue
+                else:
+
+                    metric_params_1 = {}
+                    metric_params_2 = {}
+
+                    for extension_name in extension_names:
+                        if (extension_1 := analyzer_1.get_extension(extension_name)) is not None:
+                            metric_params_1.update(extension_1.params["metric_params"])
+                        if (extension_2 := analyzer_2.get_extension(extension_name)) is not None:
+                            metric_params_2.update(extension_2.params["metric_params"])
+
+                    conflicting_metrics_between_1_2 = []
+                    # check quality metrics params
+                    for metric, params_1 in metric_params_1.items():
+                        if params_1 != metric_params_2.get(metric):
+                            conflicting_metrics_between_1_2.append(metric)
+
+                    conflicting_metrics += conflicting_metrics_between_1_2
+
+                    if len(conflicting_metrics_between_1_2) > 0:
+                        warning_message = f"Parameters used to calculate {conflicting_metrics_between_1_2} are different for sorting_analyzers #{analyzer_index_1} and #{analyzer_index_2}"
+                        if enforce_metric_params is True:
+                            raise Exception(warning_message)
+                        else:
+                            warnings.warn(warning_message)
+
+        unique_conflicting_metrics = set(conflicting_metrics)
+        return unique_conflicting_metrics
+
+    def load_and_preprocess_csv(self, paths):
+        self._load_data_files(paths)
+        self.process_test_data_for_classification()
+        self.get_metric_params_csv()
+
+    def get_metric_params_csv(self):
+
+        from itertools import chain
+
+        qm_metric_names = list(chain.from_iterable(qm_compute_name_to_column_names.values()))
+        tm_metric_names = list(chain.from_iterable(tm_compute_name_to_column_names.values()))
+
+        quality_metric_names = []
+        template_metric_names = []
+
+        for metric_name in self.metric_names:
+            if metric_name in qm_metric_names:
+                quality_metric_names.append(metric_name)
+            if metric_name in tm_metric_names:
+                template_metric_names.append(metric_name)
+
+        self.metrics_params = {}
+        if quality_metric_names != {}:
+            self.metrics_params["quality_metric_params"] = {"metric_names": quality_metric_names}
+        if template_metric_names != {}:
+            self.metrics_params["template_metric_params"] = {"metric_names": template_metric_names}
+
+        return
+
+    def process_test_data_for_classification(self):
+        """
+        Cleans the input data so that it can be used by sklearn.
+
+        Extracts the target variable and features from the loaded dataset.
+        It handles string labels by converting them to integer codes and reindexes the
+        feature matrix to match the specified metrics list. Infinite values in the features
+        are replaced with NaN, and any remaining NaN values are filled with zeros.
+
+        Raises
+        ------
+        ValueError
+            If the target column specified is not found in the loaded dataset.
+
+        Notes
+        -----
+        If the target column contains string labels, a warning is issued and the labels
+        are converted to integer codes. The mapping from string labels to integer codes
+        is stored in the `label_conversion` attribute.
+        """
+
+        # Convert string labels to integer codes to allow classification
+        new_y = self.y.astype("category").cat.codes
+        self.label_conversion = dict(zip(new_y, self.y))
+        self.y = new_y
+
+        # Extract features
+        try:
+            if (set(self.metric_names) - set(self.testing_metrics.columns) != set()) and self.verbose is True:
+                print(
+                    f"Dropped metrics (calculated but not included in metric_names): {set(self.testing_metrics.columns) - set(self.metric_names)}"
+                )
+            self.X = self.testing_metrics[self.metric_names]
+        except KeyError as e:
+            raise KeyError(f"{str(e)}, metrics_list contains invalid metric names")
+
+        self.X = self.testing_metrics.reindex(columns=self.metric_names)
+        self.X = _format_metric_dataframe(self.X)
+
+    def apply_scaling_imputation(self, imputation_strategy, scaling_technique, X_train, X_test, y_train, y_test):
+        """Impute and scale the data using the specified techniques."""
+        from sklearn.experimental import enable_iterative_imputer
+        from sklearn.impute import SimpleImputer, KNNImputer, IterativeImputer
+        from sklearn.ensemble import HistGradientBoostingRegressor
+        from sklearn.preprocessing import StandardScaler, MinMaxScaler, RobustScaler
+
+        if imputation_strategy == "knn":
+            imputer = KNNImputer(n_neighbors=5)
+        elif imputation_strategy == "iterative":
+            imputer = IterativeImputer(
+                estimator=HistGradientBoostingRegressor(random_state=self.seed), random_state=self.seed
+            )
+        else:
+            imputer = SimpleImputer(strategy=imputation_strategy)
+
+        if scaling_technique == "standard_scaler":
+            scaler = StandardScaler()
+        elif scaling_technique == "min_max_scaler":
+            scaler = MinMaxScaler()
+        elif scaling_technique == "robust_scaler":
+            scaler = RobustScaler()
+        else:
+            raise ValueError(
+                f"Unknown scaling technique: {scaling_technique}. Supported scaling techniques are 'standard_scaler', 'min_max_scaler' and 'robust_scaler."
+            )
+
+        y_train_processed = y_train.astype(int)
+        y_test = y_test.astype(int)
+
+        X_train_imputed = imputer.fit_transform(X_train)
+        X_test_imputed = imputer.transform(X_test)
+        X_train_processed = scaler.fit_transform(X_train_imputed)
+        X_test_processed = scaler.transform(X_test_imputed)
+
+        # Apply SMOTE for class imbalance
+        if self.smote:
+            try:
+                from imblearn.over_sampling import SMOTE
+            except ModuleNotFoundError:
+                raise ModuleNotFoundError("Please install imbalanced-learn package to use SMOTE")
+            smote = SMOTE(random_state=self.seed)
+            X_train_processed, y_train_processed = smote.fit_resample(X_train_processed, y_train_processed)
+
+        return X_train_processed, X_test_processed, y_train_processed, y_test, imputer, scaler
+
+    def get_classifier_instance(self, classifier_name):
+        from sklearn.ensemble import RandomForestClassifier, AdaBoostClassifier, GradientBoostingClassifier
+        from sklearn.svm import SVC
+        from sklearn.linear_model import LogisticRegression
+        from sklearn.neural_network import MLPClassifier
+
+        classifier_mapping = {
+            "RandomForestClassifier": RandomForestClassifier(random_state=self.seed),
+            "AdaBoostClassifier": AdaBoostClassifier(random_state=self.seed),
+            "GradientBoostingClassifier": GradientBoostingClassifier(random_state=self.seed),
+            "SVC": SVC(random_state=self.seed),
+            "LogisticRegression": LogisticRegression(random_state=self.seed),
+            "MLPClassifier": MLPClassifier(random_state=self.seed),
+        }
+
+        # Check lightgbm package install
+        if classifier_name == "LGBMClassifier":
+            try:
+                import lightgbm
+
+                self.requirements["lightgbm"] = lightgbm.__version__
+                classifier_mapping["LGBMClassifier"] = lightgbm.LGBMClassifier(random_state=self.seed, verbose=-1)
+            except ImportError:
+                raise ImportError("Please install lightgbm package to use LGBMClassifier")
+        elif classifier_name == "CatBoostClassifier":
+            try:
+                import catboost
+
+                self.requirements["catboost"] = catboost.__version__
+                classifier_mapping["CatBoostClassifier"] = catboost.CatBoostClassifier(
+                    silent=True, random_state=self.seed
+                )
+            except ImportError:
+                raise ImportError("Please install catboost package to use CatBoostClassifier")
+        elif classifier_name == "XGBClassifier":
+            try:
+                import xgboost
+
+                self.requirements["xgboost"] = xgboost.__version__
+                classifier_mapping["XGBClassifier"] = xgboost.XGBClassifier(
+                    use_label_encoder=False, random_state=self.seed
+                )
+            except ImportError:
+                raise ImportError("Please install xgboost package to use XGBClassifier")
+
+        if classifier_name not in classifier_mapping:
+            raise ValueError(
+                f"Unknown classifier: {classifier_name}. To see list of supported classifiers run\n\t>>> from spikeinterface.curation import get_default_classifier_search_spaces\n\t>>> print(get_default_classifier_search_spaces().keys())"
+            )
+
+        return classifier_mapping[classifier_name]
+
+    def get_classifier_search_space(self, classifier_name):
+
+        default_classifier_search_spaces = get_default_classifier_search_spaces()
+
+        if classifier_name not in default_classifier_search_spaces:
+            raise ValueError(
+                f"Unknown classifier: {classifier_name}. To see list of supported classifiers run\n\t>>> from spikeinterface.curation import get_default_classifier_search_spaces\n\t>>> print(get_default_classifier_search_spaces().keys())"
+            )
+
+        model = self.get_classifier_instance(classifier_name)
+        if self.classifier_search_space is not None:
+            param_space = self.classifier_search_space[classifier_name]
+        else:
+            param_space = default_classifier_search_spaces[classifier_name]
+        return model, param_space
+
+    def evaluate_model_config(self):
+        """
+        Evaluates the model configurations with the given imputation strategies, scaling techniques, and classifiers.
+
+        This method splits the preprocessed data into training and testing sets, then evaluates the specified
+        combinations of imputation strategies, scaling techniques, and classifiers. The evaluation results are
+        saved to the output folder.
+
+        Raises
+        ------
+        ValueError
+            If any of the specified classifier names are not recognized.
+
+        Notes
+        -----
+        The method converts the classifier names to actual classifier instances before evaluating them.
+        The evaluation results, including the best model and its parameters, are saved to the output folder.
+        """
+        from sklearn.model_selection import train_test_split
+
+        X_train, X_test, y_train, y_test = train_test_split(
+            self.X, self.y, test_size=self.test_size, random_state=self.seed, stratify=self.y
+        )
+        classifier_instances = [self.get_classifier_instance(clf) for clf in self.classifiers]
+        self._evaluate(
+            self.imputation_strategies,
+            self.scaling_techniques,
+            classifier_instances,
+            X_train,
+            X_test,
+            y_train,
+            y_test,
+            self.search_kwargs,
+        )
+
+    def _load_data_files(self, paths):
+        import pandas as pd
+
+        self.testing_metrics = pd.concat([pd.read_csv(path, index_col=0) for path in paths], axis=0)
+
+    def _evaluate(
+        self, imputation_strategies, scaling_techniques, classifiers, X_train, X_test, y_train, y_test, search_kwargs
+    ):
+        from joblib import Parallel, delayed
+        from sklearn.pipeline import Pipeline
+        import pandas as pd
+
+        results = Parallel(n_jobs=self.n_jobs)(
+            delayed(self._train_and_evaluate)(
+                imputation_strategy, scaler, classifier, X_train, X_test, y_train, y_test, idx, search_kwargs
+            )
+            for idx, (imputation_strategy, scaler, classifier) in enumerate(
+                (imputation_strategy, scaler, classifier)
+                for imputation_strategy in imputation_strategies
+                for scaler in scaling_techniques
+                for classifier in classifiers
+            )
+        )
+
+        test_accuracies, models = zip(*results)
+
+        if self.search_kwargs is None or self.search_kwargs.get("scoring"):
+            scoring_method = "balanced_accuracy"
+        else:
+            scoring_method = self.search_kwargs.get("scoring")
+
+        self.test_accuracies_df = pd.DataFrame(test_accuracies).sort_values(scoring_method, ascending=False)
+
+        best_model_id = int(self.test_accuracies_df.iloc[0]["model_id"])
+        best_model, best_imputer, best_scaler = models[best_model_id]
+
+        best_pipeline = Pipeline(
+            [("imputer", best_imputer), ("scaler", best_scaler), ("classifier", best_model.best_estimator_)]
+        )
+
+        self.best_pipeline = best_pipeline
+
+        if self.folder is not None:
+            self._save()
+
+    def _save(self):
+        from skops.io import dump
+        import sklearn
+        import pandas as pd
+
+        # export training data and labels
+        pd.DataFrame(self.X).to_csv(self.folder / f"training_data.csv", index_label="unit_id")
+        pd.DataFrame(self.y).to_csv(self.folder / f"labels.csv", index_label="unit_index")
+
+        self.requirements["scikit-learn"] = sklearn.__version__
+
+        # Dump to skops if folder is provided
+        dump(self.best_pipeline, self.folder / f"best_model.skops")
+        self.test_accuracies_df.to_csv(self.folder / f"model_accuracies.csv", float_format="%.4f")
+
+        model_info = {}
+        model_info["metric_params"] = self.metrics_params
+
+        model_info["requirements"] = self.requirements
+
+        model_info["label_conversion"] = self.label_conversion
+
+        param_file = self.folder / "model_info.json"
+        Path(param_file).write_text(json.dumps(model_info, indent=4), encoding="utf8")
+
+    def _train_and_evaluate(
+        self, imputation_strategy, scaler, classifier, X_train, X_test, y_train, y_test, model_id, search_kwargs
+    ):
+        from sklearn.metrics import balanced_accuracy_score, precision_score, recall_score
+
+        search_kwargs = set_default_search_kwargs(search_kwargs)
+
+        X_train_scaled, X_test_scaled, y_train, y_test, imputer, scaler = self.apply_scaling_imputation(
+            imputation_strategy, scaler, X_train, X_test, y_train, y_test
+        )
+        if self.verbose is True:
+            print(f"Running {classifier.__class__.__name__} with imputation {imputation_strategy} and scaling {scaler}")
+        model, param_space = self.get_classifier_search_space(classifier.__class__.__name__)
+
+        try:
+            from skopt import BayesSearchCV
+
+            model = BayesSearchCV(
+                model,
+                param_space,
+                random_state=self.seed,
+                **search_kwargs,
+            )
+        except:
+            if self.verbose is True:
+                print("BayesSearchCV from scikit-optimize not available, using RandomizedSearchCV")
+            from sklearn.model_selection import RandomizedSearchCV
+
+            model = RandomizedSearchCV(model, param_space, **search_kwargs)
+
+        model.fit(X_train_scaled, y_train)
+        y_pred = model.predict(X_test_scaled)
+        balanced_acc = balanced_accuracy_score(y_test, y_pred)
+        precision = precision_score(y_test, y_pred, average="macro")
+        recall = recall_score(y_test, y_pred, average="macro")
+        return {
+            "classifier name": classifier.__class__.__name__,
+            "imputation_strategy": imputation_strategy,
+            "scaling_strategy": scaler,
+            "balanced_accuracy": balanced_acc,
+            "precision": precision,
+            "recall": recall,
+            "model_id": model_id,
+            "best_params": model.best_params_,
+        }, (model, imputer, scaler)
+
+
+def train_model(
+    mode="analyzers",
+    labels=None,
+    analyzers=None,
+    metrics_paths=None,
+    folder=None,
+    metric_names=None,
+    imputation_strategies=None,
+    scaling_techniques=None,
+    classifiers=None,
+    test_size=0.2,
+    overwrite=False,
+    seed=None,
+    search_kwargs=None,
+    verbose=True,
+    enforce_metric_params=False,
+    **job_kwargs,
+):
+    """
+    Trains and evaluates machine learning models for spike sorting curation.
+
+    This function initializes a `CurationModelTrainer` object, loads and preprocesses the data,
+    and evaluates the specified combinations of imputation strategies, scaling techniques, and classifiers.
+    The evaluation results, including the best model and its parameters, are saved to the output folder.
+
+    Parameters
+    ----------
+    mode : "analyzers" | "csv", default: "analyzers"
+        Mode to use for training.
+    analyzers : list of SortingAnalyzer | None, default: None
+         List of SortingAnalyzer objects containing the quality metrics and labels to use for training, if using 'analyzers' mode.
+    labels : list of list | None, default: None
+        List of curated labels for each unit; must be in the same order as the metrics data.
+    metrics_paths : list of str or None, default: None
+        List of paths to the CSV files containing the metrics data if using 'csv' mode.
+    folder : str | None, default: None
+        The folder where outputs such as models and evaluation metrics will be saved.
+    metric_names : list of str | None, default: None
+        A list of metrics to use for training. If None, default metrics will be used.
+    imputation_strategies : list of str | None, default: None
+        A list of imputation strategies to try. Can be "knn”, "iterative" or any allowed
+        strategy passable to the sklearn `SimpleImputer`. If None, the default strategies
+        `["median", "most_frequent", "knn", "iterative"]` will be used.
+    scaling_techniques : list of str | None, default: None
+        A list of scaling techniques to try. Can be "standard_scaler", "min_max_scaler",
+        or "robust_scaler", If None, all techniques will be used.
+    classifiers : list of str | dict | None, default: None
+        A list of classifiers to evaluate. Optionally, a dictionary of classifiers and their hyperparameter search spaces can be provided. If None, default classifiers will be used. Check the `get_classifier_search_space` method for the default search spaces & format for custom spaces.
+    test_size : float, default: 0.2
+        Proportion of the dataset to include in the test split, passed to `train_test_split` from `sklear`.
+    overwrite : bool, default: False
+        Overwrites the `folder` if it already exists
+    seed : int | None, default: None
+        Random seed for reproducibility. If None, a random seed will be generated.
+    search_kwargs : dict or None, default: None
+        Keyword arguments passed to `BayesSearchCV` or `RandomizedSearchCV` from `sklearn`. If None, use
+        `search_kwargs = {'cv': 3, 'scoring': 'balanced_accuracy', 'n_iter': 25}`.
+    verbose : bool, default: True
+        If True, useful information is printed during training.
+    enforce_metric_params : bool, default: False
+        If True and metric parameters used to calculate metrics for different `sorting_analyzer`s are
+        different, an error will be raised.
+
+
+    Returns
+    -------
+    CurationModelTrainer
+        The `CurationModelTrainer` object used for training and evaluation.
+
+    Notes
+    -----
+    This function handles the entire workflow of initializing the trainer, loading and preprocessing the data,
+    and evaluating the models. The evaluation results are saved to the specified output folder.
+    """
+
+    if folder is None:
+        raise Exception("You must supply a folder for the model to be saved in using `folder='path/to/folder/'`")
+
+    if overwrite is False:
+        assert not Path(folder).is_dir(), f"folder {folder} already exists, choose another name or use overwrite=True"
+
+    if labels is None:
+        raise Exception("You must supply a list of lists of curated labels using `labels = [[...],[...],...]`")
+
+    if mode not in ["analyzers", "csv"]:
+        raise Exception("`mode` must be equal to 'analyzers' or 'csv'.")
+
+    if (test_size > 1.0) or (0.0 > test_size):
+        raise Exception("`test_size` must be between 0.0 and 1.0")
+
+    trainer = CurationModelTrainer(
+        labels=labels,
+        folder=folder,
+        metric_names=metric_names,
+        imputation_strategies=imputation_strategies,
+        scaling_techniques=scaling_techniques,
+        classifiers=classifiers,
+        test_size=test_size,
+        seed=seed,
+        verbose=verbose,
+        search_kwargs=search_kwargs,
+        **job_kwargs,
+    )
+
+    if mode == "analyzers":
+        assert analyzers is not None, "Analyzers must be provided as a list for mode 'analyzers'"
+        trainer.load_and_preprocess_analyzers(analyzers, enforce_metric_params)
+
+    elif mode == "csv":
+        for metrics_path in metrics_paths:
+            assert Path(metrics_path).is_file(), f"{metrics_path} is not a file."
+        trainer.load_and_preprocess_csv(metrics_paths)
+
+    trainer.evaluate_model_config()
+    return trainer
+
+
+def _get_computed_metrics(sorting_analyzer):
+    """Loads and organises the computed metrics from a sorting_analyzer into a single dataframe"""
+
+    import pandas as pd
+
+    quality_metrics, template_metrics = try_to_get_metrics_from_analyzer(sorting_analyzer)
+    calculated_metrics = pd.concat([quality_metrics, template_metrics], axis=1)
+
+    # Remove any metrics for non-existent units, raise error if no units are present
+    calculated_metrics = calculated_metrics.loc[calculated_metrics.index.isin(sorting_analyzer.sorting.get_unit_ids())]
+    if calculated_metrics.shape[0] == 0:
+        raise ValueError("No units present in sorting data")
+
+    return calculated_metrics
+
+
+def try_to_get_metrics_from_analyzer(sorting_analyzer):
+
+    extension_names = ["quality_metrics", "template_metrics"]
+    metric_extensions = [sorting_analyzer.get_extension(extension_name) for extension_name in extension_names]
+
+    if any(metric_extensions) is False:
+        raise ValueError(
+            "At least one of quality metrics or template metrics must be computed before classification.",
+            "Compute both using `sorting_analyzer.compute('quality_metrics', 'template_metrics')",
+        )
+
+    metric_extensions_data = []
+    for metric_extension in metric_extensions:
+        try:
+            metric_extensions_data.append(metric_extension.get_data())
+        except:
+            metric_extensions_data.append(None)
+
+    return metric_extensions_data
+
+
+def set_default_search_kwargs(search_kwargs):
+
+    if search_kwargs is None:
+        search_kwargs = {}
+
+    if search_kwargs.get("cv") is None:
+        search_kwargs["cv"] = 5
+    if search_kwargs.get("scoring") is None:
+        search_kwargs["scoring"] = "balanced_accuracy"
+    if search_kwargs.get("n_iter") is None:
+        search_kwargs["n_iter"] = 25
+
+    return search_kwargs
+
+
+def check_metric_names_are_the_same(metrics_for_each_analyzer):
+    """
+    Given a list of dataframes, checks that the keys are all equal.
+    """
+
+    for i, metrics_for_analyzer_1 in enumerate(metrics_for_each_analyzer):
+        for j, metrics_for_analyzer_2 in enumerate(metrics_for_each_analyzer):
+            if i > j:
+                metric_names_1 = set(metrics_for_analyzer_1.keys())
+                metric_names_2 = set(metrics_for_analyzer_2.keys())
+                if metric_names_1 != metric_names_2:
+                    metrics_in_1_but_not_2 = metric_names_1.difference(metric_names_2)
+                    metrics_in_2_but_not_1 = metric_names_2.difference(metric_names_1)
+
+                    error_message = f"Computed metrics are not equal for sorting_analyzers #{j} and #{i}\n"
+                    if metrics_in_1_but_not_2:
+                        error_message += f"#{j} does not contain {metrics_in_1_but_not_2}, which #{i} does."
+                    if metrics_in_2_but_not_1:
+                        error_message += f"#{i} does not contain {metrics_in_2_but_not_1}, which #{j} does."
+                    raise Exception(error_message)
+
+
+def _format_metric_dataframe(input_data):
+
+    input_data = input_data.map(lambda x: np.nan if np.isinf(x) else x)
+    input_data = input_data.astype("float32")
+
+    return input_data
diff --git a/src/spikeinterface/qualitymetrics/pca_metrics.py b/src/spikeinterface/qualitymetrics/pca_metrics.py
index ca21f1e45f..c789d1af82 100644
--- a/src/spikeinterface/qualitymetrics/pca_metrics.py
+++ b/src/spikeinterface/qualitymetrics/pca_metrics.py
@@ -42,6 +42,9 @@
         max_spikes=10000, min_spikes=10, min_fr=0.0, n_neighbors=4, n_components=10, radius_um=100, peak_sign="neg"
     ),
     silhouette=dict(method=("simplified",)),
+    isolation_distance=dict(),
+    l_ratio=dict(),
+    d_prime=dict(),
 )
 
 

From cead752945f912b5677b16b37c8a30e1e7bea699 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Mon, 13 Jan 2025 12:33:28 +0100
Subject: [PATCH 303/344] Fix empty merge_unit_groups

---
 .../curation/curation_format.py               | 30 +++++++++++--------
 1 file changed, 17 insertions(+), 13 deletions(-)

diff --git a/src/spikeinterface/curation/curation_format.py b/src/spikeinterface/curation/curation_format.py
index f51b782572..80f251ca43 100644
--- a/src/spikeinterface/curation/curation_format.py
+++ b/src/spikeinterface/curation/curation_format.py
@@ -242,7 +242,7 @@ def apply_curation_labels(sorting, new_unit_ids, curation_dict):
         all_values = np.zeros(sorting.unit_ids.size, dtype=values.dtype)
         for unit_ind, unit_id in enumerate(sorting.unit_ids):
             if unit_id not in new_unit_ids:
-                ind = curation_dict["unit_ids"].index(unit_id)
+                ind = list(curation_dict["unit_ids"]).index(unit_id)
                 all_values[unit_ind] = values[ind]
         sorting.set_property(key, all_values)
 
@@ -343,18 +343,22 @@ def apply_curation(
 
     elif isinstance(sorting_or_analyzer, SortingAnalyzer):
         analyzer = sorting_or_analyzer
-        analyzer = analyzer.remove_units(curation_dict["removed_units"])
-        analyzer, new_unit_ids = analyzer.merge_units(
-            curation_dict["merge_unit_groups"],
-            censor_ms=censor_ms,
-            merging_mode=merging_mode,
-            sparsity_overlap=sparsity_overlap,
-            new_id_strategy=new_id_strategy,
-            return_new_unit_ids=True,
-            format="memory",
-            verbose=verbose,
-            **job_kwargs,
-        )
+        if len(curation_dict["removed_units"]) > 0:
+            analyzer = analyzer.remove_units(curation_dict["removed_units"])
+        if len(curation_dict["merge_unit_groups"]) > 0:
+            analyzer, new_unit_ids = analyzer.merge_units(
+                curation_dict["merge_unit_groups"],
+                censor_ms=censor_ms,
+                merging_mode=merging_mode,
+                sparsity_overlap=sparsity_overlap,
+                new_id_strategy=new_id_strategy,
+                return_new_unit_ids=True,
+                format="memory",
+                verbose=verbose,
+                **job_kwargs,
+            )
+        else:
+            new_unit_ids = []
         apply_curation_labels(analyzer.sorting, new_unit_ids, curation_dict)
         return analyzer
     else:

From 3c8e96f6f56b5bf291ff8472e7f3554a9f186b13 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Mon, 13 Jan 2025 15:19:36 +0100
Subject: [PATCH 304/344] Fix sphinx doc build

---
 readthedocs.yml | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/readthedocs.yml b/readthedocs.yml
index 512fcbc709..2bbdded59e 100644
--- a/readthedocs.yml
+++ b/readthedocs.yml
@@ -1,5 +1,9 @@
 version: 2
 
+sphinx:
+  # Path to your Sphinx configuration file.
+  configuration: docs/conf.py
+
 build:
   os: ubuntu-22.04
   tools:

From e78f44b17d36de9ee67db4eee03d08f473c0f821 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Mon, 13 Jan 2025 16:06:59 +0100
Subject: [PATCH 305/344] Load extractor can read remote zarr use_times in
 get_duration

---
 src/spikeinterface/core/base.py          | 102 ++++++++++++-----------
 src/spikeinterface/core/baserecording.py |  21 +++--
 2 files changed, 70 insertions(+), 53 deletions(-)

diff --git a/src/spikeinterface/core/base.py b/src/spikeinterface/core/base.py
index 1fa218851b..64eb6f6ca3 100644
--- a/src/spikeinterface/core/base.py
+++ b/src/spikeinterface/core/base.py
@@ -16,7 +16,7 @@
 
 from .globals import get_global_tmp_folder, is_set_global_tmp_folder
 from .core_tools import (
-    check_json,
+    is_path_remote,
     clean_zarr_folder_name,
     is_dict_extractor,
     SIJsonEncoder,
@@ -761,63 +761,71 @@ def load(file_path: Union[str, Path], base_folder: Optional[Union[Path, str, boo
           * save (...)  a folder which contain data  + json (or pickle) + metadata.
 
         """
+        if not is_path_remote(file_path):
+            file_path = Path(file_path)
+
+            if base_folder is True:
+                base_folder = file_path.parent
+
+            if file_path.is_file():
+                # standard case based on a file (json or pickle)
+                if str(file_path).endswith(".json"):
+                    with open(file_path, "r") as f:
+                        d = json.load(f)
+                elif str(file_path).endswith(".pkl") or str(file_path).endswith(".pickle"):
+                    with open(file_path, "rb") as f:
+                        d = pickle.load(f)
+                else:
+                    raise ValueError(f"Impossible to load {file_path}")
+                if "warning" in d:
+                    print("The extractor was not serializable to file")
+                    return None
 
-        file_path = Path(file_path)
-        if base_folder is True:
-            base_folder = file_path.parent
-
-        if file_path.is_file():
-            # standard case based on a file (json or pickle)
-            if str(file_path).endswith(".json"):
-                with open(file_path, "r") as f:
-                    d = json.load(f)
-            elif str(file_path).endswith(".pkl") or str(file_path).endswith(".pickle"):
-                with open(file_path, "rb") as f:
-                    d = pickle.load(f)
-            else:
-                raise ValueError(f"Impossible to load {file_path}")
-            if "warning" in d:
-                print("The extractor was not serializable to file")
-                return None
+                extractor = BaseExtractor.from_dict(d, base_folder=base_folder)
+                return extractor
 
-            extractor = BaseExtractor.from_dict(d, base_folder=base_folder)
-            return extractor
+            elif file_path.is_dir():
+                # case from a folder after a calling extractor.save(...)
+                folder = file_path
+                file = None
 
-        elif file_path.is_dir():
-            # case from a folder after a calling extractor.save(...)
-            folder = file_path
-            file = None
+                if folder.suffix == ".zarr":
+                    from .zarrextractors import read_zarr
 
-            if folder.suffix == ".zarr":
-                from .zarrextractors import read_zarr
-
-                extractor = read_zarr(folder)
-            else:
-                # the is spikeinterface<=0.94.0
-                # a folder came with 'cached.json'
-                for dump_ext in ("json", "pkl", "pickle"):
-                    f = folder / f"cached.{dump_ext}"
+                    extractor = read_zarr(folder)
+                else:
+                    # the is spikeinterface<=0.94.0
+                    # a folder came with 'cached.json'
+                    for dump_ext in ("json", "pkl", "pickle"):
+                        f = folder / f"cached.{dump_ext}"
+                        if f.is_file():
+                            file = f
+
+                    # spikeinterface>=0.95.0
+                    f = folder / f"si_folder.json"
                     if f.is_file():
                         file = f
 
-                # spikeinterface>=0.95.0
-                f = folder / f"si_folder.json"
-                if f.is_file():
-                    file = f
+                    if file is None:
+                        raise ValueError(f"This folder is not a cached folder {file_path}")
+                    extractor = BaseExtractor.load(file, base_folder=folder)
+            else:
+                error_msg = (
+                    f"{file_path} is not a file or a folder. It should point to either a json, pickle file or a "
+                    "folder that is the result of extractor.save(...)"
+                )
+                raise ValueError(error_msg)
+        else:
+            # remote case - zarr
+            if str(file_path).endswith(".zarr"):
+                from .zarrextractors import read_zarr
 
-                if file is None:
-                    raise ValueError(f"This folder is not a cached folder {file_path}")
-                extractor = BaseExtractor.load(file, base_folder=folder)
+                extractor = read_zarr(file_path)
+            else:
+                raise NotImplementedError("Only zarr format is supported for remote files")
 
             return extractor
 
-        else:
-            error_msg = (
-                f"{file_path} is not a file or a folder. It should point to either a json, pickle file or a "
-                "folder that is the result of extractor.save(...)"
-            )
-            raise ValueError(error_msg)
-
     def __reduce__(self):
         """
         This function is used by pickle to serialize the object.
diff --git a/src/spikeinterface/core/baserecording.py b/src/spikeinterface/core/baserecording.py
index 7ca527e255..b42bc3a273 100644
--- a/src/spikeinterface/core/baserecording.py
+++ b/src/spikeinterface/core/baserecording.py
@@ -59,7 +59,7 @@ def __repr__(self):
         if num_segments > 1:
             samples_per_segment = [self.get_num_samples(segment_index) for segment_index in range(num_segments)]
             memory_per_segment_bytes = (self.get_memory_size(segment_index) for segment_index in range(num_segments))
-            durations = [self.get_duration(segment_index) for segment_index in range(num_segments)]
+            durations = [self.get_duration(segment_index, use_times=False) for segment_index in range(num_segments)]
 
             samples_per_segment_formated = [f"{samples:,}" for samples in samples_per_segment]
             durations_per_segment_formated = [convert_seconds_to_str(d) for d in durations]
@@ -95,7 +95,7 @@ def _repr_header(self):
         dtype = self.get_dtype()
 
         total_samples = self.get_total_samples()
-        total_duration = self.get_total_duration()
+        total_duration = self.get_total_duration(use_times=False)
         total_memory_size = self.get_total_memory_size()
 
         sf_hz = self.get_sampling_frequency()
@@ -216,7 +216,7 @@ def get_total_samples(self) -> int:
 
         return sum(samples_per_segment)
 
-    def get_duration(self, segment_index=None) -> float:
+    def get_duration(self, segment_index=None, use_times=True) -> float:
         """
         Returns the duration in seconds.
 
@@ -226,6 +226,9 @@ def get_duration(self, segment_index=None) -> float:
             The sample index to retrieve the duration for.
             For multi-segment objects, it is required, default: None
             With single segment recording returns the duration of the single segment
+        use_times : bool, default: True
+            If True, the duration is calculated using the time vector if available.
+            If False, the duration is calculated using the number of samples and the sampling frequency.
 
         Returns
         -------
@@ -234,7 +237,7 @@ def get_duration(self, segment_index=None) -> float:
         """
         segment_index = self._check_segment_index(segment_index)
 
-        if self.has_time_vector(segment_index):
+        if self.has_time_vector(segment_index) and use_times:
             times = self.get_times(segment_index)
             segment_duration = times[-1] - times[0] + (1 / self.get_sampling_frequency())
         else:
@@ -243,16 +246,22 @@ def get_duration(self, segment_index=None) -> float:
 
         return segment_duration
 
-    def get_total_duration(self) -> float:
+    def get_total_duration(self, use_times=True) -> float:
         """
         Returns the total duration in seconds
 
+        Parameters
+        ----------
+        use_times : bool, default: True
+            If True, the duration is calculated using the time vector if available.
+            If False, the duration is calculated using the number of samples and the sampling frequency.
+
         Returns
         -------
         float
             The duration in seconds
         """
-        duration = sum([self.get_duration(idx) for idx in range(self.get_num_segments())])
+        duration = sum([self.get_duration(idx, use_times) for idx in range(self.get_num_segments())])
         return duration
 
     def get_memory_size(self, segment_index=None) -> int:

From ab92a6bc7369cd908ea04fb7d62207dcb7896783 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Mon, 13 Jan 2025 16:16:26 +0100
Subject: [PATCH 306/344] oups

---
 src/spikeinterface/core/base.py | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/core/base.py b/src/spikeinterface/core/base.py
index 64eb6f6ca3..3a3171a2b4 100644
--- a/src/spikeinterface/core/base.py
+++ b/src/spikeinterface/core/base.py
@@ -761,6 +761,7 @@ def load(file_path: Union[str, Path], base_folder: Optional[Union[Path, str, boo
           * save (...)  a folder which contain data  + json (or pickle) + metadata.
 
         """
+        print(file_path, is_path_remote(file_path))
         if not is_path_remote(file_path):
             file_path = Path(file_path)
 
@@ -782,7 +783,6 @@ def load(file_path: Union[str, Path], base_folder: Optional[Union[Path, str, boo
                     return None
 
                 extractor = BaseExtractor.from_dict(d, base_folder=base_folder)
-                return extractor
 
             elif file_path.is_dir():
                 # case from a folder after a calling extractor.save(...)
@@ -809,6 +809,7 @@ def load(file_path: Union[str, Path], base_folder: Optional[Union[Path, str, boo
                     if file is None:
                         raise ValueError(f"This folder is not a cached folder {file_path}")
                     extractor = BaseExtractor.load(file, base_folder=folder)
+
             else:
                 error_msg = (
                     f"{file_path} is not a file or a folder. It should point to either a json, pickle file or a "
@@ -824,7 +825,7 @@ def load(file_path: Union[str, Path], base_folder: Optional[Union[Path, str, boo
             else:
                 raise NotImplementedError("Only zarr format is supported for remote files")
 
-            return extractor
+        return extractor
 
     def __reduce__(self):
         """

From 9614dc79721c54f1822d277d5916e2dce75f3b64 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Mon, 13 Jan 2025 16:27:06 +0100
Subject: [PATCH 307/344] oups

---
 readthedocs.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/readthedocs.yml b/readthedocs.yml
index 2bbdded59e..c6c44d83a0 100644
--- a/readthedocs.yml
+++ b/readthedocs.yml
@@ -2,7 +2,7 @@ version: 2
 
 sphinx:
   # Path to your Sphinx configuration file.
-  configuration: docs/conf.py
+  configuration: doc/conf.py
 
 build:
   os: ubuntu-22.04

From 6a6fccf59d0ee27c1292089b6654626447efb4d0 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Mon, 13 Jan 2025 16:44:58 +0100
Subject: [PATCH 308/344] Update readthedocs.yml

---
 readthedocs.yml | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/readthedocs.yml b/readthedocs.yml
index 2bbdded59e..512fcbc709 100644
--- a/readthedocs.yml
+++ b/readthedocs.yml
@@ -1,9 +1,5 @@
 version: 2
 
-sphinx:
-  # Path to your Sphinx configuration file.
-  configuration: docs/conf.py
-
 build:
   os: ubuntu-22.04
   tools:

From 47a04b31015cb73f15325331d972c2726726cea2 Mon Sep 17 00:00:00 2001
From: Divyansh Gupta <divyanshgupta95@gmail.com>
Date: Mon, 13 Jan 2025 17:38:59 +0100
Subject: [PATCH 309/344] Change to defaultt value use_binary_file=True for KS4

---
 src/spikeinterface/sorters/external/kilosort4.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/sorters/external/kilosort4.py b/src/spikeinterface/sorters/external/kilosort4.py
index 2a9fb34267..ec15506006 100644
--- a/src/spikeinterface/sorters/external/kilosort4.py
+++ b/src/spikeinterface/sorters/external/kilosort4.py
@@ -66,7 +66,7 @@ class Kilosort4Sorter(BaseSorter):
         "do_correction": True,
         "keep_good_only": False,
         "skip_kilosort_preprocessing": False,
-        "use_binary_file": None,
+        "use_binary_file": True,
         "delete_recording_dat": True,
     }
 
@@ -116,7 +116,7 @@ class Kilosort4Sorter(BaseSorter):
         "keep_good_only": "If True, only the units labeled as 'good' by Kilosort are returned in the output. (spikeinterface parameter)",
         "use_binary_file": "If True then Kilosort is run using a binary file. In this case, if the input recording is not binary compatible, it is written to a binary file in the output folder. "
         "If False then Kilosort is run on the recording object directly using the RecordingExtractorAsArray object. If None, then if the recording is binary compatible, the sorter will use the binary file, otherwise the RecordingExtractorAsArray. "
-        "Default is None. (spikeinterface parameter)",
+        "Default is True. (spikeinterface parameter)",
         "delete_recording_dat": "If True, if a temporary binary file is created, it is deleted after the sorting is done. Default is True. (spikeinterface parameter)",
     }
 

From f00c7913e2572e4cb37fd04db1509d5280a48c1e Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Tue, 14 Jan 2025 15:23:32 +0100
Subject: [PATCH 310/344] Apply suggestions from code review

Co-authored-by: Zach McKenzie <92116279+zm711@users.noreply.github.com>
---
 src/spikeinterface/core/base.py          | 1 -
 src/spikeinterface/core/baserecording.py | 2 +-
 2 files changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/spikeinterface/core/base.py b/src/spikeinterface/core/base.py
index 3a3171a2b4..119ef46ed4 100644
--- a/src/spikeinterface/core/base.py
+++ b/src/spikeinterface/core/base.py
@@ -761,7 +761,6 @@ def load(file_path: Union[str, Path], base_folder: Optional[Union[Path, str, boo
           * save (...)  a folder which contain data  + json (or pickle) + metadata.
 
         """
-        print(file_path, is_path_remote(file_path))
         if not is_path_remote(file_path):
             file_path = Path(file_path)
 
diff --git a/src/spikeinterface/core/baserecording.py b/src/spikeinterface/core/baserecording.py
index b42bc3a273..9873265c37 100644
--- a/src/spikeinterface/core/baserecording.py
+++ b/src/spikeinterface/core/baserecording.py
@@ -261,7 +261,7 @@ def get_total_duration(self, use_times=True) -> float:
         float
             The duration in seconds
         """
-        duration = sum([self.get_duration(idx, use_times) for idx in range(self.get_num_segments())])
+        duration = sum([self.get_duration(segment_index, use_times) for segment_index in range(self.get_num_segments())])
         return duration
 
     def get_memory_size(self, segment_index=None) -> int:

From 0442d889cbccf7ebbd108ef49319a700af1b4a03 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Tue, 14 Jan 2025 14:23:57 +0000
Subject: [PATCH 311/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/core/baserecording.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/spikeinterface/core/baserecording.py b/src/spikeinterface/core/baserecording.py
index 9873265c37..fbdd1fa5ba 100644
--- a/src/spikeinterface/core/baserecording.py
+++ b/src/spikeinterface/core/baserecording.py
@@ -261,7 +261,9 @@ def get_total_duration(self, use_times=True) -> float:
         float
             The duration in seconds
         """
-        duration = sum([self.get_duration(segment_index, use_times) for segment_index in range(self.get_num_segments())])
+        duration = sum(
+            [self.get_duration(segment_index, use_times) for segment_index in range(self.get_num_segments())]
+        )
         return duration
 
     def get_memory_size(self, segment_index=None) -> int:

From c4406ca46581bb247c4f5b367046f1a55a3e14af Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Tue, 14 Jan 2025 15:32:01 +0100
Subject: [PATCH 312/344] Unify error messages

---
 src/spikeinterface/core/base.py | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/src/spikeinterface/core/base.py b/src/spikeinterface/core/base.py
index 119ef46ed4..cc3b0b40ae 100644
--- a/src/spikeinterface/core/base.py
+++ b/src/spikeinterface/core/base.py
@@ -761,6 +761,10 @@ def load(file_path: Union[str, Path], base_folder: Optional[Union[Path, str, boo
           * save (...)  a folder which contain data  + json (or pickle) + metadata.
 
         """
+        error_msg = (
+            f"{file_path} is not a file or a folder. It should point to either a json, pickle file or a "
+            "folder that is the result of extractor.save(...)"
+        )
         if not is_path_remote(file_path):
             file_path = Path(file_path)
 
@@ -776,7 +780,8 @@ def load(file_path: Union[str, Path], base_folder: Optional[Union[Path, str, boo
                     with open(file_path, "rb") as f:
                         d = pickle.load(f)
                 else:
-                    raise ValueError(f"Impossible to load {file_path}")
+                    raise ValueError(error_msg)
+
                 if "warning" in d:
                     print("The extractor was not serializable to file")
                     return None
@@ -793,27 +798,22 @@ def load(file_path: Union[str, Path], base_folder: Optional[Union[Path, str, boo
 
                     extractor = read_zarr(folder)
                 else:
-                    # the is spikeinterface<=0.94.0
-                    # a folder came with 'cached.json'
+                    # For backward compatibility (v<=0.94) we check for the cached.json/pkl/pickle files
+                    # In later versions (v>0.94) we use the si_folder.json file
                     for dump_ext in ("json", "pkl", "pickle"):
                         f = folder / f"cached.{dump_ext}"
                         if f.is_file():
                             file = f
 
-                    # spikeinterface>=0.95.0
                     f = folder / f"si_folder.json"
                     if f.is_file():
                         file = f
 
                     if file is None:
-                        raise ValueError(f"This folder is not a cached folder {file_path}")
+                        raise ValueError(error_msg)
                     extractor = BaseExtractor.load(file, base_folder=folder)
 
             else:
-                error_msg = (
-                    f"{file_path} is not a file or a folder. It should point to either a json, pickle file or a "
-                    "folder that is the result of extractor.save(...)"
-                )
                 raise ValueError(error_msg)
         else:
             # remote case - zarr

From 40d2bdf8d06ebb47efcdd5a3b82b44aed9121d7f Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Tue, 14 Jan 2025 16:10:50 +0100
Subject: [PATCH 313/344] Improve error message

---
 src/spikeinterface/core/base.py | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/src/spikeinterface/core/base.py b/src/spikeinterface/core/base.py
index cc3b0b40ae..4106f9e8b5 100644
--- a/src/spikeinterface/core/base.py
+++ b/src/spikeinterface/core/base.py
@@ -822,7 +822,11 @@ def load(file_path: Union[str, Path], base_folder: Optional[Union[Path, str, boo
 
                 extractor = read_zarr(file_path)
             else:
-                raise NotImplementedError("Only zarr format is supported for remote files")
+                raise NotImplementedError(
+                    "Only zarr format is supported for remote files and you should provide a path to a .zarr "
+                    "remote path. You can save to a valid zarr folder using: "
+                    "`extractor.save(folder='path/to/folder', format='zarr')`"
+                )
 
         return extractor
 

From 89c36ac603a50b67ebdc9a466b95f6d644346c88 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Tue, 14 Jan 2025 16:36:48 +0100
Subject: [PATCH 314/344] Some change in plot_unit_summary for sigui

---
 src/spikeinterface/widgets/sorting_summary.py |  40 ++++--
 .../widgets/tests/test_widgets.py             |   6 +-
 src/spikeinterface/widgets/utils.py           |  74 +++++++++++
 .../widgets/utils_sortingview.py              | 115 +++++-------------
 4 files changed, 135 insertions(+), 100 deletions(-)

diff --git a/src/spikeinterface/widgets/sorting_summary.py b/src/spikeinterface/widgets/sorting_summary.py
index 6b8e9b7d44..46796e3be4 100644
--- a/src/spikeinterface/widgets/sorting_summary.py
+++ b/src/spikeinterface/widgets/sorting_summary.py
@@ -2,6 +2,8 @@
 
 import numpy as np
 
+import warnings
+
 from .base import BaseWidget, to_attr
 
 from .amplitudes import AmplitudesWidget
@@ -50,6 +52,8 @@ class SortingSummaryWidget(BaseWidget):
         analyzer.get_extension("quality_metrics").get_data().columns and
         analyzer.get_extension("template_metrics").get_data().columns.
         (sortingview backend)
+    extra_units_properties : None dict, default: None
+        A dict with extra units properties to display.
     curation_dict : dict or None
         When curation is True, optionaly the viewer can get a previous 'curation_dict'
         to continue/check  previous curations on this analyzer.
@@ -68,13 +72,21 @@ def __init__(
         max_amplitudes_per_unit=None,
         min_similarity_for_correlograms=0.2,
         curation=False,
-        unit_table_properties=None,
+        displayed_units_properties=None,
+        extra_units_properties=None,
         label_choices=None,
         curation_dict=None,
         label_definitions=None,
         backend=None,
+        unit_table_properties=None,
         **backend_kwargs,
     ):
+        
+        if unit_table_properties is not None:
+            warnings.warn("plot_sorting_summary() : unit_table_properties is deprecated, use displayed_units_properties instead")
+            displayed_units_properties = unit_table_properties
+
+
         sorting_analyzer = self.ensure_sorting_analyzer(sorting_analyzer)
         self.check_extensions(
             sorting_analyzer, ["correlograms", "spike_amplitudes", "unit_locations", "template_similarity"]
@@ -87,12 +99,13 @@ def __init__(
         if curation_dict is not None and label_definitions is not None:
             raise ValueError("curation_dict and label_definitions are mutualy exclusive, they cannot be not None both")
 
-        plot_data = dict(
+        data_plot = dict(
             sorting_analyzer=sorting_analyzer,
             unit_ids=unit_ids,
             sparsity=sparsity,
             min_similarity_for_correlograms=min_similarity_for_correlograms,
-            unit_table_properties=unit_table_properties,
+            displayed_units_properties=displayed_units_properties,
+            extra_units_properties=extra_units_properties,
             curation=curation,
             label_choices=label_choices,
             max_amplitudes_per_unit=max_amplitudes_per_unit,
@@ -100,7 +113,7 @@ def __init__(
             label_definitions=label_definitions,
         )
 
-        BaseWidget.__init__(self, plot_data, backend=backend, **backend_kwargs)
+        BaseWidget.__init__(self, data_plot, backend=backend, **backend_kwargs)
 
     def plot_sortingview(self, data_plot, **backend_kwargs):
         import sortingview.views as vv
@@ -171,7 +184,7 @@ def plot_sortingview(self, data_plot, **backend_kwargs):
 
         # unit ids
         v_units_table = generate_unit_table_view(
-            dp.sorting_analyzer, dp.unit_table_properties, similarity_scores=similarity_scores
+            dp.sorting_analyzer, dp.displayed_units_properties, similarity_scores=similarity_scores
         )
 
         if dp.curation:
@@ -205,15 +218,16 @@ def plot_sortingview(self, data_plot, **backend_kwargs):
     def plot_spikeinterface_gui(self, data_plot, **backend_kwargs):
         sorting_analyzer = data_plot["sorting_analyzer"]
 
-        import spikeinterface_gui
+        from spikeinterface_gui import run_mainwindow
+
 
-        app = spikeinterface_gui.mkQApp()
-        win = spikeinterface_gui.MainWindow(
+        run_mainwindow(
             sorting_analyzer,
-            curation=data_plot["curation"]
-            curation_data=data_plot["curation_dict"],
+            with_traces=True,
+            curation=data_plot["curation"],
+            curation_dict=data_plot["curation_dict"],
             label_definitions=data_plot["label_definitions"],
-            more_units_properties=data_plot["unit_table_properties"],
+            extra_units_properties=data_plot["extra_units_properties"],
+            displayed_units_properties=data_plot["displayed_units_properties"],
         )
-        win.show()
-        app.exec_()
+
diff --git a/src/spikeinterface/widgets/tests/test_widgets.py b/src/spikeinterface/widgets/tests/test_widgets.py
index 80f58f5ad9..b723a7ca9f 100644
--- a/src/spikeinterface/widgets/tests/test_widgets.py
+++ b/src/spikeinterface/widgets/tests/test_widgets.py
@@ -688,9 +688,9 @@ def test_plot_motion_info(self):
     # mytest.test_plot_unit_presence()
     # mytest.test_plot_peak_activity()
     # mytest.test_plot_multicomparison()
-    # mytest.test_plot_sorting_summary()
+    mytest.test_plot_sorting_summary()
     # mytest.test_plot_motion()
-    mytest.test_plot_motion_info()
-    plt.show()
+    # mytest.test_plot_motion_info()
+    # plt.show()
 
     # TestWidgets.tearDownClass()
diff --git a/src/spikeinterface/widgets/utils.py b/src/spikeinterface/widgets/utils.py
index ca09cc4d8f..d7789f29ed 100644
--- a/src/spikeinterface/widgets/utils.py
+++ b/src/spikeinterface/widgets/utils.py
@@ -243,3 +243,77 @@ def array_to_image(
             output_image = np.frombuffer(image.tobytes(), dtype=np.uint8).reshape(output_image.shape)
 
     return output_image
+
+
+
+def make_units_table_from_sorting(sorting, units_table=None):
+
+    if units_table is None:
+        import pandas as pd
+        units_table = pd.DataFrame(index=sorting.unit_ids)
+
+    for col in sorting.get_property_keys():
+        values = sorting.get_property(col)
+        if values.dtype.kind in "iuUSfb" and values.ndim == 1:
+            print(col, values, sorting.unit_ids)
+            print(col, len(values), len(sorting.unit_ids))
+            units_table.loc[:, col] = values
+
+    return units_table
+
+def make_units_table_from_analyzer(
+        analyzer,
+        extra_properties=None,
+    ):
+    """
+    Make a DataFrame by aggregating :
+      * quality metrics
+      * template metrics
+      * unit_position
+      * sorting properties
+      * extra columns
+
+    Parameters
+    ----------
+    sorting_analyzer : SortingAnalyzer
+        The SortingAnalyzer object
+    extra_properties : None | dict
+        Extra columns given as dict.
+
+    Returns
+    -------
+    units_table : pd.DataFrame
+        Table containing all columns.
+    """
+    import pandas as pd
+    all_df = []
+
+    if analyzer.get_extension("unit_locations") is not None:
+        locs = analyzer.get_extension("unit_locations").get_data()
+        df = pd.DataFrame(locs[:, :2], columns=["x", "y"], index=analyzer.unit_ids)
+        print(df.index, df.index.dtype)
+        all_df.append(df)
+
+    if analyzer.get_extension("quality_metrics") is not None:
+        df = analyzer.get_extension("quality_metrics").get_data()
+        print(df.index, df.index.dtype)
+        all_df.append(df)
+
+    if analyzer.get_extension("template_metrics") is not None:
+        all_df = analyzer.get_extension("template_metrics").get_data()
+        all_df.append(df)
+
+    if len(all_df) > 0:
+        units_table = pd.concat(all_df, axis=1)
+    else:
+        units_table = pd.DataFrame(index=analyzer.unit_ids)
+
+    print(units_table)
+    make_units_table_from_sorting(analyzer.sorting, units_table=units_table)
+
+    if extra_properties is not None:
+        for col, values in extra_properties.items():
+            if values.dtype.kind in "iuUSfb" and values.ndim == 1:
+                units_table.loc[:, col] = values
+
+    return units_table
\ No newline at end of file
diff --git a/src/spikeinterface/widgets/utils_sortingview.py b/src/spikeinterface/widgets/utils_sortingview.py
index a6cc562ba2..215c1eaf32 100644
--- a/src/spikeinterface/widgets/utils_sortingview.py
+++ b/src/spikeinterface/widgets/utils_sortingview.py
@@ -1,10 +1,13 @@
 from __future__ import annotations
 
+from warnings import warn
+
 import numpy as np
 
 from ..core import SortingAnalyzer, BaseSorting
 from ..core.core_tools import check_json
-from warnings import warn
+from .utils import make_units_table_from_sorting, make_units_table_from_analyzer
+
 
 
 def make_serializable(*args):
@@ -50,105 +53,49 @@ def handle_display_and_url(widget, view, **backend_kwargs):
 def generate_unit_table_view(
     sorting_or_sorting_analyzer: SortingAnalyzer | BaseSorting,
     unit_properties: list[str] | None = None,
-    similarity_scores: npndarray | None = None,
+    similarity_scores: np.ndarray | None = None,
 ):
     import sortingview.views as vv
 
     if isinstance(sorting_or_sorting_analyzer, SortingAnalyzer):
         analyzer = sorting_or_sorting_analyzer
+        units_tables = make_units_table_from_sorting(analyzer)
         sorting = analyzer.sorting
     else:
         sorting = sorting_or_sorting_analyzer
-        analyzer = None
-
-    # Find available unit properties from all sources
-    sorting_props = list(sorting.get_property_keys())
-    if analyzer is not None:
-        if analyzer.get_extension("quality_metrics") is not None:
-            qm_props = list(analyzer.get_extension("quality_metrics").get_data().columns)
-            qm_data = analyzer.get_extension("quality_metrics").get_data()
-        else:
-            qm_props = []
-        if analyzer.get_extension("template_metrics") is not None:
-            tm_props = list(analyzer.get_extension("template_metrics").get_data().columns)
-            tm_data = analyzer.get_extension("template_metrics").get_data()
-        else:
-            tm_props = []
-        # Check for any overlaps and warn user if any
-        all_props = sorting_props + qm_props + tm_props
-    else:
-        all_props = sorting_props
-        qm_props = []
-        tm_props = []
-        qm_data = None
-        tm_data = None
-
-    overlap_props = [prop for prop in all_props if all_props.count(prop) > 1]
-    if len(overlap_props) > 0:
-        warn(
-            f"Warning: Overlapping properties found in sorting, quality_metrics, and template_metrics: {overlap_props}"
-        )
-
-    # Get unit properties
+        units_tables = make_units_table_from_analyzer(sorting)
+        # analyzer = None
+    
     if unit_properties is None:
         ut_columns = []
         ut_rows = [vv.UnitsTableRow(unit_id=u, values={}) for u in sorting.unit_ids]
     else:
+        # keep only selected columns
+        unit_properties = np.array(unit_properties)
+        keep = np.isin(unit_properties, units_tables.columns)
+        unit_properties = unit_properties[keep]
+        units_tables = units_tables.loc[:, unit_properties]
+
         ut_columns = []
-        ut_rows = []
-        values = {}
-        valid_unit_properties = []
-
-        # Create columns for each property
-        for prop_name in unit_properties:
-
-            # Get property values from correct location
-            if prop_name in sorting_props:
-                property_values = sorting.get_property(prop_name)
-            elif prop_name in qm_props:
-                property_values = qm_data[prop_name].to_numpy()
-            elif prop_name in tm_props:
-                property_values = tm_data[prop_name].to_numpy()
-            else:
-                warn(f"Property '{prop_name}' not found in sorting, quality_metrics, or template_metrics")
-                continue
-
-            # make dtype available
-            val0 = np.array(property_values[0])
-            if val0.dtype.kind in ("i", "u"):
-                dtype = "int"
-            elif val0.dtype.kind in ("U", "S"):
-                dtype = "str"
-            elif val0.dtype.kind == "f":
-                dtype = "float"
-            elif val0.dtype.kind == "b":
-                dtype = "bool"
-            else:
-                warn(f"Unsupported dtype {val0.dtype} for property {prop_name}. Skipping")
-                continue
-            ut_columns.append(vv.UnitsTableColumn(key=prop_name, label=prop_name, dtype=dtype))
-            valid_unit_properties.append(prop_name)
-
-        # Create rows for each unit
-        for ui, unit in enumerate(sorting.unit_ids):
-            for prop_name in valid_unit_properties:
-
-                # Get property values from correct location
-                if prop_name in sorting_props:
-                    property_values = sorting.get_property(prop_name)
-                elif prop_name in qm_props:
-                    property_values = qm_data[prop_name].to_numpy()
-                elif prop_name in tm_props:
-                    property_values = tm_data[prop_name].to_numpy()
+        for col in units_tables.columns:
+            values = units_tables[col].to_numpy()
+            ut_columns.append(vv.UnitsTableColumn(key=col, label=col, dtype=values.dtype))
 
+        ut_rows = []
+        for unit_index, unit_id in enumerate(sorting.unit_ids):
+            row_values = {}
+            for col in units_tables.columns:
+                values = units_tables[col].to_numpy()
+                value = values[unit_index]
                 # Check for NaN values and round floats
-                val0 = np.array(property_values[0])
-                if val0.dtype.kind == "f":
-                    if np.isnan(property_values[ui]):
+                if values.dtype.kind == "f":
+                    if np.isnan(values[unit_index]):
                         continue
-                    property_values[ui] = np.format_float_positional(property_values[ui], precision=4, fractional=False)
-                values[prop_name] = property_values[ui]
-            ut_rows.append(vv.UnitsTableRow(unit_id=unit, values=check_json(values)))
+                    value = np.format_float_positional(value, precision=4, fractional=False)
+                row_values[col] = value
+            ut_rows.append(vv.UnitsTableRow(unit_id=unit_id, values=check_json(row_values)))
+
 
     v_units_table = vv.UnitsTable(rows=ut_rows, columns=ut_columns, similarity_scores=similarity_scores)
+    
     return v_units_table

From 9becf1e6b4d008529fce4a832715abed3198eb31 Mon Sep 17 00:00:00 2001
From: zm711 <92116279+zm711@users.noreply.github.com>
Date: Tue, 14 Jan 2025 12:11:36 -0500
Subject: [PATCH 315/344] break rtd build on example failure

---
 doc/conf.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/doc/conf.py b/doc/conf.py
index 41659d2e84..d229dc18ee 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -119,7 +119,9 @@
 
 # for sphinx gallery plugin
 sphinx_gallery_conf = {
-    'only_warn_on_example_error': True,
+    # This is the default but including here explicitly. Should build all docs and fail on gallery failures only.
+    # other option would be abort_on_example_error, but this fails on first failure. So we decided against this.
+    'only_warn_on_example_error': False,
     'examples_dirs': ['../examples/tutorials'],
     'gallery_dirs': ['tutorials' ],  # path where to save gallery generated examples
     'subsection_order': ExplicitOrder([

From f2cc8e3ff6f502a9719445a9d4879f97a62b7c01 Mon Sep 17 00:00:00 2001
From: Heberto Mayorquin <h.mayorquin@gmail.com>
Date: Tue, 14 Jan 2025 11:57:39 -0600
Subject: [PATCH 316/344] improve docstring

---
 .../extractors/neuropixels_utils.py           | 51 +++++++++++--------
 1 file changed, 30 insertions(+), 21 deletions(-)

diff --git a/src/spikeinterface/extractors/neuropixels_utils.py b/src/spikeinterface/extractors/neuropixels_utils.py
index 7e717dd2eb..c8e448d0f7 100644
--- a/src/spikeinterface/extractors/neuropixels_utils.py
+++ b/src/spikeinterface/extractors/neuropixels_utils.py
@@ -1,39 +1,47 @@
 from __future__ import annotations
 
 import numpy as np
+from typing import Optional
 
 
-def get_neuropixels_sample_shifts(num_channels=384, num_channels_per_adc=12, num_cycles=None):
+def get_neuropixels_sample_shifts(
+    num_channels: int = 384, num_channels_per_adc: int = 12, num_cycles: Optional[int] = None
+) -> np.ndarray:
     """
-    Calculates the relative sampling phase of each channel that results
-    from Neuropixels ADC multiplexing.
+    Calculate the relative sampling phase (inter-sample shifts) for each channel
+    in Neuropixels probes due to ADC multiplexing.
 
-    This information is needed to perform the preprocessing.phase_shift operation.
+    Neuropixels probes sample channels sequentially through multiple ADCs,
+    introducing slight temporal delays between channels within each sampling cycle.
+    These inter-sample shifts are fractions of the sampling period and are crucial
+    to consider during preprocessing steps, such as phase correction, to ensure
+    accurate alignment of the recorded signals.
 
-    See https://github.com/int-brain-lab/ibllib/blob/master/ibllib/ephys/neuropixel.py
-
-
-    for the original implementation.
+    This function computes these relative phase shifts, returning an array where
+    each value represents the fractional delay (ranging from 0 to 1) for the
+    corresponding channel.
 
     Parameters
     ----------
     num_channels : int, default: 384
-        The total number of channels in a recording.
-        All currently available Neuropixels variants have 384 channels.
+        Total number of channels in the recording.
+        Neuropixels probes typically have 384 channels.
     num_channels_per_adc : int, default: 12
-        The number of channels per ADC on the probe.
-        Neuropixels 1.0 probes have 12 ADCs.
+        Number of channels assigned to each ADC on the probe.
+        Neuropixels 1.0 probes have 12 ADCs, each handling 32 channels.
         Neuropixels 2.0 probes have 16 ADCs.
-    num_cycles: int or None, default: None
-        The number of cycles in the ADC on the probe.
-        Neuropixels 1.0 probes have 13 cycles for AP and 12 for LFP.
+    num_cycles : int or None, default: None
+        Number of cycles in the ADC sampling sequence.
+        Neuropixels 1.0 probes have 13 cycles for AP (action potential) signals
+        and 12 for LFP (local field potential) signals.
         Neuropixels 2.0 probes have 16 cycles.
-        If None, the num_channels_per_adc is used.
+        If None, defaults to the value of num_channels_per_adc.
 
     Returns
     -------
-    sample_shifts : ndarray
-        The relative phase (from 0-1) of each channel
+    sample_shifts : np.ndarray
+        Array of relative phase shifts for each channel, with values ranging from 0 to 1,
+        representing the fractional delay within the sampling period due to sequential ADC sampling.
     """
     if num_cycles is None:
         num_cycles = num_channels_per_adc
@@ -42,10 +50,11 @@ def get_neuropixels_sample_shifts(num_channels=384, num_channels_per_adc=12, num
         np.arange(num_channels), 2
     )
 
-    sample_shifts = np.zeros_like(adc_indices)
+    sample_shifts = np.zeros_like(adc_indices, dtype=float)
 
-    for a in adc_indices:
-        sample_shifts[adc_indices == a] = np.arange(num_channels_per_adc) / num_cycles
+    for a in np.unique(adc_indices):
+        channel_indices = np.where(adc_indices == a)[0]
+        sample_shifts[channel_indices] = np.arange(len(channel_indices)) / num_cycles
 
     return sample_shifts
 

From 80820853354fbc2c6a56bb5dade4c94c8dacb321 Mon Sep 17 00:00:00 2001
From: Heberto Mayorquin <h.mayorquin@gmail.com>
Date: Tue, 14 Jan 2025 12:16:45 -0600
Subject: [PATCH 317/344] zach review

---
 src/spikeinterface/extractors/neuropixels_utils.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/extractors/neuropixels_utils.py b/src/spikeinterface/extractors/neuropixels_utils.py
index c8e448d0f7..3bd9fc746b 100644
--- a/src/spikeinterface/extractors/neuropixels_utils.py
+++ b/src/spikeinterface/extractors/neuropixels_utils.py
@@ -35,7 +35,7 @@ def get_neuropixels_sample_shifts(
         Neuropixels 1.0 probes have 13 cycles for AP (action potential) signals
         and 12 for LFP (local field potential) signals.
         Neuropixels 2.0 probes have 16 cycles.
-        If None, defaults to the value of num_channels_per_adc.
+        If None, defaults to the value of `num_channels_per_adc`.
 
     Returns
     -------
@@ -50,7 +50,7 @@ def get_neuropixels_sample_shifts(
         np.arange(num_channels), 2
     )
 
-    sample_shifts = np.zeros_like(adc_indices, dtype=float)
+    sample_shifts = np.zeros_like(adc_indices)
 
     for a in np.unique(adc_indices):
         channel_indices = np.where(adc_indices == a)[0]

From bd1ebe816944ba288362ae4eb3a05d5da6da0008 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 15 Jan 2025 08:59:35 +0100
Subject: [PATCH 318/344] Fix dtype for index due to csv

---
 src/spikeinterface/core/sortinganalyzer.py | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/spikeinterface/core/sortinganalyzer.py b/src/spikeinterface/core/sortinganalyzer.py
index 55cbe6070a..9a5a7a99f5 100644
--- a/src/spikeinterface/core/sortinganalyzer.py
+++ b/src/spikeinterface/core/sortinganalyzer.py
@@ -2092,6 +2092,13 @@ def load_data(self):
                     import pandas as pd
 
                     ext_data = pd.read_csv(ext_data_file, index_col=0)
+                    # really sad hack here because csv was a bad choice for saving a DataFrame (maybe a npy per columns would have been better)
+                    unit_ids = self.sorting_analyzer.unit_ids
+                    if ext_data.shape[0] == unit_ids.size:
+                        # we force dtype to be the same as unit_ids
+                        if ext_data.index.dtype != unit_ids.dtype:
+                            ext_data.index = ext_data.index.astype(unit_ids.dtype)
+
                 elif ext_data_file.suffix == ".pkl":
                     with ext_data_file.open("rb") as f:
                         ext_data = pickle.load(f)

From e3b2f16761bf3ef0a5ef579f5e44bfeed87e9ffe Mon Sep 17 00:00:00 2001
From: Garcia Samuel <sam.garcia.die@gmail.com>
Date: Wed, 15 Jan 2025 09:19:01 +0100
Subject: [PATCH 319/344] Update src/spikeinterface/core/sortinganalyzer.py

Co-authored-by: Alessio Buccino <alejoe9187@gmail.com>
---
 src/spikeinterface/core/sortinganalyzer.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/core/sortinganalyzer.py b/src/spikeinterface/core/sortinganalyzer.py
index 9a5a7a99f5..fdad87287e 100644
--- a/src/spikeinterface/core/sortinganalyzer.py
+++ b/src/spikeinterface/core/sortinganalyzer.py
@@ -2092,7 +2092,7 @@ def load_data(self):
                     import pandas as pd
 
                     ext_data = pd.read_csv(ext_data_file, index_col=0)
-                    # really sad hack here because csv was a bad choice for saving a DataFrame (maybe a npy per columns would have been better)
+                    # we need to cast the index to the unit id dtype (int or str)
                     unit_ids = self.sorting_analyzer.unit_ids
                     if ext_data.shape[0] == unit_ids.size:
                         # we force dtype to be the same as unit_ids

From 3c1e19524c6c04284332a94fad81bc548b20659d Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 15 Jan 2025 09:35:09 +0100
Subject: [PATCH 320/344] clean

---
 src/spikeinterface/widgets/sorting_summary.py |  5 ++--
 src/spikeinterface/widgets/utils.py           | 26 ++++++++++++++-----
 .../widgets/utils_sortingview.py              | 22 +++++++++-------
 3 files changed, 35 insertions(+), 18 deletions(-)

diff --git a/src/spikeinterface/widgets/sorting_summary.py b/src/spikeinterface/widgets/sorting_summary.py
index 46796e3be4..0b127abae1 100644
--- a/src/spikeinterface/widgets/sorting_summary.py
+++ b/src/spikeinterface/widgets/sorting_summary.py
@@ -44,14 +44,13 @@ class SortingSummaryWidget(BaseWidget):
     label_choices : list or None, default: None
         List of labels to be added to the curation table
         (sortingview backend)
-    unit_table_properties : list or None, default: None
+    displayed_units_properties : list or None, default: None
         List of properties to be added to the unit table.
         These may be drawn from the sorting extractor, and, if available,
-        the quality_metrics and template_metrics extensions of the SortingAnalyzer.
+        the quality_metrics/template_metrics/unit_locations extensions of the SortingAnalyzer.
         See all properties available with sorting.get_property_keys(), and, if available,
         analyzer.get_extension("quality_metrics").get_data().columns and
         analyzer.get_extension("template_metrics").get_data().columns.
-        (sortingview backend)
     extra_units_properties : None dict, default: None
         A dict with extra units properties to display.
     curation_dict : dict or None
diff --git a/src/spikeinterface/widgets/utils.py b/src/spikeinterface/widgets/utils.py
index d7789f29ed..89025dea31 100644
--- a/src/spikeinterface/widgets/utils.py
+++ b/src/spikeinterface/widgets/utils.py
@@ -247,6 +247,22 @@ def array_to_image(
 
 
 def make_units_table_from_sorting(sorting, units_table=None):
+    """
+    Make a DataFrame from sorting properties.
+    Only for properties with ndim=1
+
+    Parameters
+    ----------
+    sorting : Sorting
+        The Sorting object
+    units_table : None | pd.DataFrame
+        Optionally a existing dataframe.
+
+    Returns
+    -------
+    units_table : pd.DataFrame
+        Table containing all columns.
+    """
 
     if units_table is None:
         import pandas as pd
@@ -255,8 +271,6 @@ def make_units_table_from_sorting(sorting, units_table=None):
     for col in sorting.get_property_keys():
         values = sorting.get_property(col)
         if values.dtype.kind in "iuUSfb" and values.ndim == 1:
-            print(col, values, sorting.unit_ids)
-            print(col, len(values), len(sorting.unit_ids))
             units_table.loc[:, col] = values
 
     return units_table
@@ -273,6 +287,8 @@ def make_units_table_from_analyzer(
       * sorting properties
       * extra columns
 
+    This used in sortingview and spikeinterface-gui to display the units table in a flexible way.
+
     Parameters
     ----------
     sorting_analyzer : SortingAnalyzer
@@ -291,12 +307,10 @@ def make_units_table_from_analyzer(
     if analyzer.get_extension("unit_locations") is not None:
         locs = analyzer.get_extension("unit_locations").get_data()
         df = pd.DataFrame(locs[:, :2], columns=["x", "y"], index=analyzer.unit_ids)
-        print(df.index, df.index.dtype)
         all_df.append(df)
 
     if analyzer.get_extension("quality_metrics") is not None:
         df = analyzer.get_extension("quality_metrics").get_data()
-        print(df.index, df.index.dtype)
         all_df.append(df)
 
     if analyzer.get_extension("template_metrics") is not None:
@@ -308,12 +322,12 @@ def make_units_table_from_analyzer(
     else:
         units_table = pd.DataFrame(index=analyzer.unit_ids)
 
-    print(units_table)
     make_units_table_from_sorting(analyzer.sorting, units_table=units_table)
 
     if extra_properties is not None:
         for col, values in extra_properties.items():
+            # the ndim = 1 is important because we need  column only for the display in gui.
             if values.dtype.kind in "iuUSfb" and values.ndim == 1:
                 units_table.loc[:, col] = values
 
-    return units_table
\ No newline at end of file
+    return units_table
diff --git a/src/spikeinterface/widgets/utils_sortingview.py b/src/spikeinterface/widgets/utils_sortingview.py
index 215c1eaf32..f6eb8ea529 100644
--- a/src/spikeinterface/widgets/utils_sortingview.py
+++ b/src/spikeinterface/widgets/utils_sortingview.py
@@ -76,26 +76,30 @@ def generate_unit_table_view(
         unit_properties = unit_properties[keep]
         units_tables = units_tables.loc[:, unit_properties]
 
+        dtype_convertor = {"i": "int", "u": "int", "f": "float", "U": "str", "S": "str", "b": "bool"}
+
         ut_columns = []
         for col in units_tables.columns:
             values = units_tables[col].to_numpy()
-            ut_columns.append(vv.UnitsTableColumn(key=col, label=col, dtype=values.dtype))
+            if values.dtype.kind in dtype_convertor:
+                txt_dtype = dtype_convertor[values.dtype.kind]
+                ut_columns.append(vv.UnitsTableColumn(key=col, label=col, dtype=txt_dtype))
 
         ut_rows = []
         for unit_index, unit_id in enumerate(sorting.unit_ids):
             row_values = {}
             for col in units_tables.columns:
                 values = units_tables[col].to_numpy()
-                value = values[unit_index]
-                # Check for NaN values and round floats
-                if values.dtype.kind == "f":
-                    if np.isnan(values[unit_index]):
-                        continue
-                    value = np.format_float_positional(value, precision=4, fractional=False)
-                row_values[col] = value
+                if values.dtype.kind in dtype_convertor:
+                    value = values[unit_index]
+                    if values.dtype.kind == "f":
+                        # Check for NaN values and round floats
+                        if np.isnan(values[unit_index]):
+                            continue
+                        value = np.format_float_positional(value, precision=4, fractional=False)
+                    row_values[col] = value
             ut_rows.append(vv.UnitsTableRow(unit_id=unit_id, values=check_json(row_values)))
 
-
     v_units_table = vv.UnitsTable(rows=ut_rows, columns=ut_columns, similarity_scores=similarity_scores)
     
     return v_units_table

From ca276f86efef69031106d83ae40117341932d577 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Wed, 15 Jan 2025 11:03:49 +0100
Subject: [PATCH 321/344] Add loading.py and change load_extractor() to load()

---
 .../benchmark/benchmark_base.py               |  10 +-
 .../comparison/multicomparisons.py            |   4 +-
 .../comparison/tests/test_hybrid.py           |   6 +-
 src/spikeinterface/core/__init__.py           |   3 +-
 src/spikeinterface/core/base.py               | 122 ++---------------
 src/spikeinterface/core/loading.py            | 127 ++++++++++++++++++
 src/spikeinterface/core/recording_tools.py    |   4 +-
 src/spikeinterface/core/sortinganalyzer.py    |  10 +-
 .../core/tests/test_baserecording.py          |  26 ++--
 .../core/tests/test_basesnippets.py           |  14 +-
 .../core/tests/test_basesorting.py            |  12 +-
 .../core/tests/test_binaryfolder.py           |   4 +-
 .../core/tests/test_generate.py               |   6 +-
 .../core/tests/test_npyfoldersnippets.py      |   4 +-
 .../core/tests/test_numpy_extractors.py       |   8 +-
 .../core/tests/test_time_handling.py          |   4 +-
 .../core/tests/test_zarrextractors.py         |   6 +-
 src/spikeinterface/core/waveform_tools.py     |   4 +-
 ...forms_extractor_backwards_compatibility.py |  14 +-
 .../tests/test_nwbextractors_streaming.py     |   4 +-
 .../postprocessing/principal_component.py     |   4 -
 .../tests/test_filter_gaussian.py             |   4 +-
 src/spikeinterface/sorters/basesorter.py      |   6 +-
 .../sorters/external/tests/test_kilosort4.py  |   4 +-
 .../sorters/internal/si_based.py              |   4 +-
 src/spikeinterface/sorters/launcher.py        |   4 +-
 src/spikeinterface/sorters/runsorter.py       |  10 +-
 .../sorters/tests/test_container_tools.py     |   4 +-
 28 files changed, 225 insertions(+), 207 deletions(-)
 create mode 100644 src/spikeinterface/core/loading.py

diff --git a/src/spikeinterface/benchmark/benchmark_base.py b/src/spikeinterface/benchmark/benchmark_base.py
index fc1b136d2d..f427557677 100644
--- a/src/spikeinterface/benchmark/benchmark_base.py
+++ b/src/spikeinterface/benchmark/benchmark_base.py
@@ -11,7 +11,7 @@
 
 from spikeinterface.core import SortingAnalyzer
 
-from spikeinterface import load_extractor, create_sorting_analyzer, load_sorting_analyzer
+from spikeinterface import load, create_sorting_analyzer, load_sorting_analyzer
 from spikeinterface.widgets import get_some_colors
 
 
@@ -150,13 +150,13 @@ def scan_folder(self):
             analyzer = load_sorting_analyzer(folder)
             self.analyzers[key] = analyzer
             # the sorting is in memory here we take the saved one because comparisons need to pickle it later
-            sorting = load_extractor(analyzer.folder / "sorting")
+            sorting = load(analyzer.folder / "sorting")
             self.datasets[key] = analyzer.recording, sorting
 
         # for rec_file in (self.folder / "datasets" / "recordings").glob("*.pickle"):
         #     key = rec_file.stem
-        #     rec = load_extractor(rec_file)
-        #     gt_sorting = load_extractor(self.folder / f"datasets" / "gt_sortings" / key)
+        #     rec = load(rec_file)
+        #     gt_sorting = load(self.folder / f"datasets" / "gt_sortings" / key)
         #     self.datasets[key] = (rec, gt_sorting)
 
         with open(self.folder / "cases.pickle", "rb") as f:
@@ -428,7 +428,7 @@ def load_folder(cls, folder):
             elif format == "sorting":
                 from spikeinterface.core import load_extractor
 
-                result[k] = load_extractor(folder / k)
+                result[k] = load(folder / k)
             elif format == "Motion":
                 from spikeinterface.sortingcomponents.motion import Motion
 
diff --git a/src/spikeinterface/comparison/multicomparisons.py b/src/spikeinterface/comparison/multicomparisons.py
index f7d9782a07..6a4be86796 100644
--- a/src/spikeinterface/comparison/multicomparisons.py
+++ b/src/spikeinterface/comparison/multicomparisons.py
@@ -7,7 +7,7 @@
 
 import numpy as np
 
-from spikeinterface.core import load_extractor, BaseSorting, BaseSortingSegment
+from spikeinterface.core import load, BaseSorting, BaseSortingSegment
 from spikeinterface.core.core_tools import define_function_from_class
 from .basecomparison import BaseMultiComparison, MixinSpikeTrainComparison, MixinTemplateComparison
 from .paircomparisons import SymmetricSortingComparison, TemplateComparison
@@ -230,7 +230,7 @@ def load_from_folder(folder_path):
         with (folder_path / "sortings.json").open() as f:
             dict_sortings = json.load(f)
         name_list = list(dict_sortings.keys())
-        sorting_list = [load_extractor(v, base_folder=folder_path) for v in dict_sortings.values()]
+        sorting_list = [load(v, base_folder=folder_path) for v in dict_sortings.values()]
         mcmp = MultiSortingComparison(sorting_list=sorting_list, name_list=list(name_list), do_matching=False, **kwargs)
         filename = str(folder_path / "multicomparison.gpickle")
         with open(filename, "rb") as f:
diff --git a/src/spikeinterface/comparison/tests/test_hybrid.py b/src/spikeinterface/comparison/tests/test_hybrid.py
index ce409ca778..22cc141f65 100644
--- a/src/spikeinterface/comparison/tests/test_hybrid.py
+++ b/src/spikeinterface/comparison/tests/test_hybrid.py
@@ -1,7 +1,7 @@
 import pytest
 import shutil
 from pathlib import Path
-from spikeinterface.core import extract_waveforms, load_waveforms, load_extractor
+from spikeinterface.core import extract_waveforms, load_waveforms, load
 from spikeinterface.core.testing import check_recordings_equal
 from spikeinterface.comparison import (
     create_hybrid_units_recording,
@@ -52,7 +52,7 @@ def test_hybrid_units_recording(setup_module):
     )
 
     # Check dumpability
-    saved_loaded = load_extractor(hybrid_units_recording.to_dict())
+    saved_loaded = load(hybrid_units_recording.to_dict())
     check_recordings_equal(hybrid_units_recording, saved_loaded, return_scaled=False)
 
     saved_1job = hybrid_units_recording.save(folder=cache_folder / "units_1job")
@@ -81,7 +81,7 @@ def test_hybrid_spikes_recording(setup_module):
     )
 
     # Check dumpability
-    saved_loaded = load_extractor(hybrid_spikes_recording.to_dict())
+    saved_loaded = load(hybrid_spikes_recording.to_dict())
     check_recordings_equal(hybrid_spikes_recording, saved_loaded, return_scaled=False)
 
     saved_1job = hybrid_spikes_recording.save(folder=cache_folder / "spikes_1job")
diff --git a/src/spikeinterface/core/__init__.py b/src/spikeinterface/core/__init__.py
index ead7007920..8b850480a9 100644
--- a/src/spikeinterface/core/__init__.py
+++ b/src/spikeinterface/core/__init__.py
@@ -1,10 +1,11 @@
-from .base import load_extractor  # , load_extractor_from_dict, load_extractor_from_json, load_extractor_from_pickle
 from .baserecording import BaseRecording, BaseRecordingSegment
 from .basesorting import BaseSorting, BaseSortingSegment, SpikeVectorSortingSegment
 from .baseevent import BaseEvent, BaseEventSegment
 from .basesnippets import BaseSnippets, BaseSnippetsSegment
 from .baserecordingsnippets import BaseRecordingSnippets
 
+from .loading import load, load_extractor
+
 # main extractor from dump and cache
 from .binaryrecordingextractor import BinaryRecordingExtractor, read_binary
 from .npzsortingextractor import NpzSortingExtractor, read_npz_sorting
diff --git a/src/spikeinterface/core/base.py b/src/spikeinterface/core/base.py
index 4106f9e8b5..2dc7e0e9bc 100644
--- a/src/spikeinterface/core/base.py
+++ b/src/spikeinterface/core/base.py
@@ -673,7 +673,7 @@ def dump_to_json(
     ) -> None:
         """
         Dump recording extractor to json file.
-        The extractor can be re-loaded with load_extractor(json_file)
+        The extractor can be re-loaded with load(json_file)
 
         Parameters
         ----------
@@ -715,7 +715,7 @@ def dump_to_pickle(
     ):
         """
         Dump recording extractor to a pickle file.
-        The extractor can be re-loaded with load_extractor(pickle_file)
+        The extractor can be re-loaded with load(pickle_file)
 
         Parameters
         ----------
@@ -752,7 +752,9 @@ def dump_to_pickle(
         file_path.write_bytes(pickle.dumps(dump_dict))
 
     @staticmethod
-    def load(file_path: Union[str, Path], base_folder: Optional[Union[Path, str, bool]] = None) -> "BaseExtractor":
+    def load(
+        file_or_folder_path: Union[str, Path], base_folder: Optional[Union[Path, str, bool]] = None
+    ) -> "BaseExtractor":
         """
         Load extractor from file path (.json or .pkl)
 
@@ -761,74 +763,10 @@ def load(file_path: Union[str, Path], base_folder: Optional[Union[Path, str, boo
           * save (...)  a folder which contain data  + json (or pickle) + metadata.
 
         """
-        error_msg = (
-            f"{file_path} is not a file or a folder. It should point to either a json, pickle file or a "
-            "folder that is the result of extractor.save(...)"
-        )
-        if not is_path_remote(file_path):
-            file_path = Path(file_path)
-
-            if base_folder is True:
-                base_folder = file_path.parent
-
-            if file_path.is_file():
-                # standard case based on a file (json or pickle)
-                if str(file_path).endswith(".json"):
-                    with open(file_path, "r") as f:
-                        d = json.load(f)
-                elif str(file_path).endswith(".pkl") or str(file_path).endswith(".pickle"):
-                    with open(file_path, "rb") as f:
-                        d = pickle.load(f)
-                else:
-                    raise ValueError(error_msg)
-
-                if "warning" in d:
-                    print("The extractor was not serializable to file")
-                    return None
-
-                extractor = BaseExtractor.from_dict(d, base_folder=base_folder)
-
-            elif file_path.is_dir():
-                # case from a folder after a calling extractor.save(...)
-                folder = file_path
-                file = None
-
-                if folder.suffix == ".zarr":
-                    from .zarrextractors import read_zarr
-
-                    extractor = read_zarr(folder)
-                else:
-                    # For backward compatibility (v<=0.94) we check for the cached.json/pkl/pickle files
-                    # In later versions (v>0.94) we use the si_folder.json file
-                    for dump_ext in ("json", "pkl", "pickle"):
-                        f = folder / f"cached.{dump_ext}"
-                        if f.is_file():
-                            file = f
-
-                    f = folder / f"si_folder.json"
-                    if f.is_file():
-                        file = f
-
-                    if file is None:
-                        raise ValueError(error_msg)
-                    extractor = BaseExtractor.load(file, base_folder=folder)
-
-            else:
-                raise ValueError(error_msg)
-        else:
-            # remote case - zarr
-            if str(file_path).endswith(".zarr"):
-                from .zarrextractors import read_zarr
-
-                extractor = read_zarr(file_path)
-            else:
-                raise NotImplementedError(
-                    "Only zarr format is supported for remote files and you should provide a path to a .zarr "
-                    "remote path. You can save to a valid zarr folder using: "
-                    "`extractor.save(folder='path/to/folder', format='zarr')`"
-                )
+        # use loading.py and keep backward compatibility
+        from .loading import load
 
-        return extractor
+        return load(file_or_folder_path, base_folder=base_folder)
 
     def __reduce__(self):
         """
@@ -1179,50 +1117,6 @@ def _check_same_version(class_string, version):
         return "unknown"
 
 
-def load_extractor(file_or_folder_or_dict, base_folder=None) -> BaseExtractor:
-    """
-    Instantiate extractor from:
-      * a dict
-      * a json file
-      * a pickle file
-      * folder (after save)
-      * a zarr folder (after save)
-
-    Parameters
-    ----------
-    file_or_folder_or_dict : dictionary or folder or file (json, pickle)
-        The file path, folder path, or dictionary to load the extractor from
-    base_folder : str | Path | bool (optional)
-        The base folder to make relative paths absolute.
-        If True and file_or_folder_or_dict is a file, the parent folder of the file is used.
-
-    Returns
-    -------
-    extractor: Recording or Sorting
-        The loaded extractor object
-    """
-    if isinstance(file_or_folder_or_dict, dict):
-        assert not isinstance(base_folder, bool), "`base_folder` must be a string or Path when loading from dict"
-        return BaseExtractor.from_dict(file_or_folder_or_dict, base_folder=base_folder)
-    else:
-        return BaseExtractor.load(file_or_folder_or_dict, base_folder=base_folder)
-
-
-def load_extractor_from_dict(d, base_folder=None) -> BaseExtractor:
-    warnings.warn("Use load_extractor(..) instead")
-    return BaseExtractor.from_dict(d, base_folder=base_folder)
-
-
-def load_extractor_from_json(json_file, base_folder=None) -> "BaseExtractor":
-    warnings.warn("Use load_extractor(..) instead")
-    return BaseExtractor.load(json_file, base_folder=base_folder)
-
-
-def load_extractor_from_pickle(pkl_file, base_folder=None) -> "BaseExtractor":
-    warnings.warn("Use load_extractor(..) instead")
-    return BaseExtractor.load(pkl_file, base_folder=base_folder)
-
-
 class BaseSegment:
     def __init__(self):
         self._parent_extractor = None
diff --git a/src/spikeinterface/core/loading.py b/src/spikeinterface/core/loading.py
new file mode 100644
index 0000000000..0afb0e85fb
--- /dev/null
+++ b/src/spikeinterface/core/loading.py
@@ -0,0 +1,127 @@
+import warnings
+from pathlib import Path
+
+
+from .base import BaseExtractor
+from .core_tools import is_path_remote
+
+
+def load(file_or_folder_or_dict, base_folder=None) -> BaseExtractor:
+    """
+    General load function to load a SpikeInterface object.
+
+    The function can load:
+        - a `Recording` or `Sorting` object from:
+            * dictionary
+            * json file
+            * pkl file
+            * binary folder (after `extractor.save(..., format='binary_folder')`)
+            * zarr folder (after `extractor.save(..., format='zarr')`)
+            * remote zarr folder
+        - (TODO) a `SortingAnalyzer` object from :
+            * binary folder
+            * zarr folder
+            * remote zarr folder
+            * WaveformExtractor folder
+
+    Parameters
+    ----------
+    file_or_folder_or_dict : dictionary or folder or file (json, pickle)
+        The file path, folder path, or dictionary to load the extractor from
+    base_folder : str | Path | bool (optional)
+        The base folder to make relative paths absolute.
+        If True and file_or_folder_or_dict is a file, the parent folder of the file is used.
+
+    Returns
+    -------
+    extractor: Recording or Sorting
+        The loaded extractor object
+    """
+    if isinstance(file_or_folder_or_dict, dict):
+        assert not isinstance(base_folder, bool), "`base_folder` must be a string or Path when loading from dict"
+        return BaseExtractor.from_dict(file_or_folder_or_dict, base_folder=base_folder)
+    else:
+        file_path = file_or_folder_or_dict
+        error_msg = (
+            f"{file_path} is not a file or a folder. It should point to either a json, pickle file or a "
+            "folder that is the result of extractor.save(...)"
+        )
+        if not is_path_remote(file_path):
+            file_path = Path(file_path)
+
+            if base_folder is True:
+                base_folder = file_path.parent
+
+            if file_path.is_file():
+                # standard case based on a file (json or pickle)
+                if str(file_path).endswith(".json"):
+                    import json
+
+                    with open(file_path, "r") as f:
+                        d = json.load(f)
+                elif str(file_path).endswith(".pkl") or str(file_path).endswith(".pickle"):
+                    import pickle
+
+                    with open(file_path, "rb") as f:
+                        d = pickle.load(f)
+                else:
+                    raise ValueError(error_msg)
+
+                # this is for back-compatibility since now unserializable objects will not
+                # be saved to file
+                if "warning" in d:
+                    print("The extractor was not serializable to file")
+                    return None
+
+                extractor = BaseExtractor.from_dict(d, base_folder=base_folder)
+
+            elif file_path.is_dir():
+                # this can be and extractor, SortingAnalyzer, or WaveformExtractor
+                folder = file_path
+                file = None
+
+                if folder.suffix == ".zarr":
+                    from .zarrextractors import read_zarr
+
+                    extractor = read_zarr(folder)
+                else:
+                    # For backward compatibility (v<=0.94) we check for the cached.json/pkl/pickle files
+                    # In later versions (v>0.94) we use the si_folder.json file
+                    for dump_ext in ("json", "pkl", "pickle"):
+                        f = folder / f"cached.{dump_ext}"
+                        if f.is_file():
+                            file = f
+
+                    f = folder / f"si_folder.json"
+                    if f.is_file():
+                        file = f
+
+                    if file is None:
+                        raise ValueError(error_msg)
+                    extractor = BaseExtractor.load(file, base_folder=folder)
+
+            else:
+                raise ValueError(error_msg)
+        else:
+            # remote case - zarr
+            if str(file_path).endswith(".zarr"):
+                from .zarrextractors import read_zarr
+
+                extractor = read_zarr(file_path)
+            else:
+                raise NotImplementedError(
+                    "Only zarr format is supported for remote files and you should provide a path to a .zarr "
+                    "remote path. You can save to a valid zarr folder using: "
+                    "`extractor.save(folder='path/to/folder', format='zarr')`"
+                )
+
+        return extractor
+
+
+def load_extractor(file_or_folder_or_dict, base_folder=None) -> BaseExtractor:
+    warnings.warn(
+        "load_extractor() is deprecated and will be removed in the future. Please use load() instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return load(file_or_folder_or_dict, base_folder=base_folder)
diff --git a/src/spikeinterface/core/recording_tools.py b/src/spikeinterface/core/recording_tools.py
index 4aabbfd587..284b1141ae 100644
--- a/src/spikeinterface/core/recording_tools.py
+++ b/src/spikeinterface/core/recording_tools.py
@@ -247,9 +247,9 @@ def _init_memory_worker(recording, arrays, shm_names, shapes, dtype, cast_unsign
     # create a local dict per worker
     worker_ctx = {}
     if isinstance(recording, dict):
-        from spikeinterface.core import load_extractor
+        from spikeinterface.core import load
 
-        worker_ctx["recording"] = load_extractor(recording)
+        worker_ctx["recording"] = load(recording)
     else:
         worker_ctx["recording"] = recording
 
diff --git a/src/spikeinterface/core/sortinganalyzer.py b/src/spikeinterface/core/sortinganalyzer.py
index 55cbe6070a..0aa80df87a 100644
--- a/src/spikeinterface/core/sortinganalyzer.py
+++ b/src/spikeinterface/core/sortinganalyzer.py
@@ -24,7 +24,7 @@
 from .baserecording import BaseRecording
 from .basesorting import BaseSorting
 
-from .base import load_extractor
+from .loading import load
 from .recording_tools import check_probe_do_not_overlap, get_rec_attributes, do_recording_attributes_match
 from .core_tools import check_json, retrieve_importing_provenance, is_path_remote, clean_zarr_folder_name
 from .sorting_tools import generate_unit_ids_for_merge_group, _get_ids_after_merging
@@ -494,7 +494,7 @@ def load_from_binary_folder(cls, folder, recording=None, backend_options=None):
                 filename = folder / f"recording.{type}"
                 if filename.exists():
                     try:
-                        recording = load_extractor(filename, base_folder=folder)
+                        recording = load(filename, base_folder=folder)
                         break
                     except:
                         recording = None
@@ -692,7 +692,7 @@ def load_from_zarr(cls, folder, recording=None, backend_options=None):
             if rec_field is not None:
                 rec_dict = rec_field[0]
                 try:
-                    recording = load_extractor(rec_dict, base_folder=folder)
+                    recording = load(rec_dict, base_folder=folder)
                 except:
                     recording = None
         else:
@@ -1192,7 +1192,7 @@ def get_sorting_provenance(self):
                 sorting_provenance = None
                 if filename.exists():
                     try:
-                        sorting_provenance = load_extractor(filename, base_folder=self.folder)
+                        sorting_provenance = load(filename, base_folder=self.folder)
                         break
                     except:
                         pass
@@ -1202,7 +1202,7 @@ def get_sorting_provenance(self):
             zarr_root = self._get_zarr_root(mode="r")
             if "sorting_provenance" in zarr_root.keys():
                 sort_dict = zarr_root["sorting_provenance"][0]
-                sorting_provenance = load_extractor(sort_dict, base_folder=self.folder)
+                sorting_provenance = load(sort_dict, base_folder=self.folder)
             else:
                 sorting_provenance = None
 
diff --git a/src/spikeinterface/core/tests/test_baserecording.py b/src/spikeinterface/core/tests/test_baserecording.py
index df614978ba..7d7ce52f27 100644
--- a/src/spikeinterface/core/tests/test_baserecording.py
+++ b/src/spikeinterface/core/tests/test_baserecording.py
@@ -12,7 +12,7 @@
 
 from probeinterface import Probe, ProbeGroup, generate_linear_probe
 
-from spikeinterface.core import BinaryRecordingExtractor, NumpyRecording, load_extractor, get_default_zarr_compressor
+from spikeinterface.core import BinaryRecordingExtractor, NumpyRecording, load, get_default_zarr_compressor
 from spikeinterface.core.base import BaseExtractor
 from spikeinterface.core.testing import check_recordings_equal
 
@@ -84,38 +84,38 @@ def test_BaseRecording(create_cache_folder):
     # dump/load dict
     d = rec.to_dict(include_annotations=True, include_properties=True)
     rec2 = BaseExtractor.from_dict(d)
-    rec3 = load_extractor(d)
+    rec3 = load(d)
     check_recordings_equal(rec, rec2, return_scaled=False, check_annotations=True, check_properties=True)
     check_recordings_equal(rec, rec3, return_scaled=False, check_annotations=True, check_properties=True)
 
     # dump/load json
     rec.dump_to_json(cache_folder / "test_BaseRecording.json")
     rec2 = BaseExtractor.load(cache_folder / "test_BaseRecording.json")
-    rec3 = load_extractor(cache_folder / "test_BaseRecording.json")
+    rec3 = load(cache_folder / "test_BaseRecording.json")
     check_recordings_equal(rec, rec2, return_scaled=False, check_annotations=True, check_properties=False)
     check_recordings_equal(rec, rec3, return_scaled=False, check_annotations=True, check_properties=False)
 
     # dump/load pickle
     rec.dump_to_pickle(cache_folder / "test_BaseRecording.pkl")
     rec2 = BaseExtractor.load(cache_folder / "test_BaseRecording.pkl")
-    rec3 = load_extractor(cache_folder / "test_BaseRecording.pkl")
+    rec3 = load(cache_folder / "test_BaseRecording.pkl")
     check_recordings_equal(rec, rec2, return_scaled=False, check_annotations=True, check_properties=True)
     check_recordings_equal(rec, rec3, return_scaled=False, check_annotations=True, check_properties=True)
 
     # dump/load dict - relative
     d = rec.to_dict(relative_to=cache_folder, recursive=True)
     rec2 = BaseExtractor.from_dict(d, base_folder=cache_folder)
-    rec3 = load_extractor(d, base_folder=cache_folder)
+    rec3 = load(d, base_folder=cache_folder)
 
     # dump/load json - relative to
     rec.dump_to_json(cache_folder / "test_BaseRecording_rel.json", relative_to=cache_folder)
     rec2 = BaseExtractor.load(cache_folder / "test_BaseRecording_rel.json", base_folder=cache_folder)
-    rec3 = load_extractor(cache_folder / "test_BaseRecording_rel.json", base_folder=cache_folder)
+    rec3 = load(cache_folder / "test_BaseRecording_rel.json", base_folder=cache_folder)
 
     # dump/load relative=True
     rec.dump_to_json(cache_folder / "test_BaseRecording_rel_true.json", relative_to=True)
     rec2 = BaseExtractor.load(cache_folder / "test_BaseRecording_rel_true.json", base_folder=True)
-    rec3 = load_extractor(cache_folder / "test_BaseRecording_rel_true.json", base_folder=True)
+    rec3 = load(cache_folder / "test_BaseRecording_rel_true.json", base_folder=True)
     check_recordings_equal(rec, rec2, return_scaled=False, check_annotations=True)
     check_recordings_equal(rec, rec3, return_scaled=False, check_annotations=True)
     with open(cache_folder / "test_BaseRecording_rel_true.json") as json_file:
@@ -127,12 +127,12 @@ def test_BaseRecording(create_cache_folder):
     # dump/load pkl - relative to
     rec.dump_to_pickle(cache_folder / "test_BaseRecording_rel.pkl", relative_to=cache_folder)
     rec2 = BaseExtractor.load(cache_folder / "test_BaseRecording_rel.pkl", base_folder=cache_folder)
-    rec3 = load_extractor(cache_folder / "test_BaseRecording_rel.pkl", base_folder=cache_folder)
+    rec3 = load(cache_folder / "test_BaseRecording_rel.pkl", base_folder=cache_folder)
 
     # dump/load relative=True
     rec.dump_to_pickle(cache_folder / "test_BaseRecording_rel_true.pkl", relative_to=True)
     rec2 = BaseExtractor.load(cache_folder / "test_BaseRecording_rel_true.pkl", base_folder=True)
-    rec3 = load_extractor(cache_folder / "test_BaseRecording_rel_true.pkl", base_folder=True)
+    rec3 = load(cache_folder / "test_BaseRecording_rel_true.pkl", base_folder=True)
     check_recordings_equal(rec, rec2, return_scaled=False, check_annotations=True)
     check_recordings_equal(rec, rec3, return_scaled=False, check_annotations=True)
     with open(cache_folder / "test_BaseRecording_rel_true.pkl", "rb") as pkl_file:
@@ -195,7 +195,7 @@ def test_BaseRecording(create_cache_folder):
     # test save with probe
     folder = cache_folder / "simple_recording3"
     rec2 = rec_p.save(folder=folder, chunk_size=10, n_jobs=2)
-    rec2 = load_extractor(folder)
+    rec2 = load(folder)
     probe2 = rec2.get_probe()
     assert np.array_equal(probe2.contact_positions, [[0, 30.0], [0.0, 0.0]])
     positions2 = rec_p.get_channel_locations()
@@ -286,7 +286,7 @@ def test_BaseRecording(create_cache_folder):
     folder = cache_folder / "recording_with_times"
     rec2 = rec.save(folder=folder)
     assert np.allclose(times1, rec2.get_times(1))
-    rec3 = load_extractor(folder)
+    rec3 = load(folder)
     assert np.allclose(times1, rec3.get_times(1))
 
     # reset times
@@ -323,7 +323,7 @@ def test_BaseRecording(create_cache_folder):
     # test save to zarr
     compressor = get_default_zarr_compressor()
     rec_zarr = rec2.save(format="zarr", folder=cache_folder / "recording", compressor=compressor)
-    rec_zarr_loaded = load_extractor(cache_folder / "recording.zarr")
+    rec_zarr_loaded = load(cache_folder / "recording.zarr")
     # annotations is False because Zarr adds compression ratios
     check_recordings_equal(rec2, rec_zarr, return_scaled=False, check_annotations=False, check_properties=True)
     check_recordings_equal(
@@ -336,7 +336,7 @@ def test_BaseRecording(create_cache_folder):
     rec_zarr2 = rec2.save(
         format="zarr", folder=cache_folder / "recording_channel_chunk", compressor=compressor, channel_chunk_size=2
     )
-    rec_zarr2_loaded = load_extractor(cache_folder / "recording_channel_chunk.zarr")
+    rec_zarr2_loaded = load(cache_folder / "recording_channel_chunk.zarr")
 
     # annotations is False because Zarr adds compression ratios
     check_recordings_equal(rec2, rec_zarr2, return_scaled=False, check_annotations=False, check_properties=True)
diff --git a/src/spikeinterface/core/tests/test_basesnippets.py b/src/spikeinterface/core/tests/test_basesnippets.py
index f243dd9d9f..3d6c19c974 100644
--- a/src/spikeinterface/core/tests/test_basesnippets.py
+++ b/src/spikeinterface/core/tests/test_basesnippets.py
@@ -10,7 +10,7 @@
 
 from probeinterface import Probe
 from spikeinterface.core import generate_snippets
-from spikeinterface.core import NumpySnippets, load_extractor
+from spikeinterface.core import NumpySnippets, load
 from spikeinterface.core.npysnippetsextractor import NpySnippetsExtractor
 from spikeinterface.core.base import BaseExtractor
 
@@ -90,27 +90,27 @@ def test_BaseSnippets(create_cache_folder):
     # dump/load dict
     d = snippets.to_dict()
     snippets2 = BaseExtractor.from_dict(d)
-    snippets3 = load_extractor(d)
+    snippets3 = load(d)
 
     # dump/load json
     snippets.dump_to_json(cache_folder / "test_BaseSnippets.json")
     snippets2 = BaseExtractor.load(cache_folder / "test_BaseSnippets.json")
-    snippets3 = load_extractor(cache_folder / "test_BaseSnippets.json")
+    snippets3 = load(cache_folder / "test_BaseSnippets.json")
 
     # dump/load pickle
     snippets.dump_to_pickle(cache_folder / "test_BaseSnippets.pkl")
     snippets2 = BaseExtractor.load(cache_folder / "test_BaseSnippets.pkl")
-    snippets3 = load_extractor(cache_folder / "test_BaseSnippets.pkl")
+    snippets3 = load(cache_folder / "test_BaseSnippets.pkl")
 
     # dump/load dict - relative
     d = snippets.to_dict(relative_to=cache_folder, recursive=True)
     snippets2 = BaseExtractor.from_dict(d, base_folder=cache_folder)
-    snippets3 = load_extractor(d, base_folder=cache_folder)
+    snippets3 = load(d, base_folder=cache_folder)
 
     # dump/load json
     snippets.dump_to_json(cache_folder / "test_BaseSnippets_rel.json", relative_to=cache_folder)
     snippets2 = BaseExtractor.load(cache_folder / "test_BaseSnippets_rel.json", base_folder=cache_folder)
-    snippets3 = load_extractor(cache_folder / "test_BaseSnippets_rel.json", base_folder=cache_folder)
+    snippets3 = load(cache_folder / "test_BaseSnippets_rel.json", base_folder=cache_folder)
 
     # cache to npy
     folder = cache_folder / "simple_snippets"
@@ -156,7 +156,7 @@ def test_BaseSnippets(create_cache_folder):
     # test save with probe
     folder = cache_folder / "simple_snippets3"
     snippets2 = snippets_p.save(folder=folder)
-    snippets2 = load_extractor(folder)
+    snippets2 = load(folder)
     probe2 = snippets2.get_probe()
     assert np.array_equal(probe2.contact_positions, [[0, 30.0], [0.0, 0.0]])
     positions2 = snippets_p.get_channel_locations()
diff --git a/src/spikeinterface/core/tests/test_basesorting.py b/src/spikeinterface/core/tests/test_basesorting.py
index 42fdf52eb1..557617ae12 100644
--- a/src/spikeinterface/core/tests/test_basesorting.py
+++ b/src/spikeinterface/core/tests/test_basesorting.py
@@ -19,7 +19,7 @@
     NumpyFolderSorting,
     create_sorting_npz,
     generate_sorting,
-    load_extractor,
+    load,
 )
 from spikeinterface.core.base import BaseExtractor
 from spikeinterface.core.testing import check_sorted_arrays_equal, check_sortings_equal
@@ -51,21 +51,21 @@ def test_BaseSorting(create_cache_folder):
     # dump/load dict
     d = sorting.to_dict(include_annotations=True, include_properties=True)
     sorting2 = BaseExtractor.from_dict(d)
-    sorting3 = load_extractor(d)
+    sorting3 = load(d)
     check_sortings_equal(sorting, sorting2, check_annotations=True, check_properties=True)
     check_sortings_equal(sorting, sorting3, check_annotations=True, check_properties=True)
 
     # dump/load json
     sorting.dump_to_json(cache_folder / "test_BaseSorting.json")
     sorting2 = BaseExtractor.load(cache_folder / "test_BaseSorting.json")
-    sorting3 = load_extractor(cache_folder / "test_BaseSorting.json")
+    sorting3 = load(cache_folder / "test_BaseSorting.json")
     check_sortings_equal(sorting, sorting2, check_annotations=True, check_properties=False)
     check_sortings_equal(sorting, sorting3, check_annotations=True, check_properties=False)
 
     # dump/load pickle
     sorting.dump_to_pickle(cache_folder / "test_BaseSorting.pkl")
     sorting2 = BaseExtractor.load(cache_folder / "test_BaseSorting.pkl")
-    sorting3 = load_extractor(cache_folder / "test_BaseSorting.pkl")
+    sorting3 = load(cache_folder / "test_BaseSorting.pkl")
     check_sortings_equal(sorting, sorting2, check_annotations=True, check_properties=True)
     check_sortings_equal(sorting, sorting3, check_annotations=True, check_properties=True)
 
@@ -122,7 +122,7 @@ def test_BaseSorting(create_cache_folder):
     sorting4 = sorting.to_numpy_sorting()
     sorting5 = sorting.to_multiprocessing(n_jobs=2)
     # create a clone with the same share mem buffer
-    sorting6 = load_extractor(sorting5.to_dict())
+    sorting6 = load(sorting5.to_dict())
     assert isinstance(sorting6, SharedMemorySorting)
     del sorting6
     del sorting5
@@ -130,7 +130,7 @@ def test_BaseSorting(create_cache_folder):
     # test save to zarr
     # compressor = get_default_zarr_compressor()
     sorting_zarr = sorting.save(format="zarr", folder=cache_folder / "sorting")
-    sorting_zarr_loaded = load_extractor(cache_folder / "sorting.zarr")
+    sorting_zarr_loaded = load(cache_folder / "sorting.zarr")
     # annotations is False because Zarr adds compression ratios
     check_sortings_equal(sorting, sorting_zarr, check_annotations=False, check_properties=True)
     check_sortings_equal(sorting_zarr, sorting_zarr_loaded, check_annotations=False, check_properties=True)
diff --git a/src/spikeinterface/core/tests/test_binaryfolder.py b/src/spikeinterface/core/tests/test_binaryfolder.py
index 1e64afe4e4..049e613541 100644
--- a/src/spikeinterface/core/tests/test_binaryfolder.py
+++ b/src/spikeinterface/core/tests/test_binaryfolder.py
@@ -5,7 +5,7 @@
 
 import numpy as np
 
-from spikeinterface.core import BinaryFolderRecording, read_binary_folder, load_extractor
+from spikeinterface.core import load
 from spikeinterface.core import generate_recording
 
 
@@ -20,7 +20,7 @@ def test_BinaryFolderRecording(create_cache_folder):
     saved_rec = rec.save(folder=folder)
     print(saved_rec)
 
-    loaded_rec = load_extractor(folder)
+    loaded_rec = load(folder)
     print(loaded_rec)
 
 
diff --git a/src/spikeinterface/core/tests/test_generate.py b/src/spikeinterface/core/tests/test_generate.py
index cb7debf3e0..3f067c7cf8 100644
--- a/src/spikeinterface/core/tests/test_generate.py
+++ b/src/spikeinterface/core/tests/test_generate.py
@@ -3,7 +3,7 @@
 
 import numpy as np
 
-from spikeinterface.core import load_extractor
+from spikeinterface.core import load
 
 from probeinterface import generate_multi_columns_probe
 from spikeinterface.core.generate import (
@@ -363,7 +363,7 @@ def test_noise_generator_consistency_after_dump(strategy, seed):
     )
     traces0 = rec0.get_traces()
 
-    rec1 = load_extractor(rec0.to_dict())
+    rec1 = load(rec0.to_dict())
     traces1 = rec1.get_traces()
 
     assert np.allclose(traces0, traces1)
@@ -545,7 +545,7 @@ def test_inject_templates():
         assert rec.get_traces(start_frame=rec_noise.get_num_frames(0) - 200, segment_index=0).shape == (200, 4)
 
         # Check dumpability
-        saved_loaded = load_extractor(rec.to_dict())
+        saved_loaded = load(rec.to_dict())
         check_recordings_equal(rec, saved_loaded, return_scaled=False)
 
 
diff --git a/src/spikeinterface/core/tests/test_npyfoldersnippets.py b/src/spikeinterface/core/tests/test_npyfoldersnippets.py
index c0d7f303bf..ebf56e3985 100644
--- a/src/spikeinterface/core/tests/test_npyfoldersnippets.py
+++ b/src/spikeinterface/core/tests/test_npyfoldersnippets.py
@@ -3,7 +3,7 @@
 from pathlib import Path
 import shutil
 
-from spikeinterface.core import load_extractor
+from spikeinterface.core import load
 from spikeinterface.core import generate_snippets
 
 
@@ -25,7 +25,7 @@ def test_NpyFolderSnippets(cache_folder_creation):
     saved_snippets = snippets.save(folder=folder)
     print(snippets)
 
-    loaded_snippets = load_extractor(folder)
+    loaded_snippets = load(folder)
     print(loaded_snippets)
 
 
diff --git a/src/spikeinterface/core/tests/test_numpy_extractors.py b/src/spikeinterface/core/tests/test_numpy_extractors.py
index fecafb8989..21bc1b7879 100644
--- a/src/spikeinterface/core/tests/test_numpy_extractors.py
+++ b/src/spikeinterface/core/tests/test_numpy_extractors.py
@@ -9,7 +9,7 @@
     SharedMemorySorting,
     NumpyEvent,
     create_sorting_npz,
-    load_extractor,
+    load,
     NpzSortingExtractor,
     generate_recording,
 )
@@ -41,7 +41,7 @@ def test_SharedMemoryRecording():
     rec = SharedMemoryRecording.from_recording(rec0, **job_kwargs)
 
     d = rec.to_dict()
-    rec_clone = load_extractor(d)
+    rec_clone = load(d)
     traces = rec_clone.get_traces(start_frame=0, end_frame=30000, segment_index=0)
 
     assert rec.shms[0].name == rec_clone.shms[0].name
@@ -87,7 +87,7 @@ def test_NumpySorting(setup_NumpyRecording):
     # print(sorting)
 
     # construct back from kwargs keep the same array
-    sorting2 = load_extractor(sorting.to_dict())
+    sorting2 = load(sorting.to_dict())
     assert np.shares_memory(sorting2._cached_spike_vector, sorting._cached_spike_vector)
 
 
@@ -109,7 +109,7 @@ def test_SharedMemorySorting():
     # print(sorting.to_spike_vector())
     d = sorting.to_dict()
 
-    sorting_reload = load_extractor(d)
+    sorting_reload = load(d)
     # print(sorting_reload)
     # print(sorting_reload.to_spike_vector())
 
diff --git a/src/spikeinterface/core/tests/test_time_handling.py b/src/spikeinterface/core/tests/test_time_handling.py
index 9b7ed11bbb..ffdb121316 100644
--- a/src/spikeinterface/core/tests/test_time_handling.py
+++ b/src/spikeinterface/core/tests/test_time_handling.py
@@ -128,7 +128,7 @@ def test_times_propagated_to_save_folder(self, request, fixture_name, mode, tmp_
 
         if mode == "zarr":
             folder_name += ".zarr"
-        recording_load = si.load_extractor(tmp_path / folder_name)
+        recording_load = si.load(tmp_path / folder_name)
 
         self._check_times_match(recording_cache, all_times)
         self._check_times_match(recording_load, all_times)
@@ -369,7 +369,7 @@ def test_save_and_load_time_shift(self, request, fixture_name, tmp_path):
 
         times_recording.save(folder=tmp_path / "my_file")
 
-        loaded_recording = si.load_extractor(tmp_path / "my_file")
+        loaded_recording = si.load(tmp_path / "my_file")
 
         for idx in range(times_recording.get_num_segments()):
             assert np.array_equal(
diff --git a/src/spikeinterface/core/tests/test_zarrextractors.py b/src/spikeinterface/core/tests/test_zarrextractors.py
index 2fc1f42ec5..cc0c60721e 100644
--- a/src/spikeinterface/core/tests/test_zarrextractors.py
+++ b/src/spikeinterface/core/tests/test_zarrextractors.py
@@ -8,7 +8,7 @@
     ZarrSortingExtractor,
     generate_recording,
     generate_sorting,
-    load_extractor,
+    load,
 )
 from spikeinterface.core.zarrextractors import add_sorting_to_zarr_group, get_default_zarr_compressor
 
@@ -63,7 +63,7 @@ def test_ZarrSortingExtractor(tmp_path):
     folder = tmp_path / "zarr_sorting"
     ZarrSortingExtractor.write_sorting(np_sorting, folder)
     sorting = ZarrSortingExtractor(folder)
-    sorting = load_extractor(sorting.to_dict())
+    sorting = load(sorting.to_dict())
 
     # store the sorting in a sub group (for instance SortingResult)
     folder = tmp_path / "zarr_sorting_sub_group"
@@ -72,7 +72,7 @@ def test_ZarrSortingExtractor(tmp_path):
     add_sorting_to_zarr_group(sorting, zarr_sorting_group)
     sorting = ZarrSortingExtractor(folder, zarr_group="sorting")
     # and reaload
-    sorting = load_extractor(sorting.to_dict())
+    sorting = load(sorting.to_dict())
 
 
 if __name__ == "__main__":
diff --git a/src/spikeinterface/core/waveform_tools.py b/src/spikeinterface/core/waveform_tools.py
index 3affd7f0ec..b78382c872 100644
--- a/src/spikeinterface/core/waveform_tools.py
+++ b/src/spikeinterface/core/waveform_tools.py
@@ -298,9 +298,9 @@ def _init_worker_distribute_buffers(
     # create a local dict per worker
     worker_ctx = {}
     if isinstance(recording, dict):
-        from spikeinterface.core import load_extractor
+        from spikeinterface.core import load
 
-        recording = load_extractor(recording)
+        recording = load(recording)
     worker_ctx["recording"] = recording
 
     if mode == "memmap":
diff --git a/src/spikeinterface/core/waveforms_extractor_backwards_compatibility.py b/src/spikeinterface/core/waveforms_extractor_backwards_compatibility.py
index 5c7584ecd8..ffe4755c75 100644
--- a/src/spikeinterface/core/waveforms_extractor_backwards_compatibility.py
+++ b/src/spikeinterface/core/waveforms_extractor_backwards_compatibility.py
@@ -23,7 +23,7 @@
 from .job_tools import split_job_kwargs
 from .sparsity import ChannelSparsity
 from .sortinganalyzer import SortingAnalyzer, load_sorting_analyzer
-from .base import load_extractor
+from .loading import load
 from .analyzer_extension_core import ComputeRandomSpikes, ComputeWaveforms, ComputeTemplates
 
 _backwards_compatibility_msg = """####
@@ -475,21 +475,21 @@ def _read_old_waveforms_extractor_binary(folder, sorting):
     recording = None
     if (folder / "recording.json").exists():
         try:
-            recording = load_extractor(folder / "recording.json", base_folder=folder)
+            recording = load(folder / "recording.json", base_folder=folder)
         except:
             pass
     elif (folder / "recording.pickle").exists():
         try:
-            recording = load_extractor(folder / "recording.pickle", base_folder=folder)
+            recording = load(folder / "recording.pickle", base_folder=folder)
         except:
             pass
 
     # sorting
     if sorting is None:
         if (folder / "sorting.json").exists():
-            sorting = load_extractor(folder / "sorting.json", base_folder=folder)
+            sorting = load(folder / "sorting.json", base_folder=folder)
         elif (folder / "sorting.pickle").exists():
-            sorting = load_extractor(folder / "sorting.pickle", base_folder=folder)
+            sorting = load(folder / "sorting.pickle", base_folder=folder)
 
     sorting_analyzer = SortingAnalyzer.create_memory(
         sorting, recording, sparsity=sparsity, return_scaled=return_scaled, rec_attributes=rec_attributes
@@ -676,7 +676,7 @@ def make_ext_params_up_to_date(ext, old_params, new_params):
 #     recording = None
 #     try:
 #         recording_dict = waveforms_root.attrs["recording"]
-#         recording = load_extractor(recording_dict, base_folder=folder)
+#         recording = load(recording_dict, base_folder=folder)
 #     except:
 #         pass
 
@@ -684,7 +684,7 @@ def make_ext_params_up_to_date(ext, old_params, new_params):
 #     if sorting is None:
 #         assert "sorting" in waveforms_root.attrs, "Could not load sorting object"
 #         sorting_dict = waveforms_root.attrs["sorting"]
-#         sorting = load_extractor(sorting_dict, base_folder=folder)
+#         sorting = load(sorting_dict, base_folder=folder)
 
 #     if "sparsity" in waveforms_root.attrs:
 #         sparsity_dict = waveforms_root.attrs["sparsity"]
diff --git a/src/spikeinterface/extractors/tests/test_nwbextractors_streaming.py b/src/spikeinterface/extractors/tests/test_nwbextractors_streaming.py
index b3c5b9c934..9724ec3d9f 100644
--- a/src/spikeinterface/extractors/tests/test_nwbextractors_streaming.py
+++ b/src/spikeinterface/extractors/tests/test_nwbextractors_streaming.py
@@ -4,7 +4,7 @@
 import pytest
 import numpy as np
 
-from spikeinterface import load_extractor
+from spikeinterface import load
 from spikeinterface.core.testing import check_recordings_equal
 from spikeinterface.core.testing import check_recordings_equal, check_sortings_equal
 from spikeinterface.extractors import NwbRecordingExtractor, NwbSortingExtractor
@@ -219,7 +219,7 @@ def test_sorting_s3_nwb_zarr(tmp_path):
     assert not sorting.check_serializability("pickle")
 
     # test to/from dict
-    sorting_loaded = load_extractor(sorting.to_dict())
+    sorting_loaded = load(sorting.to_dict())
 
     # just take 3 random units to test
     rng = np.random.default_rng(seed=2205)
diff --git a/src/spikeinterface/postprocessing/principal_component.py b/src/spikeinterface/postprocessing/principal_component.py
index 809f2c5bba..794ad68b2f 100644
--- a/src/spikeinterface/postprocessing/principal_component.py
+++ b/src/spikeinterface/postprocessing/principal_component.py
@@ -658,10 +658,6 @@ def _all_pc_extractor_chunk(segment_index, start_frame, end_frame, worker_ctx):
 
 def _init_work_all_pc_extractor(recording, sorting, all_pcs_args, nbefore, nafter, unit_channels, pca_model):
     worker_ctx = {}
-    if isinstance(recording, dict):
-        from spikeinterface.core import load_extractor
-
-        recording = load_extractor(recording)
     worker_ctx["recording"] = recording
     worker_ctx["sorting"] = sorting
 
diff --git a/src/spikeinterface/preprocessing/tests/test_filter_gaussian.py b/src/spikeinterface/preprocessing/tests/test_filter_gaussian.py
index 54682f2e94..3682b186f2 100644
--- a/src/spikeinterface/preprocessing/tests/test_filter_gaussian.py
+++ b/src/spikeinterface/preprocessing/tests/test_filter_gaussian.py
@@ -1,7 +1,7 @@
 import numpy as np
 import pytest
 from pathlib import Path
-from spikeinterface.core import load_extractor, set_global_tmp_folder
+from spikeinterface.core import load, set_global_tmp_folder
 from spikeinterface.core.testing import check_recordings_equal
 from spikeinterface.core.generate import generate_recording
 from spikeinterface.preprocessing import gaussian_filter
@@ -23,7 +23,7 @@ def test_filter_gaussian(tmp_path):
     assert rec_filtered.get_traces(segment_index=1, start_frame=rec_filtered.get_num_frames(1) - 200).shape == (200, 3)
 
     # Check dumpability
-    saved_loaded = load_extractor(rec_filtered.to_dict())
+    saved_loaded = load(rec_filtered.to_dict())
     check_recordings_equal(rec_filtered, saved_loaded, return_scaled=False)
 
     saved_1job = rec_filtered.save(folder=tmp_path / "1job")
diff --git a/src/spikeinterface/sorters/basesorter.py b/src/spikeinterface/sorters/basesorter.py
index c59fa29c05..4492057f21 100644
--- a/src/spikeinterface/sorters/basesorter.py
+++ b/src/spikeinterface/sorters/basesorter.py
@@ -15,7 +15,7 @@
 import warnings
 
 
-from spikeinterface.core import load_extractor, BaseRecordingSnippets, BaseRecording
+from spikeinterface.core import load, BaseRecordingSnippets, BaseRecording
 from spikeinterface.core.core_tools import check_json
 from spikeinterface.core.globals import get_global_job_kwargs
 from spikeinterface.core.job_tools import fix_job_kwargs, split_job_kwargs
@@ -210,9 +210,9 @@ def load_recording_from_folder(cls, output_folder, with_warnings=False):
                 )
                 recording = None
             else:
-                recording = load_extractor(json_file, base_folder=output_folder)
+                recording = load(json_file, base_folder=output_folder)
         elif pickle_file.exists():
-            recording = load_extractor(pickle_file, base_folder=output_folder)
+            recording = load(pickle_file, base_folder=output_folder)
 
         return recording
 
diff --git a/src/spikeinterface/sorters/external/tests/test_kilosort4.py b/src/spikeinterface/sorters/external/tests/test_kilosort4.py
index dbaf3ffc5e..5e1e908411 100644
--- a/src/spikeinterface/sorters/external/tests/test_kilosort4.py
+++ b/src/spikeinterface/sorters/external/tests/test_kilosort4.py
@@ -2,7 +2,7 @@
 import pytest
 from pathlib import Path
 
-from spikeinterface import load_extractor, generate_ground_truth_recording
+from spikeinterface import load, generate_ground_truth_recording
 from spikeinterface.sorters import Kilosort4Sorter, run_sorter
 from spikeinterface.sorters.tests.common_tests import SorterCommonTestSuite
 
@@ -15,7 +15,7 @@ class Kilosort4SorterCommonTestSuite(SorterCommonTestSuite, unittest.TestCase):
     # 4 channels is to few for KS4
     def setUp(self):
         if (self.cache_folder / "rec").is_dir():
-            recording = load_extractor(self.cache_folder / "rec")
+            recording = load(self.cache_folder / "rec")
         else:
             recording, _ = generate_ground_truth_recording(num_channels=32, durations=[60], seed=0)
             recording = recording.save(folder=self.cache_folder / "rec", verbose=False, format="binary")
diff --git a/src/spikeinterface/sorters/internal/si_based.py b/src/spikeinterface/sorters/internal/si_based.py
index 68aeead8e9..bd4324bb87 100644
--- a/src/spikeinterface/sorters/internal/si_based.py
+++ b/src/spikeinterface/sorters/internal/si_based.py
@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from spikeinterface.core import load_extractor, NumpyRecording
+from spikeinterface.core import load, NumpyRecording
 
 from spikeinterface.sorters import BaseSorter
 
@@ -20,7 +20,7 @@ def _setup_recording(cls, recording, output_folder, params, verbose):
 
     @classmethod
     def _get_result_from_folder(cls, output_folder):
-        sorting = load_extractor(output_folder / "sorting")
+        sorting = load(output_folder / "sorting")
         return sorting
 
     @classmethod
diff --git a/src/spikeinterface/sorters/launcher.py b/src/spikeinterface/sorters/launcher.py
index 7ed5b29556..db660804aa 100644
--- a/src/spikeinterface/sorters/launcher.py
+++ b/src/spikeinterface/sorters/launcher.py
@@ -188,7 +188,7 @@ def run_sorter_jobs(job_list, engine="loop", engine_kwargs={}, return_output=Fal
 
 _slurm_script = """#! {python}
 from numpy import array
-from spikeinterface import load_extractor
+from spikeinterface import load
 from spikeinterface.sorters import run_sorter
 
 rec_dict = {recording_dict}
@@ -196,7 +196,7 @@ def run_sorter_jobs(job_list, engine="loop", engine_kwargs={}, return_output=Fal
 kwargs = dict(
 {kwargs_txt}
 )
-kwargs['recording'] = load_extractor(rec_dict)
+kwargs['recording'] = load(rec_dict)
 
 run_sorter(**kwargs)
 """
diff --git a/src/spikeinterface/sorters/runsorter.py b/src/spikeinterface/sorters/runsorter.py
index d28af7b99c..d536d2480a 100644
--- a/src/spikeinterface/sorters/runsorter.py
+++ b/src/spikeinterface/sorters/runsorter.py
@@ -16,7 +16,7 @@
 from .. import __version__ as si_version
 
 
-from ..core import BaseRecording, NumpySorting, load_extractor
+from ..core import BaseRecording, NumpySorting, load
 from ..core.core_tools import check_json, is_editable_mode
 from .sorterlist import sorter_dict
 from .utils import (
@@ -408,7 +408,7 @@ def run_sorter_container(
     py_script = f"""
 import json
 from pathlib import Path
-from spikeinterface import load_extractor
+from spikeinterface import load
 from spikeinterface.sorters import run_sorter_local
 
 if __name__ == '__main__':
@@ -417,9 +417,9 @@ def run_sorter_container(
     json_rec = Path('{parent_folder_unix}/in_container_recording.json')
     pickle_rec = Path('{parent_folder_unix}/in_container_recording.pickle')
     if json_rec.exists():
-        recording = load_extractor(json_rec)
+        recording = load(json_rec)
     else:
-        recording = load_extractor(pickle_rec)
+        recording = load(pickle_rec)
 
     # load params in container
     with open('{parent_folder_unix}/in_container_params.json', encoding='utf8', mode='r') as f:
@@ -652,7 +652,7 @@ def run_sorter_container(
                 sorting = SorterClass.get_result_from_folder(folder)
             except Exception as e:
                 try:
-                    sorting = load_extractor(in_container_sorting_folder)
+                    sorting = load(in_container_sorting_folder)
                 except FileNotFoundError:
                     SpikeSortingError(f"Spike sorting in {mode} failed with the following error:\n{run_sorter_output}")
 
diff --git a/src/spikeinterface/sorters/tests/test_container_tools.py b/src/spikeinterface/sorters/tests/test_container_tools.py
index 0369bca860..606fe9940e 100644
--- a/src/spikeinterface/sorters/tests/test_container_tools.py
+++ b/src/spikeinterface/sorters/tests/test_container_tools.py
@@ -30,8 +30,8 @@ def setup_module(tmp_path_factory):
 
 def test_find_recording_folders(setup_module):
     cache_folder = setup_module
-    rec1 = si.load_extractor(cache_folder / "mono")
-    rec2 = si.load_extractor(cache_folder / "multi" / "binary.json", base_folder=cache_folder / "multi")
+    rec1 = si.load(cache_folder / "mono")
+    rec2 = si.load(cache_folder / "multi" / "binary.json", base_folder=cache_folder / "multi")
 
     d1 = rec1.to_dict()
     d2 = rec2.to_dict()

From 7f37dfff7038063c8a92032196da0d182eebab93 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Wed, 15 Jan 2025 11:07:27 +0100
Subject: [PATCH 322/344] Add use_times option in get_duration/total_duration

---
 src/spikeinterface/core/baserecording.py | 23 +++++++++++++++++------
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/src/spikeinterface/core/baserecording.py b/src/spikeinterface/core/baserecording.py
index 7ca527e255..fbdd1fa5ba 100644
--- a/src/spikeinterface/core/baserecording.py
+++ b/src/spikeinterface/core/baserecording.py
@@ -59,7 +59,7 @@ def __repr__(self):
         if num_segments > 1:
             samples_per_segment = [self.get_num_samples(segment_index) for segment_index in range(num_segments)]
             memory_per_segment_bytes = (self.get_memory_size(segment_index) for segment_index in range(num_segments))
-            durations = [self.get_duration(segment_index) for segment_index in range(num_segments)]
+            durations = [self.get_duration(segment_index, use_times=False) for segment_index in range(num_segments)]
 
             samples_per_segment_formated = [f"{samples:,}" for samples in samples_per_segment]
             durations_per_segment_formated = [convert_seconds_to_str(d) for d in durations]
@@ -95,7 +95,7 @@ def _repr_header(self):
         dtype = self.get_dtype()
 
         total_samples = self.get_total_samples()
-        total_duration = self.get_total_duration()
+        total_duration = self.get_total_duration(use_times=False)
         total_memory_size = self.get_total_memory_size()
 
         sf_hz = self.get_sampling_frequency()
@@ -216,7 +216,7 @@ def get_total_samples(self) -> int:
 
         return sum(samples_per_segment)
 
-    def get_duration(self, segment_index=None) -> float:
+    def get_duration(self, segment_index=None, use_times=True) -> float:
         """
         Returns the duration in seconds.
 
@@ -226,6 +226,9 @@ def get_duration(self, segment_index=None) -> float:
             The sample index to retrieve the duration for.
             For multi-segment objects, it is required, default: None
             With single segment recording returns the duration of the single segment
+        use_times : bool, default: True
+            If True, the duration is calculated using the time vector if available.
+            If False, the duration is calculated using the number of samples and the sampling frequency.
 
         Returns
         -------
@@ -234,7 +237,7 @@ def get_duration(self, segment_index=None) -> float:
         """
         segment_index = self._check_segment_index(segment_index)
 
-        if self.has_time_vector(segment_index):
+        if self.has_time_vector(segment_index) and use_times:
             times = self.get_times(segment_index)
             segment_duration = times[-1] - times[0] + (1 / self.get_sampling_frequency())
         else:
@@ -243,16 +246,24 @@ def get_duration(self, segment_index=None) -> float:
 
         return segment_duration
 
-    def get_total_duration(self) -> float:
+    def get_total_duration(self, use_times=True) -> float:
         """
         Returns the total duration in seconds
 
+        Parameters
+        ----------
+        use_times : bool, default: True
+            If True, the duration is calculated using the time vector if available.
+            If False, the duration is calculated using the number of samples and the sampling frequency.
+
         Returns
         -------
         float
             The duration in seconds
         """
-        duration = sum([self.get_duration(idx) for idx in range(self.get_num_segments())])
+        duration = sum(
+            [self.get_duration(segment_index, use_times) for segment_index in range(self.get_num_segments())]
+        )
         return duration
 
     def get_memory_size(self, segment_index=None) -> int:

From 94e297941e0643a2b218703ed7e55c1fdbed3a75 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Wed, 15 Jan 2025 11:07:59 +0100
Subject: [PATCH 323/344] Revert use_times changes

---
 src/spikeinterface/core/baserecording.py | 23 ++++++-----------------
 1 file changed, 6 insertions(+), 17 deletions(-)

diff --git a/src/spikeinterface/core/baserecording.py b/src/spikeinterface/core/baserecording.py
index fbdd1fa5ba..7ca527e255 100644
--- a/src/spikeinterface/core/baserecording.py
+++ b/src/spikeinterface/core/baserecording.py
@@ -59,7 +59,7 @@ def __repr__(self):
         if num_segments > 1:
             samples_per_segment = [self.get_num_samples(segment_index) for segment_index in range(num_segments)]
             memory_per_segment_bytes = (self.get_memory_size(segment_index) for segment_index in range(num_segments))
-            durations = [self.get_duration(segment_index, use_times=False) for segment_index in range(num_segments)]
+            durations = [self.get_duration(segment_index) for segment_index in range(num_segments)]
 
             samples_per_segment_formated = [f"{samples:,}" for samples in samples_per_segment]
             durations_per_segment_formated = [convert_seconds_to_str(d) for d in durations]
@@ -95,7 +95,7 @@ def _repr_header(self):
         dtype = self.get_dtype()
 
         total_samples = self.get_total_samples()
-        total_duration = self.get_total_duration(use_times=False)
+        total_duration = self.get_total_duration()
         total_memory_size = self.get_total_memory_size()
 
         sf_hz = self.get_sampling_frequency()
@@ -216,7 +216,7 @@ def get_total_samples(self) -> int:
 
         return sum(samples_per_segment)
 
-    def get_duration(self, segment_index=None, use_times=True) -> float:
+    def get_duration(self, segment_index=None) -> float:
         """
         Returns the duration in seconds.
 
@@ -226,9 +226,6 @@ def get_duration(self, segment_index=None, use_times=True) -> float:
             The sample index to retrieve the duration for.
             For multi-segment objects, it is required, default: None
             With single segment recording returns the duration of the single segment
-        use_times : bool, default: True
-            If True, the duration is calculated using the time vector if available.
-            If False, the duration is calculated using the number of samples and the sampling frequency.
 
         Returns
         -------
@@ -237,7 +234,7 @@ def get_duration(self, segment_index=None, use_times=True) -> float:
         """
         segment_index = self._check_segment_index(segment_index)
 
-        if self.has_time_vector(segment_index) and use_times:
+        if self.has_time_vector(segment_index):
             times = self.get_times(segment_index)
             segment_duration = times[-1] - times[0] + (1 / self.get_sampling_frequency())
         else:
@@ -246,24 +243,16 @@ def get_duration(self, segment_index=None, use_times=True) -> float:
 
         return segment_duration
 
-    def get_total_duration(self, use_times=True) -> float:
+    def get_total_duration(self) -> float:
         """
         Returns the total duration in seconds
 
-        Parameters
-        ----------
-        use_times : bool, default: True
-            If True, the duration is calculated using the time vector if available.
-            If False, the duration is calculated using the number of samples and the sampling frequency.
-
         Returns
         -------
         float
             The duration in seconds
         """
-        duration = sum(
-            [self.get_duration(segment_index, use_times) for segment_index in range(self.get_num_segments())]
-        )
+        duration = sum([self.get_duration(idx) for idx in range(self.get_num_segments())])
         return duration
 
     def get_memory_size(self, segment_index=None) -> int:

From 67343bb95145fa68c54fae1cc1040d44127be638 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Wed, 15 Jan 2025 11:19:41 +0100
Subject: [PATCH 324/344] Add experiment_name annotation to open ephys

---
 src/spikeinterface/extractors/neoextractors/openephys.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/spikeinterface/extractors/neoextractors/openephys.py b/src/spikeinterface/extractors/neoextractors/openephys.py
index 24bc7591e4..dd24e6cae7 100644
--- a/src/spikeinterface/extractors/neoextractors/openephys.py
+++ b/src/spikeinterface/extractors/neoextractors/openephys.py
@@ -250,6 +250,7 @@ def __init__(
                 except:
                     warnings.warn(f"Could not load synchronized timestamps for {stream_name}")
 
+        self.annotate(experiment_name=f"experiment{exp_id}")
         self._stream_folders = stream_folders
 
         self._kwargs.update(

From 941a053f45fd7b89691c004e74fa396fb29ca6f6 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Wed, 15 Jan 2025 13:20:06 +0100
Subject: [PATCH 325/344] default displayed props

---
 src/spikeinterface/widgets/sorting_summary.py | 33 ++++++++++++-------
 .../widgets/utils_sortingview.py              | 12 ++++---
 2 files changed, 30 insertions(+), 15 deletions(-)

diff --git a/src/spikeinterface/widgets/sorting_summary.py b/src/spikeinterface/widgets/sorting_summary.py
index 0b127abae1..480fb76ceb 100644
--- a/src/spikeinterface/widgets/sorting_summary.py
+++ b/src/spikeinterface/widgets/sorting_summary.py
@@ -16,6 +16,8 @@
 from ..core import SortingAnalyzer
 
 
+_default_displayed_unit_properties = ["firing_rate", "num_spikes", "x", "y", "amplitude", "snr", "rp_violation"]
+
 class SortingSummaryWidget(BaseWidget):
     """
     Plots spike sorting summary.
@@ -44,14 +46,14 @@ class SortingSummaryWidget(BaseWidget):
     label_choices : list or None, default: None
         List of labels to be added to the curation table
         (sortingview backend)
-    displayed_units_properties : list or None, default: None
+    displayed_unit_properties : list or None, default: None
         List of properties to be added to the unit table.
         These may be drawn from the sorting extractor, and, if available,
         the quality_metrics/template_metrics/unit_locations extensions of the SortingAnalyzer.
         See all properties available with sorting.get_property_keys(), and, if available,
         analyzer.get_extension("quality_metrics").get_data().columns and
         analyzer.get_extension("template_metrics").get_data().columns.
-    extra_units_properties : None dict, default: None
+    extra_unit_properties : None dict, default: None
         A dict with extra units properties to display.
     curation_dict : dict or None
         When curation is True, optionaly the viewer can get a previous 'curation_dict'
@@ -71,8 +73,8 @@ def __init__(
         max_amplitudes_per_unit=None,
         min_similarity_for_correlograms=0.2,
         curation=False,
-        displayed_units_properties=None,
-        extra_units_properties=None,
+        displayed_unit_properties=None,
+        extra_unit_properties=None,
         label_choices=None,
         curation_dict=None,
         label_definitions=None,
@@ -82,8 +84,12 @@ def __init__(
     ):
         
         if unit_table_properties is not None:
-            warnings.warn("plot_sorting_summary() : unit_table_properties is deprecated, use displayed_units_properties instead")
-            displayed_units_properties = unit_table_properties
+            warnings.warn(
+                "plot_sorting_summary() : unit_table_properties is deprecated, use displayed_unit_properties instead",
+                category=DeprecationWarning,
+                stacklevel=2,
+                )
+            displayed_unit_properties = unit_table_properties
 
 
         sorting_analyzer = self.ensure_sorting_analyzer(sorting_analyzer)
@@ -98,13 +104,18 @@ def __init__(
         if curation_dict is not None and label_definitions is not None:
             raise ValueError("curation_dict and label_definitions are mutualy exclusive, they cannot be not None both")
 
+        if displayed_unit_properties is None:
+            displayed_unit_properties = list(_default_displayed_unit_properties)
+            if extra_unit_properties is not None:
+                displayed_unit_properties += list(extra_unit_properties.keys())
+        
         data_plot = dict(
             sorting_analyzer=sorting_analyzer,
             unit_ids=unit_ids,
             sparsity=sparsity,
             min_similarity_for_correlograms=min_similarity_for_correlograms,
-            displayed_units_properties=displayed_units_properties,
-            extra_units_properties=extra_units_properties,
+            displayed_unit_properties=displayed_unit_properties,
+            extra_unit_properties=extra_unit_properties,
             curation=curation,
             label_choices=label_choices,
             max_amplitudes_per_unit=max_amplitudes_per_unit,
@@ -183,7 +194,7 @@ def plot_sortingview(self, data_plot, **backend_kwargs):
 
         # unit ids
         v_units_table = generate_unit_table_view(
-            dp.sorting_analyzer, dp.displayed_units_properties, similarity_scores=similarity_scores
+            dp.sorting_analyzer, dp.displayed_unit_properties, similarity_scores=similarity_scores
         )
 
         if dp.curation:
@@ -226,7 +237,7 @@ def plot_spikeinterface_gui(self, data_plot, **backend_kwargs):
             curation=data_plot["curation"],
             curation_dict=data_plot["curation_dict"],
             label_definitions=data_plot["label_definitions"],
-            extra_units_properties=data_plot["extra_units_properties"],
-            displayed_units_properties=data_plot["displayed_units_properties"],
+            extra_unit_properties=data_plot["extra_unit_properties"],
+            displayed_unit_properties=data_plot["displayed_unit_properties"],
         )
 
diff --git a/src/spikeinterface/widgets/utils_sortingview.py b/src/spikeinterface/widgets/utils_sortingview.py
index f6eb8ea529..2a7a8d5ec4 100644
--- a/src/spikeinterface/widgets/utils_sortingview.py
+++ b/src/spikeinterface/widgets/utils_sortingview.py
@@ -59,11 +59,11 @@ def generate_unit_table_view(
 
     if isinstance(sorting_or_sorting_analyzer, SortingAnalyzer):
         analyzer = sorting_or_sorting_analyzer
-        units_tables = make_units_table_from_sorting(analyzer)
+        units_tables = make_units_table_from_analyzer(analyzer)
         sorting = analyzer.sorting
     else:
         sorting = sorting_or_sorting_analyzer
-        units_tables = make_units_table_from_analyzer(sorting)
+        units_tables = make_units_table_from_sorting(sorting)
         # analyzer = None
     
     if unit_properties is None:
@@ -79,7 +79,9 @@ def generate_unit_table_view(
         dtype_convertor = {"i": "int", "u": "int", "f": "float", "U": "str", "S": "str", "b": "bool"}
 
         ut_columns = []
-        for col in units_tables.columns:
+        for col in unit_properties:
+            if col not in units_tables.columns:
+                continue
             values = units_tables[col].to_numpy()
             if values.dtype.kind in dtype_convertor:
                 txt_dtype = dtype_convertor[values.dtype.kind]
@@ -88,7 +90,9 @@ def generate_unit_table_view(
         ut_rows = []
         for unit_index, unit_id in enumerate(sorting.unit_ids):
             row_values = {}
-            for col in units_tables.columns:
+            for col in unit_properties:
+                if col not in units_tables.columns:
+                    continue
                 values = units_tables[col].to_numpy()
                 if values.dtype.kind in dtype_convertor:
                     value = values[unit_index]

From 418bb869d128245c075130f526edf4194f4d5b19 Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Wed, 15 Jan 2025 15:25:14 +0100
Subject: [PATCH 326/344] Improve get prototype waveform using skip.

* Skipping peaks if enough have been collected

* fix

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

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

* Docs and cleaning n_jobs within sc2

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

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

* Exclude 32 chan probe by default for motion correction

* One pass to get the prototype

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

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

* Verbose flag

* WIP

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

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

* WIP

* Fixes for the clustering

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

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

* WIP

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

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

* WIP

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

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

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

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

* job_kwargs propagated everywhere

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

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

* Removing noise templates

* Skipping waveforms re-detection if matched filtering

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

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

* In case of both peak detection, waveforms should be aligned

* WIP

* Whitening

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

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

* WIP

* WIP

* Harmonization of get_prototype_and_waveforms

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

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

* Docstrings and cosmetics

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

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

* Refactoring get_prototype

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

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

* Docstrings

* Removing artefactual templates due to matched filtering

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

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

* Fix

* Cleaning and adapting code for clustering

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

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

* Fixing engine

* Typos

* Revert split related stuffs

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

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

* Fix

* Margin_ms for filtering is too short

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

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

* Update src/spikeinterface/sortingcomponents/tools.py

Co-authored-by: Garcia Samuel <sam.garcia.die@gmail.com>

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

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

* Default params

* Verbose

* Faster mixture merging

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

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

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Garcia Samuel <sam.garcia.die@gmail.com>
---
 src/spikeinterface/core/template.py           |   1 +
 .../sorters/internal/spyking_circus2.py       | 113 +++++++----
 .../sortingcomponents/clustering/circus.py    |  67 ++++---
 .../clustering/clustering_tools.py            |  10 +-
 .../clustering/random_projections.py          |  38 +++-
 .../sortingcomponents/peak_detection.py       |   9 +-
 .../sortingcomponents/peak_localization.py    |   6 +-
 .../tests/test_peak_detection.py              |   6 +-
 src/spikeinterface/sortingcomponents/tools.py | 176 +++++++++++++++++-
 9 files changed, 346 insertions(+), 80 deletions(-)

diff --git a/src/spikeinterface/core/template.py b/src/spikeinterface/core/template.py
index b64f0610ea..3e3fcc7384 100644
--- a/src/spikeinterface/core/template.py
+++ b/src/spikeinterface/core/template.py
@@ -205,6 +205,7 @@ def to_sparse(self, sparsity):
             unit_ids=self.unit_ids,
             probe=self.probe,
             check_for_consistent_sparsity=self.check_for_consistent_sparsity,
+            is_scaled=self.is_scaled,
         )
 
     def get_one_template_dense(self, unit_index):
diff --git a/src/spikeinterface/sorters/internal/spyking_circus2.py b/src/spikeinterface/sorters/internal/spyking_circus2.py
index 6e84cc996f..a3a3523591 100644
--- a/src/spikeinterface/sorters/internal/spyking_circus2.py
+++ b/src/spikeinterface/sorters/internal/spyking_circus2.py
@@ -6,12 +6,16 @@
 import numpy as np
 
 from spikeinterface.core import NumpySorting
-from spikeinterface.core.job_tools import fix_job_kwargs
+from spikeinterface.core.job_tools import fix_job_kwargs, split_job_kwargs
 from spikeinterface.core.recording_tools import get_noise_levels
 from spikeinterface.core.template import Templates
 from spikeinterface.core.waveform_tools import estimate_templates
 from spikeinterface.preprocessing import common_reference, whiten, bandpass_filter, correct_motion
-from spikeinterface.sortingcomponents.tools import cache_preprocessing
+from spikeinterface.sortingcomponents.tools import (
+    cache_preprocessing,
+    get_prototype_and_waveforms_from_recording,
+    get_shuffled_recording_slices,
+)
 from spikeinterface.core.basesorting import minimum_spike_dtype
 from spikeinterface.core.sparsity import compute_sparsity
 from spikeinterface.core.sortinganalyzer import create_sorting_analyzer
@@ -26,7 +30,7 @@ class Spykingcircus2Sorter(ComponentsBasedSorter):
     _default_params = {
         "general": {"ms_before": 2, "ms_after": 2, "radius_um": 75},
         "sparsity": {"method": "snr", "amplitude_mode": "peak_to_peak", "threshold": 0.25},
-        "filtering": {"freq_min": 150, "freq_max": 7000, "ftype": "bessel", "filter_order": 2},
+        "filtering": {"freq_min": 150, "freq_max": 7000, "ftype": "bessel", "filter_order": 2, "margin_ms": 10},
         "whitening": {"mode": "local", "regularize": False},
         "detection": {"peak_sign": "neg", "detect_threshold": 4},
         "selection": {
@@ -53,6 +57,7 @@ class Spykingcircus2Sorter(ComponentsBasedSorter):
         "cache_preprocessing": {"mode": "memory", "memory_limit": 0.5, "delete_cache": True},
         "multi_units_only": False,
         "job_kwargs": {"n_jobs": 0.5},
+        "seed": 42,
         "debug": False,
     }
 
@@ -74,18 +79,21 @@ class Spykingcircus2Sorter(ComponentsBasedSorter):
         "merging": "A dictionary to specify the final merging param to group cells after template matching (get_potential_auto_merge)",
         "motion_correction": "A dictionary to be provided if motion correction has to be performed (dense probe only)",
         "apply_preprocessing": "Boolean to specify whether circus 2 should preprocess the recording or not. If yes, then high_pass filtering + common\
-                                                    median reference + zscore",
+                                                    median reference + whitening",
+        "apply_motion_correction": "Boolean to specify whether circus 2 should apply motion correction to the recording or not",
+        "matched_filtering": "Boolean to specify whether circus 2 should detect peaks via matched filtering (slightly slower)",
         "cache_preprocessing": "How to cache the preprocessed recording. Mode can be memory, file, zarr, with extra arguments. In case of memory (default), \
                          memory_limit will control how much RAM can be used. In case of folder or zarr, delete_cache controls if cache is cleaned after sorting",
         "multi_units_only": "Boolean to get only multi units activity (i.e. one template per electrode)",
         "job_kwargs": "A dictionary to specify how many jobs and which parameters they should used",
+        "seed": "An int to control how chunks are shuffled while detecting peaks",
         "debug": "Boolean to specify if internal data structures made during the sorting should be kept for debugging",
     }
 
     sorter_description = """Spyking Circus 2 is a rewriting of Spyking Circus, within the SpikeInterface framework
     It uses a more conservative clustering algorithm (compared to Spyking Circus), which is less prone to hallucinate units and/or find noise.
     In addition, it also uses a full Orthogonal Matching Pursuit engine to reconstruct the traces, leading to more spikes
-    being discovered."""
+    being discovered. The code is much faster and memory efficient, inheriting from all the preprocessing possibilities of spikeinterface"""
 
     @classmethod
     def get_sorter_version(cls):
@@ -114,7 +122,7 @@ def _run_from_folder(cls, sorter_output_folder, params, verbose):
         from spikeinterface.sortingcomponents.clustering import find_cluster_from_peaks
         from spikeinterface.sortingcomponents.matching import find_spikes_from_templates
         from spikeinterface.sortingcomponents.tools import remove_empty_templates
-        from spikeinterface.sortingcomponents.tools import get_prototype_spike, check_probe_for_drift_correction
+        from spikeinterface.sortingcomponents.tools import check_probe_for_drift_correction
 
         job_kwargs = fix_job_kwargs(params["job_kwargs"])
         job_kwargs.update({"progress_bar": verbose})
@@ -131,10 +139,14 @@ def _run_from_folder(cls, sorter_output_folder, params, verbose):
         ## First, we are filtering the data
         filtering_params = params["filtering"].copy()
         if params["apply_preprocessing"]:
+            if verbose:
+                print("Preprocessing the recording (bandpass filtering + CMR + whitening)")
             recording_f = bandpass_filter(recording, **filtering_params, dtype="float32")
             if num_channels > 1:
                 recording_f = common_reference(recording_f)
         else:
+            if verbose:
+                print("Skipping preprocessing (whitening only)")
             recording_f = recording
             recording_f.annotate(is_filtered=True)
 
@@ -157,12 +169,14 @@ def _run_from_folder(cls, sorter_output_folder, params, verbose):
         # TODO add , regularize=True chen ready
         whitening_kwargs = params["whitening"].copy()
         whitening_kwargs["dtype"] = "float32"
-        whitening_kwargs["radius_um"] = radius_um
+        whitening_kwargs["regularize"] = whitening_kwargs.get("regularize", False)
         if num_channels == 1:
             whitening_kwargs["regularize"] = False
+        if whitening_kwargs["regularize"]:
+            whitening_kwargs["regularize_kwargs"] = {"method": "LedoitWolf"}
 
         recording_w = whiten(recording_f, **whitening_kwargs)
-        noise_levels = get_noise_levels(recording_w, return_scaled=False)
+        noise_levels = get_noise_levels(recording_w, return_scaled=False, **job_kwargs)
 
         if recording_w.check_serializability("json"):
             recording_w.dump(sorter_output_folder / "preprocessed_recording.json", relative_to=None)
@@ -173,9 +187,8 @@ def _run_from_folder(cls, sorter_output_folder, params, verbose):
 
         ## Then, we are detecting peaks with a locally_exclusive method
         detection_params = params["detection"].copy()
-        detection_params.update(job_kwargs)
-
-        detection_params["radius_um"] = detection_params.get("radius_um", 50)
+        selection_params = params["selection"].copy()
+        detection_params["radius_um"] = radius_um
         detection_params["exclude_sweep_ms"] = exclude_sweep_ms
         detection_params["noise_levels"] = noise_levels
 
@@ -183,17 +196,47 @@ def _run_from_folder(cls, sorter_output_folder, params, verbose):
         nbefore = int(ms_before * fs / 1000.0)
         nafter = int(ms_after * fs / 1000.0)
 
+        skip_peaks = not params["multi_units_only"] and selection_params.get("method", "uniform") == "uniform"
+        max_n_peaks = selection_params["n_peaks_per_channel"] * num_channels
+        n_peaks = max(selection_params["min_n_peaks"], max_n_peaks)
+
+        if params["debug"]:
+            clustering_folder = sorter_output_folder / "clustering"
+            clustering_folder.mkdir(parents=True, exist_ok=True)
+            np.save(clustering_folder / "noise_levels.npy", noise_levels)
+
         if params["matched_filtering"]:
-            peaks = detect_peaks(recording_w, "locally_exclusive", **detection_params, skip_after_n_peaks=5000)
-            prototype = get_prototype_spike(recording_w, peaks, ms_before, ms_after, **job_kwargs)
+            prototype, waveforms, _ = get_prototype_and_waveforms_from_recording(
+                recording_w,
+                n_peaks=10000,
+                ms_before=ms_before,
+                ms_after=ms_after,
+                seed=params["seed"],
+                **detection_params,
+                **job_kwargs,
+            )
             detection_params["prototype"] = prototype
             detection_params["ms_before"] = ms_before
-            peaks = detect_peaks(recording_w, "matched_filtering", **detection_params)
+            if params["debug"]:
+                np.save(clustering_folder / "waveforms.npy", waveforms)
+                np.save(clustering_folder / "prototype.npy", prototype)
+            if skip_peaks:
+                detection_params["skip_after_n_peaks"] = n_peaks
+                detection_params["recording_slices"] = get_shuffled_recording_slices(
+                    recording_w, seed=params["seed"], **job_kwargs
+                )
+            peaks = detect_peaks(recording_w, "matched_filtering", **detection_params, **job_kwargs)
         else:
-            peaks = detect_peaks(recording_w, "locally_exclusive", **detection_params)
+            waveforms = None
+            if skip_peaks:
+                detection_params["skip_after_n_peaks"] = n_peaks
+                detection_params["recording_slices"] = get_shuffled_recording_slices(
+                    recording_w, seed=params["seed"], **job_kwargs
+                )
+            peaks = detect_peaks(recording_w, "locally_exclusive", **detection_params, **job_kwargs)
 
-        if verbose:
-            print("We found %d peaks in total" % len(peaks))
+        if not skip_peaks and verbose:
+            print("Found %d peaks in total" % len(peaks))
 
         if params["multi_units_only"]:
             sorting = NumpySorting.from_peaks(peaks, sampling_frequency, unit_ids=recording_w.unit_ids)
@@ -201,14 +244,12 @@ def _run_from_folder(cls, sorter_output_folder, params, verbose):
             ## We subselect a subset of all the peaks, by making the distributions os SNRs over all
             ## channels as flat as possible
             selection_params = params["selection"]
-            selection_params["n_peaks"] = min(len(peaks), selection_params["n_peaks_per_channel"] * num_channels)
-            selection_params["n_peaks"] = max(selection_params["min_n_peaks"], selection_params["n_peaks"])
-
+            selection_params["n_peaks"] = n_peaks
             selection_params.update({"noise_levels": noise_levels})
             selected_peaks = select_peaks(peaks, **selection_params)
 
             if verbose:
-                print("We kept %d peaks for clustering" % len(selected_peaks))
+                print("Kept %d peaks for clustering" % len(selected_peaks))
 
             ## We launch a clustering (using hdbscan) relying on positions and features extracted on
             ## the fly from the snippets
@@ -218,10 +259,13 @@ def _run_from_folder(cls, sorter_output_folder, params, verbose):
             clustering_params["radius_um"] = radius_um
             clustering_params["waveforms"]["ms_before"] = ms_before
             clustering_params["waveforms"]["ms_after"] = ms_after
+            clustering_params["few_waveforms"] = waveforms
             clustering_params["noise_levels"] = noise_levels
-            clustering_params["ms_before"] = exclude_sweep_ms
-            clustering_params["ms_after"] = exclude_sweep_ms
+            clustering_params["ms_before"] = ms_before
+            clustering_params["ms_after"] = ms_after
+            clustering_params["verbose"] = verbose
             clustering_params["tmp_folder"] = sorter_output_folder / "clustering"
+            clustering_params["noise_threshold"] = detection_params.get("detect_threshold", 4)
 
             legacy = clustering_params.get("legacy", True)
 
@@ -246,12 +290,8 @@ def _run_from_folder(cls, sorter_output_folder, params, verbose):
             unit_ids = np.arange(len(np.unique(labeled_peaks["unit_index"])))
             sorting = NumpySorting(labeled_peaks, sampling_frequency, unit_ids=unit_ids)
 
-            clustering_folder = sorter_output_folder / "clustering"
-            clustering_folder.mkdir(parents=True, exist_ok=True)
-
-            if not params["debug"]:
-                shutil.rmtree(clustering_folder)
-            else:
+            if params["debug"]:
+                np.save(clustering_folder / "peak_labels", peak_labels)
                 np.save(clustering_folder / "labels", labels)
                 np.save(clustering_folder / "peaks", selected_peaks)
 
@@ -294,7 +334,7 @@ def _run_from_folder(cls, sorter_output_folder, params, verbose):
                     np.save(fitting_folder / "spikes", spikes)
 
                 if verbose:
-                    print("We found %d spikes" % len(spikes))
+                    print("Found %d spikes" % len(spikes))
 
                 ## And this is it! We have a spyking circus
                 sorting = np.zeros(spikes.size, dtype=minimum_spike_dtype)
@@ -334,10 +374,10 @@ def _run_from_folder(cls, sorter_output_folder, params, verbose):
                 sorting.save(folder=curation_folder)
                 # np.save(fitting_folder / "amplitudes", guessed_amplitudes)
 
-            sorting = final_cleaning_circus(recording_w, sorting, templates, **merging_params)
+            sorting = final_cleaning_circus(recording_w, sorting, templates, merging_params, **job_kwargs)
 
             if verbose:
-                print(f"Final merging, keeping {len(sorting.unit_ids)} units")
+                print(f"Kept {len(sorting.unit_ids)} units after final merging")
 
         folder_to_delete = None
         cache_mode = params["cache_preprocessing"].get("mode", "memory")
@@ -376,17 +416,18 @@ def create_sorting_analyzer_with_templates(sorting, recording, templates, remove
     return sa
 
 
-def final_cleaning_circus(recording, sorting, templates, **merging_kwargs):
+def final_cleaning_circus(recording, sorting, templates, merging_kwargs, **job_kwargs):
 
     from spikeinterface.core.sorting_tools import apply_merges_to_sorting
 
     sa = create_sorting_analyzer_with_templates(sorting, recording, templates)
 
-    sa.compute("unit_locations", method="monopolar_triangulation")
+    sa.compute("unit_locations", method="monopolar_triangulation", **job_kwargs)
     similarity_kwargs = merging_kwargs.pop("similarity_kwargs", {})
-    sa.compute("template_similarity", **similarity_kwargs)
+    sa.compute("template_similarity", **similarity_kwargs, **job_kwargs)
     correlograms_kwargs = merging_kwargs.pop("correlograms_kwargs", {})
-    sa.compute("correlograms", **correlograms_kwargs)
+    sa.compute("correlograms", **correlograms_kwargs, **job_kwargs)
+
     auto_merge_kwargs = merging_kwargs.pop("auto_merge", {})
     merges = get_potential_auto_merge(sa, resolve_graph=True, **auto_merge_kwargs)
     sorting = apply_merges_to_sorting(sa.sorting, merges)
diff --git a/src/spikeinterface/sortingcomponents/clustering/circus.py b/src/spikeinterface/sortingcomponents/clustering/circus.py
index 243c854bba..bc173a6ff0 100644
--- a/src/spikeinterface/sortingcomponents/clustering/circus.py
+++ b/src/spikeinterface/sortingcomponents/clustering/circus.py
@@ -40,13 +40,7 @@ class CircusClustering:
     """
 
     _default_params = {
-        "hdbscan_kwargs": {
-            "min_cluster_size": 25,
-            "allow_single_cluster": True,
-            "core_dist_n_jobs": -1,
-            "cluster_selection_method": "eom",
-            # "cluster_selection_epsilon" : 5 ## To be optimized
-        },
+        "hdbscan_kwargs": {"min_cluster_size": 10, "allow_single_cluster": True, "min_samples": 5},
         "cleaning_kwargs": {},
         "waveforms": {"ms_before": 2, "ms_after": 2},
         "sparsity": {"method": "snr", "amplitude_mode": "peak_to_peak", "threshold": 0.25},
@@ -57,8 +51,10 @@ class CircusClustering:
         },
         "radius_um": 100,
         "n_svd": [5, 2],
+        "few_waveforms": None,
         "ms_before": 0.5,
         "ms_after": 0.5,
+        "noise_threshold": 4,
         "rank": 5,
         "noise_levels": None,
         "tmp_folder": None,
@@ -86,12 +82,25 @@ def main_function(cls, recording, peaks, params, job_kwargs=dict()):
         tmp_folder.mkdir(parents=True, exist_ok=True)
 
         # SVD for time compression
-        few_peaks = select_peaks(peaks, recording=recording, method="uniform", n_peaks=10000, margin=(nbefore, nafter))
-        few_wfs = extract_waveform_at_max_channel(
-            recording, few_peaks, ms_before=ms_before, ms_after=ms_after, **job_kwargs
-        )
+        if params["few_waveforms"] is None:
+            few_peaks = select_peaks(
+                peaks, recording=recording, method="uniform", n_peaks=10000, margin=(nbefore, nafter)
+            )
+            few_wfs = extract_waveform_at_max_channel(
+                recording, few_peaks, ms_before=ms_before, ms_after=ms_after, **job_kwargs
+            )
+            wfs = few_wfs[:, :, 0]
+        else:
+            offset = int(params["waveforms"]["ms_before"] * fs / 1000)
+            wfs = params["few_waveforms"][:, offset - nbefore : offset + nafter]
+
+        # Ensure all waveforms have a positive max
+        wfs *= np.sign(wfs[:, nbefore])[:, np.newaxis]
+
+        # Remove outliers
+        valid = np.argmax(np.abs(wfs), axis=1) == nbefore
+        wfs = wfs[valid]
 
-        wfs = few_wfs[:, :, 0]
         from sklearn.decomposition import TruncatedSVD
 
         tsvd = TruncatedSVD(params["n_svd"][0])
@@ -189,7 +198,7 @@ def main_function(cls, recording, peaks, params, job_kwargs=dict()):
             original_labels = peaks["channel_index"]
             from spikeinterface.sortingcomponents.clustering.split import split_clusters
 
-            min_size = params["hdbscan_kwargs"].get("min_cluster_size", 50)
+            min_size = 2 * params["hdbscan_kwargs"].get("min_cluster_size", 10)
 
             peak_labels, _ = split_clusters(
                 original_labels,
@@ -225,38 +234,54 @@ def main_function(cls, recording, peaks, params, job_kwargs=dict()):
         nbefore = int(params["waveforms"]["ms_before"] * fs / 1000.0)
         nafter = int(params["waveforms"]["ms_after"] * fs / 1000.0)
 
+        if params["noise_levels"] is None:
+            params["noise_levels"] = get_noise_levels(recording, return_scaled=False, **job_kwargs)
+
         templates_array = estimate_templates(
-            recording, spikes, unit_ids, nbefore, nafter, return_scaled=False, job_name=None, **job_kwargs
+            recording,
+            spikes,
+            unit_ids,
+            nbefore,
+            nafter,
+            return_scaled=False,
+            job_name=None,
+            **job_kwargs,
         )
 
+        best_channels = np.argmax(np.abs(templates_array[:, nbefore, :]), axis=1)
+        peak_snrs = np.abs(templates_array[:, nbefore, :])
+        best_snrs_ratio = (peak_snrs / params["noise_levels"])[np.arange(len(peak_snrs)), best_channels]
+        valid_templates = best_snrs_ratio > params["noise_threshold"]
+
         if d["rank"] is not None:
             from spikeinterface.sortingcomponents.matching.circus import compress_templates
 
             _, _, _, templates_array = compress_templates(templates_array, d["rank"])
 
         templates = Templates(
-            templates_array=templates_array,
+            templates_array=templates_array[valid_templates],
             sampling_frequency=fs,
             nbefore=nbefore,
             sparsity_mask=None,
             channel_ids=recording.channel_ids,
-            unit_ids=unit_ids,
+            unit_ids=unit_ids[valid_templates],
             probe=recording.get_probe(),
             is_scaled=False,
         )
 
-        if params["noise_levels"] is None:
-            params["noise_levels"] = get_noise_levels(recording, return_scaled=False, **job_kwargs)
-
         sparsity = compute_sparsity(templates, noise_levels=params["noise_levels"], **params["sparsity"])
         templates = templates.to_sparse(sparsity)
         empty_templates = templates.sparsity_mask.sum(axis=1) == 0
         templates = remove_empty_templates(templates)
+
         mask = np.isin(peak_labels, np.where(empty_templates)[0])
         peak_labels[mask] = -1
 
+        mask = np.isin(peak_labels, np.where(~valid_templates)[0])
+        peak_labels[mask] = -1
+
         if verbose:
-            print("We found %d raw clusters, starting to clean with matching..." % (len(templates.unit_ids)))
+            print("Found %d raw clusters, starting to clean with matching" % (len(templates.unit_ids)))
 
         cleaning_job_kwargs = job_kwargs.copy()
         cleaning_job_kwargs["progress_bar"] = False
@@ -267,6 +292,6 @@ def main_function(cls, recording, peaks, params, job_kwargs=dict()):
         )
 
         if verbose:
-            print("We kept %d non-duplicated clusters..." % len(labels))
+            print("Kept %d non-duplicated clusters" % len(labels))
 
         return labels, peak_labels
diff --git a/src/spikeinterface/sortingcomponents/clustering/clustering_tools.py b/src/spikeinterface/sortingcomponents/clustering/clustering_tools.py
index 08a1384333..93db9a268f 100644
--- a/src/spikeinterface/sortingcomponents/clustering/clustering_tools.py
+++ b/src/spikeinterface/sortingcomponents/clustering/clustering_tools.py
@@ -570,7 +570,7 @@ def detect_mixtures(templates, method_kwargs={}, job_kwargs={}, tmp_folder=None,
         )
     else:
         recording = NumpyRecording(zdata, sampling_frequency=fs)
-        recording = SharedMemoryRecording.from_recording(recording)
+        recording = SharedMemoryRecording.from_recording(recording, **job_kwargs)
 
     recording = recording.set_probe(templates.probe)
     recording.annotate(is_filtered=True)
@@ -587,6 +587,8 @@ def detect_mixtures(templates, method_kwargs={}, job_kwargs={}, tmp_folder=None,
 
     keep_searching = True
 
+    local_job_kargs = {"n_jobs": 1, "progress_bar": False}
+
     DEBUG = False
     while keep_searching:
 
@@ -604,7 +606,11 @@ def detect_mixtures(templates, method_kwargs={}, job_kwargs={}, tmp_folder=None,
             local_params.update({"ignore_inds": ignore_inds + [i]})
 
             spikes, more_outputs = find_spikes_from_templates(
-                sub_recording, method="circus-omp-svd", method_kwargs=local_params, extra_outputs=True, **job_kwargs
+                sub_recording,
+                method="circus-omp-svd",
+                method_kwargs=local_params,
+                extra_outputs=True,
+                **local_job_kargs,
             )
             local_params["precomputed"] = more_outputs
             valid = (spikes["sample_index"] >= 0) * (spikes["sample_index"] < duration + 2 * margin)
diff --git a/src/spikeinterface/sortingcomponents/clustering/random_projections.py b/src/spikeinterface/sortingcomponents/clustering/random_projections.py
index 484a7376c1..1d4d8881ad 100644
--- a/src/spikeinterface/sortingcomponents/clustering/random_projections.py
+++ b/src/spikeinterface/sortingcomponents/clustering/random_projections.py
@@ -53,6 +53,7 @@ class RandomProjectionClustering:
         "random_seed": 42,
         "noise_levels": None,
         "smoothing_kwargs": {"window_length_ms": 0.25},
+        "noise_threshold": 4,
         "tmp_folder": None,
         "verbose": True,
     }
@@ -129,28 +130,49 @@ def main_function(cls, recording, peaks, params, job_kwargs=dict()):
         nbefore = int(params["waveforms"]["ms_before"] * fs / 1000.0)
         nafter = int(params["waveforms"]["ms_after"] * fs / 1000.0)
 
+        if params["noise_levels"] is None:
+            params["noise_levels"] = get_noise_levels(recording, return_scaled=False, **job_kwargs)
+
         templates_array = estimate_templates(
-            recording, spikes, unit_ids, nbefore, nafter, return_scaled=False, job_name=None, **job_kwargs
+            recording,
+            spikes,
+            unit_ids,
+            nbefore,
+            nafter,
+            return_scaled=False,
+            job_name=None,
+            **job_kwargs,
         )
 
+        best_channels = np.argmax(np.abs(templates_array[:, nbefore, :]), axis=1)
+        peak_snrs = np.abs(templates_array[:, nbefore, :])
+        best_snrs_ratio = (peak_snrs / params["noise_levels"])[np.arange(len(peak_snrs)), best_channels]
+        valid_templates = best_snrs_ratio > params["noise_threshold"]
+
         templates = Templates(
-            templates_array=templates_array,
+            templates_array=templates_array[valid_templates],
             sampling_frequency=fs,
             nbefore=nbefore,
             sparsity_mask=None,
             channel_ids=recording.channel_ids,
-            unit_ids=unit_ids,
+            unit_ids=unit_ids[valid_templates],
             probe=recording.get_probe(),
             is_scaled=False,
         )
-        if params["noise_levels"] is None:
-            params["noise_levels"] = get_noise_levels(recording, return_scaled=False, **job_kwargs)
-        sparsity = compute_sparsity(templates, params["noise_levels"], **params["sparsity"])
+
+        sparsity = compute_sparsity(templates, noise_levels=params["noise_levels"], **params["sparsity"])
         templates = templates.to_sparse(sparsity)
+        empty_templates = templates.sparsity_mask.sum(axis=1) == 0
         templates = remove_empty_templates(templates)
 
+        mask = np.isin(peak_labels, np.where(empty_templates)[0])
+        peak_labels[mask] = -1
+
+        mask = np.isin(peak_labels, np.where(~valid_templates)[0])
+        peak_labels[mask] = -1
+
         if verbose:
-            print("We found %d raw clusters, starting to clean with matching..." % (len(templates.unit_ids)))
+            print("Found %d raw clusters, starting to clean with matching" % (len(templates.unit_ids)))
 
         cleaning_job_kwargs = job_kwargs.copy()
         cleaning_job_kwargs["progress_bar"] = False
@@ -161,6 +183,6 @@ def main_function(cls, recording, peaks, params, job_kwargs=dict()):
         )
 
         if verbose:
-            print("We kept %d non-duplicated clusters..." % len(labels))
+            print("Kept %d non-duplicated clusters" % len(labels))
 
         return labels, peak_labels
diff --git a/src/spikeinterface/sortingcomponents/peak_detection.py b/src/spikeinterface/sortingcomponents/peak_detection.py
index d03744f8f9..12955e2c40 100644
--- a/src/spikeinterface/sortingcomponents/peak_detection.py
+++ b/src/spikeinterface/sortingcomponents/peak_detection.py
@@ -118,7 +118,11 @@ def detect_peaks(
         squeeze_output = True
     else:
         squeeze_output = False
-        job_name += f"  + {len(pipeline_nodes)} nodes"
+        if len(pipeline_nodes) == 1:
+            plural = ""
+        else:
+            plural = "s"
+        job_name += f" + {len(pipeline_nodes)} node{plural}"
 
         # because node are modified inplace (insert parent) they need to copy incase
         # the same pipeline is run several times
@@ -677,7 +681,6 @@ def __init__(
         medians = medians[:, None]
         noise_levels = np.median(np.abs(conv_random_data - medians), axis=1) / 0.6744897501960817
         self.abs_thresholds = noise_levels * detect_threshold
-
         self._dtype = np.dtype(base_peak_dtype + [("z", "float32")])
 
     def get_dtype(self):
@@ -727,8 +730,8 @@ def compute(self, traces, start_frame, end_frame, segment_index, max_margin):
             return (np.zeros(0, dtype=self._dtype),)
 
         peak_sample_ind += self.exclude_sweep_size + self.conv_margin + self.nbefore
-
         peak_amplitude = traces[peak_sample_ind, peak_chan_ind]
+
         local_peaks = np.zeros(peak_sample_ind.size, dtype=self._dtype)
         local_peaks["sample_index"] = peak_sample_ind
         local_peaks["channel_index"] = peak_chan_ind
diff --git a/src/spikeinterface/sortingcomponents/peak_localization.py b/src/spikeinterface/sortingcomponents/peak_localization.py
index 08bcabf5e5..1e4e0edded 100644
--- a/src/spikeinterface/sortingcomponents/peak_localization.py
+++ b/src/spikeinterface/sortingcomponents/peak_localization.py
@@ -33,7 +33,7 @@
     get_grid_convolution_templates_and_weights,
 )
 
-from .tools import get_prototype_spike
+from .tools import get_prototype_and_waveforms_from_peaks
 
 
 def get_localization_pipeline_nodes(
@@ -73,8 +73,8 @@ def get_localization_pipeline_nodes(
             assert isinstance(peak_source, (PeakRetriever, SpikeRetriever))
             # extract prototypes silently
             job_kwargs["progress_bar"] = False
-            method_kwargs["prototype"] = get_prototype_spike(
-                recording, peak_source.peaks, ms_before=ms_before, ms_after=ms_after, **job_kwargs
+            method_kwargs["prototype"], _, _ = get_prototype_and_waveforms_from_peaks(
+                recording, peaks=peak_source.peaks, ms_before=ms_before, ms_after=ms_after, **job_kwargs
             )
         extract_dense_waveforms = ExtractDenseWaveforms(
             recording, parents=[peak_source], ms_before=ms_before, ms_after=ms_after, return_output=False
diff --git a/src/spikeinterface/sortingcomponents/tests/test_peak_detection.py b/src/spikeinterface/sortingcomponents/tests/test_peak_detection.py
index 7c34f5948d..341ed3426d 100644
--- a/src/spikeinterface/sortingcomponents/tests/test_peak_detection.py
+++ b/src/spikeinterface/sortingcomponents/tests/test_peak_detection.py
@@ -22,7 +22,7 @@
 )
 
 from spikeinterface.core.node_pipeline import run_node_pipeline
-from spikeinterface.sortingcomponents.tools import get_prototype_spike
+from spikeinterface.sortingcomponents.tools import get_prototype_and_waveforms_from_peaks
 
 from spikeinterface.sortingcomponents.tests.common import make_dataset
 
@@ -314,7 +314,9 @@ def test_detect_peaks_locally_exclusive_matched_filtering(recording, job_kwargs)
 
     ms_before = 1.0
     ms_after = 1.0
-    prototype = get_prototype_spike(recording, peaks_by_channel_np, ms_before, ms_after, **job_kwargs)
+    prototype, _, _ = get_prototype_and_waveforms_from_peaks(
+        recording, peaks=peaks_by_channel_np, ms_before=ms_before, ms_after=ms_after, **job_kwargs
+    )
 
     peaks_local_mf_filtering = detect_peaks(
         recording,
diff --git a/src/spikeinterface/sortingcomponents/tools.py b/src/spikeinterface/sortingcomponents/tools.py
index 1501582336..1bd2381cda 100644
--- a/src/spikeinterface/sortingcomponents/tools.py
+++ b/src/spikeinterface/sortingcomponents/tools.py
@@ -69,25 +69,174 @@ def extract_waveform_at_max_channel(rec, peaks, ms_before=0.5, ms_after=1.5, **j
     return all_wfs
 
 
-def get_prototype_spike(recording, peaks, ms_before=0.5, ms_after=0.5, nb_peaks=1000, **job_kwargs):
+def get_prototype_and_waveforms_from_peaks(
+    recording, peaks, n_peaks=5000, ms_before=0.5, ms_after=0.5, seed=None, **all_kwargs
+):
+    """
+    Function to extract a prototype waveform from peaks.
+
+    Parameters
+    ----------
+    recording : Recording
+        The recording object containing the data.
+    peaks : numpy.array, optional
+        Array of peaks, if None, peaks will be detected, by default None.
+    n_peaks : int, optional
+        Number of peaks to consider, by default 5000.
+    ms_before : float, optional
+        Time in milliseconds before the peak to extract the waveform, by default 0.5.
+    ms_after : float, optional
+        Time in milliseconds after the peak to extract the waveform, by default 0.5.
+    seed : int or None, optional
+        Seed for random number generator, by default None.
+    **all_kwargs : dict
+        Additional keyword arguments for peak detection and job kwargs.
+
+    Returns
+    -------
+    prototype : numpy.array
+        The prototype waveform.
+    waveforms : numpy.array
+        The extracted waveforms for the selected peaks.
+    peaks : numpy.array
+        The selected peaks used to extract waveforms.
+    """
     from spikeinterface.sortingcomponents.peak_selection import select_peaks
 
+    _, job_kwargs = split_job_kwargs(all_kwargs)
+
     nbefore = int(ms_before * recording.sampling_frequency / 1000.0)
     nafter = int(ms_after * recording.sampling_frequency / 1000.0)
 
-    few_peaks = select_peaks(peaks, recording=recording, method="uniform", n_peaks=nb_peaks, margin=(nbefore, nafter))
-
+    few_peaks = select_peaks(
+        peaks, recording=recording, method="uniform", n_peaks=n_peaks, margin=(nbefore, nafter), seed=seed
+    )
     waveforms = extract_waveform_at_max_channel(
         recording, few_peaks, ms_before=ms_before, ms_after=ms_after, **job_kwargs
     )
+
+    with np.errstate(divide="ignore", invalid="ignore"):
+        prototype = np.nanmedian(waveforms[:, :, 0] / (np.abs(waveforms[:, nbefore, 0][:, np.newaxis])), axis=0)
+
+    return prototype, waveforms[:, :, 0], few_peaks
+
+
+def get_prototype_and_waveforms_from_recording(
+    recording, n_peaks=5000, ms_before=0.5, ms_after=0.5, seed=None, **all_kwargs
+):
+    """
+    Function to extract a prototype waveform from peaks detected on the fly.
+
+    Parameters
+    ----------
+    recording : Recording
+        The recording object containing the data.
+    n_peaks : int, optional
+        Number of peaks to consider, by default 5000.
+    ms_before : float, optional
+        Time in milliseconds before the peak to extract the waveform, by default 0.5.
+    ms_after : float, optional
+        Time in milliseconds after the peak to extract the waveform, by default 0.5.
+    seed : int or None, optional
+        Seed for random number generator, by default None.
+    **all_kwargs : dict
+        Additional keyword arguments for peak detection and job kwargs.
+
+    Returns
+    -------
+    prototype : numpy.array
+        The prototype waveform.
+    waveforms : numpy.array
+        The extracted waveforms for the selected peaks.
+    peaks : numpy.array
+        The selected peaks used to extract waveforms.
+    """
+    from spikeinterface.sortingcomponents.peak_detection import detect_peaks
+    from spikeinterface.core.node_pipeline import ExtractSparseWaveforms
+
+    detection_kwargs, job_kwargs = split_job_kwargs(all_kwargs)
+
+    nbefore = int(ms_before * recording.sampling_frequency / 1000.0)
+    node = ExtractSparseWaveforms(
+        recording,
+        parents=None,
+        return_output=True,
+        ms_before=ms_before,
+        ms_after=ms_after,
+        radius_um=0,
+    )
+
+    pipeline_nodes = [node]
+
+    recording_slices = get_shuffled_recording_slices(recording, seed=seed, **job_kwargs)
+
+    res = detect_peaks(
+        recording,
+        pipeline_nodes=pipeline_nodes,
+        skip_after_n_peaks=n_peaks,
+        recording_slices=recording_slices,
+        **detection_kwargs,
+        **job_kwargs,
+    )
+
+    rng = np.random.RandomState(seed)
+    indices = rng.permutation(np.arange(len(res[0])))
+
+    few_peaks = res[0][indices[:n_peaks]]
+    waveforms = res[1][indices[:n_peaks]]
+
     with np.errstate(divide="ignore", invalid="ignore"):
         prototype = np.nanmedian(waveforms[:, :, 0] / (np.abs(waveforms[:, nbefore, 0][:, np.newaxis])), axis=0)
-    return prototype
+
+    return prototype, waveforms[:, :, 0], few_peaks
+
+
+def get_prototype_and_waveforms(
+    recording, n_peaks=5000, peaks=None, ms_before=0.5, ms_after=0.5, seed=None, **all_kwargs
+):
+    """
+    Function to extract a prototype waveform either from peaks or from a peak detection. Note that in case
+    of a peak detection, the detection stops as soon as n_peaks are detected.
+
+    Parameters
+    ----------
+    recording : Recording
+        The recording object containing the data.
+    n_peaks : int, optional
+        Number of peaks to consider, by default 5000.
+    peaks : numpy.array, optional
+        Array of peaks, if None, peaks will be detected, by default None.
+    ms_before : float, optional
+        Time in milliseconds before the peak to extract the waveform, by default 0.5.
+    ms_after : float, optional
+        Time in milliseconds after the peak to extract the waveform, by default 0.5.
+    seed : int or None, optional
+        Seed for random number generator, by default None.
+    **all_kwargs : dict
+        Additional keyword arguments for peak detection and job kwargs.
+
+    Returns
+    -------
+    prototype : numpy.array
+        The prototype waveform.
+    waveforms : numpy.array
+        The extracted waveforms for the selected peaks.
+    peaks : numpy.array
+        The selected peaks used to extract waveforms.
+    """
+    if peaks is None:
+        return get_prototype_and_waveforms_from_recording(
+            recording, n_peaks, ms_before=ms_before, ms_after=ms_after, seed=seed, **all_kwargs
+        )
+    else:
+        return get_prototype_and_waveforms_from_peaks(
+            recording, peaks, n_peaks, ms_before=ms_before, ms_after=ms_after, seed=seed, **all_kwargs
+        )
 
 
 def check_probe_for_drift_correction(recording, dist_x_max=60):
     num_channels = recording.get_num_channels()
-    if num_channels < 32:
+    if num_channels <= 32:
         return False
     else:
         locations = recording.get_channel_locations()
@@ -151,3 +300,20 @@ def fit_sigmoid(xdata, ydata, p0=None):
 
     popt, pcov = curve_fit(sigmoid, xdata, ydata, p0)
     return popt
+
+
+def get_shuffled_recording_slices(recording, seed=None, **job_kwargs):
+    from spikeinterface.core.job_tools import ensure_chunk_size
+    from spikeinterface.core.job_tools import divide_segment_into_chunks
+
+    chunk_size = ensure_chunk_size(recording, **job_kwargs)
+    recording_slices = []
+    for segment_index in range(recording.get_num_segments()):
+        num_frames = recording.get_num_samples(segment_index)
+        chunks = divide_segment_into_chunks(num_frames, chunk_size)
+        recording_slices.extend([(segment_index, frame_start, frame_stop) for frame_start, frame_stop in chunks])
+
+    rng = np.random.default_rng(seed)
+    recording_slices = rng.permutation(recording_slices)
+
+    return recording_slices

From 13d9c568d25ba079fdf43499542c4498789d5736 Mon Sep 17 00:00:00 2001
From: Heberto Mayorquin <h.mayorquin@gmail.com>
Date: Thu, 16 Jan 2025 08:59:56 -0600
Subject: [PATCH 327/344] revert code change

---
 src/spikeinterface/extractors/neuropixels_utils.py | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/src/spikeinterface/extractors/neuropixels_utils.py b/src/spikeinterface/extractors/neuropixels_utils.py
index 3bd9fc746b..f7841aeae2 100644
--- a/src/spikeinterface/extractors/neuropixels_utils.py
+++ b/src/spikeinterface/extractors/neuropixels_utils.py
@@ -52,10 +52,8 @@ def get_neuropixels_sample_shifts(
 
     sample_shifts = np.zeros_like(adc_indices)
 
-    for a in np.unique(adc_indices):
-        channel_indices = np.where(adc_indices == a)[0]
-        sample_shifts[channel_indices] = np.arange(len(channel_indices)) / num_cycles
-
+    for adc_index in adc_indices:
+        sample_shifts[adc_indices == adc_index] = np.arange(num_channels_per_adc) / num_cycles
     return sample_shifts
 
 

From 9b8f3d230358de623154630014dcc19db5075165 Mon Sep 17 00:00:00 2001
From: Garcia Samuel <sam.garcia.die@gmail.com>
Date: Fri, 17 Jan 2025 12:12:14 +0100
Subject: [PATCH 328/344] yep

Co-authored-by: Alessio Buccino <alejoe9187@gmail.com>
---
 src/spikeinterface/widgets/sorting_summary.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/spikeinterface/widgets/sorting_summary.py b/src/spikeinterface/widgets/sorting_summary.py
index 480fb76ceb..76d418b64d 100644
--- a/src/spikeinterface/widgets/sorting_summary.py
+++ b/src/spikeinterface/widgets/sorting_summary.py
@@ -55,12 +55,12 @@ class SortingSummaryWidget(BaseWidget):
         analyzer.get_extension("template_metrics").get_data().columns.
     extra_unit_properties : None dict, default: None
         A dict with extra units properties to display.
-    curation_dict : dict or None
+    curation_dict : dict or None, default: None
         When curation is True, optionaly the viewer can get a previous 'curation_dict'
         to continue/check  previous curations on this analyzer.
         In this case label_definitions must be None beacuse it is already included in the curation_dict.
         (spikeinterface_gui backend)
-    label_definitions : dict or None
+    label_definitions : dict or None, default: None
         When curation is True, optionaly the user can provide a label_definitions dict.
         This replaces the label_choices in the curation_format.
         (spikeinterface_gui backend)

From e8b4fe12e1674bd4e3d95734b33a94cd011a0fef Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Fri, 17 Jan 2025 16:00:59 +0000
Subject: [PATCH 329/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/widgets/sorting_summary.py   | 11 +++++------
 src/spikeinterface/widgets/utils.py             | 10 ++++++----
 src/spikeinterface/widgets/utils_sortingview.py |  5 ++---
 3 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/src/spikeinterface/widgets/sorting_summary.py b/src/spikeinterface/widgets/sorting_summary.py
index 76d418b64d..2271e5a4cb 100644
--- a/src/spikeinterface/widgets/sorting_summary.py
+++ b/src/spikeinterface/widgets/sorting_summary.py
@@ -18,6 +18,7 @@
 
 _default_displayed_unit_properties = ["firing_rate", "num_spikes", "x", "y", "amplitude", "snr", "rp_violation"]
 
+
 class SortingSummaryWidget(BaseWidget):
     """
     Plots spike sorting summary.
@@ -65,6 +66,7 @@ class SortingSummaryWidget(BaseWidget):
         This replaces the label_choices in the curation_format.
         (spikeinterface_gui backend)
     """
+
     def __init__(
         self,
         sorting_analyzer: SortingAnalyzer,
@@ -82,16 +84,15 @@ def __init__(
         unit_table_properties=None,
         **backend_kwargs,
     ):
-        
+
         if unit_table_properties is not None:
             warnings.warn(
                 "plot_sorting_summary() : unit_table_properties is deprecated, use displayed_unit_properties instead",
                 category=DeprecationWarning,
                 stacklevel=2,
-                )
+            )
             displayed_unit_properties = unit_table_properties
 
-
         sorting_analyzer = self.ensure_sorting_analyzer(sorting_analyzer)
         self.check_extensions(
             sorting_analyzer, ["correlograms", "spike_amplitudes", "unit_locations", "template_similarity"]
@@ -108,7 +109,7 @@ def __init__(
             displayed_unit_properties = list(_default_displayed_unit_properties)
             if extra_unit_properties is not None:
                 displayed_unit_properties += list(extra_unit_properties.keys())
-        
+
         data_plot = dict(
             sorting_analyzer=sorting_analyzer,
             unit_ids=unit_ids,
@@ -230,7 +231,6 @@ def plot_spikeinterface_gui(self, data_plot, **backend_kwargs):
 
         from spikeinterface_gui import run_mainwindow
 
-
         run_mainwindow(
             sorting_analyzer,
             with_traces=True,
@@ -240,4 +240,3 @@ def plot_spikeinterface_gui(self, data_plot, **backend_kwargs):
             extra_unit_properties=data_plot["extra_unit_properties"],
             displayed_unit_properties=data_plot["displayed_unit_properties"],
         )
-
diff --git a/src/spikeinterface/widgets/utils.py b/src/spikeinterface/widgets/utils.py
index 89025dea31..7d5cf98c01 100644
--- a/src/spikeinterface/widgets/utils.py
+++ b/src/spikeinterface/widgets/utils.py
@@ -245,7 +245,6 @@ def array_to_image(
     return output_image
 
 
-
 def make_units_table_from_sorting(sorting, units_table=None):
     """
     Make a DataFrame from sorting properties.
@@ -266,6 +265,7 @@ def make_units_table_from_sorting(sorting, units_table=None):
 
     if units_table is None:
         import pandas as pd
+
         units_table = pd.DataFrame(index=sorting.unit_ids)
 
     for col in sorting.get_property_keys():
@@ -275,10 +275,11 @@ def make_units_table_from_sorting(sorting, units_table=None):
 
     return units_table
 
+
 def make_units_table_from_analyzer(
-        analyzer,
-        extra_properties=None,
-    ):
+    analyzer,
+    extra_properties=None,
+):
     """
     Make a DataFrame by aggregating :
       * quality metrics
@@ -302,6 +303,7 @@ def make_units_table_from_analyzer(
         Table containing all columns.
     """
     import pandas as pd
+
     all_df = []
 
     if analyzer.get_extension("unit_locations") is not None:
diff --git a/src/spikeinterface/widgets/utils_sortingview.py b/src/spikeinterface/widgets/utils_sortingview.py
index 2a7a8d5ec4..451b1d145e 100644
--- a/src/spikeinterface/widgets/utils_sortingview.py
+++ b/src/spikeinterface/widgets/utils_sortingview.py
@@ -9,7 +9,6 @@
 from .utils import make_units_table_from_sorting, make_units_table_from_analyzer
 
 
-
 def make_serializable(*args):
     dict_to_serialize = {int(i): a for i, a in enumerate(args)}
     serializable_dict = check_json(dict_to_serialize)
@@ -65,7 +64,7 @@ def generate_unit_table_view(
         sorting = sorting_or_sorting_analyzer
         units_tables = make_units_table_from_sorting(sorting)
         # analyzer = None
-    
+
     if unit_properties is None:
         ut_columns = []
         ut_rows = [vv.UnitsTableRow(unit_id=u, values={}) for u in sorting.unit_ids]
@@ -105,5 +104,5 @@ def generate_unit_table_view(
             ut_rows.append(vv.UnitsTableRow(unit_id=unit_id, values=check_json(row_values)))
 
     v_units_table = vv.UnitsTable(rows=ut_rows, columns=ut_columns, similarity_scores=similarity_scores)
-    
+
     return v_units_table

From 7e49ab963d2ed108d61688e4f9e16ab46f938768 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Fri, 17 Jan 2025 17:12:43 +0100
Subject: [PATCH 330/344] Update src/spikeinterface/widgets/sorting_summary.py

---
 src/spikeinterface/widgets/sorting_summary.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/widgets/sorting_summary.py b/src/spikeinterface/widgets/sorting_summary.py
index 2271e5a4cb..8587830862 100644
--- a/src/spikeinterface/widgets/sorting_summary.py
+++ b/src/spikeinterface/widgets/sorting_summary.py
@@ -54,7 +54,7 @@ class SortingSummaryWidget(BaseWidget):
         See all properties available with sorting.get_property_keys(), and, if available,
         analyzer.get_extension("quality_metrics").get_data().columns and
         analyzer.get_extension("template_metrics").get_data().columns.
-    extra_unit_properties : None dict, default: None
+    extra_unit_properties : dict or None, default: None
         A dict with extra units properties to display.
     curation_dict : dict or None, default: None
         When curation is True, optionaly the viewer can get a previous 'curation_dict'

From 4831ad0851e71910b3fce9e2630b6c7cc72190d3 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Sat, 18 Jan 2025 16:16:33 +0100
Subject: [PATCH 331/344] Use pd.concat instead of df.append

---
 src/spikeinterface/widgets/utils.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/spikeinterface/widgets/utils.py b/src/spikeinterface/widgets/utils.py
index 7d5cf98c01..ae1dce8571 100644
--- a/src/spikeinterface/widgets/utils.py
+++ b/src/spikeinterface/widgets/utils.py
@@ -309,15 +309,15 @@ def make_units_table_from_analyzer(
     if analyzer.get_extension("unit_locations") is not None:
         locs = analyzer.get_extension("unit_locations").get_data()
         df = pd.DataFrame(locs[:, :2], columns=["x", "y"], index=analyzer.unit_ids)
-        all_df.append(df)
+        all_df = pd.concat([all_df, df])
 
     if analyzer.get_extension("quality_metrics") is not None:
         df = analyzer.get_extension("quality_metrics").get_data()
-        all_df.append(df)
+        all_df = pd.concat([all_df, df])
 
     if analyzer.get_extension("template_metrics") is not None:
         all_df = analyzer.get_extension("template_metrics").get_data()
-        all_df.append(df)
+        all_df = pd.concat([all_df, df])
 
     if len(all_df) > 0:
         units_table = pd.concat(all_df, axis=1)

From 2ba92b7c7987cb12142556c0cbeb8f34bccb6cb3 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Sat, 18 Jan 2025 16:26:19 +0100
Subject: [PATCH 332/344] Fix template metrics sv

---
 src/spikeinterface/widgets/utils.py | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/spikeinterface/widgets/utils.py b/src/spikeinterface/widgets/utils.py
index ae1dce8571..75c6248f0f 100644
--- a/src/spikeinterface/widgets/utils.py
+++ b/src/spikeinterface/widgets/utils.py
@@ -309,15 +309,15 @@ def make_units_table_from_analyzer(
     if analyzer.get_extension("unit_locations") is not None:
         locs = analyzer.get_extension("unit_locations").get_data()
         df = pd.DataFrame(locs[:, :2], columns=["x", "y"], index=analyzer.unit_ids)
-        all_df = pd.concat([all_df, df])
+        all_df.append(df)
 
     if analyzer.get_extension("quality_metrics") is not None:
         df = analyzer.get_extension("quality_metrics").get_data()
-        all_df = pd.concat([all_df, df])
+        all_df.append(df)
 
     if analyzer.get_extension("template_metrics") is not None:
-        all_df = analyzer.get_extension("template_metrics").get_data()
-        all_df = pd.concat([all_df, df])
+        df = analyzer.get_extension("template_metrics").get_data()
+        all_df.append(df)
 
     if len(all_df) > 0:
         units_table = pd.concat(all_df, axis=1)

From 6cf86f958331dc7965206568b0cf4e9b0772149d Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Sat, 18 Jan 2025 17:31:54 +0100
Subject: [PATCH 333/344] Fix tests and warning

---
 src/spikeinterface/widgets/sorting_summary.py |  2 +-
 .../widgets/tests/test_widgets.py             | 25 ++++++++++++++-----
 .../widgets/utils_sortingview.py              |  6 ++---
 3 files changed, 22 insertions(+), 11 deletions(-)

diff --git a/src/spikeinterface/widgets/sorting_summary.py b/src/spikeinterface/widgets/sorting_summary.py
index 8587830862..8eada29b0e 100644
--- a/src/spikeinterface/widgets/sorting_summary.py
+++ b/src/spikeinterface/widgets/sorting_summary.py
@@ -16,7 +16,7 @@
 from ..core import SortingAnalyzer
 
 
-_default_displayed_unit_properties = ["firing_rate", "num_spikes", "x", "y", "amplitude", "snr", "rp_violation"]
+_default_displayed_unit_properties = ["firing_rate", "num_spikes", "x", "y", "amplitude_median", "snr", "rp_violation"]
 
 
 class SortingSummaryWidget(BaseWidget):
diff --git a/src/spikeinterface/widgets/tests/test_widgets.py b/src/spikeinterface/widgets/tests/test_widgets.py
index b723a7ca9f..d5ffec6dba 100644
--- a/src/spikeinterface/widgets/tests/test_widgets.py
+++ b/src/spikeinterface/widgets/tests/test_widgets.py
@@ -73,7 +73,9 @@ def setUpClass(cls):
             spike_amplitudes=dict(),
             unit_locations=dict(),
             spike_locations=dict(),
-            quality_metrics=dict(metric_names=["snr", "isi_violation", "num_spikes", "amplitude_cutoff"]),
+            quality_metrics=dict(
+                metric_names=["snr", "isi_violation", "num_spikes", "firing_rate", "amplitude_cutoff"]
+            ),
             template_metrics=dict(),
             correlograms=dict(),
             template_similarity=dict(),
@@ -531,18 +533,29 @@ def test_plot_sorting_summary(self):
         possible_backends = list(sw.SortingSummaryWidget.get_possible_backends())
         for backend in possible_backends:
             if backend not in self.skip_backends:
-                sw.plot_sorting_summary(self.sorting_analyzer_dense, backend=backend, **self.backend_kwargs[backend])
-                sw.plot_sorting_summary(self.sorting_analyzer_sparse, backend=backend, **self.backend_kwargs[backend])
+                sw.plot_sorting_summary(
+                    self.sorting_analyzer_dense,
+                    displayed_unit_properties=[],
+                    backend=backend,
+                    **self.backend_kwargs[backend],
+                )
+                sw.plot_sorting_summary(
+                    self.sorting_analyzer_sparse,
+                    displayed_unit_properties=[],
+                    backend=backend,
+                    **self.backend_kwargs[backend],
+                )
                 sw.plot_sorting_summary(
                     self.sorting_analyzer_sparse,
                     sparsity=self.sparsity_strict,
+                    displayed_unit_properties=[],
                     backend=backend,
                     **self.backend_kwargs[backend],
                 )
-                # add unit_properties
+                # select unit_properties
                 sw.plot_sorting_summary(
                     self.sorting_analyzer_sparse,
-                    unit_table_properties=["firing_rate", "snr"],
+                    displayed_unit_properties=["firing_rate", "snr"],
                     backend=backend,
                     **self.backend_kwargs[backend],
                 )
@@ -550,7 +563,7 @@ def test_plot_sorting_summary(self):
                 with self.assertWarns(UserWarning):
                     sw.plot_sorting_summary(
                         self.sorting_analyzer_sparse,
-                        unit_table_properties=["missing_property"],
+                        displayed_unit_properties=["missing_property"],
                         backend=backend,
                         **self.backend_kwargs[backend],
                     )
diff --git a/src/spikeinterface/widgets/utils_sortingview.py b/src/spikeinterface/widgets/utils_sortingview.py
index 451b1d145e..d594414287 100644
--- a/src/spikeinterface/widgets/utils_sortingview.py
+++ b/src/spikeinterface/widgets/utils_sortingview.py
@@ -72,6 +72,8 @@ def generate_unit_table_view(
         # keep only selected columns
         unit_properties = np.array(unit_properties)
         keep = np.isin(unit_properties, units_tables.columns)
+        if sum(keep) < len(unit_properties):
+            warn(f"Some unit properties are not in the sorting: {unit_properties[~keep]}")
         unit_properties = unit_properties[keep]
         units_tables = units_tables.loc[:, unit_properties]
 
@@ -79,8 +81,6 @@ def generate_unit_table_view(
 
         ut_columns = []
         for col in unit_properties:
-            if col not in units_tables.columns:
-                continue
             values = units_tables[col].to_numpy()
             if values.dtype.kind in dtype_convertor:
                 txt_dtype = dtype_convertor[values.dtype.kind]
@@ -90,8 +90,6 @@ def generate_unit_table_view(
         for unit_index, unit_id in enumerate(sorting.unit_ids):
             row_values = {}
             for col in unit_properties:
-                if col not in units_tables.columns:
-                    continue
                 values = units_tables[col].to_numpy()
                 if values.dtype.kind in dtype_convertor:
                     value = values[unit_index]

From dafed8030bd1911d189f2196e8ea15f2a633a675 Mon Sep 17 00:00:00 2001
From: Charlie Windolf <charliexwindolf@gmail.com>
Date: Mon, 20 Jan 2025 14:24:28 -0500
Subject: [PATCH 334/344] Fix channels bug in average_across_direction, and add
 a test

---
 .../preprocessing/average_across_direction.py              | 2 +-
 .../preprocessing/tests/test_average_across_direction.py   | 7 +++++++
 2 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/src/spikeinterface/preprocessing/average_across_direction.py b/src/spikeinterface/preprocessing/average_across_direction.py
index ee2083d3c4..e74f5eaa8f 100644
--- a/src/spikeinterface/preprocessing/average_across_direction.py
+++ b/src/spikeinterface/preprocessing/average_across_direction.py
@@ -132,7 +132,7 @@ def get_traces(self, start_frame, end_frame, channel_indices):
         # now, divide by the number of channels at that position
         traces /= self.n_chans_each_pos
 
-        return traces
+        return traces[:, channel_indices]
 
 
 # function for API
diff --git a/src/spikeinterface/preprocessing/tests/test_average_across_direction.py b/src/spikeinterface/preprocessing/tests/test_average_across_direction.py
index dc3edc3b1d..c0965d8e51 100644
--- a/src/spikeinterface/preprocessing/tests/test_average_across_direction.py
+++ b/src/spikeinterface/preprocessing/tests/test_average_across_direction.py
@@ -37,6 +37,13 @@ def test_average_across_direction():
     assert np.all(geom_avgy[:2, 0] == 0)
     assert np.all(geom_avgy[2, 0] == 1.5)
 
+    # test with channel ids
+    # use chans at y in (1, 2)
+    traces = rec_avgy.get_traces(channel_ids=["0-1", "2-3"])
+    assert traces.shape == (100, 2)
+    assert np.all(traces[:, 0] == 0.5)
+    assert np.all(traces[:, 1] == 2.5)
+
     # test averaging across x
     rec_avgx = average_across_direction(rec, direction="x")
     traces = rec_avgx.get_traces()

From 6b5083732d92cbee0d0631a1459ffc1c2f58ec2f Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Tue, 21 Jan 2025 10:38:33 +0000
Subject: [PATCH 335/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/core/waveform_tools.py | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/spikeinterface/core/waveform_tools.py b/src/spikeinterface/core/waveform_tools.py
index 8228932785..76a1289711 100644
--- a/src/spikeinterface/core/waveform_tools.py
+++ b/src/spikeinterface/core/waveform_tools.py
@@ -301,9 +301,8 @@ def _init_worker_distribute_buffers(
         from spikeinterface.core import load
 
         recording = load(recording)
-        
-    worker_dict["recording"] = recording
 
+    worker_dict["recording"] = recording
 
     if mode == "memmap":
         # in memmap mode we have the "too many open file" problem with linux

From f4c2480538a4331b5eaf9ec665a3ab26ba549737 Mon Sep 17 00:00:00 2001
From: Samuel Garcia <sam.garcia.die@gmail.com>
Date: Tue, 21 Jan 2025 15:19:02 +0100
Subject: [PATCH 336/344] Remove the glonals warnings for job_kwargs when
 n_jobs=1. More informative progresse bar. darwin default job_kwargs

---
 src/spikeinterface/core/job_tools.py          | 45 ++++++++++---------
 src/spikeinterface/core/tests/test_globals.py |  8 ----
 .../core/tests/test_job_tools.py              |  1 -
 3 files changed, 25 insertions(+), 29 deletions(-)

diff --git a/src/spikeinterface/core/job_tools.py b/src/spikeinterface/core/job_tools.py
index ed8a26683c..27cf8a6d8f 100644
--- a/src/spikeinterface/core/job_tools.py
+++ b/src/spikeinterface/core/job_tools.py
@@ -69,10 +69,23 @@ def get_best_job_kwargs():
     n_cpu = os.cpu_count()
 
     if platform.system() == "Linux":
-        # maybe we should test this more but with linux the fork is still faster than threading
         pool_engine = "process"
         mp_context = "fork"
 
+    elif platform.system() == "Darwin":
+        pool_engine = "process"
+        mp_context = "spawn"
+
+    else:  # windows
+        # on windows and macos the fork is forbidden and process+spwan is super slow at startup
+        # so let's go to threads
+        pool_engine = "thread"
+        mp_context = None
+        n_jobs = n_cpu
+        max_threads_per_worker = 1
+
+    if platform.system() in ("Linux", "Darwin"):
+        # here we try to balance between the number of workers (n_jobs) and the number of sub thread
         # this is totally empirical but this is a good start
         if n_cpu <= 16:
             # for small n_cpu let's make many process
@@ -83,14 +96,6 @@ def get_best_job_kwargs():
             n_cpu = int(n_cpu / 4)
             max_threads_per_worker = 8
 
-    else:  # windows and mac
-        # on windows and macos the fork is forbidden and process+spwan is super slow at startup
-        # so let's go to threads
-        pool_engine = "thread"
-        mp_context = None
-        n_jobs = n_cpu
-        max_threads_per_worker = 1
-
     return dict(
         pool_engine=pool_engine,
         mp_context=mp_context,
@@ -151,14 +156,14 @@ def fix_job_kwargs(runtime_job_kwargs):
     n_jobs = max(n_jobs, 1)
     job_kwargs["n_jobs"] = min(n_jobs, os.cpu_count())
 
-    if "n_jobs" not in runtime_job_kwargs and job_kwargs["n_jobs"] == 1 and not is_set_global_job_kwargs_set():
-        warnings.warn(
-            "`n_jobs` is not set so parallel processing is disabled! "
-            "To speed up computations, it is recommended to set n_jobs either "
-            "globally (with the `spikeinterface.set_global_job_kwargs()` function) or "
-            "locally (with the `n_jobs` argument). Use `spikeinterface.set_global_job_kwargs?` "
-            "for more information about job_kwargs."
-        )
+    # if "n_jobs" not in runtime_job_kwargs and job_kwargs["n_jobs"] == 1 and not is_set_global_job_kwargs_set():
+    #     warnings.warn(
+    #         "`n_jobs` is not set so parallel processing is disabled! "
+    #         "To speed up computations, it is recommended to set n_jobs either "
+    #         "globally (with the `spikeinterface.set_global_job_kwargs()` function) or "
+    #         "locally (with the `n_jobs` argument). Use `spikeinterface.set_global_job_kwargs?` "
+    #         "for more information about job_kwargs."
+    #     )
 
     return job_kwargs
 
@@ -465,7 +470,7 @@ def run(self, recording_slices=None):
 
         if self.n_jobs == 1:
             if self.progress_bar:
-                recording_slices = tqdm(recording_slices, desc=self.job_name, total=len(recording_slices))
+                recording_slices = tqdm(recording_slices, desc=f"{self.job_name} (no parallelization)", total=len(recording_slices))
 
             worker_dict = self.init_func(*self.init_args)
             if self.need_worker_index:
@@ -510,7 +515,7 @@ def run(self, recording_slices=None):
                     results = executor.map(process_function_wrapper, recording_slices)
 
                     if self.progress_bar:
-                        results = tqdm(results, desc=self.job_name, total=len(recording_slices))
+                        results = tqdm(results, desc=f"{self.job_name} (workers: {n_jobs} processes)", total=len(recording_slices))
 
                     for res in results:
                         if self.handle_returns:
@@ -528,7 +533,7 @@ def run(self, recording_slices=None):
                 if self.progress_bar:
                     # here the tqdm threading do not work (maybe collision) so we need to create a pbar
                     # before thread spawning
-                    pbar = tqdm(desc=self.job_name, total=len(recording_slices))
+                    pbar = tqdm(desc=f"{self.job_name} (workers: {n_jobs} threads)", total=len(recording_slices))
 
                 if self.need_worker_index:
                     lock = threading.Lock()
diff --git a/src/spikeinterface/core/tests/test_globals.py b/src/spikeinterface/core/tests/test_globals.py
index 3f86558303..a2633f5e1d 100644
--- a/src/spikeinterface/core/tests/test_globals.py
+++ b/src/spikeinterface/core/tests/test_globals.py
@@ -46,10 +46,6 @@ def test_global_job_kwargs():
     )
     global_job_kwargs = get_global_job_kwargs()
 
-    # test warning when not setting n_jobs and calling fix_job_kwargs
-    with pytest.warns(UserWarning):
-        job_kwargs_split = fix_job_kwargs({})
-
     assert global_job_kwargs == dict(
         pool_engine="thread",
         n_jobs=1,
@@ -61,10 +57,6 @@ def test_global_job_kwargs():
     set_global_job_kwargs(**job_kwargs)
     assert get_global_job_kwargs() == job_kwargs
 
-    # after setting global job kwargs, fix_job_kwargs should not raise a warning
-    with warnings.catch_warnings():
-        warnings.simplefilter("error")
-        job_kwargs_split = fix_job_kwargs({})
 
     # test updating only one field
     partial_job_kwargs = dict(n_jobs=2)
diff --git a/src/spikeinterface/core/tests/test_job_tools.py b/src/spikeinterface/core/tests/test_job_tools.py
index 88d52ebb1f..b0c169890c 100644
--- a/src/spikeinterface/core/tests/test_job_tools.py
+++ b/src/spikeinterface/core/tests/test_job_tools.py
@@ -283,7 +283,6 @@ def test_get_best_job_kwargs():
 # def quick_becnhmark():
 #     # keep this commented do not remove
 
-
 #     from spikeinterface.generation import generate_drifting_recording
 #     from spikeinterface.sortingcomponents.peak_detection import detect_peaks
 #     from spikeinterface import get_noise_levels

From 760538b50a30497e0879650953ed9823006367be Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Tue, 21 Jan 2025 14:20:00 +0000
Subject: [PATCH 337/344] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/spikeinterface/core/job_tools.py          | 8 ++++++--
 src/spikeinterface/core/tests/test_globals.py | 1 -
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/src/spikeinterface/core/job_tools.py b/src/spikeinterface/core/job_tools.py
index 27cf8a6d8f..19edab195f 100644
--- a/src/spikeinterface/core/job_tools.py
+++ b/src/spikeinterface/core/job_tools.py
@@ -470,7 +470,9 @@ def run(self, recording_slices=None):
 
         if self.n_jobs == 1:
             if self.progress_bar:
-                recording_slices = tqdm(recording_slices, desc=f"{self.job_name} (no parallelization)", total=len(recording_slices))
+                recording_slices = tqdm(
+                    recording_slices, desc=f"{self.job_name} (no parallelization)", total=len(recording_slices)
+                )
 
             worker_dict = self.init_func(*self.init_args)
             if self.need_worker_index:
@@ -515,7 +517,9 @@ def run(self, recording_slices=None):
                     results = executor.map(process_function_wrapper, recording_slices)
 
                     if self.progress_bar:
-                        results = tqdm(results, desc=f"{self.job_name} (workers: {n_jobs} processes)", total=len(recording_slices))
+                        results = tqdm(
+                            results, desc=f"{self.job_name} (workers: {n_jobs} processes)", total=len(recording_slices)
+                        )
 
                     for res in results:
                         if self.handle_returns:
diff --git a/src/spikeinterface/core/tests/test_globals.py b/src/spikeinterface/core/tests/test_globals.py
index a2633f5e1d..cc8ff10075 100644
--- a/src/spikeinterface/core/tests/test_globals.py
+++ b/src/spikeinterface/core/tests/test_globals.py
@@ -57,7 +57,6 @@ def test_global_job_kwargs():
     set_global_job_kwargs(**job_kwargs)
     assert get_global_job_kwargs() == job_kwargs
 
-
     # test updating only one field
     partial_job_kwargs = dict(n_jobs=2)
     set_global_job_kwargs(**partial_job_kwargs)

From 4f5024a0c9aa93c54183430ca506c21217a23b2a Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Tue, 21 Jan 2025 15:50:05 +0100
Subject: [PATCH 338/344] Add get_start_time/get_stop_time and use it for
 get_duration

---
 src/spikeinterface/core/baserecording.py | 82 ++++++++++++++++--------
 src/spikeinterface/core/loading.py       |  2 +-
 2 files changed, 58 insertions(+), 26 deletions(-)

diff --git a/src/spikeinterface/core/baserecording.py b/src/spikeinterface/core/baserecording.py
index fbdd1fa5ba..47f09c0e59 100644
--- a/src/spikeinterface/core/baserecording.py
+++ b/src/spikeinterface/core/baserecording.py
@@ -59,7 +59,7 @@ def __repr__(self):
         if num_segments > 1:
             samples_per_segment = [self.get_num_samples(segment_index) for segment_index in range(num_segments)]
             memory_per_segment_bytes = (self.get_memory_size(segment_index) for segment_index in range(num_segments))
-            durations = [self.get_duration(segment_index, use_times=False) for segment_index in range(num_segments)]
+            durations = [self.get_duration(segment_index) for segment_index in range(num_segments)]
 
             samples_per_segment_formated = [f"{samples:,}" for samples in samples_per_segment]
             durations_per_segment_formated = [convert_seconds_to_str(d) for d in durations]
@@ -95,7 +95,7 @@ def _repr_header(self):
         dtype = self.get_dtype()
 
         total_samples = self.get_total_samples()
-        total_duration = self.get_total_duration(use_times=False)
+        total_duration = self.get_total_duration()
         total_memory_size = self.get_total_memory_size()
 
         sf_hz = self.get_sampling_frequency()
@@ -216,7 +216,7 @@ def get_total_samples(self) -> int:
 
         return sum(samples_per_segment)
 
-    def get_duration(self, segment_index=None, use_times=True) -> float:
+    def get_duration(self, segment_index=None) -> float:
         """
         Returns the duration in seconds.
 
@@ -226,44 +226,27 @@ def get_duration(self, segment_index=None, use_times=True) -> float:
             The sample index to retrieve the duration for.
             For multi-segment objects, it is required, default: None
             With single segment recording returns the duration of the single segment
-        use_times : bool, default: True
-            If True, the duration is calculated using the time vector if available.
-            If False, the duration is calculated using the number of samples and the sampling frequency.
 
         Returns
         -------
         float
             The duration in seconds
         """
-        segment_index = self._check_segment_index(segment_index)
-
-        if self.has_time_vector(segment_index) and use_times:
-            times = self.get_times(segment_index)
-            segment_duration = times[-1] - times[0] + (1 / self.get_sampling_frequency())
-        else:
-            segment_num_samples = self.get_num_samples(segment_index=segment_index)
-            segment_duration = segment_num_samples / self.get_sampling_frequency()
-
+        segment_duration = (
+            self.get_stop_time(segment_index) - self.get_start_time(segment_index) + (1 / self.get_sampling_frequency())
+        )
         return segment_duration
 
-    def get_total_duration(self, use_times=True) -> float:
+    def get_total_duration(self) -> float:
         """
         Returns the total duration in seconds
 
-        Parameters
-        ----------
-        use_times : bool, default: True
-            If True, the duration is calculated using the time vector if available.
-            If False, the duration is calculated using the number of samples and the sampling frequency.
-
         Returns
         -------
         float
             The duration in seconds
         """
-        duration = sum(
-            [self.get_duration(segment_index, use_times) for segment_index in range(self.get_num_segments())]
-        )
+        duration = sum([self.get_duration(segment_index) for segment_index in range(self.get_num_segments())])
         return duration
 
     def get_memory_size(self, segment_index=None) -> int:
@@ -456,6 +439,40 @@ def get_times(self, segment_index=None) -> np.ndarray:
         times = rs.get_times()
         return times
 
+    def get_start_time(self, segment_index=None) -> float:
+        """Get the start time of the recording segment.
+
+        Parameters
+        ----------
+        segment_index : int or None, default: None
+            The segment index (required for multi-segment)
+
+        Returns
+        -------
+        float
+            The start time in seconds
+        """
+        segment_index = self._check_segment_index(segment_index)
+        rs = self._recording_segments[segment_index]
+        return rs.get_start_time()
+
+    def get_stop_time(self, segment_index=None) -> float:
+        """Get the stop time of the recording segment.
+
+        Parameters
+        ----------
+        segment_index : int or None, default: None
+            The segment index (required for multi-segment)
+
+        Returns
+        -------
+        float
+            The stop time in seconds
+        """
+        segment_index = self._check_segment_index(segment_index)
+        rs = self._recording_segments[segment_index]
+        return rs.get_stop_time()
+
     def has_time_vector(self, segment_index=None):
         """Check if the segment of the recording has a time vector.
 
@@ -914,6 +931,21 @@ def get_times(self) -> np.ndarray:
                 time_vector += self.t_start
             return time_vector
 
+    def get_start_time(self) -> float:
+        if self.time_vector is not None:
+            return self.time_vector[0]
+        else:
+            return self.t_start if self.t_start is not None else 0.0
+
+    def get_stop_time(self) -> float:
+        if self.time_vector is not None:
+            return self.time_vector[-1]
+        else:
+            t_stop = self.get_num_samples() / self.sampling_frequency
+            if self.t_start is not None:
+                t_stop += self.t_start
+            return t_stop
+
     def get_times_kwargs(self) -> dict:
         """
         Retrieves the timing attributes characterizing a RecordingSegment
diff --git a/src/spikeinterface/core/loading.py b/src/spikeinterface/core/loading.py
index 0afb0e85fb..c8dc44160e 100644
--- a/src/spikeinterface/core/loading.py
+++ b/src/spikeinterface/core/loading.py
@@ -104,7 +104,7 @@ def load(file_or_folder_or_dict, base_folder=None) -> BaseExtractor:
                 raise ValueError(error_msg)
         else:
             # remote case - zarr
-            if str(file_path).endswith(".zarr"):
+            if str(file_path).endswith(".zarr") or str(file_path).endswith(".zarr/"):
                 from .zarrextractors import read_zarr
 
                 extractor = read_zarr(file_path)

From 8a20f22e09a049cdbae79cd79ccc07cb289269b5 Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Tue, 21 Jan 2025 15:53:31 +0100
Subject: [PATCH 339/344] Fix precision/recall in hybrid example

---
 doc/how_to/benchmark_with_hybrid_recordings.rst     | 5 ++---
 examples/how_to/benchmark_with_hybrid_recordings.py | 3 ++-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/doc/how_to/benchmark_with_hybrid_recordings.rst b/doc/how_to/benchmark_with_hybrid_recordings.rst
index 9975bb1a4b..5121a69690 100644
--- a/doc/how_to/benchmark_with_hybrid_recordings.rst
+++ b/doc/how_to/benchmark_with_hybrid_recordings.rst
@@ -2531,9 +2531,8 @@ Although non of the sorters find all units perfectly, ``Kilosort2.5``,
 ``Kilosort4``, and ``SpyKING CIRCUS 2`` all find around 10-12 hybrid
 units with accuracy greater than 80%. ``Kilosort4`` has a better overall
 curve, being able to find almost all units with an accuracy above 50%.
-``Kilosort2.5`` performs well when looking at precision (finding all
-spikes in a hybrid unit), at the cost of lower recall (finding spikes
-when it shouldn’t).
+``Kilosort2.5`` performs well when looking at precision (not finding spikes
+when it shouldn’t), but it has a lower recall (finding all spikes in the ground truth).
 
 In this example, we showed how to:
 
diff --git a/examples/how_to/benchmark_with_hybrid_recordings.py b/examples/how_to/benchmark_with_hybrid_recordings.py
index abf6a25ff5..d983578797 100644
--- a/examples/how_to/benchmark_with_hybrid_recordings.py
+++ b/examples/how_to/benchmark_with_hybrid_recordings.py
@@ -276,7 +276,8 @@
 # From the performance plots, we can see that there is no clear "winner", but `Kilosort3` definitely performs worse than the other options.
 #
 # Although non of the sorters find all units perfectly, `Kilosort2.5`, `Kilosort4`, and `SpyKING CIRCUS 2` all find around 10-12 hybrid units with accuracy greater than 80%.
-# `Kilosort4` has a better overall curve, being able to find almost all units with an accuracy above 50%. `Kilosort2.5` performs well when looking at precision (finding all spikes in a hybrid unit), at the cost of lower recall (finding spikes when it shouldn't).
+# `Kilosort4` has a better overall curve, being able to find almost all units with an accuracy above 50%. `Kilosort2.5` performs well when looking at precision (not finding spikes
+# when it shouldn’t), but it has a lower recall (finding all spikes in the ground truth).
 #
 #
 # In this example, we showed how to:

From 3c6444b565e0de6d14fd741de2a93d149486d63c Mon Sep 17 00:00:00 2001
From: Alessio Buccino <alejoe9187@gmail.com>
Date: Tue, 21 Jan 2025 16:18:26 +0100
Subject: [PATCH 340/344] get_stop_time -> get_end_time and fix tests

---
 src/spikeinterface/core/baserecording.py | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/spikeinterface/core/baserecording.py b/src/spikeinterface/core/baserecording.py
index 47f09c0e59..3e7283090b 100644
--- a/src/spikeinterface/core/baserecording.py
+++ b/src/spikeinterface/core/baserecording.py
@@ -233,7 +233,7 @@ def get_duration(self, segment_index=None) -> float:
             The duration in seconds
         """
         segment_duration = (
-            self.get_stop_time(segment_index) - self.get_start_time(segment_index) + (1 / self.get_sampling_frequency())
+            self.get_end_time(segment_index) - self.get_start_time(segment_index) + (1 / self.get_sampling_frequency())
         )
         return segment_duration
 
@@ -456,7 +456,7 @@ def get_start_time(self, segment_index=None) -> float:
         rs = self._recording_segments[segment_index]
         return rs.get_start_time()
 
-    def get_stop_time(self, segment_index=None) -> float:
+    def get_end_time(self, segment_index=None) -> float:
         """Get the stop time of the recording segment.
 
         Parameters
@@ -471,7 +471,7 @@ def get_stop_time(self, segment_index=None) -> float:
         """
         segment_index = self._check_segment_index(segment_index)
         rs = self._recording_segments[segment_index]
-        return rs.get_stop_time()
+        return rs.get_end_time()
 
     def has_time_vector(self, segment_index=None):
         """Check if the segment of the recording has a time vector.
@@ -937,11 +937,11 @@ def get_start_time(self) -> float:
         else:
             return self.t_start if self.t_start is not None else 0.0
 
-    def get_stop_time(self) -> float:
+    def get_end_time(self) -> float:
         if self.time_vector is not None:
             return self.time_vector[-1]
         else:
-            t_stop = self.get_num_samples() / self.sampling_frequency
+            t_stop = (self.get_num_samples() - 1) / self.sampling_frequency
             if self.t_start is not None:
                 t_stop += self.t_start
             return t_stop

From 7bb12f086c6c86e68401858d1b5b76fe25cb0491 Mon Sep 17 00:00:00 2001
From: Charlie Windolf <charliexwindolf@gmail.com>
Date: Tue, 21 Jan 2025 11:26:04 -0500
Subject: [PATCH 341/344] Check for channel_indices is None

---
 src/spikeinterface/preprocessing/average_across_direction.py | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/spikeinterface/preprocessing/average_across_direction.py b/src/spikeinterface/preprocessing/average_across_direction.py
index e74f5eaa8f..88c5f7301a 100644
--- a/src/spikeinterface/preprocessing/average_across_direction.py
+++ b/src/spikeinterface/preprocessing/average_across_direction.py
@@ -132,7 +132,10 @@ def get_traces(self, start_frame, end_frame, channel_indices):
         # now, divide by the number of channels at that position
         traces /= self.n_chans_each_pos
 
-        return traces[:, channel_indices]
+        if channel_indices is not None:
+            traces = traces[:, channel_indices]
+
+        return traces
 
 
 # function for API

From bb1c11e90a9fa56bce826b6308574d416ec24921 Mon Sep 17 00:00:00 2001
From: Joe Ziminski <55797454+JoeZiminski@users.noreply.github.com>
Date: Thu, 23 Jan 2025 14:37:40 +0000
Subject: [PATCH 342/344] Fix dtype on time_range

---
 src/spikeinterface/widgets/traces.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/widgets/traces.py b/src/spikeinterface/widgets/traces.py
index f5dadc780f..f944a4a80e 100644
--- a/src/spikeinterface/widgets/traces.py
+++ b/src/spikeinterface/widgets/traces.py
@@ -145,7 +145,7 @@ def __init__(
         fs = rec0.get_sampling_frequency()
         if time_range is None:
             time_range = (t_start, t_start + 1.0)
-        time_range = np.array(time_range)
+        time_range = np.array(time_range, dtype=np.float64)
         if time_range[1] > t_end:
             warnings.warn(
                 "You have selected a time after the end of the segment. The range will be clipped to " f"{t_end}"

From f4912d9e538d47c901c32c43b45ca1d2d1af1d35 Mon Sep 17 00:00:00 2001
From: Garcia Samuel <sam.garcia.die@gmail.com>
Date: Thu, 23 Jan 2025 17:13:19 +0100
Subject: [PATCH 343/344] Merci pierre

---
 src/spikeinterface/core/job_tools.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/spikeinterface/core/job_tools.py b/src/spikeinterface/core/job_tools.py
index 19edab195f..38a08c0fab 100644
--- a/src/spikeinterface/core/job_tools.py
+++ b/src/spikeinterface/core/job_tools.py
@@ -93,7 +93,7 @@ def get_best_job_kwargs():
             max_threads_per_worker = 1
         else:
             # let's have fewer processes with more threads each
-            n_cpu = int(n_cpu / 4)
+            n_jobs = int(n_cpu / 4)
             max_threads_per_worker = 8
 
     return dict(

From ae19c2ab0c570988076e4a623d26eb7cf9e66b97 Mon Sep 17 00:00:00 2001
From: Pierre Yger <pierre.yger@gmail.com>
Date: Fri, 24 Jan 2025 15:59:07 +0100
Subject: [PATCH 344/344] Adding Hanning filtering for waveforms pipeline node

---
 .../sortingcomponents/clustering/circus.py    | 15 ++++--
 .../test_waveforms/test_hanning_filter.py     | 33 ++++++++++++
 .../waveforms/hanning_filter.py               | 50 +++++++++++++++++++
 3 files changed, 95 insertions(+), 3 deletions(-)
 create mode 100644 src/spikeinterface/sortingcomponents/tests/test_waveforms/test_hanning_filter.py
 create mode 100644 src/spikeinterface/sortingcomponents/waveforms/hanning_filter.py

diff --git a/src/spikeinterface/sortingcomponents/clustering/circus.py b/src/spikeinterface/sortingcomponents/clustering/circus.py
index bc173a6ff0..884e4cace8 100644
--- a/src/spikeinterface/sortingcomponents/clustering/circus.py
+++ b/src/spikeinterface/sortingcomponents/clustering/circus.py
@@ -20,6 +20,7 @@
 from spikeinterface.core.recording_tools import get_noise_levels, get_channel_distances
 from spikeinterface.sortingcomponents.peak_selection import select_peaks
 from spikeinterface.sortingcomponents.waveforms.temporal_pca import TemporalPCAProjection
+from spikeinterface.sortingcomponents.waveforms.hanning_filter import HanningFilter
 from spikeinterface.core.template import Templates
 from spikeinterface.core.sparsity import compute_sparsity
 from spikeinterface.sortingcomponents.tools import remove_empty_templates
@@ -101,6 +102,12 @@ def main_function(cls, recording, peaks, params, job_kwargs=dict()):
         valid = np.argmax(np.abs(wfs), axis=1) == nbefore
         wfs = wfs[valid]
 
+        # Perform Hanning filtering
+        hanning_before = np.hanning(2 * nbefore)
+        hanning_after = np.hanning(2 * nafter)
+        hanning = np.concatenate((hanning_before[:nbefore], hanning_after[nafter:]))
+        wfs *= hanning
+
         from sklearn.decomposition import TruncatedSVD
 
         tsvd = TruncatedSVD(params["n_svd"][0])
@@ -134,11 +141,13 @@ def main_function(cls, recording, peaks, params, job_kwargs=dict()):
             radius_um=radius_um,
         )
 
-        node2 = TemporalPCAProjection(
-            recording, parents=[node0, node1], return_output=True, model_folder_path=model_folder
+        node2 = HanningFilter(recording, parents=[node0, node1], return_output=False)
+
+        node3 = TemporalPCAProjection(
+            recording, parents=[node0, node2], return_output=True, model_folder_path=model_folder
         )
 
-        pipeline_nodes = [node0, node1, node2]
+        pipeline_nodes = [node0, node1, node2, node3]
 
         if len(params["recursive_kwargs"]) == 0:
             from sklearn.decomposition import PCA
diff --git a/src/spikeinterface/sortingcomponents/tests/test_waveforms/test_hanning_filter.py b/src/spikeinterface/sortingcomponents/tests/test_waveforms/test_hanning_filter.py
new file mode 100644
index 0000000000..1b006af429
--- /dev/null
+++ b/src/spikeinterface/sortingcomponents/tests/test_waveforms/test_hanning_filter.py
@@ -0,0 +1,33 @@
+import pytest
+
+
+from spikeinterface.sortingcomponents.waveforms.hanning_filter import HanningFilter
+
+from spikeinterface.core.node_pipeline import (
+    PeakRetriever,
+    ExtractDenseWaveforms,
+    run_node_pipeline,
+)
+
+
+def test_hanning_filter(generated_recording, detected_peaks, chunk_executor_kwargs):
+    recording = generated_recording
+    peaks = detected_peaks
+
+    # Parameters
+    ms_before = 1.0
+    ms_after = 1.0
+
+    # Node initialization
+    peak_retriever = PeakRetriever(recording, peaks)
+
+    extract_waveforms = ExtractDenseWaveforms(
+        recording=recording, parents=[peak_retriever], ms_before=ms_before, ms_after=ms_after, return_output=True
+    )
+
+    hanning_filter = HanningFilter(recording=recording, parents=[peak_retriever, extract_waveforms])
+    pipeline_nodes = [peak_retriever, extract_waveforms, hanning_filter]
+
+    # Extract projected waveforms and compare
+    waveforms, denoised_waveforms = run_node_pipeline(recording, nodes=pipeline_nodes, job_kwargs=chunk_executor_kwargs)
+    assert waveforms.shape == denoised_waveforms.shape
diff --git a/src/spikeinterface/sortingcomponents/waveforms/hanning_filter.py b/src/spikeinterface/sortingcomponents/waveforms/hanning_filter.py
new file mode 100644
index 0000000000..e5d4962997
--- /dev/null
+++ b/src/spikeinterface/sortingcomponents/waveforms/hanning_filter.py
@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+
+from typing import List, Optional
+import numpy as np
+from spikeinterface.core import BaseRecording
+from spikeinterface.core.node_pipeline import PipelineNode, WaveformsNode, find_parent_of_type
+
+
+class HanningFilter(WaveformsNode):
+    """
+    Hanning Filtering to remove border effects while extracting waveforms
+
+    Parameters
+    ----------
+    recording: BaseRecording
+        The recording extractor object
+    return_output: bool, default: True
+        Whether to return output from this node
+    parents: list of PipelineNodes, default: None
+        The parent nodes of this node
+    """
+
+    def __init__(
+        self,
+        recording: BaseRecording,
+        return_output: bool = True,
+        parents: Optional[List[PipelineNode]] = None,
+    ):
+        waveform_extractor = find_parent_of_type(parents, WaveformsNode)
+        if waveform_extractor is None:
+            raise TypeError(f"HanningFilter should have a single {WaveformsNode.__name__} in its parents")
+
+        super().__init__(
+            recording,
+            waveform_extractor.ms_before,
+            waveform_extractor.ms_after,
+            return_output=return_output,
+            parents=parents,
+        )
+
+        hanning_before = np.hanning(2 * self.nbefore)
+        hanning_after = np.hanning(2 * self.nafter)
+        hanning = np.concatenate((hanning_before[: self.nbefore], hanning_after[self.nafter :]))
+        self.hanning = hanning[:, None]
+        self._kwargs.update(dict())
+
+    def compute(self, traces, peaks, waveforms):
+        denoised_waveforms = waveforms * self.hanning
+        return denoised_waveforms