Backwards compatibility for sync stream in OpenEphysBinary (#3839)

Author: h-mayorquin

src/spikeinterface/extractors/neoextractors/openephys.py

@@ -139,21 +139,47 @@ class OpenEphysBinaryRecordingExtractor(NeoBaseRecordingExtractor):
     all_annotations : bool, default: False
         Load exhaustively all annotation from neo
 
+    Notes
+    -----
+    If no stream is explicitly specified and there are exactly two streams (neural data and
+    synchronization data), the neural data stream will be automatically selected.
     """
 
     NeoRawIOClass = "OpenEphysBinaryRawIO"
 
     def __init__(
         self,
-        folder_path,
-        load_sync_channel=False,
-        load_sync_timestamps=False,
-        experiment_names=None,
-        stream_id=None,
-        stream_name=None,
-        block_index=None,
-        all_annotations=False,
+        folder_path: str | Path,
+        load_sync_channel: bool = False,
+        load_sync_timestamps: bool = False,
+        experiment_names: str | list | None = None,
+        stream_id: str = None,
+        stream_name: str = None,
+        block_index: int = None,
+        all_annotations: bool = False,
     ):
+
+        if load_sync_channel:
+            import warnings
+
+            warning_message = (
+                "OpenEphysBinaryRecordingExtractor: load_sync_channel is deprecated and will"
+                "be removed in version 0.104, use the stream_name or stream_id to load the sync stream if needed"
+            )
+            warnings.warn(warning_message, DeprecationWarning, stacklevel=2)
+
+        stream_is_not_specified = stream_name is None and stream_id is None
+        if stream_is_not_specified:
+            available_stream_names, _ = self.get_streams(folder_path, load_sync_channel, experiment_names)
+
+            # Auto-select neural data stream when there are exactly two streams (neural + sync)
+            # and no stream was explicitly specified
+            if len(available_stream_names) == 2:
+                has_sync_stream = any("SYNC" in stream for stream in available_stream_names)
+                if has_sync_stream:
+                    neural_stream_name = next(stream for stream in available_stream_names if "SYNC" not in stream)
+                    stream_name = neural_stream_name
+
         neo_kwargs = self.map_to_neo_kwargs(folder_path, load_sync_channel, experiment_names)
         NeoBaseRecordingExtractor.__init__(
             self,
@@ -163,95 +189,104 @@ def __init__(
             all_annotations=all_annotations,
             **neo_kwargs,
         )
-        # get streams to find correct probe
-        stream_names, stream_ids = self.get_streams(folder_path, load_sync_channel, experiment_names)
-        if stream_name is None and stream_id is None:
-            stream_name = stream_names[0]
-        elif stream_name is None:
-            stream_name = stream_names[stream_ids.index(stream_id)]
-
-        # find settings file
-        if "#" in stream_name:
-            record_node, oe_stream = stream_name.split("#")
-        else:
-            record_node = ""
-            oe_stream = stream_name
-        exp_ids = sorted(list(self.neo_reader.folder_structure[record_node]["experiments"].keys()))
-        if block_index is None:
-            exp_id = exp_ids[0]
-        else:
-            exp_id = exp_ids[block_index]
-        rec_ids = sorted(
-            list(self.neo_reader.folder_structure[record_node]["experiments"][exp_id]["recordings"].keys())
-        )
-
-        # do not load probe for NIDQ stream or if load_sync_channel is True
-        if "NI-DAQmx" not in stream_name and not load_sync_channel:
-            settings_file = self.neo_reader.folder_structure[record_node]["experiments"][exp_id]["settings_file"]
 
-            if Path(settings_file).is_file():
-                probe = probeinterface.read_openephys(
-                    settings_file=settings_file, stream_name=stream_name, raise_error=False
-                )
+        stream_is_sync = "SYNC" in self.stream_name
+        if not stream_is_sync:
+            # get streams to find correct probe
+            stream_names, stream_ids = self.get_streams(folder_path, load_sync_channel, experiment_names)
+            if stream_name is None and stream_id is None:
+                stream_name = stream_names[0]
+            elif stream_name is None:
+                stream_name = stream_names[stream_ids.index(stream_id)]
+
+            # find settings file
+            if "#" in stream_name:
+                record_node, oe_stream = stream_name.split("#")
+            else:
+                record_node = ""
+                oe_stream = stream_name
+            exp_ids = sorted(list(self.neo_reader.folder_structure[record_node]["experiments"].keys()))
+            if block_index is None:
+                exp_id = exp_ids[0]
             else:
-                probe = None
+                exp_id = exp_ids[block_index]
+            rec_ids = sorted(
+                list(self.neo_reader.folder_structure[record_node]["experiments"][exp_id]["recordings"].keys())
+            )
 
-            if probe is not None:
-                if probe.shank_ids is not None:
-                    self.set_probe(probe, in_place=True, group_mode="by_shank")
-                else:
-                    self.set_probe(probe, in_place=True)
-
-                # this handles a breaking change in probeinterface after v0.2.18
-                # in the new version, the Neuropixels model name is stored in the "model_name" annotation,
-                # rather than in the "probe_name" annotation
-                model_name = probe.annotations.get("model_name", None)
-                if model_name is None:
-                    model_name = probe.annotations["probe_name"]
-
-                # load num_channels_per_adc depending on probe type
-                if "2.0" in model_name:
-                    num_channels_per_adc = 16
-                    num_cycles_in_adc = 16
-                    total_channels = 384
-                else:  # NP1.0
-                    num_channels_per_adc = 12
-                    num_cycles_in_adc = 13 if "AP" in stream_name else 12
-                    total_channels = 384
-
-                # sample_shifts is generated from total channels (384) channels
-                # when only some channels are saved we need to slice this vector (like we do for the probe)
-                sample_shifts = get_neuropixels_sample_shifts(total_channels, num_channels_per_adc, num_cycles_in_adc)
-                if self.get_num_channels() != total_channels:
-                    # need slice because not all channel are saved
-                    chans = probeinterface.get_saved_channel_indices_from_openephys_settings(settings_file, oe_stream)
-                    # lets clip to 384 because this contains also the synchro channel
-                    chans = chans[chans < total_channels]
-                    sample_shifts = sample_shifts[chans]
-                self.set_property("inter_sample_shift", sample_shifts)
-
-        # load synchronized timestamps and set_times to recording
-        recording_folder = Path(folder_path) / record_node
-        stream_folders = []
-        for segment_index, rec_id in enumerate(rec_ids):
-            stream_folder = recording_folder / f"experiment{exp_id}" / f"recording{rec_id}" / "continuous" / oe_stream
-            stream_folders.append(stream_folder)
-            if load_sync_timestamps:
-                if (stream_folder / "sample_numbers.npy").is_file():
-                    # OE version>=v0.6
-                    sync_times = np.load(stream_folder / "timestamps.npy")
-                elif (stream_folder / "synchronized_timestamps.npy").is_file():
-                    # version<v0.6
-                    sync_times = np.load(stream_folder / "synchronized_timestamps.npy")
+            # do not load probe for NIDQ stream or if load_sync_channel is True
+            if "NI-DAQmx" not in stream_name and not load_sync_channel:
+                settings_file = self.neo_reader.folder_structure[record_node]["experiments"][exp_id]["settings_file"]
+
+                if Path(settings_file).is_file():
+                    probe = probeinterface.read_openephys(
+                        settings_file=settings_file, stream_name=stream_name, raise_error=False
+                    )
                 else:
-                    sync_times = None
-                try:
-                    self.set_times(times=sync_times, segment_index=segment_index, with_warning=False)
-                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
+                    probe = None
+
+                if probe is not None:
+                    if probe.shank_ids is not None:
+                        self.set_probe(probe, in_place=True, group_mode="by_shank")
+                    else:
+                        self.set_probe(probe, in_place=True)
+
+                    # this handles a breaking change in probeinterface after v0.2.18
+                    # in the new version, the Neuropixels model name is stored in the "model_name" annotation,
+                    # rather than in the "probe_name" annotation
+                    model_name = probe.annotations.get("model_name", None)
+                    if model_name is None:
+                        model_name = probe.annotations["probe_name"]
+
+                    # load num_channels_per_adc depending on probe type
+                    if "2.0" in model_name:
+                        num_channels_per_adc = 16
+                        num_cycles_in_adc = 16
+                        total_channels = 384
+                    else:  # NP1.0
+                        num_channels_per_adc = 12
+                        num_cycles_in_adc = 13 if "AP" in stream_name else 12
+                        total_channels = 384
+
+                    # sample_shifts is generated from total channels (384) channels
+                    # when only some channels are saved we need to slice this vector (like we do for the probe)
+                    sample_shifts = get_neuropixels_sample_shifts(
+                        total_channels, num_channels_per_adc, num_cycles_in_adc
+                    )
+                    if self.get_num_channels() != total_channels:
+                        # need slice because not all channel are saved
+                        chans = probeinterface.get_saved_channel_indices_from_openephys_settings(
+                            settings_file, oe_stream
+                        )
+                        # lets clip to 384 because this contains also the synchro channel
+                        chans = chans[chans < total_channels]
+                        sample_shifts = sample_shifts[chans]
+                    self.set_property("inter_sample_shift", sample_shifts)
+
+            # load synchronized timestamps and set_times to recording
+            recording_folder = Path(folder_path) / record_node
+            stream_folders = []
+            for segment_index, rec_id in enumerate(rec_ids):
+                stream_folder = (
+                    recording_folder / f"experiment{exp_id}" / f"recording{rec_id}" / "continuous" / oe_stream
+                )
+                stream_folders.append(stream_folder)
+                if load_sync_timestamps:
+                    if (stream_folder / "sample_numbers.npy").is_file():
+                        # OE version>=v0.6
+                        sync_times = np.load(stream_folder / "timestamps.npy")
+                    elif (stream_folder / "synchronized_timestamps.npy").is_file():
+                        # version<v0.6
+                        sync_times = np.load(stream_folder / "synchronized_timestamps.npy")
+                    else:
+                        sync_times = None
+                    try:
+                        self.set_times(times=sync_times, segment_index=segment_index, with_warning=False)
+                    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(
             dict(