Propagate photon series type to imaging interfaces (#866)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Cody Baker <[email protected]>

CHANGELOG.md

@@ -46,6 +46,7 @@
 * Fixed a bug that prevented passing `nwbfile=None` and a `backend_configuration` to `NWBConverter.run_conversion`. [PR #885](https://github.com/catalystneuro/neuroconv/pull/885)
 
 ### Improvements
+* Added soft deprecation warning for removing `photon_series_type` from `get_metadata()` and `get_metadata_schema()` (in [PR #847](https://github.com/catalystneuro/neuroconv/pull/847)). [PR #866](https://github.com/catalystneuro/neuroconv/pull/866)
 * Fixed docstrings related to backend configurations for various methods. [PR #822](https://github.com/catalystneuro/neuroconv/pull/822)
 * Propagated `photon_series_type` to `BaseImagingExtractorInterface` init instead of passing it as an argument of `get_metadata()` and `get_metadata_schema()`. [PR #847](https://github.com/catalystneuro/neuroconv/pull/847)
 * Added automatic `backend` detection when a `backend_configuration` is passed to an interface or converter. [PR #840](https://github.com/catalystneuro/neuroconv/pull/840)

src/neuroconv/datainterfaces/ophys/baseimagingextractorinterface.py

@@ -1,5 +1,6 @@
 """Author: Ben Dichter."""
 
+import warnings
 from typing import Literal, Optional
 
 import numpy as np
@@ -44,7 +45,18 @@ def __init__(
         self.verbose = verbose
         self.photon_series_type = photon_series_type
 
-    def get_metadata_schema(self) -> dict:
+    def get_metadata_schema(
+        self, photon_series_type: Optional[Literal["OnePhotonSeries", "TwoPhotonSeries"]] = None
+    ) -> dict:
+
+        if photon_series_type is not None:
+            warnings.warn(
+                "The 'photon_series_type' argument is deprecated and will be removed in a future version. "
+                "Please set 'photon_series_type' during the initialization of the BaseImagingExtractorInterface instance.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            self.photon_series_type = photon_series_type
         metadata_schema = super().get_metadata_schema()
 
         metadata_schema["required"] = ["Ophys"]
@@ -87,7 +99,19 @@ def get_metadata_schema(self) -> dict:
         fill_defaults(metadata_schema, self.get_metadata())
         return metadata_schema
 
-    def get_metadata(self) -> DeepDict:
+    def get_metadata(
+        self, photon_series_type: Optional[Literal["OnePhotonSeries", "TwoPhotonSeries"]] = None
+    ) -> DeepDict:
+
+        if photon_series_type is not None:
+            warnings.warn(
+                "The 'photon_series_type' argument is deprecated and will be removed in a future version. "
+                "Please set 'photon_series_type' during the initialization of the BaseImagingExtractorInterface instance.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            self.photon_series_type = photon_series_type
+
         from ...tools.roiextractors import get_nwb_imaging_metadata
 
         metadata = super().get_metadata()

src/neuroconv/datainterfaces/ophys/hdf5/hdf5datainterface.py

@@ -1,3 +1,5 @@
+from typing import Literal
+
 from ..baseimagingextractorinterface import BaseImagingExtractorInterface
 from ....utils import ArrayType, FilePathType
 
@@ -18,6 +20,7 @@ def __init__(
         metadata: dict = None,
         channel_names: ArrayType = None,
         verbose: bool = True,
+        photon_series_type: Literal["OnePhotonSeries", "TwoPhotonSeries"] = "TwoPhotonSeries",
     ):
         """
 
@@ -40,4 +43,5 @@ def __init__(
             metadata=metadata,
             channel_names=channel_names,
             verbose=verbose,
+            photon_series_type=photon_series_type,
         )

src/neuroconv/datainterfaces/ophys/sbx/sbxdatainterface.py

@@ -1,3 +1,5 @@
+from typing import Literal
+
 from ..baseimagingextractorinterface import BaseImagingExtractorInterface
 from ....utils import FilePathType
 
@@ -9,7 +11,13 @@ class SbxImagingInterface(BaseImagingExtractorInterface):
     associated_suffixes = (".sbx",)
     info = "Interface for Scanbox imaging data."
 
-    def __init__(self, file_path: FilePathType, sampling_frequency: float = None, verbose: bool = True):
+    def __init__(
+        self,
+        file_path: FilePathType,
+        sampling_frequency: float = None,
+        verbose: bool = True,
+        photon_series_type: Literal["OnePhotonSeries", "TwoPhotonSeries"] = "TwoPhotonSeries",
+    ):
         """
         Parameters
         ----------
@@ -19,7 +27,12 @@ def __init__(self, file_path: FilePathType, sampling_frequency: float = None, ve
         verbose : bool, default: True
         """
 
-        super().__init__(file_path=file_path, sampling_frequency=sampling_frequency, verbose=verbose)
+        super().__init__(
+            file_path=file_path,
+            sampling_frequency=sampling_frequency,
+            verbose=verbose,
+            photon_series_type=photon_series_type,
+        )
 
     def get_metadata(self) -> dict:
         metadata = super().get_metadata()

src/neuroconv/datainterfaces/ophys/tiff/tiffdatainterface.py

@@ -1,3 +1,5 @@
+from typing import Literal
+
 from ..baseimagingextractorinterface import BaseImagingExtractorInterface
 from ....utils import FilePathType
 
@@ -15,7 +17,13 @@ def get_source_schema(cls) -> dict:
         source_schema["properties"]["file_path"]["description"] = "Path to Tiff file."
         return source_schema
 
-    def __init__(self, file_path: FilePathType, sampling_frequency: float, verbose: bool = True):
+    def __init__(
+        self,
+        file_path: FilePathType,
+        sampling_frequency: float,
+        verbose: bool = True,
+        photon_series_type: Literal["OnePhotonSeries", "TwoPhotonSeries"] = "TwoPhotonSeries",
+    ):
         """
         Initialize reading of TIFF file.
 
@@ -24,5 +32,11 @@ def __init__(self, file_path: FilePathType, sampling_frequency: float, verbose:
         file_path : FilePathType
         sampling_frequency : float
         verbose : bool, default: True
+        photon_series_type : {'OnePhotonSeries', 'TwoPhotonSeries'}, default: "TwoPhotonSeries"
         """
-        super().__init__(file_path=file_path, sampling_frequency=sampling_frequency, verbose=verbose)
+        super().__init__(
+            file_path=file_path,
+            sampling_frequency=sampling_frequency,
+            verbose=verbose,
+            photon_series_type=photon_series_type,
+        )

src/neuroconv/tools/testing/mock_interfaces.py

@@ -174,8 +174,8 @@ def __init__(
         self.verbose = verbose
         self.photon_series_type = photon_series_type
 
-    def get_metadata(self) -> dict:
+    def get_metadata(self, photon_series_type: Optional[Literal["OnePhotonSeries", "TwoPhotonSeries"]] = None) -> dict:
         session_start_time = datetime.now().astimezone()
-        metadata = super().get_metadata()
+        metadata = super().get_metadata(photon_series_type=photon_series_type)
         metadata["NWBFile"]["session_start_time"] = session_start_time
         return metadata

tests/test_ophys/test_baseimagingextractorinterface.py

@@ -0,0 +1,15 @@
+from hdmf.testing import TestCase
+
+from neuroconv.tools.testing.mock_interfaces import MockImagingInterface
+
+
+class TestBaseImagingExtractorInterface(TestCase):
+    def setUp(self):
+        self.mock_imaging_interface = MockImagingInterface()
+
+    def test_photon_series_type_warning_triggered_in_get_metadata(self):
+        with self.assertWarnsWith(
+            warn_type=DeprecationWarning,
+            exc_msg="The 'photon_series_type' argument is deprecated and will be removed in a future version. Please set 'photon_series_type' during the initialization of the BaseImagingExtractorInterface instance.",
+        ):
+            self.mock_imaging_interface.get_metadata(photon_series_type="TwoPhotonSeries")