output - shlomitya/eye-tracker-analyzer GitHub Wiki

The analyzer will produce the following outputs within the output folder selected in the analysis pane.

Grouped graphs folder

If 'Plot group figures' was selected within the eye movements analysis dialogue, a folder will be created which will contain all group-level plots, according to the analyses selected. Only relevant when two or more .ETA files are loaded.

Individual subject folder(s)

If 'Plot individual figures' was selected within the eye movements analysis dialogue, a folder will be created for each .ETA file loaded, numbered in the order of the loaded files, which will contain single-subject level plots, according to the analyses selected. If 'Create Individual Analysis Structs' option was selected in the analysis pane, a MATLAB analysis struct will also be created under each folder.

Error log

At the root output folder, the toolbox will generate a .txt file containing errors that were produced during the analysis.

MATLAB analysis struct(s)

At the root output folder, the toolbox will generate a MATLAB struct that contains all analysis parameters, data inspection manual changes, raw eye positions, and extracted saccade measurements. When a single .ETA file is loaded, the struct will include only that participant's analysis results. When multiple .ETA files are loaded and the 'Create Individual Analysis Structs' option is not selected, the struct will aggregate the output of all participants. If selected, the struct will only include the group-level parameters and statistics, while the individual-level output will be created and saved in a struct under each individual's folder.

The structure of the analysis struct is as follows:

eye_movement_data [struct] - A structure summarizing all subject-level analyzed eye-movement data. Organized by subject (.ETA filename) and includes the following:
- saccades [struct] - Stores saccade-related data. Has a field for each condition (trigger) name detected, which comprises a struct that is organized as follows:
  - number_of_saccades [vector] - A 1 x T vector that stores the number of saccades detected for each trial t. NaN denotes rejected trial.
  - durations [cell array] - A 1 x T cell array in which each cell contains a 1 x N_t saccade durations [ms, defined onset to offset] detected for saccades 1 to n in trial t. Empty cell denotes no saccades detected or rejected trial.
  - amplitudes [cell array] - A 1 x T cell array in which each cell contains a 1 x N_t saccade amplitudes [visual degrees] detected for saccades 1 to n in trial t. Empty cell denotes no saccades detected, NaN denotes rejected trial.
  - directions [cell array] - A 1 x T cell array in which each cell contains a 1 x N_t saccade directions [radians] detected for saccades 1 to n in trial t. Empty cell denotes no saccades detected, NaN denotes rejected trial.
  - onsets [cell array] - A 1 x T cell array in which each cell contains a 1 x N_t saccade onsets [samples relative to first sample] detected for saccades 1 to n in trial t. Empty cell denotes no saccades detected, NaN denotes rejected trial.
  - velocities [cell array] - A 1 x T cell array in which each cell contains a 1 x N_t max saccade velocity [visual degrees/ms] detected for saccades 1 to n in trial t. Empty cell denotes no saccades detected, NaN denotes rejected trial.
  - logical_onsetes_mat [logical matrix] - A T x S logical matrix in which each element indicates whether a saccade was detected (1) or not (0) for samples 1 to s_t (columns) for trials 1 to t (rows). NaN indicates a missing value. As this matrix is created trial-wise, it is possible NaN will be appended to the end of the row if a longer segment is added to the matrix during analysis.
- eyeballing_stats [struct] - Stores information related to manual changes done during data inspection. Has a field for each condition (trigger) name detected, which comprises a struct that is organized as follows:
  - accepted_saccades_nr [vector] - A 1 x T vector that stores the number of saccades accepted (unaltered) for each trial t. NaN denotes rejected trial.
  - rejected_saccades_nr [vector] - A 1 x T vector that stores the number of saccades rejected for each trial t. NaN denotes rejected trial.
  - user_generated_saccades_nr [vector] - A 1 x T vector that stores the number of saccades manually generated for each trial t. NaN denotes rejected trial.
  - blinked_out_saccades_nr [vector] - A 1 x T vector that stores the number of saccades rejected via manual dropped-out segments each trial t. NaN denotes rejected trial.
  - was_trial_rejected [logical array] - A 1 x T logical array that indicates whether a trial was manually rejected (1) or not (0).
- fixations [struct] - Stores fixation-related data. Has a field for each condition (trigger) name detected, which comprises a struct that is organized as follows:
  - onsets [cell array] - A 1 x T cell array in which each cell contains a 1 x N_t fixation onsets [samples, starting segment's first sample] detected for fixations 1 to n in trial t. NaN denotes rejected trial.
  - coordinates_left [cell array] - A 1 x T cell array in which each cell contains an N_t 2 coordinates [pixels] on the X (1st column) and Y (second column) axes for the left eye for fixations 1 to n in trial t. NaN denotes rejected trial.
  - coordinates_right [cell array]- A 1 x T cell array in which each cell contains an N_t 2 coordinates [pixels] on the X (1st column) and Y (second column) axes for the right eye for fixations 1 to n in trial t. NaN denotes rejected trial.
  - durations [cell array] - A 1 x T cell array in which each cell contains a 1 x N_t fixation durations [samples, defined from saccade or blink offset or segment start to next onset or segment end] detected for fixations 1 to n in trial t. NaN denotes rejected trial.
- raw_data [struct] - Stores raw gaze data. Has a field for each condition (trigger) name detected, which comprises a struct that is organized as follows:
  - vergence [struct] - A structure containing data about intra-ocular distance of the eyes. Comprises of two variables:
    - x [matrix] - A T x S matrix in which each element shows the distance between the eyes (right minus left, in visual degrees) on the x-axis for samples 1 to s_t (columns) for trials 1 to t (rows). NaN indicates a missing value. As this matrix is created trial-wise, it is possible NaN will be appended to the end of the row if a longer segment is added to the matrix during analysis.
    - y [matrix] - A T x S matrix in which each element shows the distance between the eyes (right minus left, in visual degrees) on the y-axis for samples 1 to s_t (columns) for trials 1 to t (rows). NaN indicates a missing value. As this matrix is created trial-wise, it is possible NaN will be appended to the end of the row if a longer segment is added to the matrix during analysis.
  - non_nan_times [logical array] - A T x S logical array in which each element shows whether the current sample is NaN (1) or not (0), for samples 1 to s_t (columns) for trials 1 to t (rows). NaN indicates a missing value and is usually the result of NaNs appended to the matrix when longer trials are added to it.
  - right_eye [struct] - A structure containing raw gaze data of the right eye. Comprises of two variables:
    - x [matrix] - A T x S matrix in which each element shows the horizontal gaze position [pixels] of the right eye for samples 1 to s_t (columns) for trials 1 to t (rows). NaN indicates a missing value. As this matrix is created trial-wise, it is possible NaN will be appended to the end of the row if a longer segment is added to the matrix during analysis.
    - y [matrix] - A T x S matrix in which each element shows the vertical gaze position [pixels] of the right eye for samples 1 to s_t (columns) for trials 1 to t (rows). NaN indicates a missing value. As this matrix is created trial-wise, it is possible NaN will be appended to the end of the row if a longer segment is added to the matrix during analysis.
  - left_eye [struct] - A structure containing raw gaze data of the left eye. Comprises of two variables:
    - x [matrix] - A T x S matrix in which each element shows the horizontal gaze position [pixels] of the left eye for samples 1 to s_t (columns) for trials 1 to t (rows). NaN indicates a missing value. As this matrix is created trial-wise, it is possible NaN will be appended to the end of the row if a longer segment is added to the matrix during analysis.
    - y [matrix] - A T x S matrix in which each element shows the vertical gaze position [pixels] of the left eye for samples 1 to s_t (columns) for trials 1 to t (rows). NaN indicates a missing value. As this matrix is created trial-wise, it is possible NaN will be appended to the end of the row if a longer segment is added to the matrix during analysis.
- metadata [struct] - Stores information related to the original .edf file. Has two fields, as follows:
  - sampling_rate [variable] - The original sampling rate (Hz) used to record the data.
  - original_filename [variable] - The name of the .edf file analyzed.
- pupil size [struct] - Stores extracted pupil size (as diameter or area, according to eye tracker settings during recording). Has a field for each condition (trigger) name detected, which comprises a struct that is organized as follows:
  - left_eye [matrix] - A T x S matrix in which each element shows the pupil size [arbitrary units] of the left eye for samples 1 to s_t (columns) for trials 1 to t (rows). NaN indicates a missing value, including samples discarded due to blinks. As this matrix is created trial-wise, it is possible NaN will be appended to the end of the row if a longer segment is added to the matrix during analysis.
  - right_eye [matrix] - A T x S matrix in which each element shows the pupil size [arbitrary units] of the right eye for samples 1 to s_t (columns) for trials 1 to t (rows). NaN indicates a missing value, including samples discarded due to blinks. As this matrix is created trial-wise, it is possible NaN will be appended to the end of the row if a longer segment is added to the matrix during analysis.
- detection [struct] - Stores detection quality information. Only created when choosing to generate main sequence plots. Has a field for each condition (trigger) name detected, which comprises a struct that is organized as follows:
  - main_sequence_r [variable] - The log-log Pearson correlation between the current condition's saccade amplitudes and velocities. NaN indicates there were too few (<=2) saccades detected to calculate the Pearson correlation.
  - main_sequence_p [variable] - The p value corresponding with the given Pearson correlation, given n-2 degrees-of-freedom with n defined as the number of saccades detected. NaN indicates there were too few (<=2) saccades detected to calculate the Pearson correlation.
parameters [struct] - A structure aggregating all the analysis parameters and options. Contains the following structures:
- saccade_analysis_parameters [struct] - Contains all saccade detection parameters selected within the analysis parameters panel. Contains the following variables:
  - amp_lim [variable] - The defined saccade amplitude upper limit [visual degree].
  - amp_lim_low [variable] - The defined saccade amplitude lower limit [visual degree].
  - vel_vec_type [variable] - The algorithm used to convert gaze data to velocity. Currently hidden from the user and set by default to 1, indicating sample-by-sample velocity conversion (i.e., no running average).
  - detection [string] - The Detection parameter chosen from the other options. Could be either 'Binocular', 'Monocular (L)' or 'Monocular (R)'. Notice that this parameter saves the detection option picked by the user, which might differ from the detection done in practice (i.e. when selection is not viable in the data).
  - vel_threshold [variable] - The defined velocity threshold [visual degrees / ms].
  - saccade_dur_min [variable] - The defined minimum time between saccades [ms].
  - frequency_max [variable] - The defined minimum duration for a saccade [ms].
  - do_filter [logical] - Whether lowpass filtering was performed (1) or not (0). Set to 1 by default.
  - filter_bandpass [variable] - the defined lowpass filter cutoff frequency [Hz].
- graph_parameters [struct] - Contains all parameters related to graph generation. Consists of the following variable:
  - smoothing_window_len [variable] - The smoothing window length for saccade rate [ms] defined in the analysis options.
- blink_analysis_parameters [struct] - Contains all parameters related to the blink detection algorithm defined in the other options. Consists of the following:
  - blink_delta [variable] - The defined blink delta [ms].
  - blink_detection [string] - The selected blink detection algorithm. Can be either 'SR Research', 'Pupil-based', or 'Both'.