remove old function

Author: h-mayorquin

src/probeinterface/__init__.py

@@ -28,7 +28,6 @@
     parse_spikeglx_snsGeomMap,
     get_saved_channel_indices_from_spikeglx_meta,
     read_openephys,
-    read_openephys_binary,
     get_saved_channel_indices_from_openephys_settings,
 )
 from .utils import combine_probes

src/probeinterface/neuropixels_tools.py

@@ -1599,55 +1599,72 @@ def read_openephys(
     raise_error: bool = True,
 ) -> Probe:
     """
-    Read probe positions from Open Ephys folder when using the Neuropix-PXI plugin.
-    The reader assumes that the NP_PROBE fields are available in the settings file.
-    Open Ephys versions 0.5.x and 0.6.x are supported:
-    * For version 0.6.x, the probe names are inferred from the STREAM field. Probe
-      information is then populated sequentially with the NP_PROBE fields.
-    * For version 0.5.x, STREAMs are not available. In this case, if multiple probes
-      are available, they are named sequentially based on the nodeId. E.g. "100.0",
-      "100.1". These substrings are used for selection.
-
-    When ``oebin_file`` is provided, the function also reads the structure.oebin to
-    compute ``device_channel_indices`` that map each probe contact to its column in
-    the binary data file. This is required for correct channel ordering when reading
-    binary recordings.
+    Read a Neuropixels probe geometry from an Open Ephys settings.xml file.
+
+    A single settings.xml can describe multiple probes (one ``<NP_PROBE>`` element
+    per probe). When the file contains more than one probe, use one of the three
+    mutually exclusive selectors (``stream_name``, ``probe_name``, or
+    ``serial_number``) to choose which probe to return.
+
+    By default the function returns a probe with identity wiring
+    (``device_channel_indices = [0, 1, 2, ...]``). When ``oebin_file`` is also
+    provided, the function reads the structure.oebin to compute
+    ``device_channel_indices`` that map each probe contact to its column in
+    the binary data file.
+
+    Open Ephys versions 0.5.x, 0.6.x, and 1.0 are supported. For version
+    0.6.x+, probe names are inferred from ``<STREAM>`` elements. For version
+    0.5.x (no ``<STREAM>`` elements), probes are named sequentially based on
+    the processor's ``nodeId`` (e.g. ``"100.0"``, ``"100.1"``).
 
     Parameters
     ----------
-    settings_file :  Path, str, or None
-        If more than one settings.xml file is in the folder structure, this argument
-        is required to indicate which settings file to use
+    settings_file : Path or str
+        Path to the Open Ephys settings.xml file. Each experiment under a
+        Record Node has its own settings file (``settings.xml`` for experiment 1,
+        ``settings_2.xml`` for experiment 2, etc.). The caller is responsible
+        for passing the correct one.
     stream_name : str or None
-        If more than one probe is used, the 'stream_name' indicates which probe to load base on the
-        stream. For example, if there are 3 probes ('ProbeA', 'ProbeB', ProbeC) and the stream_name is
-        contains the substring 'ProbeC' (e.g. 'my-stream-ProbeC'), then the probe associated with
-        ProbeC is returned. If this argument is used, the 'probe_name' and 'serial_number' must be None.
+        Select a probe by substring match against probe names derived from
+        ``<STREAM>`` elements. For example, if the settings file has probes
+        ``"ProbeA"``, ``"ProbeB"``, ``"ProbeC"``, passing
+        ``stream_name="Record Node 104#Neuropix-PXI-100.ProbeC-AP"`` selects
+        ProbeC because ``"ProbeC"`` is a substring of the stream name. This is
+        what SpikeInterface passes (the neo stream name). Mutually exclusive
+        with ``probe_name`` and ``serial_number``.
     probe_name : str or None
-        If more than one probe is used, the 'probe_name' indicates which probe to load base on the
-        probe name (e.g. "ProbeB"). If this argument is used, the 'stream_name' and 'serial_number'
-        must be None.
+        Select a probe by exact match against its name (e.g. ``"ProbeB"``).
+        Useful for interactive use. Mutually exclusive with ``stream_name``
+        and ``serial_number``.
     serial_number : str or None
-        If more than one probe is used, the 'serial_number' indicates which probe to load base on the
-        serial number. If this argument is used, the 'stream_name' and 'probe_name'
-        must be None.
+        Select a probe by exact match against its serial number. Useful for
+        automated pipelines that track probes by hardware serial. Mutually
+        exclusive with ``stream_name`` and ``probe_name``.
     oebin_file : Path, str, or None
-        Path to the structure.oebin JSON file. When provided, ``stream_name`` is
-        required and ``device_channel_indices`` are computed from the oebin's
-        ``electrode_index`` metadata. When None, identity wiring is used.
-    fix_x_position_for_oe_5: bool
-        The neuropixels PXI plugin in the open-ephys < 0.6.0 contains a bug in the y position. This option allow to fix it.
-    raise_error: bool
-        If True, any error would raise an exception. If False, None is returned. Default True
-
-    Note
-    ----
-    The electrode positions are only available when recording using the Neuropix-PXI plugin version >= 0.3.3
+        Path to the structure.oebin JSON file for a specific recording. When
+        provided, ``stream_name`` is required. The oebin's ``electrode_index``
+        metadata is used to compute ``device_channel_indices`` mapping each
+        probe contact to its binary file column. When None, identity wiring
+        is used.
+    fix_x_position_for_oe_5 : bool
+        Correct a y-position bug in the Neuropix-PXI plugin for Open Ephys
+        < 0.6.0, where multi-shank probe y-coordinates included an erroneous
+        shank pitch offset. Despite the parameter name, this corrects the y
+        (not x) position. Default True.
+    raise_error : bool
+        If True, any error raises an exception. If False, None is returned.
+        Default True.
 
     Returns
     -------
-    probe : Probe object
-
+    probe : Probe or None
+        The probe with ``device_channel_indices`` set. Returns None if
+        ``raise_error`` is False and an error occurs.
+
+    Notes
+    -----
+    Electrode positions are only available when recording with the
+    Neuropix-PXI plugin version >= 0.3.3.
     """
     if oebin_file is not None and stream_name is None:
         raise ValueError("stream_name is required when oebin_file is provided.")
@@ -1678,46 +1695,6 @@ def read_openephys(
     return probe
 
 
-def read_openephys_binary(
-    settings_file: str | Path,
-    oebin_file: str | Path,
-    stream_name: str,
-    fix_x_position_for_oe_5: bool = True,
-) -> Probe:
-    """
-    Read probe positions from an Open Ephys binary format recording.
-
-    .. deprecated::
-        Use ``read_openephys(..., oebin_file=...)`` instead.
-
-    Parameters
-    ----------
-    settings_file : Path or str
-        Path to the Open Ephys settings.xml file.
-    oebin_file : Path or str
-        Path to the structure.oebin JSON file.
-    stream_name : str
-        Stream name to select which probe and oebin stream to use.
-    fix_x_position_for_oe_5 : bool
-        Fix a y-position bug in Open Ephys < 0.6.0. Default True.
-
-    Returns
-    -------
-    probe : Probe
-    """
-    warnings.warn(
-        "read_openephys_binary is deprecated. Use read_openephys(..., oebin_file=...) instead.",
-        DeprecationWarning,
-        stacklevel=2,
-    )
-    return read_openephys(
-        settings_file,
-        stream_name=stream_name,
-        oebin_file=oebin_file,
-        fix_x_position_for_oe_5=fix_x_position_for_oe_5,
-    )
-
-
 def get_saved_channel_indices_from_openephys_settings(
     settings_file: str | Path, stream_name: str
 ) -> Optional[np.array]:

tests/test_io/test_openephys.py

@@ -9,7 +9,7 @@
 
 from probeinterface import read_openephys
 from probeinterface.neuropixels_tools import _parse_openephys_settings, _select_openephys_probe_info
-from probeinterface.neuropixels_tools import _slice_catalogue_probe, build_neuropixels_probe, read_openephys_binary
+from probeinterface.neuropixels_tools import _slice_catalogue_probe, build_neuropixels_probe
 from probeinterface.testing import validate_probe_dict
 
 data_path = Path(__file__).absolute().parent.parent / "data" / "openephys"
@@ -469,7 +469,7 @@ def _read_oebin_electrode_indices(oebin_file, stream_name):
     return []
 
 
-def test_read_openephys_binary_wiring():
+def test_read_openephys_with_oebin_wiring():
     """Verify wiring invariant: for each contact, the oebin's electrode_index at the
     assigned binary column matches the contact's electrode index."""
     settings = data_path / "OE_Neuropix-PXI-NP1-binary" / "Record_Node_101" / "settings.xml"
@@ -478,7 +478,7 @@ def test_read_openephys_binary_wiring():
     )
     stream_name = "Neuropix-PXI-100.ProbeA"
 
-    probe = read_openephys_binary(settings, oebin, stream_name)
+    probe = read_openephys(settings, stream_name=stream_name, oebin_file=oebin)
 
     assert probe.get_contact_count() == 384
     assert probe.device_channel_indices is not None
@@ -494,31 +494,36 @@ def test_read_openephys_binary_wiring():
         )
 
 
-def test_read_openephys_binary_contact_ids_match_canonical_pattern():
-    """Verify that read_openephys_binary contact_ids are consistent with SpikeGLX (issue #394)."""
+def test_read_openephys_with_oebin_contact_ids_match_canonical_pattern():
+    """Verify that contact_ids with oebin are consistent with SpikeGLX (issue #394)."""
     # NP2014 single-shank
-    probe = read_openephys_binary(
+    probe = read_openephys(
         data_path / "OE_Neuropix-PXI-NP1-binary" / "Record_Node_101" / "settings.xml",
-        data_path / "OE_Neuropix-PXI-NP1-binary" / "Record_Node_101" / "experiment1" / "recording1" / "structure.oebin",
-        "Neuropix-PXI-100.ProbeA",
+        stream_name="Neuropix-PXI-100.ProbeA",
+        oebin_file=data_path
+        / "OE_Neuropix-PXI-NP1-binary"
+        / "Record_Node_101"
+        / "experiment1"
+        / "recording1"
+        / "structure.oebin",
     )
     _assert_contact_ids_match_canonical_pattern(probe, "NP2014 binary")
 
     # NP1032 4-shank
-    probe = read_openephys_binary(
+    probe = read_openephys(
         data_path / "OE_Neuropix-PXI-NP2-4shank-binary" / "Record_Node_101" / "settings.xml",
-        data_path
+        stream_name="Neuropix-PXI-100.ProbeA-AP",
+        oebin_file=data_path
         / "OE_Neuropix-PXI-NP2-4shank-binary"
         / "Record_Node_101"
         / "experiment4"
         / "recording2"
         / "structure.oebin",
-        "Neuropix-PXI-100.ProbeA-AP",
     )
     _assert_contact_ids_match_canonical_pattern(probe, "NP1032 binary")
 
 
-def test_read_openephys_binary_sync_channel_filtered():
+def test_read_openephys_with_oebin_sync_channel_filtered():
     """Verify that the oebin sync channel (385 channels) is filtered, producing 384 contacts."""
     settings = data_path / "OE_Neuropix-PXI-NP2-4shank-binary" / "Record_Node_101" / "settings.xml"
     oebin = (
@@ -530,90 +535,34 @@ def test_read_openephys_binary_sync_channel_filtered():
         / "structure.oebin"
     )
 
-    probe = read_openephys_binary(settings, oebin, "Neuropix-PXI-100.ProbeA-AP")
+    probe = read_openephys(settings, stream_name="Neuropix-PXI-100.ProbeA-AP", oebin_file=oebin)
     assert probe.get_contact_count() == 384
 
 
-def test_read_openephys_binary_plugin_channel_key():
-    """Verify that plugin_channel_key annotation is set."""
+def test_read_openephys_with_oebin_plugin_channel_key():
+    """Verify that plugin_channel_key annotation is set when using oebin_file."""
     settings = data_path / "OE_Neuropix-PXI-NP1-binary" / "Record_Node_101" / "settings.xml"
     oebin = (
         data_path / "OE_Neuropix-PXI-NP1-binary" / "Record_Node_101" / "experiment1" / "recording1" / "structure.oebin"
     )
     stream_name = "Neuropix-PXI-100.ProbeA"
 
-    probe = read_openephys_binary(settings, oebin, stream_name)
+    probe = read_openephys(settings, stream_name=stream_name, oebin_file=oebin)
     keys = probe.contact_annotations.get("plugin_channel_key", None)
     assert keys is not None, "plugin_channel_key annotation not set"
     assert len(keys) == probe.get_contact_count()
-    # Keys should be like "CH0", "CH1", etc.
     assert all(k.startswith("CH") for k in keys)
 
 
-def test_read_openephys_binary_no_matching_stream():
-    """Verify error when stream_name doesn't match any oebin stream."""
+def test_read_openephys_with_oebin_no_matching_stream():
+    """Verify error when stream_name doesn't match any probe in settings."""
     settings = data_path / "OE_Neuropix-PXI-NP1-binary" / "Record_Node_101" / "settings.xml"
     oebin = (
         data_path / "OE_Neuropix-PXI-NP1-binary" / "Record_Node_101" / "experiment1" / "recording1" / "structure.oebin"
     )
 
     with pytest.raises(Exception, match="Inconsistency between provided stream"):
-        read_openephys_binary(settings, oebin, "NonExistentStream")
-
-
-def test_read_openephys_with_oebin_file():
-    """Verify read_openephys(..., oebin_file=...) matches read_openephys_binary results."""
-    settings = data_path / "OE_Neuropix-PXI-NP1-binary" / "Record_Node_101" / "settings.xml"
-    oebin = (
-        data_path / "OE_Neuropix-PXI-NP1-binary" / "Record_Node_101" / "experiment1" / "recording1" / "structure.oebin"
-    )
-    stream_name = "Neuropix-PXI-100.ProbeA"
-
-    probe = read_openephys(settings, stream_name=stream_name, oebin_file=oebin)
-
-    assert probe.get_contact_count() == 384
-    assert probe.device_channel_indices is not None
-
-    # Wiring invariant
-    oebin_electrode_indices = _read_oebin_electrode_indices(oebin, stream_name)
-    for i, contact_id in enumerate(probe.contact_ids):
-        electrode_index = int(contact_id.split("e")[-1])
-        column = probe.device_channel_indices[i]
-        assert oebin_electrode_indices[column] == electrode_index
-
-
-def test_read_openephys_with_oebin_file_4shank():
-    """Verify read_openephys(..., oebin_file=...) works for 4-shank probes."""
-    settings = data_path / "OE_Neuropix-PXI-NP2-4shank-binary" / "Record_Node_101" / "settings.xml"
-    oebin = (
-        data_path
-        / "OE_Neuropix-PXI-NP2-4shank-binary"
-        / "Record_Node_101"
-        / "experiment4"
-        / "recording2"
-        / "structure.oebin"
-    )
-    stream_name = "Neuropix-PXI-100.ProbeA-AP"
-
-    probe = read_openephys(settings, stream_name=stream_name, oebin_file=oebin)
-
-    assert probe.get_contact_count() == 384
-    _assert_contact_ids_match_canonical_pattern(probe, "NP1032 oebin_file")
-
-
-def test_read_openephys_with_oebin_file_plugin_channel_key():
-    """Verify that plugin_channel_key annotation is set when using oebin_file."""
-    settings = data_path / "OE_Neuropix-PXI-NP1-binary" / "Record_Node_101" / "settings.xml"
-    oebin = (
-        data_path / "OE_Neuropix-PXI-NP1-binary" / "Record_Node_101" / "experiment1" / "recording1" / "structure.oebin"
-    )
-    stream_name = "Neuropix-PXI-100.ProbeA"
-
-    probe = read_openephys(settings, stream_name=stream_name, oebin_file=oebin)
-    keys = probe.contact_annotations.get("plugin_channel_key", None)
-    assert keys is not None, "plugin_channel_key annotation not set"
-    assert len(keys) == probe.get_contact_count()
-    assert all(k.startswith("CH") for k in keys)
+        read_openephys(settings, stream_name="NonExistentStream", oebin_file=oebin)
 
 
 def test_read_openephys_oebin_file_requires_stream_name():
@@ -668,18 +617,6 @@ def test_read_openephys_multishank_wiring():
         )
 
 
-def test_read_openephys_binary_deprecation_warning():
-    """Verify that read_openephys_binary emits a DeprecationWarning."""
-    settings = data_path / "OE_Neuropix-PXI-NP1-binary" / "Record_Node_101" / "settings.xml"
-    oebin = (
-        data_path / "OE_Neuropix-PXI-NP1-binary" / "Record_Node_101" / "experiment1" / "recording1" / "structure.oebin"
-    )
-    stream_name = "Neuropix-PXI-100.ProbeA"
-
-    with pytest.warns(DeprecationWarning, match="read_openephys_binary is deprecated"):
-        read_openephys_binary(settings, oebin, stream_name)
-
-
 if __name__ == "__main__":
     # test_multiple_probes()
     # test_NP_Ultra()