📖 describe#

Analyze EDF Trials and Extract Statistics#

The describe() function allows users to analyze eye-tracking trial data from an EDF (Eye Data Format) file. It computes key statistics for a given trial or all trials, including:

  • Total duration of the trial

  • Number of fixations, saccades, and blinks

  • Average fixation duration

  • Average saccade amplitude

  • This function is useful for summarizing eye movement behavior from recorded trials.

describe can directly work with EDF file or you can first Convert data using export function and then import files and use describe function.

import etformat as et
et.describe(r"K:\Packages for python\etformat misc\test.EDF")
---------------------------------------------------------------------------
KeyboardInterrupt                         Traceback (most recent call last)
Cell In[1], line 2
      1 import etformat as et
----> 2 et.describe(r"K:\Packages for python\etformat misc\test.EDF")

File k:\packages for python\etformat\etformat\describe.py:34, in describe(data_source, trial_number)
     31     return None
     33 # Load EDF file
---> 34 edf = EDFFile(edf_file_path, loadevents=True, loadsamples=True)
     36 if edf.samples is None or edf.events is None:
     37     print("⚠️ No valid sample or event data found in the EDF file.")

File k:\packages for python\etformat\etformat\edffile.py:103, in EDFFile.__init__(self, filename, consistency, loadevents, loadsamples, sample_fields, start_marker_string, end_marker_string, parse_events, wide_variables, trigger_marker, verbose, libpath)
    101 data_type = self._edfapi.edf_get_next_data(self._file)
    102 while data_type != EDF_NO_PENDING_ITEMS:
--> 103     allf_data_ptr = self._edfapi.edf_get_float_data(self._file)
    104     if data_type in EDF_EVENT_CODES.keys():
    105         # trial start
    106         if data_type == EDF_EVENTS["MESSAGEEVENT"] and \
    107            allf_data_ptr.contents.fe["message"].startswith(start_marker_string):

KeyboardInterrupt: 

Warning

if you see an error here regarding file is because of compiler error due to jupyter-book` code works in natural environment.

if you have already exported data there are two seperate files after conversion which are EDFfilename_events.csv and EDFfilename_samples.csv which can be used to analyze data.

import pandas as pd
import etformat as et

# Load CSV files
samples = pd.read_csv(r"K:\Packages for python\etformat misc\test_samples.csv")
events = pd.read_csv(r"K:\Packages for python\etformat misc\test_events.csv")

# Describe all trials using the CSV DataFrames
df = et.describe((events, samples))
df
Trial Total Duration (ms) Total Samples Number of Fixations Number of Saccades Number of Blinks Avg Fixation Duration (ms) Avg Saccade Amplitude
0 1.0 NaN 0 0 0 0 NaN NaN
1 2.0 9969.0 9970 33 33 1 302.090909 1.719866
2 3.0 8620.0 8621 32 32 0 269.375000 1.878651
3 4.0 4353.0 4354 11 11 1 395.727273 2.549112
4 5.0 13173.0 13174 42 42 2 313.642857 2.061150
... ... ... ... ... ... ... ... ...
475 476.0 2073.0 2074 6 6 1 345.500000 2.770143
476 477.0 2445.0 2446 7 6 1 349.285714 2.862927
477 478.0 2426.0 2427 5 5 1 485.200000 3.219999
478 479.0 2190.0 2191 7 8 2 312.857143 2.438215
479 480.0 2515.0 2516 7 6 0 359.285714 2.789500

480 rows × 8 columns

# Describe trial #3 using CSV
trial_stats = et.describe((events, samples), trial_number=3)
trial_stats
{'Trial': 3.0,
 'Total Duration (ms)': 8620.0,
 'Total Samples': 8621.0,
 'Number of Fixations': 32.0,
 'Number of Saccades': 32.0,
 'Number of Blinks': 0.0,
 'Avg Fixation Duration (ms)': 269.375,
 'Avg Saccade Amplitude': 1.8786510980887818}