Add more documentation; Fix LIMS query typo

This is a combination of the following two commits:

1) Add more documentation

   This commit adds more documentation to brain_observatory.behavior
   data api methods.

2) Fix a couple of LIMS query typos

   A set of typos where a semicolon was introduced within a single quote
   block resulted in a non-functional query. This commit fixes these
   typos.

Author: njmei

allensdk/brain_observatory/behavior/session_apis/data_io/behavior_lims_api.py

@@ -73,7 +73,7 @@ def from_foraging_id(cls,
         query = f"""
             SELECT id
             FROM behavior_sessions
-            WHERE foraging_id = '{foraging_id};'
+            WHERE foraging_id = '{foraging_id}';
         """
         session_id = lims_db.fetchone(query, strict=True)
         return cls(session_id, lims_credentials=lims_credentials)
@@ -221,7 +221,7 @@ def get_stimulus_name(self) -> str:
             SELECT stages.name
             FROM behavior_sessions bs
             JOIN stages ON stages.id = bs.state_id
-            WHERE bs.id = '{self.foraging_id};'
+            WHERE bs.id = '{self.foraging_id}';
         """
         return self.mtrain_db.fetchone(query, strict=True)
 

allensdk/brain_observatory/behavior/session_apis/data_io/behavior_ophys_json_api.py

@@ -106,8 +106,8 @@ def get_driver_line(self) -> str:
         return self.data['driver_line']
 
     def external_specimen_name(self) -> int:
-        """Get the external specimen id for the subject associated with an
-        ophys experiment"""
+        """Get the external specimen id (LabTracks ID) for the subject
+        associated with an ophys experiment"""
         return self.data['external_specimen_name']
 
     def get_full_genotype(self) -> str:
@@ -116,6 +116,7 @@ def get_full_genotype(self) -> str:
         return self.data['full_genotype']
 
     def get_behavior_stimulus_file(self) -> str:
+        """Get the filepath to the StimulusPickle file for the session"""
         return self.data['behavior_stimulus_file']
 
     def get_dff_file(self) -> str:

allensdk/brain_observatory/behavior/session_apis/data_io/behavior_ophys_lims_api.py

@@ -49,6 +49,8 @@ def get_ophys_experiment_id(self) -> int:
 
     @memoize
     def get_ophys_session_id(self) -> int:
+        """Get the ophys session id associated with the ophys experiment
+        id used to initialize the API"""
         query = """
                 SELECT os.id FROM ophys_sessions os
                 JOIN ophys_experiment oe ON oe.ophys_session_id = os.id
@@ -58,6 +60,8 @@ def get_ophys_session_id(self) -> int:
 
     @memoize
     def get_experiment_container_id(self) -> int:
+        """Get the experiment container id associated with the ophys
+        experiment id used to initialize the API"""
         query = """
                 SELECT visual_behavior_experiment_container_id
                 FROM ophys_experiments_visual_behavior_experiment_containers
@@ -67,6 +71,8 @@ def get_experiment_container_id(self) -> int:
 
     @memoize
     def get_behavior_stimulus_file(self) -> str:
+        """Get the filepath to the StimulusPickle file for the session
+        associated with the ophys experiment id used to initialize the API"""
         query = """
                 SELECT wkf.storage_directory || wkf.filename AS stim_file
                 FROM ophys_experiments oe
@@ -83,6 +89,8 @@ def get_behavior_stimulus_file(self) -> str:
 
     @memoize
     def get_nwb_filepath(self) -> str:
+        """Get the filepath of the nwb file associated with the ophys
+        experiment"""
         query = """
                 SELECT wkf.storage_directory || wkf.filename AS nwb_file
                 FROM ophys_experiments oe
@@ -96,6 +104,8 @@ def get_nwb_filepath(self) -> str:
 
     @memoize
     def get_eye_tracking_filepath(self) -> str:
+        """Get the filepath of the eye tracking file (*.h5) associated with the
+        ophys experiment"""
         query = """
                 SELECT wkf.storage_directory || wkf.filename
                 AS eye_tracking_file
@@ -112,7 +122,7 @@ def get_eye_tracking_filepath(self) -> str:
 
     @staticmethod
     def get_ophys_experiment_df() -> pd.DataFrame:
-
+        """Get a DataFrame of metadata for ophys experiments"""
         api = (credential_injector(LIMS_DB_CREDENTIAL_MAP)
                (PostgresQueryMixin)())
         query = """

allensdk/brain_observatory/behavior/session_apis/data_io/ophys_lims_api.py

@@ -55,7 +55,7 @@ def get_plane_group_count(self) -> int:
                 ON pg.id = oe.ophys_imaging_plane_group_id
             WHERE
                 -- only 1 session for an experiment
-                os.id = (SELECT id from sess limit 1)
+                os.id = (SELECT id from sess limit 1);
         """
         return self.lims_db.fetchone(query, strict=True)
 
@@ -72,7 +72,7 @@ def get_imaging_plane_group(self) -> Optional[int]:
             FROM ophys_experiments oe
             JOIN ophys_imaging_plane_groups pg
             ON pg.id = oe.ophys_imaging_plane_group_id
-            WHERE oe.id = {self.get_ophys_experiment_id()}
+            WHERE oe.id = {self.get_ophys_experiment_id()};
         """
         # Non-mesoscope data will not have results
         group_order = self.lims_db.fetchall(query)
@@ -93,7 +93,7 @@ def get_behavior_session_id(self) -> Optional[int]:
             JOIN ophys_sessions os ON oe.ophys_session_id = os.id
             -- but not every ophys_session has a behavior_session
             LEFT JOIN behavior_sessions bs ON os.id = bs.ophys_session_id
-            WHERE oe.id = {self.get_ophys_experiment_id()}
+            WHERE oe.id = {self.get_ophys_experiment_id()};
         """
         response = self.lims_db.fetchall(query)     # Can be null
         if not len(response):
@@ -260,8 +260,8 @@ def get_driver_line(self) -> str:
 
     @memoize
     def get_external_specimen_name(self) -> int:
-        """Get the external specimen id for the subject associated with an
-        ophys experiment"""
+        """Get the external specimen id (LabTracks ID) for the subject
+        associated with an ophys experiment"""
         query = """
                 SELECT sp.external_specimen_name
                 FROM ophys_experiments oe
@@ -454,7 +454,7 @@ def get_raw_cell_specimen_table_dict(self) -> dict:
         query = """
                 SELECT *
                 FROM cell_rois cr
-                WHERE cr.ophys_cell_segmentation_run_id = {}
+                WHERE cr.ophys_cell_segmentation_run_id = {};
                 """.format(ophys_cell_seg_run_id)
         initial_cs_table = pd.read_sql(query, self.lims_db.get_connection())
         cell_specimen_table = initial_cs_table.rename(