rename spikegadgets (#440)

Author: h-mayorquin

src/probeinterface/__init__.py

@@ -15,6 +15,8 @@
     read_BIDS_probe,
     write_BIDS_probe,
     read_spikegadgets,
+    read_spikegadgets_neuropixels,
+    has_spikegadgets_neuropixels_probes,
     read_mearec,
     read_nwb,
     read_maxwell,

src/probeinterface/io.py

@@ -733,12 +733,17 @@ def write_csv(file, probe):
     raise NotImplementedError
 
 
-def read_spikegadgets(file: str | Path, raise_error: bool = True) -> ProbeGroup:
+def read_spikegadgets_neuropixels(file: str | Path, raise_error: bool = True) -> ProbeGroup:
     """
     Find active channels of the given Neuropixels probe from a SpikeGadgets .rec file.
     SpikeGadgets headstages support up to three Neuropixels 1.0 probes (as of March 28, 2024),
     and information for all probes will be returned in a ProbeGroup object.
 
+    This function only supports Neuropixels probes recorded with SpikeGadgets
+    headstages (``HardwareConfiguration`` entries with ``name == "NeuroPixels1"``).
+    It does not handle tetrodes or other probe types that SpikeGadgets can
+    record. Use :func:`has_spikegadgets_neuropixels_probes` to check whether a
+    ``.rec`` file contains Neuropixels probe geometry before calling this reader.
 
     Parameters
     ----------
@@ -834,6 +839,67 @@ def read_spikegadgets(file: str | Path, raise_error: bool = True) -> ProbeGroup:
     return probe_group
 
 
+def read_spikegadgets(*args, **kwargs) -> ProbeGroup:
+    """
+    Deprecated alias for :func:`read_spikegadgets_neuropixels`.
+
+    The name ``read_spikegadgets`` is misleading because the function only reads
+    Neuropixels probe geometry, not arbitrary SpikeGadgets ``.rec`` recordings.
+    Use :func:`read_spikegadgets_neuropixels` instead, and
+    :func:`has_spikegadgets_neuropixels_probes` to check whether a ``.rec`` file
+    has Neuropixels geometry before calling it.
+    """
+    warnings.warn(
+        "read_spikegadgets is deprecated and will be removed in a future release. "
+        "Use read_spikegadgets_neuropixels instead.",
+        category=DeprecationWarning,
+        stacklevel=2,
+    )
+    return read_spikegadgets_neuropixels(*args, **kwargs)
+
+
+def has_spikegadgets_neuropixels_probes(file: str | Path) -> bool:
+    """
+    Return True if the SpikeGadgets ``.rec`` file describes at least one
+    Neuropixels probe.
+
+    Detection scans the ``HardwareConfiguration`` block of the ``.rec`` XML
+    header for ``Device`` entries whose ``name`` attribute matches a known
+    Neuropixels source name (currently ``"NeuroPixels1"``). The presence of
+    any such entry is the ground-truth signal that the file contains
+    Neuropixels probe geometry, independent of what other hardware the
+    headstage is also streaming.
+
+    Intended use: callers that route heterogeneous SpikeGadgets recordings
+    (mixing tetrodes, Neuropixels, etc.) can gate the call to
+    :func:`read_spikegadgets_neuropixels` on this helper and skip probe
+    attachment for non-Neuropixels recordings.
+
+    Parameters
+    ----------
+    file : str or Path
+        Path to the SpikeGadgets ``.rec`` file.
+
+    Returns
+    -------
+    bool
+    """
+    try:
+        header_txt = parse_spikegadgets_header(file)
+        root = ElementTree.fromstring(header_txt)
+    except Exception:
+        return False
+
+    hconf = root.find("HardwareConfiguration")
+    if hconf is None:
+        return False
+
+    for device in hconf:
+        if device.attrib.get("name") == "NeuroPixels1":
+            return True
+    return False
+
+
 def parse_spikegadgets_header(file: str | Path) -> str:
     """
     Parse file (SpikeGadgets .rec format) into a string until "</Configuration>",

tests/test_io/test_spikegadgets.py

@@ -1,7 +1,13 @@
 from pathlib import Path
 from xml.etree import ElementTree
 
-from probeinterface import read_spikegadgets
+import pytest
+
+from probeinterface import (
+    read_spikegadgets,
+    read_spikegadgets_neuropixels,
+    has_spikegadgets_neuropixels_probes,
+)
 from probeinterface.io import parse_spikegadgets_header
 from probeinterface.testing import validate_probe_dict
 
@@ -18,7 +24,7 @@ def test_parse_meta():
 
 
 def test_neuropixels_1_reader():
-    probe_group = read_spikegadgets(data_path / test_file, raise_error=False)
+    probe_group = read_spikegadgets_neuropixels(data_path / test_file, raise_error=False)
     assert len(probe_group.probes) == 2
     for probe in probe_group.probes:
         probe_dict = probe.to_dict(array_as_list=True)
@@ -29,6 +35,25 @@ def test_neuropixels_1_reader():
     assert probe_group.get_contact_count() == 768
 
 
+def test_read_spikegadgets_deprecation_warning():
+    # Old read_spikegadgets name must still work but emit DeprecationWarning pointing at the new name.
+    with pytest.warns(DeprecationWarning, match="read_spikegadgets_neuropixels"):
+        read_spikegadgets(data_path / test_file, raise_error=False)
+
+
+def test_has_spikegadgets_neuropixels_probes_positive():
+    # A real Neuropixels .rec header should report True.
+    assert has_spikegadgets_neuropixels_probes(data_path / test_file) is True
+
+
+def test_has_spikegadgets_neuropixels_probes_missing_file():
+    # Unreadable / nonexistent files return False rather than raising.
+    assert has_spikegadgets_neuropixels_probes(data_path / "does_not_exist.rec") is False
+
+
 if __name__ == "__main__":
     test_parse_meta()
     test_neuropixels_1_reader()
+    test_read_spikegadgets_deprecation_warning()
+    test_has_spikegadgets_neuropixels_probes_positive()
+    test_has_spikegadgets_neuropixels_probes_missing_file()