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: 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_rowpd.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: Series) float [source]¶
Calculate the area of corneal reflection (cr) or eye ellipse fits using the ellipse formula.
- Parameters:
- df_rowpd.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: Series, pupil_areas: Series, outliers: Series, dilation_frames: int = 2) Series [source]¶
Determine eye tracking frames which contain likely blinks or outliers
- Parameters:
- eye_areaspd.Series
A pandas series of eye areas.
- pupil_areaspd.Series
A pandas series of pupil areas.
- outlierspd.Series
A pandas series containing bool values of outlier rows.
- dilation_framesint, 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: DataFrame, z_threshold: float) 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_dfpd.DataFrame
A dataframe containing only columns where outlier detection is desired. (e.g. “cr_area”, “eye_area”, “pupil_area”)
- z_thresholdfloat
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.filter_on_blinks(eye_tracking_data: DataFrame)[source]¶
Set data is specified columns where likely_blink is true to NaN.
Modify the DataFrame in place.
- Parameters:
- eye_tracking_datapandas.DataFrame
Data frame containing eye tracking data.
- allensdk.brain_observatory.behavior.eye_tracking_processing.load_eye_tracking_hdf(eye_tracking_file: Path) 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_filePath
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: DataFrame, frame_times: Series, z_threshold: float = 3.0, dilation_frames: int = 2) DataFrame [source]¶
Processes and refines raw eye tracking data by adding additional computed feature columns.
- Parameters:
- eye_datapd.DataFrame
A ‘raw’ eye tracking dataframe produced by load_eye_tracking_hdf()
- frame_timespd.Series
A series of frame times acquired from a behavior + ophy session ‘sync file’.
- z_thresholdfloat
z-score values higher than the z_threshold will be considered outliers, by default 3.0.
- dilation_framesint, 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.