Refactor Miniscope Extractor Naming (#374)

* rename legacy extractor * docstring and name correction * name change on init * changelog --------- Co-authored-by: Szonja Weigl <[email protected]>
catalystneuro · Oct 22, 2024 · 5d8284b · 5d8284b
1 parent 2cbf4f0
commit 5d8284b
Show file tree

Hide file tree

Showing 3 changed files with 53 additions and 15 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,6 +11,7 @@
 ### Improvements
 * Removed unnecessary import checks for scipy, h5py, and zarr [PR #364](https://github.com/catalystneuro/roiextractors/pull/364)
 * Improved the error message for the `set_timestamps` method in the `ImagingExtractor` class[PR #377](https://github.com/catalystneuro/roiextractors/pull/377)
+* Renamed `MiniscopeImagingExtractor` to`MiniscopeMultiRecordingImagingExtractor` class[PR #374](https://github.com/catalystneuro/roiextractors/pull/374)
 
 ### Testing
 

diff --git a/src/roiextractors/extractors/miniscopeimagingextractor/__init__.py b/src/roiextractors/extractors/miniscopeimagingextractor/__init__.py
@@ -11,4 +11,4 @@
     An ImagingExtractor for the Miniscope video (.avi) format.
 """
 
-from .miniscopeimagingextractor import MiniscopeImagingExtractor
+from .miniscopeimagingextractor import MiniscopeImagingExtractor, MiniscopeMultiRecordingImagingExtractor
diff --git a/src/roiextractors/extractors/miniscopeimagingextractor/miniscopeimagingextractor.py b/src/roiextractors/extractors/miniscopeimagingextractor/miniscopeimagingextractor.py
@@ -10,6 +10,7 @@
 import re
 from pathlib import Path
 from typing import Optional, Tuple, List
+import warnings
 
 import numpy as np
 
@@ -18,19 +19,43 @@
 from ...extraction_tools import PathType, DtypeType, get_package
 
 
-class MiniscopeImagingExtractor(MultiImagingExtractor):  # TODO: rename to MiniscopeMultiImagingExtractor
-    """An ImagingExtractor for the Miniscope video (.avi) format.
-
-    This format consists of video (.avi) file(s) and configuration files (.json).
-    One _MiniscopeImagingExtractor is created for each video file and then combined into the MiniscopeImagingExtractor.
+class MiniscopeMultiRecordingImagingExtractor(MultiImagingExtractor):
+    """
+    ImagingExtractor processes multiple separate Miniscope recordings within the same session.
+
+    Important, this extractor consolidates the recordings as a single continuous dataset.
+
+    Expected directory structure:
+
+    .
+    ├── C6-J588_Disc5
+    │   ├── 15_03_28  (timestamp)
+    │   │   ├── BehavCam_2
+    │   │   ├── metaData.json
+    │   │   └── Miniscope
+    │   ├── 15_06_28 (timestamp)
+    │   │   ├── BehavCam_2
+    │   │   ├── metaData.json
+    │   │   └── Miniscope
+    │   └── 15_07_58 (timestamp)
+    │       ├── BehavCam_2
+    │       ├── metaData.json
+    │       └── Miniscope
+    └──
+
+    Where the Miniscope folders contain a collection of .avi files and a metaData.json file.
+
+    For each video file, a _MiniscopeSingleVideoExtractor is created. These individual extractors
+    are then combined into the MiniscopeMultiRecordingImagingExtractor to handle the session's recordings
+    as a unified, continuous dataset.
     """
 
-    extractor_name = "MiniscopeImaging"
+    extractor_name = "MiniscopeMultiRecordingImagingExtractor"
     is_writable = True
     mode = "folder"
 
     def __init__(self, folder_path: PathType):
-        """Create a MiniscopeImagingExtractor instance from a folder path.
+        """Create a MiniscopeMultiRecordingImagingExtractor instance from a folder path.
 
         Parameters
         ----------
@@ -58,24 +83,36 @@ def __init__(self, folder_path: PathType):
 
         imaging_extractors = []
         for file_path in miniscope_avi_file_paths:
-            extractor = _MiniscopeImagingExtractor(file_path=file_path)
+            extractor = _MiniscopeSingleVideoExtractor(file_path=file_path)
             extractor._sampling_frequency = self._sampling_frequency
             imaging_extractors.append(extractor)
 
         super().__init__(imaging_extractors=imaging_extractors)
 
 
-class _MiniscopeImagingExtractor(ImagingExtractor):
-    """An ImagingExtractor for the Miniscope video (.avi) format.
+# Temporary renaming to keep backwards compatibility
+class MiniscopeImagingExtractor(MiniscopeMultiRecordingImagingExtractor):
+    def __init__(self, *args, **kwargs):
+        warnings.warn(
+            "MiniscopeImagingExtractor is unstable and might change its signature. "
+            "Please use MiniscopeMultiRecordingImagingExtractor instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        super().__init__(*args, **kwargs)
+
+
+class _MiniscopeSingleVideoExtractor(ImagingExtractor):
+    """An auxiliar extractor to get data from a single Miniscope video (.avi) file.
 
-    This format consists of a single video (.avi) file and configuration file (.json).
-    Multiple _MiniscopeImagingExtractor are combined into the MiniscopeImagingExtractor for public access.
+    This format consists of a single video (.avi)
+    Multiple _MiniscopeSingleVideoExtractor are combined by downstream extractors to extract the data
     """
 
-    extractor_name = "_MiniscopeImaging"
+    extractor_name = "_MiniscopeSingleVideo"
 
     def __init__(self, file_path: PathType):
-        """Create a _MiniscopeImagingExtractor instance from a file path.
+        """Create a _MiniscopeSingleVideoExtractor instance from a file path.
 
         Parameters
         ----------