extract_metrics_example.m

% =========================================================================
% FILE: extract_metrics_example.m
% =========================================================================
% PURPOSE:
%   This is the MAIN ENTRY POINT for the toolkit. Run this script first.
%   It automatically finds every participant data file (*.mat) in the
%   current folder and runs the analysis on each one.
%
% HOW TO USE:
%   1. Place this script in the same folder as your .mat data files.
%   2. Open MATLAB and set the Current Folder to that location.
%   3. Press the green Run button (or type "extract_metrics_example" in
%      the Command Window and press Enter).
%   4. The script will loop through every .mat file, run the analysis,
%      save the output plots as PNG images, then move on to the next file.
%
% WHAT IT DOES:
%   For each participant data file (.mat), the script:
%     - Loads the file into MATLAB memory
%     - Runs the saccadic re-referencing analysis
%       (how often did the participant's first eye movement land OUTSIDE
%        the blind spot / scotoma?)
%     - Saves all result figures as PNG images in the same folder
%     - Clears the data from memory and loads the next participant
%
% TO ANALYZE A DIFFERENT METRIC:
%   Replace the line "saccadic_rereferencing_first_saccade_metrics" with:
%     - "Fixation_stability_metric"            (for fixation stability)
%     - "Saccadic_precision_latency_percent_metrics" (for saccadic precision)
%   You can also add multiple metric scripts one after the other to run
%   all three analyses on every participant automatically.
%
% INPUT:  .mat files in the current folder (one file per participant session)
% OUTPUT: PNG image files saved to the current folder (one set per participant)
%
% REFERENCE: Maniglia, Visscher & Seitz (Journal of Vision, 2020)
% =========================================================================

% Clear everything in memory before starting a fresh analysis run
clear all

% Find all .mat files in the current folder.
% 'dir' returns information about files matching the pattern '*.mat'
nameOffile = dir(['*.mat']);

% Loop through each .mat file found (i = file number 1, 2, 3, ...)
for i = 1:length(nameOffile)

    % Get the filename of the current participant's data file
    newest = nameOffile(i).name;

    % Load that file into MATLAB memory.
    % This creates variables like EyeSummary, TrialNum, baseName, etc.
    load(['./' newest]);

    % ------------------------------------------------------------------
    % Run the analysis script.
    % The script uses the variables just loaded from the .mat file.
    % Swap this line to run a different metric (see header above).
    % ------------------------------------------------------------------
    saccadic_rereferencing_first_saccade_metrics

    % Close all open figure windows to keep things tidy before the next file
    close all

    % Clear all variables EXCEPT the list of filenames, so the next
    % participant's data loads into a clean workspace
    clearvars -except nameOffile

end