📖 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}