allensdk.brain_observatory.behavior.eye_tracking_processing module¶
-
exception
allensdk.brain_observatory.behavior.eye_tracking_processing.
EyeTrackingError
[source]¶ Bases:
Exception
-
allensdk.brain_observatory.behavior.eye_tracking_processing.
compute_circular_area
(df_row: pandas.core.series.Series) → float[source]¶ Calculate the area of the pupil as a circle using the max of the height/width as radius.
Note: This calculation assumes that the pupil is a perfect circle and any eccentricity is a result of the angle at which the pupil is being viewed.
Parameters: - df_row : pd.Series
A row from an eye tracking dataframe containing only “pupil_width” and “pupil_height”.
Returns: - float
The circular area of the pupil in pixels^2.
-
allensdk.brain_observatory.behavior.eye_tracking_processing.
compute_elliptical_area
(df_row: pandas.core.series.Series) → float[source]¶ Calculate the area of corneal reflection (cr) or eye ellipse fits using the ellipse formula.
Parameters: - df_row : pd.Series
A row from an eye tracking dataframe containing either: “cr_width”, “cr_height” or “eye_width”, “eye_height”
Returns: - float
The elliptical area of the eye or cr in pixels^2
-
allensdk.brain_observatory.behavior.eye_tracking_processing.
determine_likely_blinks
(eye_areas: pandas.core.series.Series, pupil_areas: pandas.core.series.Series, outliers: pandas.core.series.Series, dilation_frames: int = 2) → pandas.core.series.Series[source]¶ Determine eye tracking frames which contain likely blinks or outliers
Parameters: - eye_areas : pd.Series
A pandas series of eye areas.
- pupil_areas : pd.Series
A pandas series of pupil areas.
- outliers : pd.Series
A pandas series containing bool values of outlier rows.
- dilation_frames : int, optional
Determines the number of additional adjacent frames to mark as ‘likely_blink’, by default 2.
Returns: - pd.Series
A pandas series of bool values that has the same length as the number of eye tracking dataframe rows (frames).
-
allensdk.brain_observatory.behavior.eye_tracking_processing.
determine_outliers
(data_df: pandas.core.frame.DataFrame, z_threshold: float) → pandas.core.series.Series[source]¶ Given a dataframe and some z-score threshold return a pandas boolean Series where each entry indicates whether a given row contains at least one outlier (where outliers are calculated along columns).
Parameters: - data_df : pd.DataFrame
A dataframe containing only columns where outlier detection is desired. (e.g. “cr_area”, “eye_area”, “pupil_area”)
- z_threshold : float
z-score values higher than the z_threshold will be considered outliers.
Returns: - pd.Series
A pandas boolean Series whose length == len(data_df.index). True denotes that a row in the data_df contains at least one outlier.
-
allensdk.brain_observatory.behavior.eye_tracking_processing.
load_eye_tracking_hdf
(eye_tracking_file: pathlib.Path) → pandas.core.frame.DataFrame[source]¶ Load a DeepLabCut hdf5 file containing eye tracking data into a dataframe.
Note: The eye tracking hdf5 file contains 3 separate dataframes. One for corneal reflection (cr), eye, and pupil ellipse fits. This function loads and returns this data as a single dataframe.
Parameters: - eye_tracking_file : Path
Path to an hdf5 file produced by the DeepLabCut eye tracking pipeline. The hdf5 file will contain the following keys: “cr”, “eye”, “pupil”. Each key has an associated dataframe with the following columns: “center_x”, “center_y”, “height”, “width”, “phi”.
Returns: - pd.DataFrame
A dataframe containing combined corneal reflection (cr), eyelid (eye), and pupil data. Column names for each field will be renamed by prepending the field name. (e.g. center_x -> eye_center_x)
-
allensdk.brain_observatory.behavior.eye_tracking_processing.
process_eye_tracking_data
(eye_data: pandas.core.frame.DataFrame, frame_times: pandas.core.series.Series, z_threshold: float = 3.0, dilation_frames: int = 2) → pandas.core.frame.DataFrame[source]¶ Processes and refines raw eye tracking data by adding additional computed feature columns.
Parameters: - eye_data : pd.DataFrame
A ‘raw’ eye tracking dataframe produced by load_eye_tracking_hdf()
- frame_times : pd.Series
A series of frame times acquired from a behavior + ophy session ‘sync file’.
- z_threshold : float
z-score values higher than the z_threshold will be considered outliers, by default 3.0.
- dilation_frames : int, optional
Determines the number of additional adjacent frames to mark as ‘likely_blink’, by default 2.
Returns: - pd.DataFrame
A refined eye tracking dataframe that contains additional information about frame times, eye areas, pupil areas, and frames with likely blinks/outliers.
Raises: - EyeTrackingError
If the number of sync file frame times does not match the number of eye tracking frames.