Use ProbeGroup object instead of contact_vector property and set_probe/probegroup from select_channels_with_probe/probegroup

.github/scripts/create_probe_compat_fixtures.py

@@ -0,0 +1,137 @@
+#!/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.
+
+Note: we use `in_place=True` since a bug (fixed in #4300) prevented probes_info to be properly
+saved as annotations in the probegroup when using `in_place=False` in spikeinterface 0.104.*.
+"""
+
+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.set_probe(probe, in_place=True)
+
+rec_single_bin = rec_single.save(folder=str(OUTPUT_DIR / "single_probe_binary"))
+rec_single_zarr = rec_single.save(folder=str(OUTPUT_DIR / "single_probe.zarr"), format="zarr")
+rec_single_bin.dump_to_json(str(OUTPUT_DIR / "single_probe.json"))
+rec_single_bin.dump_to_pickle(str(OUTPUT_DIR / "single_probe.pkl"))
+
+# -----------------------------------------------------------------------
+# 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.set_probegroup(pg, in_place=True)
+
+rec_two_bin = rec_two.save(folder=str(OUTPUT_DIR / "two_probe_binary"))
+rec_two_zarr = rec_two.save(folder=str(OUTPUT_DIR / "two_probe.zarr"), format="zarr")
+rec_two_bin.dump_to_json(str(OUTPUT_DIR / "two_probe.json"))
+rec_two_bin.dump_to_pickle(str(OUTPUT_DIR / "two_probe.pkl"))
+
+# -----------------------------------------------------------------------
+# 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.set_probe(probe_sh, in_place=True)
+
+rec_sh_bin = rec_sh.save(folder=str(OUTPUT_DIR / "shuffled_probe_binary"))
+rec_sh_zarr = rec_sh.save(folder=str(OUTPUT_DIR / "shuffled_probe.zarr"), format="zarr")
+rec_sh_bin.dump_to_json(str(OUTPUT_DIR / "shuffled_probe.json"))
+rec_sh_bin.dump_to_pickle(str(OUTPUT_DIR / "shuffled_probe.pkl"))
+
+print(f"Fixtures written to: {OUTPUT_DIR.resolve()}")
+
+# -----------------------------------------------------------------------
+# Fixture 4: two probes with interleaved device_channel_indices
+# -----------------------------------------------------------------------
+n = 8
+probe_A = generate_linear_probe(num_elec=n, 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)])
+probe_A.set_device_channel_indices(np.arange(0, 2 * n, 2))  # even indices
+probe_A.create_auto_shape()
+
+probe_B = generate_linear_probe(num_elec=n, 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)])
+probe_B.set_device_channel_indices(np.arange(1, 2 * n, 2))  # odd indices
+probe_B.create_auto_shape()
+
+pg = ProbeGroup()
+pg.add_probe(probe_A)
+pg.add_probe(probe_B)
+
+n_total = 2 * n
+traces2 = np.arange(1000 * n_total, dtype="int16").reshape(1000, n_total)
+rec_two_inter = NumpyRecording([traces2], sampling_frequency=30000.0)
+rec_two_inter.set_probegroup(pg, in_place=True)
+
+rec_two_inter_bin = rec_two_inter.save(folder=str(OUTPUT_DIR / "two_probe_interleaved_binary"))
+rec_two_inter_zarr = rec_two_inter.save(folder=str(OUTPUT_DIR / "two_probe_interleaved.zarr"), format="zarr")
+rec_two_inter_bin.dump_to_json(str(OUTPUT_DIR / "two_probe_interleaved.json"))
+rec_two_inter_bin.dump_to_pickle(str(OUTPUT_DIR / "two_probe_interleaved.pkl"))

.github/workflows/probe_backward_compat.yml

@@ -0,0 +1,58 @@
+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 ${{ matrix.si-version }} → current)
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        si-version:
+          - '0.102.*'
+          - '0.103.*'
+          - '0.104.*'
+    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 ${{ matrix.si-version }} to create fixtures
+        run: uv pip install --system "spikeinterface[core]==${{ matrix.si-version }}"
+
+      - 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]