Use ProbeGroup object instead of contact_vector property

.github/scripts/create_probe_compat_fixtures.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python
+"""
+Creates probe compatibility fixtures using the *currently installed* spikeinterface.
+
+Run this script with spikeinterface==0.104.* installed to produce the fixture
+files consumed by test_probe_backward_compat.py:
+
+    python create_probe_compat_fixtures.py [output_dir]
+
+If output_dir is omitted, fixtures are written to ./probe_compat_fixtures.
+"""
+
+import sys
+import shutil
+import numpy as np
+from pathlib import Path
+
+import spikeinterface
+
+print(f"Creating fixtures with spikeinterface {spikeinterface.__version__}")
+
+OUTPUT_DIR = Path(sys.argv[1]) if len(sys.argv) > 1 else Path("probe_compat_fixtures")
+if OUTPUT_DIR.exists():
+    shutil.rmtree(OUTPUT_DIR)
+OUTPUT_DIR.mkdir(parents=True)
+
+from probeinterface import generate_linear_probe, ProbeGroup
+from spikeinterface.core import NumpyRecording
+
+# -----------------------------------------------------------------------
+# Fixture 1: single probe, sequential device_channel_indices
+# -----------------------------------------------------------------------
+n = 8
+probe = generate_linear_probe(num_elec=n, ypitch=20.0)
+probe.annotate(name="test_probe", manufacturer="test_vendor")
+probe.set_contact_ids([f"e{i}" for i in range(n)])
+probe.set_device_channel_indices(np.arange(n))
+probe.create_auto_shape()
+
+traces = np.arange(1000 * n, dtype="int16").reshape(1000, n)
+rec_single = NumpyRecording([traces], sampling_frequency=30000.0)
+rec_single = rec_single.set_probe(probe)  # old API: in_place=False, returns new recording
+
+rec_single.save(folder=str(OUTPUT_DIR / "single_probe_binary"))
+rec_single.save(folder=str(OUTPUT_DIR / "single_probe.zarr"), format="zarr")
+
+# -----------------------------------------------------------------------
+# Fixture 2: two probes with per-probe name/manufacturer
+# -----------------------------------------------------------------------
+n_A, n_B = 8, 8
+probe_A = generate_linear_probe(num_elec=n_A, ypitch=20.0)
+probe_A.move([0.0, 0.0])
+probe_A.annotate(name="probe_A", manufacturer="vendor_X")
+probe_A.set_contact_ids([f"a{i}" for i in range(n_A)])
+probe_A.set_device_channel_indices(np.arange(n_A))
+probe_A.create_auto_shape()
+
+probe_B = generate_linear_probe(num_elec=n_B, ypitch=20.0)
+probe_B.move([500.0, 0.0])
+probe_B.annotate(name="probe_B", manufacturer="vendor_Y")
+probe_B.set_contact_ids([f"b{i}" for i in range(n_B)])
+probe_B.set_device_channel_indices(np.arange(n_A, n_A + n_B))
+probe_B.create_auto_shape()
+
+pg = ProbeGroup()
+pg.add_probe(probe_A)
+pg.add_probe(probe_B)
+
+n_total = n_A + n_B
+traces2 = np.arange(1000 * n_total, dtype="int16").reshape(1000, n_total)
+rec_two = NumpyRecording([traces2], sampling_frequency=30000.0)
+rec_two = rec_two.set_probegroup(pg)  # old API: in_place=False, returns new recording
+
+rec_two.save(folder=str(OUTPUT_DIR / "two_probe_binary"))
+rec_two.save(folder=str(OUTPUT_DIR / "two_probe.zarr"), format="zarr")
+
+# -----------------------------------------------------------------------
+# Fixture 3: probe with shuffled device_channel_indices
+# Verifies that the channel-reordering logic is preserved across versions.
+# -----------------------------------------------------------------------
+n = 8
+probe_sh = generate_linear_probe(num_elec=n, ypitch=20.0)
+probe_sh.annotate(name="shuffled_probe", manufacturer="shuffle_vendor")
+shuffled_dci = np.array([3, 0, 7, 1, 5, 2, 6, 4])  # permutation of 0..7
+probe_sh.set_device_channel_indices(shuffled_dci)
+
+# traces[:, j] corresponds to recording channel j, which after set_probe
+# is mapped to the contact whose dci equals j.
+traces3 = np.arange(1000 * n, dtype="int16").reshape(1000, n)
+rec_sh = NumpyRecording([traces3], sampling_frequency=30000.0)
+rec_sh = rec_sh.set_probe(probe_sh)  # old API
+
+rec_sh.save(folder=str(OUTPUT_DIR / "shuffled_probe_binary"))
+rec_sh.save(folder=str(OUTPUT_DIR / "shuffled_probe.zarr"), format="zarr")
+
+print(f"Fixtures written to: {OUTPUT_DIR.resolve()}")

.github/workflows/probe_backward_compat.yml

@@ -0,0 +1,51 @@
+name: Probe backward compatibility
+
+on:
+  pull_request:
+    types: [synchronize, opened, reopened]
+    branches:
+      - main
+    paths:
+      - 'src/spikeinterface/core/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  probe-backward-compat:
+    name: Probe compat (SI 0.104.* → current)
+    runs-on: ubuntu-latest
+    env:
+      SI_PROBE_COMPAT_FIXTURES_DIR: ${{ github.workspace }}/probe_compat_fixtures
+
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: '3.11'
+          enable-cache: false
+
+      # Step 1: install the OLD release and create fixtures.
+      # The fixture script uses the old in_place=False default (returns a new recording),
+      # saves to binary folder + JSON, and writes a known probe name/manufacturer/contact_ids.
+      - name: Install spikeinterface 0.104.* to create fixtures
+        run: uv pip install --system "spikeinterface[core]==0.104.*"
+
+      - name: Create compatibility fixtures with old version
+        run: python .github/scripts/create_probe_compat_fixtures.py "$SI_PROBE_COMPAT_FIXTURES_DIR"
+
+      # Step 2: install the NEW version from this PR source and run the load tests.
+      - name: Install new spikeinterface from source
+        run: uv pip install --system -e . --group test-core
+
+      - name: Run backward compatibility tests
+        run: pytest src/spikeinterface/core/tests/test_probe_backward_compat.py -v

doc/api.rst

@@ -16,6 +16,12 @@ spikeinterface.core
     .. automethod:: BaseRecording.dump_to_json
     .. automethod:: BaseRecording.dump_to_pickle
     .. automethod:: BaseRecording.remove_channels
+    .. automethod:: BaseRecording.set_probe
+    .. automethod:: BaseRecording.set_probegroup
+    .. automethod:: BaseRecording.reset_probe
+    .. automethod:: BaseRecording.select_channels_with_probe
+    .. automethod:: BaseRecording.select_channels_with_probegroup
+    .. automethod:: BaseRecording.split_by
     .. autoclass:: BaseSorting
         :members:
     .. automethod:: BaseSorting.save
@@ -25,6 +31,8 @@ spikeinterface.core
     .. automethod:: BaseSorting.dump
     .. automethod:: BaseSorting.dump_to_json
     .. automethod:: BaseSorting.dump_to_pickle
+    .. automethod:: BaseSorting.split_by
+    .. automethod:: BaseSorting.register_recording
     .. autoclass:: BaseSnippets
         :members:
     .. automethod:: BaseSnippets.save

doc/get_started/quickstart.rst

@@ -198,8 +198,9 @@ to set it *manually*.
 
 
 If your recording does not have a ``Probe``, you can set it using
-``set_probe``. Note: ``set_probe`` creates a copy of the recording with
-the new probe, rather than modifying the existing recording in place.
+``set_probe``. Note: ``set_probe`` modifies the recording in place. To
+get a new recording object with a subset of channels attached to a probe,
+use ``select_channels_with_probe``.
 There is more information
 `here <https://spikeinterface.readthedocs.io/en/latest/modules_gallery/core/plot_3_handle_probe_info.html>`__.
 

doc/modules/core.rst

@@ -522,12 +522,18 @@ The probe has 4 shanks, which can be loaded as separate groups (and spike sorted
     # add wiring
     probe.wiring_to_device('ASSY-156>RHD2164')
 
-    # set probe
-    recording_w_probe = recording.set_probe(probe)
-    # set probe with group info and return a new recording object
-    recording_w_probe = recording.set_probe(probe, group_mode="by_shank")
-    # set probe in place, ie, modify the current recording
-    recording.set_probe(probe, group_mode="by_shank", in_place=True)
+    # set probe (modifies the recording in place)
+    recording.set_probe(probe)
+    # set probe with group info derived from shank ids (in place)
+    recording.set_probe(probe, group_mode="by_shank")
+
+    # to get a *new* recording without modifying the original, use select_channels_with_probe
+    recording_w_probe = recording.select_channels_with_probe(probe)
+    recording_w_probe = recording.select_channels_with_probe(probe, group_mode="by_shank")
+
+    # multi-probe recordings use set_probegroup / select_channels_with_probegroup
+    recording.set_probegroup(probegroup)
+    recording_w_probegroup = recording.select_channels_with_probegroup(probegroup)
 
     # retrieve probe
     probe_from_recording = recording.get_probe()

examples/forhowto/plot_working_with_tetrodes.py

@@ -62,15 +62,15 @@
 # We can now attach the :code:`tetrode_group` to our recording. To check if this worked, we'll
 # plot the probe map
 
-recording_with_probe = recording.set_probegroup(tetrode_group)
-plot_probe_map(recording_with_probe)
+recording.set_probegroup(tetrode_group)
+plot_probe_map(recording)
 
 ##############################################################################
 # Looks good! Now that the recording is aware of the probe geometry, we can
 # begin a standard spike sorting pipeline. First, we can apply preprocessing.
 # Note that we apply this preprocessing on the entire bundle of tetrodes.
 
-preprocessed_recording = spre.bandpass_filter(recording_with_probe)
+preprocessed_recording = spre.bandpass_filter(recording)
 
 ##############################################################################
 # WARNING: a very common preprocessing step is to apply a common median

examples/get_started/quickstart.py

@@ -137,8 +137,8 @@
 # -
 
 # If your recording does not have a `Probe`, you can set it using `set_probe`.
-# Note: `set_probe` creates a copy of the recording with the new probe,
-# rather than modifying the existing recording in place.
+# Note: `set_probe` modifies the recording in place. To get a new recording
+# object with a subset of channels attached to a probe, use `select_channels_with_probe`.
 # There is more information [here](https://spikeinterface.readthedocs.io/en/latest/modules_gallery/core/plot_3_handle_probe_info.html).
 
 # Using the `spikeinterface.preprocessing` module, you can perform preprocessing on the recordings.

examples/tutorials/core/plot_1_recording_extractor.py

@@ -70,7 +70,7 @@
 probe.set_device_channel_indices(np.arange(7))
 
 # then we need to actually set the probe to the recording object
-recording = recording.set_probe(probe)
+recording.set_probe(probe)
 plot_probe(probe)
 
 ##############################################################################

examples/tutorials/core/plot_3_handle_probe_info.py

@@ -43,8 +43,8 @@
 print(other_probe)
 
 other_probe.set_device_channel_indices(np.arange(32))
-recording_2_shanks = recording.set_probe(other_probe, group_mode="by_shank")
-plot_probe(recording_2_shanks.get_probe())
+recording.set_probe(other_probe, group_mode="by_shank")
+plot_probe(recording.get_probe())
 
 ###############################################################################
 # Now let's check what we have loaded. The :code:`group_mode='by_shank'` automatically
@@ -53,11 +53,11 @@
 # We can access this information either as a dict with :code:`outputs='dict'` (default)
 # or as a list of recordings with :code:`outputs='list'`.
 
-print(recording_2_shanks)
-print(f'\nGroup Property: {recording_2_shanks.get_property("group")}\n')
+print(recording)
+print(f'\nGroup Property: {recording.get_property("group")}\n')
 
 # Here we split as a dict
-sub_recording_dict = recording_2_shanks.split_by(property="group", outputs='dict')
+sub_recording_dict = recording.split_by(property="group", outputs='dict')
 
 # Then we can pull out the individual sub-recordings
 sub_rec0 = sub_recording_dict[0]

src/spikeinterface/core/base.py

@@ -220,6 +220,14 @@ def id_to_index(self, id) -> int:
         return ind
 
     def annotate(self, **new_annotations) -> None:
+        """Adds annotations.
+
+        Parameters
+        ----------
+        **new_annotations : dict
+            Key-value pairs of annotations to add. If an annotation key already exists,
+            it will be overwritten.
+        """
         self._annotations.update(new_annotations)
 
     def set_annotation(self, annotation_key: str, value: Any, overwrite=False) -> None:
@@ -243,6 +251,24 @@ def set_annotation(self, annotation_key: str, value: Any, overwrite=False) -> No
             else:
                 raise ValueError(f"{annotation_key} is already an annotation key. Use 'overwrite=True' to overwrite it")
 
+    def delete_annotation(self, annotation_key: str) -> None:
+        """Deletes existing annotation.
+
+        Parameters
+        ----------
+        annotation_key : str
+            The annotation key to delete
+
+        Raises
+        ------
+        ValueError
+            If the annotation key does not exist
+        """
+        if annotation_key in self._annotations.keys():
+            del self._annotations[annotation_key]
+        else:
+            raise ValueError(f"{annotation_key} is not an annotation key")
+
     def get_preferred_mp_context(self):
         """
         Get the preferred context for multiprocessing.
@@ -441,6 +467,15 @@ def copy_metadata(
         if self._preferred_mp_context is not None:
             other._preferred_mp_context = self._preferred_mp_context
 
+        if not only_main:
+            self._extra_metadata_copy(other)
+
+    def _extra_metadata_copy(self, other: "BaseExtractor") -> None:
+        """
+        This is a hook to copy extra metadata that is not in the annotations/properties dict.
+        """
+        pass
+
     def to_dict(
         self,
         include_annotations: bool = False,
@@ -574,6 +609,8 @@ def to_dict(
                 folder_metadata = Path(folder_metadata).resolve().absolute().relative_to(relative_to)
             dump_dict["folder_metadata"] = str(folder_metadata)
 
+        self._extra_metadata_to_dict(dump_dict)
+
         return dump_dict
 
     @staticmethod
@@ -610,8 +647,6 @@ def load_metadata_from_folder(self, folder_metadata):
         # hack to load probe for recording
         folder_metadata = Path(folder_metadata)
 
-        self._extra_metadata_from_folder(folder_metadata)
-
         # load properties
         prop_folder = folder_metadata / "properties"
         if prop_folder.is_dir():
@@ -621,6 +656,8 @@ def load_metadata_from_folder(self, folder_metadata):
                     key = prop_file.stem
                     self.set_property(key, values)
 
+        self._extra_metadata_from_folder(folder_metadata)
+
     def save_metadata_to_folder(self, folder_metadata):
         self._extra_metadata_to_folder(folder_metadata)
 
@@ -862,6 +899,14 @@ def _extra_metadata_to_folder(self, folder):
         # This implemented in BaseRecording for probe
         pass
 
+    def _extra_metadata_from_dict(self, dump_dict):
+        # This implemented in BaseRecording for probe
+        pass
+
+    def _extra_metadata_to_dict(self, dump_dict):
+        # This implemented in BaseRecording for probe
+        pass
+
     def save(self, **kwargs) -> "BaseExtractor":
         """
         Save a SpikeInterface object.
@@ -997,10 +1042,10 @@ def save_to_folder(
         else:
             warnings.warn("The extractor is not serializable to file. The provenance will not be saved.")
 
-        self.save_metadata_to_folder(folder)
-
         # save data (done the subclass)
+        self.save_metadata_to_folder(folder)
         cached = self._save(folder=folder, verbose=verbose, **save_kwargs)
+        cached.load_metadata_from_folder(folder)
 
         # copy properties/
         self.copy_metadata(cached)
@@ -1155,6 +1200,8 @@ def _load_extractor_from_dict(dic) -> "BaseExtractor":
     for k, v in dic["properties"].items():
         extractor.set_property(k, v)
 
+    extractor._extra_metadata_from_dict(dic)
+
     return extractor