add descriptions to args in the source schema (#886)

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

@@ -44,7 +44,8 @@
 * Support for pathlib in source data schema validation. [PR #854](https://github.com/catalystneuro/neuroconv/pull/854)
 * Use `ZoneInfo` instead of `dateutil.tz` in the conversion gallery. [PR #858](https://github.com/catalystneuro/neuroconv/pull/858)
 * Exposed `progress_bar_class` to ecephys and ophys data iterators. [PR #861](https://github.com/catalystneuro/neuroconv/pull/861)
-* Unified the signatures between `add_units`, `add_sorting` and `write_sorting` [PR #875](https://github.com/catalystneuro/neuroconv/pull/875)
+* Unified the signatures between `add_units`, `add_sorting` and `write_sorting`. [PR #875](https://github.com/catalystneuro/neuroconv/pull/875)
+* Improved descriptions of all folder and file paths in the source schema, useful for rendering in the GUIDE. [PR #886](https://github.com/catalystneuro/neuroconv/pull/886)
 
 ### Testing
 * Add general test for metadata in-place modification by interfaces. [PR #815](https://github.com/catalystneuro/neuroconv/pull/815)

src/neuroconv/datainterfaces/behavior/deeplabcut/deeplabcutdatainterface.py

@@ -59,6 +59,13 @@ class DeepLabCutInterface(BaseTemporalAlignmentInterface):
 
     _timestamps = None
 
+    @classmethod
+    def get_source_schema(cls) -> dict:
+        source_schema = super().get_source_schema()
+        source_schema["properties"]["file_path"]["description"] = "Path to the .h5 file output by dlc."
+        source_schema["properties"]["config_file_path"]["description"] = "Path to .yml config file"
+        return source_schema
+
     def __init__(
         self,
         file_path: FilePathType,

src/neuroconv/datainterfaces/behavior/fictrac/fictracdatainterface.py

@@ -147,6 +147,12 @@ class FicTracDataInterface(BaseTemporalAlignmentInterface):
         },
     }
 
+    @classmethod
+    def get_source_schema(cls) -> dict:
+        source_schema = super().get_source_schema()
+        source_schema["properties"]["file_path"]["description"] = "Path to the .dat file (the output of fictrac)"
+        return source_schema
+
     def __init__(
         self,
         file_path: FilePathType,

src/neuroconv/datainterfaces/behavior/miniscope/miniscopedatainterface.py

@@ -15,6 +15,14 @@ class MiniscopeBehaviorInterface(BaseDataInterface):
     associated_suffixes = (".avi",)
     info = "Interface for Miniscope behavior video data."
 
+    @classmethod
+    def get_source_schema(cls) -> dict:
+        source_schema = super().get_source_schema()
+        source_schema["properties"]["folder_path"][
+            "description"
+        ] = "The main Miniscope folder. The movie files are expected to be in sub folders within the main folder."
+        return source_schema
+
     def __init__(self, folder_path: FolderPathType):
         """
         Initialize reading recordings from the Miniscope behavioral camera.

src/neuroconv/datainterfaces/behavior/sleap/sleapdatainterface.py

@@ -18,6 +18,15 @@ class SLEAPInterface(BaseTemporalAlignmentInterface):
     associated_suffixes = (".slp", ".mp4")
     info = "Interface for SLEAP pose estimation datasets."
 
+    @classmethod
+    def get_source_schema(cls) -> dict:
+        source_schema = super().get_source_schema()
+        source_schema["properties"]["file_path"]["description"] = "Path to the .slp file (the output of sleap)"
+        source_schema["properties"]["video_file_path"][
+            "description"
+        ] = "Path of the video for extracting timestamps (optional)."
+        return source_schema
+
     def __init__(
         self,
         file_path: FilePathType,

src/neuroconv/datainterfaces/ecephys/alphaomega/alphaomegadatainterface.py

@@ -13,6 +13,12 @@ class AlphaOmegaRecordingInterface(BaseRecordingExtractorInterface):
     associated_suffixes = (".mpx",)
     info = "Interface class for converting AlphaOmega recording data."
 
+    @classmethod
+    def get_source_schema(cls) -> dict:
+        source_schema = super().get_source_schema()
+        source_schema["properties"]["folder_path"]["description"] = "Path to the folder of .mpx files."
+        return source_schema
+
     def __init__(self, folder_path: FolderPathType, verbose: bool = True, es_key: str = "ElectricalSeries"):
         """
         Load and prepare data for AlphaOmega.

src/neuroconv/datainterfaces/ecephys/axona/axonadatainterface.py

@@ -23,6 +23,12 @@ class AxonaRecordingInterface(BaseRecordingExtractorInterface):
     associated_suffixes = (".bin", ".set")
     info = "Interface for Axona recording data."
 
+    @classmethod
+    def get_source_schema(cls) -> dict:
+        source_schema = super().get_source_schema()
+        source_schema["properties"]["file_path"]["description"] = "Path to .bin file."
+        return source_schema
+
     def __init__(self, file_path: FilePathType, verbose: bool = True, es_key: str = "ElectricalSeries"):
         """
 

src/neuroconv/datainterfaces/ecephys/biocam/biocamdatainterface.py

@@ -13,6 +13,12 @@ class BiocamRecordingInterface(BaseRecordingExtractorInterface):
     associated_suffixes = (".bwr",)
     info = "Interface for Biocam recording data."
 
+    @classmethod
+    def get_source_schema(cls) -> dict:
+        schema = super().get_source_schema()
+        schema["properties"]["file_path"]["description"] = "Path to the .bwr file."
+        return schema
+
     def __init__(self, file_path: FilePathType, verbose: bool = True, es_key: str = "ElectricalSeries"):
         """
         Load and prepare data for Biocam.

src/neuroconv/datainterfaces/ecephys/blackrock/blackrockdatainterface.py

@@ -18,7 +18,9 @@ class BlackrockRecordingInterface(BaseRecordingExtractorInterface):
     @classmethod
     def get_source_schema(cls):
         source_schema = get_schema_from_method_signature(method=cls.__init__, exclude=["block_index", "seg_index"])
-        source_schema["properties"]["file_path"]["description"] = "Path to Blackrock file."
+        source_schema["properties"]["file_path"][
+            "description"
+        ] = "Path to the Blackrock file with suffix being .ns1, .ns2, .ns3, .ns4m .ns4, or .ns6."
         return source_schema
 
     def __init__(
@@ -34,7 +36,7 @@ def __init__(
         Parameters
         ----------
         file_path : FilePathType
-            The path to the Blackrock with suffix being .ns1, .ns2, .ns3, .ns4m .ns4, or .ns6
+            Path to the Blackrock file with suffix being .ns1, .ns2, .ns3, .ns4m .ns4, or .ns6
         verbose: bool, default: True
         es_key : str, default: "ElectricalSeries"
         """
@@ -76,7 +78,7 @@ class BlackrockSortingInterface(BaseSortingExtractorInterface):
     def get_source_schema(cls) -> dict:
         metadata_schema = get_schema_from_method_signature(method=cls.__init__)
         metadata_schema["additionalProperties"] = True
-        metadata_schema["properties"]["file_path"].update(description="Path to Blackrock file.")
+        metadata_schema["properties"]["file_path"].update(description="Path to Blackrock .nev file.")
         return metadata_schema
 
     def __init__(self, file_path: FilePathType, sampling_frequency: float = None, verbose: bool = True):

src/neuroconv/datainterfaces/ecephys/cellexplorer/cellexplorerdatainterface.py

@@ -288,7 +288,22 @@ class CellExplorerRecordingInterface(BaseRecordingExtractorInterface):
     sampling_frequency_key = "sr"
     binary_file_extension = "dat"
 
+    @classmethod
+    def get_source_schema(cls) -> dict:
+        source_schema = super().get_source_schema()
+        source_schema["properties"]["folder_path"]["description"] = "Folder containing the .session.mat file"
+        return source_schema
+
     def __init__(self, folder_path: FolderPathType, verbose: bool = True, es_key: str = "ElectricalSeries"):
+        """
+
+        Parameters
+        ----------
+        folder_path: str
+            Folder containing the .session.mat file.
+        verbose: bool, default=True
+        es_key: str, default="ElectricalSeries"
+        """
         self.session_path = Path(folder_path)
 
         # No super here, we need to do everything by hand

src/neuroconv/datainterfaces/ecephys/edf/edfdatainterface.py

@@ -16,6 +16,12 @@ class EDFRecordingInterface(BaseRecordingExtractorInterface):
     associated_suffixes = (".edf",)
     info = "Interface for European Data Format (EDF) recording data."
 
+    @classmethod
+    def get_source_schema(cls) -> dict:
+        source_schema = super().get_source_schema()
+        source_schema["properties"]["file_path"]["description"] = "Path to the .edf file."
+        return source_schema
+
     def __init__(self, file_path: FilePathType, verbose: bool = True, es_key: str = "ElectricalSeries"):
         """
         Load and prepare data for EDF.

src/neuroconv/datainterfaces/ecephys/intan/intandatainterface.py

@@ -47,6 +47,12 @@ class IntanRecordingInterface(BaseRecordingExtractorInterface):
     info = "Interface for Intan recording data."
     stream_id = "0"  # This is the only stream_id of Intan that might have neural data
 
+    @classmethod
+    def get_source_schema(cls) -> dict:
+        source_schema = super().get_source_schema()
+        source_schema["properties"]["file_path"]["description"] = "Path to either a .rhd or a .rhs file"
+        return source_schema
+
     def __init__(
         self,
         file_path: FilePathType,

src/neuroconv/datainterfaces/ecephys/kilosort/kilosortdatainterface.py

@@ -9,6 +9,14 @@ class KiloSortSortingInterface(BaseSortingExtractorInterface):
     associated_suffixes = (".npy",)
     info = "Interface for KiloSort sorting data."
 
+    @classmethod
+    def get_source_schema(cls) -> dict:
+        source_schema = super().get_source_schema()
+        source_schema["properties"]["folder_path"][
+            "description"
+        ] = "Path to the output Phy folder (containing the params.py)"
+        return source_schema
+
     def __init__(
         self,
         folder_path: FolderPathType,

src/neuroconv/datainterfaces/ecephys/mcsraw/mcsrawdatainterface.py

@@ -13,6 +13,12 @@ class MCSRawRecordingInterface(BaseRecordingExtractorInterface):
     associated_suffixes = (".raw",)
     info = "Interface for MCSRaw recording data."
 
+    @classmethod
+    def get_source_schema(cls) -> dict:
+        source_schema = super().get_source_schema()
+        source_schema["properties"]["file_path"]["description"] = "Path to the .raw file."
+        return source_schema
+
     def __init__(self, file_path: FilePathType, verbose: bool = True, es_key: str = "ElectricalSeries"):
         """
         Load and prepare data for MCSRaw.

src/neuroconv/datainterfaces/ecephys/mearec/mearecdatainterface.py

@@ -16,6 +16,12 @@ class MEArecRecordingInterface(BaseRecordingExtractorInterface):
     associated_suffixes = (".h5",)
     info = "Interface for MEArec recording data."
 
+    @classmethod
+    def get_source_schema(cls) -> dict:
+        source_schema = super().get_source_schema()
+        source_schema["properties"]["file_path"]["description"] = "Path to the MEArec .h5 file."
+        return source_schema
+
     def __init__(self, file_path: FilePathType, verbose: bool = True, es_key: str = "ElectricalSeries"):
         """
         Load and prepare data for MEArec.

src/neuroconv/datainterfaces/ecephys/neuralynx/neuralynxdatainterface.py

@@ -24,6 +24,14 @@ def get_stream_names(cls, folder_path: FolderPathType) -> List[str]:
         stream_names, _ = NeuralynxRecordingExtractor.get_streams(folder_path=folder_path)
         return stream_names
 
+    @classmethod
+    def get_source_schema(cls) -> dict:
+        source_schema = super().get_source_schema()
+        source_schema["properties"]["folder_path"][
+            "description"
+        ] = 'Path to Neuralynx directory containing ".nse", ".ntt", ".nse", or ".nev" files.'
+        return source_schema
+
     def __init__(
         self,
         folder_path: FolderPathType,
@@ -37,7 +45,7 @@ def __init__(
         Parameters
         ----------
         folder_path: FolderPathType
-            Path to OpenEphys directory.
+            Path to Neuralynx directory.
         stream_name : str, optional
             The name of the recording stream to load; only required if there is more than one stream detected.
             Call `NeuralynxRecordingInterface.get_stream_names(folder_path=...)` to see what streams are available.

src/neuroconv/datainterfaces/ecephys/neuroscope/neuroscopedatainterface.py

@@ -101,6 +101,12 @@ class NeuroScopeRecordingInterface(BaseRecordingExtractorInterface):
     associated_suffixes = (".dat", ".xml")
     info = "Interface for converting NeuroScope recording data."
 
+    @classmethod
+    def get_source_schema(self) -> dict:
+        source_schema = super().get_source_schema()
+        source_schema["properties"]["file_path"]["description"] = "Path to .dat file."
+        return source_schema
+
     @staticmethod
     def get_ecephys_metadata(xml_file_path: str) -> dict:
         """Auto-populates ecephys metadata from the xml_file_path."""
@@ -188,6 +194,12 @@ class NeuroScopeLFPInterface(BaseLFPExtractorInterface):
 
     ExtractorName = "NeuroScopeRecordingExtractor"
 
+    @classmethod
+    def get_source_schema(self) -> dict:
+        source_schema = super().get_source_schema()
+        source_schema["properties"]["file_path"]["description"] = "Path to .lfp or .eeg file."
+        return source_schema
+
     def __init__(
         self,
         file_path: FilePathType,
@@ -200,7 +212,7 @@ def __init__(
         Parameters
         ----------
         file_path : FilePathType
-            Path to .dat file.
+            Path to .lfp or .eeg file.
         gain : float, optional
             Conversion factors from int16 to Volts are not contained in xml_file_path; set them explicitly here.
             Most common value is 0.195 for an intan recording system.
@@ -240,6 +252,19 @@ class NeuroScopeSortingInterface(BaseSortingExtractorInterface):
     associated_suffixes = (".res", ".clu", ".res.*", ".clu.*", ".xml")
     info = "Interface for converting NeuroScope recording data."
 
+    @classmethod
+    def get_source_schema(self) -> dict:
+        source_schema = super().get_source_schema()
+        source_schema["properties"]["folder_path"]["description"] = "Path to folder containing .res and .clu files."
+        source_schema["properties"]["keep_mua_units"][
+            "description"
+        ] = "Whether to return sorted spikes from multi-unit activity."
+        source_schema["properties"]["exclude_shanks"]["description"] = "List of indices to ignore."
+        source_schema["properties"]["xml_file_path"][
+            "description"
+        ] = "Path to .xml file containing device and electrode configuration."
+        return source_schema
+
     def __init__(
         self,
         folder_path: FolderPathType,
@@ -257,7 +282,6 @@ def __init__(
             Path to folder containing .clu and .res files.
         keep_mua_units : bool, default: True
             Optional. Whether to return sorted spikes from multi-unit activity.
-            The default is True.
         exclude_shanks : list, optional
             List of indices to ignore. The set of all possible indices is chosen by default, extracted as the
             final integer of all the .res.%i and .clu.%i pairs.

src/neuroconv/datainterfaces/ecephys/openephys/openephysbinarydatainterface.py

@@ -65,7 +65,7 @@ def __init__(
         Parameters
         ----------
         folder_path: FolderPathType
-            Path to OpenEphys directory.
+            Path to directory containing OpenEphys binary files.
         stream_name : str, optional
             The name of the recording stream to load; only required if there is more than one stream detected.
             Call `OpenEphysRecordingInterface.get_stream_names(folder_path=...)` to see what streams are available.

src/neuroconv/datainterfaces/ecephys/openephys/openephysdatainterface.py

@@ -16,6 +16,14 @@ class OpenEphysRecordingInterface(BaseRecordingExtractorInterface):
 
     ExtractorName = "OpenEphysBinaryRecordingExtractor"
 
+    @classmethod
+    def get_source_schema(cls) -> dict:
+        source_schema = super().get_source_schema()
+        source_schema["properties"]["folder_path"][
+            "description"
+        ] = "Path to OpenEphys directory (.continuous or .dat files)."
+        return source_schema
+
     def __new__(
         cls,
         folder_path: FolderPathType,

src/neuroconv/datainterfaces/ecephys/openephys/openephyssortingdatainterface.py

@@ -15,7 +15,9 @@ def get_source_schema(cls) -> dict:
         metadata_schema = get_schema_from_method_signature(
             method=cls.__init__, exclude=["recording_id", "experiment_id"]
         )
-        metadata_schema["properties"]["folder_path"].update(description="Path to directory containing OpenEphys files.")
+        metadata_schema["properties"]["folder_path"].update(
+            description="Path to directory containing OpenEphys .spikes files."
+        )
         metadata_schema["additionalProperties"] = False
         return metadata_schema
 

src/neuroconv/datainterfaces/ecephys/phy/phydatainterface.py

@@ -16,9 +16,12 @@ class PhySortingInterface(BaseSortingExtractorInterface):
 
     @classmethod
     def get_source_schema(cls) -> dict:
-        schema = super().get_source_schema()
-        schema["properties"]["exclude_cluster_groups"]["items"] = dict(type="string")
-        return schema
+        source_schema = super().get_source_schema()
+        source_schema["properties"]["exclude_cluster_groups"]["items"] = dict(type="string")
+        source_schema["properties"]["folder_path"][
+            "description"
+        ] = "Path to the output Phy folder (containing the params.py)."
+        return source_schema
 
     def __init__(
         self,

src/neuroconv/datainterfaces/ecephys/plexon/plexondatainterface.py

@@ -15,6 +15,12 @@ class PlexonRecordingInterface(BaseRecordingExtractorInterface):
     associated_suffixes = (".plx",)
     info = "Interface for Plexon recording data."
 
+    @classmethod
+    def get_source_schema(cls) -> dict:
+        source_schema = super().get_source_schema()
+        source_schema["properties"]["file_path"]["description"] = "Path to the .plx file."
+        return source_schema
+
     def __init__(self, file_path: FilePathType, verbose: bool = True, es_key: str = "ElectricalSeries"):
         """
         Load and prepare data for Plexon.
@@ -53,6 +59,12 @@ class PlexonSortingInterface(BaseSortingExtractorInterface):
     associated_suffixes = (".plx",)
     info = "Interface for Plexon sorting data."
 
+    @classmethod
+    def get_source_schema(cls) -> dict:
+        source_schema = super().get_source_schema()
+        source_schema["properties"]["file_path"]["description"] = "Path to the plexon spiking data (.plx file)."
+        return source_schema
+
     def __init__(self, file_path: FilePathType, verbose: bool = True):
         """
         Load and prepare data for Plexon.

src/neuroconv/datainterfaces/ecephys/spike2/spike2datainterface.py

@@ -29,7 +29,7 @@ class Spike2RecordingInterface(BaseRecordingExtractorInterface):
     def get_source_schema(cls) -> dict:
         source_schema = get_schema_from_method_signature(method=cls.__init__, exclude=["smrx_channel_ids"])
         source_schema.update(additionalProperties=True)
-        source_schema["properties"]["file_path"].update(description="Path to CED data file.")
+        source_schema["properties"]["file_path"].update(description="Path to .smr or .smrx file.")
         return source_schema
 
     @classmethod