Quickstart with Sample Data

Produce and verify a labeled EyeSort 1.0 dataset from the open sample files.

Outcome

In about 30 minutes, you will produce a verified <sample>_processed.set/.fdt, a labeling summary, and an optional eyesort_bins.txt. EyeSort labels fixation events; saccade direction is only a criterion on those fixations.

Before you begin

Install EyeSort 1.0.
Download the open sample data and configurations or the release compatibility bundle.
Extract the files to a writable working directory.
Create a separate empty output directory.

Use the configuration supplied with the sample. Values shown as placeholders in the Step 2 GUI are not universal experiment settings.

1. Launch and verify EyeSort

Start EEGLAB:

eeglab
which eegplugin_eyesort -all

Open the EyeSort menu.

Expected result: The menu reports EyeSort v1.0 and shows Steps 1–4, BDF generation, event-code conversion, History Scripts, and Help.

Verify in MATLAB: which should return one intended plugin path. Remove duplicate EyeSort paths before continuing.

2. Load the sample dataset

Choose EyeSort → 1. Load EEG Dataset(s). Click Browse Files, select one sample .set file, choose the output directory, and click Confirm.

Expected result: The sample dataset appears in EEGLAB. EyeSort remembers the output directory; it will auto-save there after labeling.

Verify in MATLAB:

EEG.filename
numel(EEG.event)
unique(string({EEG.event.type}))
eyesort_single_output_dir

Confirm that fixation, saccade, trial, condition, and item events are present.

3. Map text interest areas

Choose EyeSort → 2. Setup Interest Areas → Text-Based Sentence Contents and Interest Areas. Use Load Configuration when the sample includes a Step 2 .mat file. Otherwise enter the values documented with the sample, including:

the sample IA text file;
measured sentence offset and pixels per character;
ordered region names;
condition-label, condition-code, and item-code columns;
trial and optional stimulus-window triggers;
condition and item trigger lists;
fixation/saccade event types and X fields.

Save a named copy of the configuration. Optionally choose Save Intermediate Dataset(s), then click Confirm.

Expected result: EyeSort reports trigger and assignment counts. EEG.eyesort_processed becomes true. An optional intermediate is named <sample>_eyesort_ia.set/.fdt.

Verify in MATLAB:

assert(EEG.eyesort_processed)
EEG.region_names
d = EEG.eyesort_step2_diagnostics;
[d.fixation_events_seen d.fixations_assigned_to_region]
d.missing_text_file_keys

The mapped-fixation count should be positive, and missing keys should match only intentionally unused rows.

4. Inspect the mapping

Choose EyeSort → 2. Setup Interest Areas → Inspect Parsed Regions. Compare several rows with the sample stimulus text. Check spaces, region order, and pixel boundaries. Export the table if you want a QC record.

Expected result: Each condition–item row shows the intended literal text and plausible [start, end] boundaries for every region.

Verify in MATLAB:

mapped = find(~cellfun(@isempty, {EEG.event.current_region}));
EEG.event(mapped(1))

Inspect current_region, current_word, current_word_text, region_pass_number, fixation_in_pass, and is_last_in_pass. If the mapping is wrong, correct Step 2 before continuing.

5. Queue and apply fixation labels

Choose EyeSort → 4. Eye-Tracking Event Labeling. Load the sample label queue if supplied. Otherwise create a broad first label:

enter a descriptive label name;
choose Numeric code (CCRRLL);
select one region known to contain sample fixations;
leave optional filters unchecked for the first validation label;
click Add Label to Queue.

Save the full queue, then click Apply All & Finish. If a conflict dialog appears, review the existing and proposed labels before choosing replace or keep.

Expected result: At least one fixation matches. EyeSort automatically writes <sample>_processed.set/.fdt and eyesort_labeling_summary_NNN.csv to the Step 1 output directory. There is no separate save command.

Verify in MATLAB:

labeled = ~cellfun(@isempty, {EEG.event.eyesort_full_code});
assert(nnz(labeled) > 0)
unique({EEG.event(labeled).eyesort_full_code})
unique({EEG.event(labeled).bdf_label_description})
EEG.eyesort_last_label_diagnostics

Spot-check that original_type preserves the incoming fixation marker and that bdf_full_description is readable.

6. Reload the saved output

Use the actual base filename shown in the output directory:

EEG = pop_loadset('filename', 'SAMPLE_processed.set', ...
                  'filepath', '/path/to/output');
assert(EEG.eyesort_processed)
labeled = ~cellfun(@isempty, {EEG.event.eyesort_full_code});
T = table({EEG.event(labeled).original_type}', ...
          {EEG.event(labeled).eyesort_full_code}', ...
          {EEG.event(labeled).bdf_full_description}', ...
          'VariableNames', {'Original','CanonicalCode','Description'});
T(1:min(10,height(T)), :)

Expected result: The reloaded file contains canonical codes, original types, descriptions, and all Step 2 behavioral metadata.

7. Generate and verify the optional BDF

Choose EyeSort → Generate BINLISTER BDF File and save the default eyesort_bins.txt.

Expected result: The file contains one or more BINLISTER bins. Codes with the same condition description and label description may be joined in one expression.

Verify in MATLAB:

assert(isfile(fullfile('/path/to/output', 'eyesort_bins.txt')))
type(fullfile('/path/to/output', 'eyesort_bins.txt'))

Before running BINLISTER, keep or restore numeric event types:

EEG = pop_convert_event_codes(EEG, 'numeric');

Preserve the run

Choose EyeSort → History Scripts → Save processing history script. Keep the generated .m file with its text-IA config, label queue, and localized IA-file sidecars.

For your own data, next read prepare inputs, the single-dataset guide, and reporting guidance.