📊 saccade_amplitude_average

📊 saccade_amplitude_average#

Calculate Average Saccade Amplitude#

The saccade_amplitude_average() function calculates the average saccade amplitude for each trial in eye-tracking data. This is useful for analyzing eye movement patterns across trials and understanding the magnitude of saccadic eye movements.

The function:

  1. Processes each trial in the events data

  2. Identifies saccade events (ENDSACC)

  3. Calculates the Euclidean distance between start and end gaze positions

  4. Converts pixel distances to visual degrees

  5. Computes the average amplitude for each trial

Parameters#

  • events (str or DataFrame): Path to events CSV file or pandas DataFrame with events data

  • output_path (str, optional): Path to save the output CSV file. If None and events is a path, a path will be generated based on the input file

Returns#

  • When output_path is provided: Path to the output CSV file with average saccade amplitudes

  • When output_path is None and events is a DataFrame: DataFrame with average saccade amplitude results

import etformat as et
import pandas as pd

# Load event data
events = pd.read_csv(r"D:\Github_web_page_website\test_events.csv")

# Calculate average saccade amplitudes using DataFrame input
results_df = et.saccade_amplitude_average(events)
results_df.head()

📖 etformat 1.1.1 - For Documentation, visit: https://ahsankhodami.github.io/etformat/intro.html

Calculating average saccade amplitudes from DataFrame
Found 480 trials in the events file
trial average
0 1.0 2.67
1 2.0 2.16
2 3.0 1.86
3 4.0 2.70
4 5.0 1.44

You can also use file paths directly:

# # Calculate average saccade amplitudes from a file path
# output_path = et.saccade_amplitude_average("test_events.csv")
# print(f"Results saved to: {output_path}")

Understanding the Output#

The output includes:

  • trial: The trial number/identifier

  • average: The average saccade amplitude in degrees of visual angle for that trial

A higher value indicates larger saccadic eye movements, which could reflect increased search behavior or larger shifts of attention.

Contents