tobii_pytracker.analyze.SaccadeAnalyzer

class tobii_pytracker.analyze.SaccadeAnalyzer(output_folder: Path, method: Literal['ivt', 'acceleration'] = 'ivt', velocity_threshold: float = 100.0, acceleration_threshold: float = 5000.0, min_duration: float = 0.01, filter_micro_saccades: bool = False, micro_saccade_threshold: float = 30.0)

Calculates saccade metrics (dx, dy, dt, amplitude, velocity, acceleration) from gaze data.

This version supports multiple parameterizations:

• Velocity-based or acceleration-based saccade detection.

• Optional micro-saccade filtering.

Parameters

output_folderPath

Directory where results or plots can be saved.

method{‘ivt’, ‘acceleration’}, optional

Saccade detection algorithm:

• ‘ivt’ → Velocity-threshold (I-VT)

• ‘acceleration’ → Acceleration-threshold

Default = ‘ivt’.

velocity_thresholdfloat, optional

Minimum velocity (pixels/second) to classify as a saccade (I-VT only). Default = 100.

acceleration_thresholdfloat, optional

Minimum acceleration (pixels/second²) to classify as a saccade (acceleration only). Default = 5000.

min_durationfloat, optional

Minimum duration (seconds) to consider a saccade valid. Default = 0.01.

filter_micro_saccadesbool, optional

Whether to remove micro-saccades (small-amplitude movements). Default = False.

micro_saccade_thresholdfloat, optional

Amplitude threshold (in pixels) below which a saccade is considered a micro-saccade and removed. Default = 30 pixels (roughly ~1° visual angle at 60 cm and 1080p resolution).

__init__(output_folder: Path, method: Literal['ivt', 'acceleration'] = 'ivt', velocity_threshold: float = 100.0, acceleration_threshold: float = 5000.0, min_duration: float = 0.01, filter_micro_saccades: bool = False, micro_saccade_threshold: float = 30.0)

Methods

__init__(output_folder[, method, ...])
analyze(background_data)	Compute saccade events and metrics.
plot_analysis(saccades, screenshot_path[, ...])	Overlay saccades on top of the screenshot.

analyze(background_data: DataFrame) → DataFrame

Compute saccade events and metrics.

Parameters

background_datapd.DataFrame

Flattened gaze data with columns: [‘avg_gaze_x’, ‘avg_gaze_y’, ‘system_time’, ‘set_name’, ‘slide_index’]

Returns

pd.DataFrame

DataFrame of saccade events with columns: [‘set_name’,’slide_index’,’start_time’,’end_time’,’duration’,

‘x_start’,’y_start’,’x_end’,’y_end’,’amplitude’,’peak_velocity’, ‘mean_velocity’,’mean_acceleration’]

plot_analysis(saccades: DataFrame, screenshot_path: Path, set_name: str | None = None, slide_index: int | None = None, title: str | None = None, flip_y: bool = True, color: str = 'cyan', alpha: float = 0.8, linewidth: float = 2.0, show: bool = True, save_path: Path | None = None)

Overlay saccades on top of the screenshot.

Parameters

saccadespd.DataFrame

Output of analyze(). Can contain all sets/slides.

screenshot_pathPath

Path to the corresponding screenshot.

set_namestr, optional

Filter by participant ID.

slide_indexint, optional

Filter by slide index.

titlestr, optional

Custom title.

flip_ybool, optional

Whether to invert Y axis.

colorstr, optional

Line color for saccades.

alphafloat, optional

Transparency level.

linewidthfloat, optional

Line thickness.

show : bool, optional save_path : Path, optional