Updated docstrings after code review

Author: kushalbakshi

element_array_ephys/ephys_acute.py

@@ -21,8 +21,14 @@
 _linking_module = None
 
 
-def activate(ephys_schema_name, probe_schema_name=None, *, create_schema=True,
-             create_tables=True, linking_module=None):
+def activate(
+    ephys_schema_name: str,
+    probe_schema_name: str = None,
+    *,
+    create_schema: bool = True,
+    create_tables: bool = True,
+    linking_module: str = None,
+):
     """Activates the `ephys` and `probe` schemas. 
 
     Args:
@@ -31,6 +37,17 @@ def activate(ephys_schema_name, probe_schema_name=None, *, create_schema=True,
         create_schema (bool): If True, schema will be created in the database.
         create_tables (bool): If True, tables related to the schema will be created in the database.
         linking_module (str): A string containing the module name or module containing the required dependencies to activate the schema.
+    
+    Dependencies:
+
+    Upstream tables:
+        Session: A parent table to ProbeInsertion
+        Probe: A parent table to EphysRecording. Probe information is required before electrophysiology data is imported.
+        
+    Functions: 
+        get_ephys_root_data_dir(): Returns absolute path for root data director(y/ies) with all electrophysiological recording sessions, as a list of string(s).
+        get_session_direction(session_key: dict): Returns path to electrophysiology data for the a particular session as a list of strings.
+        get_processed_data_dir(): Optional. Returns absolute path for processed data. Defaults to root directory. 
     """
 
     if isinstance(linking_module, str):
@@ -71,7 +88,8 @@ def get_session_directory(session_key: dict) -> str:
     """Retrieve the session directory with Neuropixels for the given session.
 
     Args:
-        session_key (dict): A dictionary mapping subject to an entry in the subject table, and session_datetime corresponding to a session in the database. 
+        session_key (dict): A dictionary mapping subject to an entry in the subject table, and session_datetime corresponding to a session in the database.
+
     Returns: 
         A string for the path to the session directory. 
     """
@@ -216,8 +234,8 @@ class EphysRecording(dj.Imported):
 
     Attributes:
         ProbeInsertion (foreign key): ProbeInsertion primary key. 
-        probe.ElectrodeConfig (query): probe.ElectrodeConfig primary key. 
-        AcquisitionSoftware (query): AcquisitionSoftware primary key.
+        probe.ElectrodeConfig (dict): probe.ElectrodeConfig primary key. 
+        AcquisitionSoftware (dict): AcquisitionSoftware primary key.
         sampling_rate (float): sampling rate of the recording in Hertz (Hz).
         recording_datetime (datetime): datetime of the recording from this probe.
         recording_duration (float): duration of the entire recording from this probe in seconds. 
@@ -238,7 +256,7 @@ class EphysFile(dj.Part):
         """Paths of electrophysiology recording files for each insertion.
 
         Attributes:
-            master (foreign key): EphysRecording primary key.
+            EphysRecording (foreign key): EphysRecording primary key.
             file_path (varchar(255) ): relative file path for electrophysiology recording.
         """
 
@@ -384,7 +402,7 @@ class Electrode(dj.Part):
         """Saves local field potential data for each electrode.
 
         Attributes: 
-            master (foreign key): LFP primary key.
+            LFP (foreign key): LFP primary key.
             probe.ElectrodeConfig.Electrode (foreign key): probe.ElectrodeConfig.Electrode primary key.
             lfp (longblob): LFP recording at this electrode in microvolts.
         """
@@ -496,7 +514,7 @@ class ClusteringParamSet(dj.Lookup):
 
     Attributes: 
         paramset_idx (foreign key): Unique ID for the clustering parameter set. 
-        ClusteringMethod (query): ClusteringMethod primary key.
+        ClusteringMethod (dict): ClusteringMethod primary key.
         paramset_desc (varchar(128) ): Description of the clustering parameter set.
         param_set_hash (uuid): UUID hash for the parameter set. 
         params (longblob)
@@ -583,7 +601,7 @@ class ClusteringTask(dj.Manual):
         EphysRecording (foreign key): EphysRecording primary key.
         ClusteringParamSet (foreign key): ClusteringParamSet primary key.
         clustering_outdir_dir (varchar (255) ): Relative path to output clustering results. 
-        task_mode (enum('load', 'trigger') ): Either loads or computes clustering.
+        task_mode (enum): `Trigger` and `load` either computes clustering or imports existing clustering data, respectively.
     """
 
     definition = """
@@ -596,7 +614,7 @@ class ClusteringTask(dj.Manual):
     """
 
     @classmethod
-    def infer_output_dir(cls, key, relative=False, mkdir=False):
+    def infer_output_dir(cls, key: dict, relative: bool = False, mkdir: bool = False):
         """Infer output directory if it is not provided. 
         
         Args:
@@ -626,7 +644,7 @@ def infer_output_dir(cls, key, relative=False, mkdir=False):
         return output_dir.relative_to(processed_dir) if relative else output_dir
 
     @classmethod
-    def auto_generate_entries(cls, ephys_recording_key, paramset_idx=0):
+    def auto_generate_entries(cls, ephys_recording_key: dict, paramset_idx: int = 0):
         """Autogenerate entries based on a particular ephys recording.
 
         Args:
@@ -822,10 +840,10 @@ class Unit(dj.Part):
         """Single unit properties after clustering and curation.
 
         Attributes: 
-            master (foreign key): CuratedClustering primary key. 
+            CuratedClustering (foreign key): CuratedClustering primary key. 
             unit (foreign key, int): Unique integer identifying a single unit.
-            probe.ElectrodeConfig.Electrode (query): probe.ElectrodeConfig.Electrode primary key.
-            ClusteringQualityLabel (query): CLusteringQualityLabel primary key.
+            probe.ElectrodeConfig.Electrode (dict): probe.ElectrodeConfig.Electrode primary key.
+            ClusteringQualityLabel (dict): CLusteringQualityLabel primary key.
             spike_count (int): Number of spikes in this recording for this unit.
             spike_times (longblob): Spike times of this unit, relative to start time of EphysRecording. 
             spike_sites (longblob): Array of electrode associated with each spike.
@@ -918,7 +936,7 @@ class PeakWaveform(dj.Part):
         """Mean waveform across spikes for a given unit. 
 
         Attributes:
-            master (foreign key): WaveformSet primary key. 
+            WaveformSet (foreign key): WaveformSet primary key. 
             CuratedClustering.Unit (foreign key): CuratedClustering.Unit primary key.
             peak_electrode_waveform (longblob): Mean waveform for a given unit at its representative electrode. 
         """
@@ -935,7 +953,7 @@ class Waveform(dj.Part):
         """Spike waveforms for a given unit. 
 
         Attributes:
-            master (foreign key): WaveformSet primary key.
+            WaveformSet (foreign key): WaveformSet primary key.
             CuratedClustering.Unit (foreign key): CuratedClustering.Unit primary key. 
             probe.ElectrodeConfig.Electrode (foreign key): probe.ElectrodeConfig.Electrode primary key.
             waveform_mean (longblob): mean waveform across spikes of the unit in microvolts. 
@@ -1051,7 +1069,7 @@ class Cluster(dj.Part):
         """Cluster metrics for a unit.
 
         Attributes: 
-            master (foreign key): QualityMetrics primary key. 
+            QualityMetrics (foreign key): QualityMetrics primary key. 
             CuratedClustering.Unit (foreign key): CuratedClustering.Unit primary key. 
             firing_rate (float): Firing rate of the unit.
             snr (float): Signal-to-noise ratio for a unit.
@@ -1095,7 +1113,7 @@ class Waveform(dj.Part):
         """Waveform metrics for a particular unit. 
 
         Attributes: 
-            master (foreign key): QualityMetrics primary key. 
+            QualityMetrics (foreign key): QualityMetrics primary key. 
             CuratedClustering.Unit (foreign key): CuratedClustering.Unit primary key. 
             amplitude (float): Absolute difference between waveform peak and trough in microvolts. 
             duration (float): Time between waveform peak and trough in milliseconds. 
@@ -1150,7 +1168,7 @@ def make(self, key):
 
 # ---------------- HELPER FUNCTIONS ----------------
 
-def get_spikeglx_meta_filepath(ephys_recording_key):
+def get_spikeglx_meta_filepath(ephys_recording_key: dict) -> str:
     """Get spikeGLX data filepath.
     """
     # attempt to retrieve from EphysRecording.EphysFile
@@ -1187,7 +1205,7 @@ def get_spikeglx_meta_filepath(ephys_recording_key):
     return spikeglx_meta_filepath
 
 
-def get_openephys_probe_data(ephys_recording_key):
+def get_openephys_probe_data(ephys_recording_key: dict) -> list:
     """Get OpenEphys probe data from file.
     """
     inserted_probe_serial_number = (ProbeInsertion * probe.Probe
@@ -1205,7 +1223,7 @@ def get_openephys_probe_data(ephys_recording_key):
     return probe_data
 
 
-def get_neuropixels_channel2electrode_map(ephys_recording_key, acq_software):
+def get_neuropixels_channel2electrode_map(ephys_recording_key: dict, acq_software: str) -> dict:
     """Get the channel map for neuropixels probe.
     """
     if acq_software == 'SpikeGLX':
@@ -1243,12 +1261,13 @@ def get_neuropixels_channel2electrode_map(ephys_recording_key, acq_software):
     return channel2electrode_map
 
 
-def generate_electrode_config(probe_type: str, electrodes: list):
+def generate_electrode_config(probe_type: str, electrodes: list) -> dict:
     """Generate and insert new ElectrodeConfig
     
     Args:
         probe_type (str): probe type (e.g. neuropixels 2.0 - SS)
         electrodes (list): Electrode dict (keys of the probe.ProbeType.Electrode table)
+
     Returns:
         dict: representing a key of the probe.ElectrodeConfig table
     """
@@ -1275,8 +1294,8 @@ def generate_electrode_config(probe_type: str, electrodes: list):
     return electrode_config_key
 
 
-def get_recording_channels_details(ephys_recording_key):
-    """Get details of recording channels for a givenn recording.
+def get_recording_channels_details(ephys_recording_key: dict) -> np.array:
+    """Get details of recording channels for a given recording.
     """
     channels_details = {}