allensdk.brain_observatory.behavior.eye_tracking_processing module

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

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:
RuntimeError

If the number of sync file frame times does not match the number of eye tracking frames.