Merge pull request #1703 from AllenInstitute/rc/2.3.0

rc/2.3.0

Author: djkapner

CHANGELOG.md

@@ -1,6 +1,20 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
+## [2.3.0] = 2020-10-09
+
+### Added
+- Adds load sync data for individual plane sets to relate accurate event timings to mesoscope data.
+- Adds public API method to access the behavior\_session\_id from an instance of BehaviorOphysSession.
+
+### Changes
+- Visual behavior running speed is now low-pass filtered at 10Hz. The raw running speed data is still available. The running speed is corrected for encoder threshold croissing artifacts.
+- Support for stimulus gratings for visual behavior.
+- Updates to some visual behavior pynwb implementations.
+
+### Bug Fixes
+- Fixed an eye-tracking sync problem.
+
 ## [2.2.0] = 2020-09-03
 
 ### Added

allensdk/__init__.py

@@ -37,7 +37,7 @@
 
 
 
-__version__ = '2.2.0'
+__version__ = '2.3.0'
 
 
 try:

allensdk/brain_observatory/behavior/behavior_data_session.py

@@ -19,6 +19,8 @@ def __init__(self, api: Optional[BehaviorDataApi] = None):
         self._rewards = None
         self._running_data_df = None
         self._running_speed = None
+        self._raw_running_data_df = None
+        self._raw_running_speed = None
         self._stimulus_presentations = None
         self._stimulus_templates = None
         self._stimulus_timestamps = None
@@ -92,17 +94,39 @@ def rewards(self) -> pd.DataFrame:
     def rewards(self, value):
         self._rewards = value
 
+    @property
+    def raw_running_data_df(self) -> pd.DataFrame:
+        """Get running speed data without the 10Hz low pass filter.
+
+            Returns
+            -------
+            pd.DataFrame
+                Dataframe containing various signals used to compute running
+                speed, and the unfiltered speed.
+        """
+        if self._raw_running_data_df is None:
+            self._raw_running_data_df = self.api.get_running_data_df(
+                lowpass=False)
+        return self._raw_running_data_df
+
+    @raw_running_data_df.setter
+    def raw_running_data_df(self, value):
+        self._raw_running_data_df = value
+
     @property
     def running_data_df(self) -> pd.DataFrame:
-        """Get running speed data.
+        """Get running speed data. By default applies a 10Hz low pass
+        filter to the data. To get the running speed without the filter,
+        use `raw_running_data_df`.
 
         Returns
         -------
         pd.DataFrame
-            Dataframe containing various signals used to compute running speed.
+            Dataframe containing various signals used to compute running
+            speed, and the filtered speed.
         """
         if self._running_data_df is None:
-            self._running_data_df = self.api.get_running_data_df()
+            self._running_data_df = self.api.get_running_data_df(lowpass=True)
         return self._running_data_df
 
     @running_data_df.setter
@@ -112,7 +136,8 @@ def running_data_df(self, value):
     @property
     def running_speed(self) -> RunningSpeed:
         """Get running speed using timestamps from
-        self.get_stimulus_timestamps.
+        self.get_stimulus_timestamps. Applies a 10Hz filter to the 
+        speed. To get the unfiltered speed, use `raw_running_speed`.
 
         NOTE: Do not correct for monitor delay.
 
@@ -125,13 +150,36 @@ def running_speed(self) -> RunningSpeed:
                 Running speed of the experimental subject (in cm / s).
         """
         if self._running_speed is None:
-            self._running_speed = self.api.get_running_speed()
+            self._running_speed = self.api.get_running_speed(lowpass=True)
         return self._running_speed
 
     @running_speed.setter
     def running_speed(self, value):
         self._running_speed = value
 
+    @property
+    def raw_running_speed(self) -> RunningSpeed:
+        """Get running speed using timestamps from
+        self.get_stimulus_timestamps. Does not apply the 10Hz filter.
+
+        NOTE: Do not correct for monitor delay.
+
+        Returns
+        -------
+        RunningSpeed (NamedTuple with two fields)
+            timestamps : np.ndarray
+                Timestamps of running speed data samples
+            values : np.ndarray
+                Running speed of the experimental subject (in cm / s).
+        """
+        if self._raw_running_speed is None:
+            self._raw_running_speed = self.api.get_running_speed(lowpass=False)
+        return self._raw_running_speed
+
+    @raw_running_speed.setter
+    def raw_running_speed(self, value):
+        self._raw_running_speed = value
+
     @property
     def stimulus_presentations(self) -> pd.DataFrame:
         """Get stimulus presentation data.

allensdk/brain_observatory/behavior/behavior_ophys_api/behavior_ophys_nwb_api.py

@@ -18,13 +18,13 @@
 from allensdk.brain_observatory.nwb.nwb_api import NwbApi
 from allensdk.brain_observatory.nwb.nwb_utils import set_omitted_stop_time
 from allensdk.brain_observatory.behavior.trials_processing import TRIAL_COLUMN_DESCRIPTION_DICT
-from allensdk.brain_observatory.behavior.schemas import OphysBehaviorMetaDataSchema, OphysBehaviorTaskParametersSchema
-from allensdk.brain_observatory.nwb.metadata import load_LabMetaData_extension
+from allensdk.brain_observatory.behavior.schemas import OphysBehaviorMetadataSchema, BehaviorTaskParametersSchema
+from allensdk.brain_observatory.nwb.metadata import load_pynwb_extension
 from allensdk.brain_observatory.behavior.behavior_ophys_api import BehaviorOphysApiBase
 
 
-load_LabMetaData_extension(OphysBehaviorMetaDataSchema, 'AIBS_ophys_behavior')
-load_LabMetaData_extension(OphysBehaviorTaskParametersSchema, 'AIBS_ophys_behavior')
+load_pynwb_extension(OphysBehaviorMetadataSchema, 'ndx-aibs-behavior-ophys')
+load_pynwb_extension(BehaviorTaskParametersSchema, 'ndx-aibs-behavior-ophys')
 
 
 class BehaviorOphysNwbApi(NwbApi, BehaviorOphysApiBase):
@@ -170,16 +170,26 @@ def get_segmentation_mask_image(self, image_api=None) -> sitk.Image:
     def get_metadata(self) -> dict:
 
         metadata_nwb_obj = self.nwbfile.lab_meta_data['metadata']
-        data = OphysBehaviorMetaDataSchema(exclude=['experiment_datetime']).dump(metadata_nwb_obj)
+        data = OphysBehaviorMetadataSchema(exclude=['experiment_datetime']).dump(metadata_nwb_obj)
+
+        # Add subject related metadata to behavior ophys metadata
+        nwb_subject = self.nwbfile.subject
+        data['LabTracks_ID'] = int(nwb_subject.subject_id)
+        data['sex'] = nwb_subject.sex
+        data['age'] = nwb_subject.age
+        data['full_genotype'] = nwb_subject.genotype
+        data['reporter_line'] = list(nwb_subject.reporter_line)
+        data['driver_line'] = list(nwb_subject.driver_line)
+
         experiment_datetime = metadata_nwb_obj.experiment_datetime
-        data['experiment_datetime'] = OphysBehaviorMetaDataSchema().load({'experiment_datetime': experiment_datetime}, partial=True)['experiment_datetime']            
+        data['experiment_datetime'] = OphysBehaviorMetadataSchema().load({'experiment_datetime': experiment_datetime}, partial=True)['experiment_datetime']            
         data['behavior_session_uuid'] = uuid.UUID(data['behavior_session_uuid'])
         return data
 
     def get_task_parameters(self) -> dict:
 
         metadata_nwb_obj = self.nwbfile.lab_meta_data['task_parameters']
-        data = OphysBehaviorTaskParametersSchema().dump(metadata_nwb_obj)
+        data = BehaviorTaskParametersSchema().dump(metadata_nwb_obj)
         return data
 
     def get_cell_specimen_table(self) -> pd.DataFrame:

allensdk/brain_observatory/behavior/behavior_ophys_session.py

@@ -1,7 +1,7 @@
 import numpy as np
 import pandas as pd
 import xarray as xr
-from typing import Any
+from typing import Any, Optional
 import logging
 
 
@@ -71,6 +71,8 @@ def __init__(self, api=None,
         self._cell_specimen_table = None
         self._running_speed = None
         self._running_data_df = None
+        self._raw_running_speed = None
+        self._raw_running_data_df = None
         self._stimulus_presentations = None
         self._stimulus_templates = None
         self._licks = None
@@ -96,6 +98,13 @@ def ophys_experiment_id(self) -> int:
         """
         return self.api.get_ophys_experiment_id()
 
+    @property
+    def behavior_session_id(self) -> Optional[int]:
+        """Returns the unique identifier for the behavior session
+        associated with this experiment, if applicable.
+        """
+        return self.api.get_behavior_session_id()
+
     @property
     def max_projection(self) -> Image:
         """2D max projection image.
@@ -172,12 +181,16 @@ def cell_specimen_table(self, value):
 
     @property
     def running_speed(self) -> RunningSpeed:
-        """Running speed of mouse.  NamedTuple with two fields
+        """Running speed of mouse, filtered with 10Hz low pass filter,
+        To get the unfiltered running speed, use `raw_running_speed`.
+        Returns
+        -------
+        allensdk.brain_observatory.running_speed.RunningSpeed
+            NamedTuple with two fields:
             timestamps : numpy.ndarray
                 Timestamps of running speed data samples
             values : np.ndarray
                 Running speed of the experimental subject (in cm / s).
-        :rtype: allensdk.brain_observatory.running_speed.RunningSpeed
         """
         if self._running_speed is None:
             self._running_speed = self.api.get_running_speed()
@@ -187,19 +200,66 @@ def running_speed(self) -> RunningSpeed:
     def running_speed(self, value):
         self._running_speed = value
 
+    @property
+    def raw_running_speed(self) -> RunningSpeed:
+        """Running speed of mouse, unfiltered.
+
+        Returns
+        -------
+        allensdk.brain_observatory.running_speed.RunningSpeed
+            NamedTuple with two fields:
+            timestamps : numpy.ndarray
+                Timestamps of running speed data samples
+            values : np.ndarray
+                Running speed of the experimental subject (in cm / s).
+        """
+        if self._raw_running_speed is None:
+            self._raw_running_speed = self.api.get_running_speed(lowpass=False)
+        return self._raw_running_speed
+
+    @raw_running_speed.setter
+    def raw_running_speed(self, value):
+        self._raw_running_speed = value
+
     @property
     def running_data_df(self) -> pd.DataFrame:
-        """Dataframe containing various signals used to compute running speed
-        :rtype: pandas.DataFrame
+        """Get running speed data. By default applies a 10Hz low pass
+        filter to the data. To get the running speed without the filter,
+        use `raw_running_data_df`.
+
+        Returns
+        -------
+        pd.DataFrame
+            Dataframe containing various signals used to compute running
+            speed, and the filtered speed.
         """
         if self._running_data_df is None:
-            self._running_data_df = self.api.get_running_data_df()
+            self._running_data_df = self.api.get_running_data_df(lowpass=True)
         return self._running_data_df
 
     @running_data_df.setter
     def running_data_df(self, value):
         self._running_data_df = value
 
+    @property
+    def raw_running_data_df(self) -> pd.DataFrame:
+        """Get running speed  data. Does not apply the 10Hz filter.
+
+        Returns
+        -------
+        pd.DataFrame
+            Dataframe containing various signals used to compute running
+            speed, and the unfilteredfiltered speed.
+        """
+        if self._raw_running_data_df is None:
+            self._raw_running_data_df = self.api.get_running_data_df(
+                lowpass=False)
+        return self._raw_running_data_df
+
+    @raw_running_data_df.setter
+    def raw_running_data_df(self, value):
+        self._raw_running_data_df = value
+
     @property
     def stimulus_presentations(self) -> pd.DataFrame:
         """Table whose rows are stimulus presentations (i.e. a given image,

allensdk/brain_observatory/behavior/internal/behavior_base.py

@@ -14,6 +14,13 @@ class BehaviorBase(abc.ABC):
     Child classes should be instantiated with a fetch API that implements these
     methods.
     """
+    @abc.abstractmethod
+    def get_behavior_session_id(self) -> int:
+        """Returns the behavior_session_id associated with this experiment,
+        if applicable.
+        """
+        raise NotImplementedError()
+
     @abc.abstractmethod
     def get_licks(self) -> pd.DataFrame:
         """Get lick data from pkl file.

allensdk/brain_observatory/behavior/internal/behavior_ophys_base.py

@@ -1,4 +1,5 @@
 import abc
+from typing import Optional
 
 import numpy as np
 import pandas as pd
@@ -12,8 +13,16 @@ class BehaviorOphysBase(BehaviorBase):
     behavior+ophys session data.
 
     Child classes should be instantiated with a fetch API that implements these
-    methods. Both fetch API and session object should inherit from this base.
+    methods.
     """
+
+    @abc.abstractmethod
+    def get_ophys_session_id(self) -> Optional[int]:
+        """Returns the ophys_session_id associated with this experiment,
+        if applicable.
+        """
+        raise NotImplementedError()
+
     @abc.abstractmethod
     def get_average_projection(self) -> Image:
         """Get an image whose values are the average obtained values at