Module eyekit.analysis

Functions for calculating common analysis measures, such as total fixation duration or initial landing position.

Functions

def initial_fixation_duration(interest_areas, fixation_sequence)

Given an interest area or collection of interest areas, return the duration of the initial fixation on each interest area. Returns a dictionary in which the keys are interest area IDs and the values are initial fixation durations.

View code on GitHub

def total_fixation_duration(interest_areas, fixation_sequence)

Given an interest area or collection of interest areas, return the total fixation duration on each interest area. Returns a dictionary in which the keys are interest area IDs and the values are total fixation durations.

View code on GitHub

def gaze_duration(interest_areas, fixation_sequence)

Given an interest area or collection of interest areas, return the gaze duration on each interest area. Gaze duration is the sum duration of all fixations inside an interest area until the area is exited for the first time. Returns a dictionary in which the keys are interest area IDs and the values are gaze durations.

View code on GitHub

def initial_landing_position(interest_areas, fixation_sequence)

Given an interest area or collection of interest areas, return the initial landing position (expressed in character positions) on each interest area. Counting is from 1, so a 1 indicates the initial fixation landed on the first character and so forth. Returns a dictionary in which the keys are interest area IDs and the values are initial landing positions.

View code on GitHub

def initial_landing_x(interest_areas, fixation_sequence)

Given an interest area or collection of interest areas, return the initial landing position (expressed in pixel distance from the start of the interest area) on each interest area. Returns a dictionary in which the keys are interest area IDs and the values are initial landing positions.

View code on GitHub

def duration_mass(text_block, fixation_sequence, n=1, gamma=30)

Given a TextBlock and FixationSequence, distribute the durations of the fixations probabilistically across the TextBlock. Specifically, the duration of fixation f is distributed over all characters C in its line according to the probability that the reader is "seeing" each character (see p_characters_fixation()), and this is summed over all fixations:

$$\sum_{f \in F} p(C|f) \cdot f_\mathrm{dur}$$

Returns a 2D Numpy array, the sum of which is equal to the total duration of all fixations. This can be passed to Image.draw_text_block_heatmap() for visualization. Duration mass reveals the parts of the text that received the most attention. Optionally, this can be performed over higher-level ngrams by setting n > 1.

View code on GitHub

def p_characters_fixation(text_block, fixation, n=1, gamma=30)

Given a TextBlock and Fixation, calculate the probability that the reader is "seeing" each character in the text. We assume that the closer a character is to the fixation point, the greater the probability that the participant is "seeing" (i.e., processing) that character. Specifically, for a given fixation f, we compute a Gaussian distribution over all characters in the line according to:

$$p(c|f) \propto \mathrm{exp} \frac{ -\mathrm{ED}(f_\mathrm{pos}, c_\mathrm{pos})^2 }{2\gamma^2}$$

where γ (gamma) is a free parameter controlling the rate at which probability decays with the Euclidean distance (ED) between the position of fixation f and the position of character c.

Returns a 2D Numpy array representing a probability distribution over all characters, with all its mass confined to the line that the fixation occurred inside, and with greater mass closer to fixation points. This array can be passed to Image.draw_text_block_heatmap() for visualization. Optionally, this calculation can be performed over higher-level ngrams by setting n > 1.

View code on GitHub