Soft deprecate file_path for SpikeGLXRecordingInterface and `Spik…

…eGLXNIDQInterface` (#1155)

Co-authored-by: Ben Dichter <[email protected]>

CHANGELOG.md

@@ -2,7 +2,8 @@
 
 ## Deprecations
 * Removed use of `jsonschema.RefResolver` as it will be deprecated from the jsonschema library [PR #1133](https://github.com/catalystneuro/neuroconv/pull/1133)
-* Completely removed compression settings from most places[PR #1126](https://github.com/catalystneuro/neuroconv/pull/1126)
+* Completely removed compression settings from most places [PR #1126](https://github.com/catalystneuro/neuroconv/pull/1126)
+* Soft deprecation for `file_path` as an argument of  `SpikeGLXNIDQInterface` and `SpikeGLXRecordingInterface` [PR #1155](https://github.com/catalystneuro/neuroconv/pull/1155)
 
 ## Bug Fixes
 * datetime objects now can be validated as conversion options [#1139](https://github.com/catalystneuro/neuroconv/pull/1126)
@@ -11,7 +12,6 @@
 * `SpikeGLXConverterPipe` converter now accepts multi-probe structures with multi-trigger and does not assume a specific folder structure [#1150](https://github.com/catalystneuro/neuroconv/pull/1150)
 * `SpikeGLXNIDQInterface` is no longer written as an ElectricalSeries [#1152](https://github.com/catalystneuro/neuroconv/pull/1152)
 
-
 ## Features
 * Propagate the `unit_electrode_indices` argument from the spikeinterface tools to `BaseSortingExtractorInterface`. This allows users to map units to the electrode table when adding sorting data [PR #1124](https://github.com/catalystneuro/neuroconv/pull/1124)
 * Imaging interfaces have a new conversion option `always_write_timestamps` that can be used to force writing timestamps even if neuroconv's heuristics indicates regular sampling rate [PR #1125](https://github.com/catalystneuro/neuroconv/pull/1125)
@@ -22,14 +22,12 @@
 * YAML specification files now accepts an outer keyword `upload_to_dandiset="< six-digit ID >"` to automatically upload the produced NWB files to the DANDI archive [PR #1089](https://github.com/catalystneuro/neuroconv/pull/1089)
 *`SpikeGLXNIDQInterface` now handdles digital demuxed channels (`XD0`) [#1152](https://github.com/catalystneuro/neuroconv/pull/1152)
 
-
-
-
 ## Improvements
 * Use mixing tests for ecephy's mocks [PR #1136](https://github.com/catalystneuro/neuroconv/pull/1136)
 * Use pytest format for dandi tests to avoid window permission error on teardown [PR #1151](https://github.com/catalystneuro/neuroconv/pull/1151)
 * Added many docstrings for public functions [PR #1063](https://github.com/catalystneuro/neuroconv/pull/1063)
 
+
 # v0.6.5 (November 1, 2024)
 
 ## Bug Fixes

docs/conversion_examples_gallery/combinations/spikeglx_and_phy.rst

@@ -16,8 +16,8 @@ were are combining a SpikeGLX recording with Phy sorting results using the
     >>> from neuroconv.datainterfaces import SpikeGLXRecordingInterface, PhySortingInterface
     >>>
     >>> # For this interface we need to pass the location of the ``.bin`` file. Change the file_path to the location in your system
-    >>> file_path = f"{ECEPHY_DATA_PATH}/spikeglx/Noise4Sam_g0/Noise4Sam_g0_imec0/Noise4Sam_g0_t0.imec0.ap.bin"
-    >>> interface_spikeglx = SpikeGLXRecordingInterface(file_path=file_path, verbose=False)
+    >>> folder_path = f"{ECEPHY_DATA_PATH}/spikeglx/Noise4Sam_g0/Noise4Sam_g0_imec0"
+    >>> interface_spikeglx = SpikeGLXRecordingInterface(folder_path=folder_path, stream_id="imec0.ap", verbose=False)
     >>>
     >>> folder_path = f"{ECEPHY_DATA_PATH}/phy/phy_example_0"  # Change the folder_path to the location of the data in your system
     >>> interface_phy = PhySortingInterface(folder_path=folder_path, verbose=False)

docs/conversion_examples_gallery/recording/spikeglx.rst

@@ -51,9 +51,10 @@ Defining a 'stream' as a single band on a single NeuroPixels probe, we can conve
     >>> from neuroconv.datainterfaces import SpikeGLXRecordingInterface
     >>>
     >>> # For this interface we need to pass the location of the ``.bin`` file
-    >>> file_path = f"{ECEPHY_DATA_PATH}/spikeglx/Noise4Sam_g0/Noise4Sam_g0_imec0/Noise4Sam_g0_t0.imec0.ap.bin"
-    >>> # Change the file_path to the location in your system
-    >>> interface = SpikeGLXRecordingInterface(file_path=file_path, verbose=False)
+    >>> folder_path = f"{ECEPHY_DATA_PATH}/spikeglx/Noise4Sam_g0/Noise4Sam_g0_imec0"
+    >>> # Options for the streams are "imec0.ap", "imec0.lf", "imec1.ap", "imec1.lf", etc.
+    >>> # Depending on the device and the band of interest, choose the appropriate stream
+    >>> interface = SpikeGLXRecordingInterface(folder_path=folder_path, stream_id="imec0.ap", verbose=False)
     >>>
     >>> # Extract what metadata we can from the source files
     >>> metadata = interface.get_metadata()

src/neuroconv/datainterfaces/ecephys/spikeglx/spikeglxdatainterface.py

@@ -1,5 +1,6 @@
 """DataInterfaces for SpikeGLX."""
 
+import warnings
 from pathlib import Path
 from typing import Optional
 
@@ -79,6 +80,15 @@ def __init__(
                 "SpikeGLXRecordingInterface is not designed to handle nidq files. Use SpikeGLXNIDQInterface instead"
             )
 
+        if file_path is not None:
+            warnings.warn(
+                "file_path is deprecated and will be removed by the end of 2025. "
+                "The first argument of this interface will be `folder_path` afterwards. "
+                "Use folder_path and stream_id instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
         if file_path is not None and stream_id is None:
             self.stream_id = fetch_stream_id_for_spikelgx_file(file_path)
             self.folder_path = Path(file_path).parent

src/neuroconv/datainterfaces/ecephys/spikeglx/spikeglxnidqinterface.py

@@ -36,7 +36,7 @@ def __init__(
         self,
         file_path: Optional[FilePath] = None,
         verbose: bool = True,
-        load_sync_channel: bool = False,
+        load_sync_channel: Optional[bool] = None,
         es_key: str = "ElectricalSeriesNIDQ",
         folder_path: Optional[DirectoryPath] = None,
     ):
@@ -56,7 +56,7 @@ def __init__(
         es_key : str, default: "ElectricalSeriesNIDQ"
         """
 
-        if load_sync_channel:
+        if load_sync_channel is not None:
 
             warnings.warn(
                 "The 'load_sync_channel' parameter is deprecated and will be removed in June 2025. "
@@ -65,6 +65,15 @@ def __init__(
                 stacklevel=2,
             )
 
+        if file_path is not None:
+            warnings.warn(
+                "file_path is deprecated and will be removed by the end of 2025. "
+                "The first argument of this interface will be `folder_path` afterwards. "
+                "Use folder_path and stream_id instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
         if file_path is None and folder_path is None:
             raise ValueError("Either 'file_path' or 'folder_path' must be provided.")