Skip to content

EyeSort 1.0

Latest
Latest

Choose a tag to compare

View all tags
@Brandon1S Brandon1S released this 09 Jul 02:28
· 1 commit to main since this release
v1.0
b6e9e34
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

EyeSort toolbox is a free, open-source software for behavior-contingent labeling of synchronized EEG and eye-tracking events in reading experiments. It is distributed as an EEGLAB plugin and builds on the EEGLAB Toolbox event and dataset framework.

EyeSort operates between synchronization and analysis: once fixation and saccade events are already in EEG.event, it maps those events onto text-defined interest areas, applies region and behavior-based labels, and writes traceable event markers that can feed ERPLAB/BINLISTER workflows, FRP analyses, or deconvolution models.

EyeSort 1.0

Download EyeSort 1.0

Download the plugin ZIP above (eyesort1.0.zip). It unpacks to an eyesort1.0 folder.
Place that folder in your EEGLAB plugins directory, launch EEGLAB, and confirm the EyeSort menu is present.

What this release includes

We highly recommend all new users to read through the user manual to understand both toolbox functionality and workflow.

Source code for the plugin is attached automatically by GitHub. Install by placing the EyeSort folder in your EEGLAB plugins directory, then launch EEGLAB and confirm the EyeSort menu is present.

Before using your own data: work through the manual and sample files first. The README is a short overview only; the manual covers installation, input preparation, GUI steps, scripting, quality control, and troubleshooting.

Requirements at a glance

  • MATLAB + EEGLAB
  • .set datasets with synchronized fixation/saccade events already in EEG.event
  • Tab-delimited interest-area text file (one row per stimulus/trial)

EyeSort does not preprocess EEG, clean eye-tracker data, correct artifacts, or synchronize modalities. Those steps must be finished upstream.

Default eye-event names match common EYE-EEG outputs (R_fixation, R_saccade, fix_avgpos_x, sac_startpos_x, sac_endpos_x) and can be changed in the GUI.

Menu workflow

  1. Load EEG Dataset(s)
  2. Setup Interest Areas → Text-Based Sentence Contents and Interest Areas
  3. Setup Interest Areas → Inspect Parsed Regions (optional)
  4. Import IA Columns to Events (optional)
  5. Eye-Tracking Event Labeling
  6. Generate BINLISTER BDF File (optional)
  7. Modify Event Code Format (optional)
  8. History Scripts → Save processing history script (optional)

Release notes

Scripted reproducibility

GUI sessions can now be exported as portable MATLAB scripts via History Scripts → Save processing history script. The exported .m file replays Text IA assignment, optional column import, label-queue application, summary CSV writing, and optional BDF generation without reopening dialogs. Config sidecars travel with the script so a new batch can be run by pointing inputDir at a different folder.

Input diagnostics

Trigger codes, condition/item keys, and interest-area mismatches are validated up front and reported in structured diagnostics instead of failing quietly with zero matches. Step 2 shows preflight GUI feedback; assignment diagnostics are stored on the dataset; IA import checks columns/rows more carefully; and labeling reports which queued labels matched nothing. Trigger matching also accepts flexible numeric/string forms rather than requiring S-prefixed codes.

Configurable event marker formats

Users can now choose how labeled events are written to EEG.event.type during labeling, and can convert already-labeled datasets later with Modify Event Code Format. In all cases, EyeSort keeps canonical CCRRLL codes in eyesort_full_code, eyesort_condition_code, eyesort_region_code, and eyesort_label_code, so marker display can change without losing the underlying label identity.

Supported formats:

Format What is written to EEG.event.type Example
numeric 6-digit CCRRLL code (ERPLAB / BINLISTER compatible) 010203
description Condition + label description Identical PreTarget_NoSkip
description_word Condition + label description + fixated word text Identical PreTarget_NoSkip the
description_index Condition + label description + fixated word index (region.word) Identical PreTarget_NoSkip 4_2
region_content Full text of the currently fixated region the quick brown fox
original Restore the pre-EyeSort event code from original_type R_fixation

Choose the format in the labeling GUI, or convert afterward without re-running the full labeling pipeline.

Performance and batch UX

Step 2 trigger validation is substantially faster on large event lists. Progress waitbars work across labeling, Text IA, IA import, and event-code conversion. After batch labeling, import, or conversion, the first updated dataset is reloaded into EEGLAB so the workspace reflects real output.

Other fixes

Batch event-code conversion edge cases, history-string improvements for batch runs, and assorted MATLAB Code Analyzer cleanups (preallocation, scalar checks, datetime usage).

Support

Open a GitHub issue for bugs or unexpected results.

License: GPL-3.0-or-later (LICENSE)

Assets 5
Loading