API Reference

abra.data

abra.data.read

function abra.data.read(filename, eyes_recorded = "auto", both_eyes_recorded = False,
                        mode="d", start_msg=r"TRIAL \d{1,2} START",
                        end_msg=r"TRIAL \d{1,2} END")

The read function is used to create a data object that will contain important information from the eye-tracking data file. The information stored are timestamps, pupil size, eye movements, messages, events, trial markers (start and end), and sample rates. You can use the parameters to create specialized data extractions. Read function will read in the ascii file and extract the data.

Parameters:

  • file_name: Takes in the name of the file you are trying to extract data from

  • mode: 'd' = default, use the default start and end times given in the file. 'u' = user defined, take in start_msg and end_msg to use as the.

  • eyes_recorded: Define which eye data to extract if both eyes are being recorded. default is "auto" which will take whichever eye it finds first

  • both_eyes_recorded: True = if both eyes were recorded. False = is only the left or right eyes was being recorded.

  • start_msg: use regular expression to identify the user inputed start message markers, ex. r"TRIAL \d START"

  • end_msg: use regular expression to identify the user inputed end message makers, ex. r"TRIAL \d END"

Returns:


function remove_eye_blinks(abra_obj, buffer=50, interpolate='linear', inplace=False)

Takes in the data object made from the read function and removes eye blinks from the data.

Parameters:

  • abra_obj: data object

  • buffer: Time in ms of a buffer to remove eye blinks from data. Default is set to 50ms

  • interpolate: Option of whether you would like to interpolate the data. Default is "linear" None is the other option

  • inplace: Option to remove eye blinks inplace or not

Return:

dataobj = abra.data.read(filename)

rm_blink = abra.data.remove_eye_blinks(dataobj)


abra.data.Data

The data object is an object created by the read function. The object stores timestamps, start and end trial markers, sample rate, messages, event (fixation and saccade), pupil size, and eye movements.

Parameters:

  • timestamps List, List of timestamps within the eye-tracker data.

  • sample_rate: int, The value of the sample rate of the data.

  • messages: List, List of messages that are within the trials in the eye-tracker data.

  • events: dict, The events dictionary of holds all event triggers within the data. The key is the event type and the value is the information that the event contained.

  • trial_markers: dict, trial_markers is a dictionary that holds the timestamps of the start and end of the specified events. The keys are "start" and "end".

  • pupil_size: List, The pupil_size list hold float values of the pupil size within the trials recorded. The pupil_size list has the same indexing as timestamps. eg. index 0 for pupil_size is correlated to the timestamp at timestamp index 0

  • movement: list, Movement is a 2d list that hold values for the x-axis and y-axis. Movement[0] is a list of movement coordinates at the x-axis. Movement[1] is a list of movement coordinates at the y-axis. Both list indexing is correlated to the indexing of timestamps.

Return:

  • Data: returns a data object

Methods:

abra.data.Data.create_session

Method create_session(self, conditions=None)

create_session is a function within the data object. The function will sort the data into a list of trial objects. This function will return a session object.

Parameter:

  • conditions: condition you want to apply to the method. Default is None

Returns:

  • Session: The Session object that contains a list of Trial objects.
 data = abra.data.read(filename)
 data.create_session()

abra.data.Data.create_epochs

Method create_epochs(self, event_timestamps, conditions=None,
              pre_event=200, post_event=200, pupil_baseline=None)

The create_epoch function creates a list of time-locked epochs and returns an epoch object.

Parameters:

  • event_timestamps: Starting timestamps for all time locked events.

  • conditions:Desired event condition.

  • pre_event: Milliseconds before defined starting timestamps.

  • post_event: Milliseconds after defined starting timestamps.

  • pupil_baseline: Baselining for pupil size data. The baseline period will be the milliseconds before pre_event

Return:

  • Epoch: The Epoch objects that contains a list of the time locked trials
data = abra.data.read(filename)
data.create_epochs(conditions = None, pre_event = 200, post_event = 200, pupil_baseline = None)


abra.trial

abra.trial.Trial

Class Trial(self, timestamps, pupil_size, movement_X = [], movement_y = [], event_L = [], event_R = [])

Parameters:

  • timestamps: list of timestamps
  • pupil_size: list of pupil sizes
  • movement_X: list of movements in x-axis
  • movement_y: list of movements in y-axis
  • event_L: list of fixation events for the left eye
  • event_R: list of fixation events for the right eye

Return:

  • Trial: returns a Trial object

Method:

abra.trail.Trial.summary

Method summary(self, verbose = False)

Returns a dictionary of statistics of pupil data.

Parameters:

  • verbose: boolean, True will print the summary.

Return:

  • summary: Dictionary of summary statistic for pupil size containing, [mean]: pupil mean, [variance]: pupil variance, [stdev]: pupil standard deviation, [length]: pupil size, [min]: pupil minimum, [max]: pupil maximum

abra.session

abra.session.base

Class Base(self, data, sample_rate, conditions=None)

Parameters:

  • data: List of Trial objects

  • sample_rate: Hold the value of the sample rate that the trial was recorded with

  • conditions: Condition that you want the data to be treated with.

Methods:

abra.session.Base.summary

summary(self, verbose = False)

Returns a dictionary that holds summary statistics for pupil size of all the trials in the base class.

Parameter:

  • verbose: boolean, True will print the summary.

Return:

  • summary: Dictionary of summary statistic for pupil size containing, [mean]: pupil mean, [variance]: pupil variance, [stdev]: pupil standard deviation, [length]: pupil size, [min]: pupil minimum, [max]: pupil maximum

abra.session.Base.get_trial

get_trial(self, trial_num)

Will return the data from specified trial.

Parameter:

  • trial_num: int, trial number you want to find.

Return:

  • Trial object: Return Trial object by specified trial number

abra.session.Base.get_pupil

get_pupil(self)

Returns a list pupil sizes in each trial

Return:

  • numpy array: a nested list of pupil sizes for each trial.

abra.session.Base.get_movement

get_movement(self)

Returns a list of eye movements in each trial

Return:

  • numpy array: a 2d array that holds eye movements in the x-axis at index 0 and movements in the y-axis at index 1. At each index there is a nested list for the movement direction per trial.

abra.session.Base.get_timestamps

get_timestamps(self)

Returns a list of timestamps in each trial

Return:

  • numpy array: nested list of timestamps for each trial

abra.session.Base.get_fixation

get_fixation(self)

Returns a list of eye movements during fixation for each trial.

Return:

  • numpy array: a 2d array that holds eye movements during fixation in the x-axis at index 0 and movements in the y-axis at index 1. At each index there is a nested list for the eye movement direction per trial.

abra.session.Base.select

select(self, indexes)

Selects specified trial by index value.

Return:

  • Trial object: Return Trial object by specified index list of Trial objects

abra.session.Base.plot_pupil_size

plot_pupil_size(self, trial_num = 1)

Plots pupil size of the specified trial.

Return:

  • matplotlib plot: returns a plot

abra.session.Base.plot_tragectory

plot_tragectory(self, trial_num = 1, image_file = None, screen_size = (1920,1080))

Plots eye movement for specified trial. Can plot over image and specify dimension the screen used with eye-tracker.

Paramters:

  • trial_num: int, trial to plot eye movement

  • image_file: string, file path to image

  • screen_size: list, Resolution dimension of the screen used. (Width, Height)

Return:

  • matplotlib plot: returns a plot

abra.session.Base.plot_xy

plot_xy(self, trial_num = 1)

Plots horizontal and vertical eye movement across the time of the trial.

Paramter:

  • trial_num: int, trial to plot for eye movement

Return:

  • matplotlib plot: returns a plot

abra.session.Base.get_x_y

get_x_y(self, data)

Gets the mean and length of eye movement for each fixation in the specified trial.

Paramter

  • data: list of eye movements during fixation for specified trial

Return:

  • numpy array, numpy array: returns 2 numpy arrays. The first contains the mean and length of eye movements in the horizontal direction and the second contains movements in the vertical direction.

abra.session.Base.get_bubble_plot

get_bubble_plot(self, trial_num = 1, image_file = None, screen_size = (1920, 1080))

A bubble plot is created to visualize fixation points during specified trial. image_file give the option to plot fixation points over imagea used during eye-tracking recording sessions.

Parameters:

  • trial_num: int, trial to plot fixation points

  • image_file: string, image file path

  • screen_size: list, Resolution dimension of the screen used. (Width, Height)

Return:

  • matplotlib plot: returns a bubble plot

abra.session.Session

Session(Base)

Subclass of Base that hold whole trials

Parameter:

  • Base: [Base][#abrasessionBase] class

Attributes:

  • data: List of Trial objects

  • sample_rate: Hold the value of the sample rate that the trial was recorded with

  • conditions: Condition that you want the data to be treated with.

Return:

  • Session: returns a Session object

abra.session.Epoch

Epochs(Base)

Subclass of Base that hold time locking epochs

Parameter:

  • Base: [Base][#abrasessionBase] class

Attributes:

  • data: List of Trial objects

  • sample_rate: Hold the value of the sample rate that the trial was recorded with

  • conditions: Condition that you want the data to be treated with.

Return:

  • Epoch: returns a Epoch object

abra.Visualization

Class Visualization(data, quality_list)

Used to visualize pupil size and eye movements across trial time to inspect if plots resemble a good trial or bad trial. When Visualization object is created, it will create tkinter GUI application giving the options to move to the next trial, go to the previous trial, specify if the trial is good or bad, and save the quality list to to any directory.

Parameters:

  • data: Sessions or Epoch object

  • quality_list: file path to quality list. Default is None

Returns:

  • Visualization: returns a Visualization object holding all information predefined including quality list.
  • tkinter GUI: opens a tkinter GUI application to inspect trials.