Troubleshooting

This page covers common issues and their solutions. If you don't find your issue here, please open an issue on GitHub.

Installation Issues

No EyeSort menu in EEGLAB

Symptoms: The EyeSort menu doesn't appear in the EEGLAB toolbar after installation.

Solutions:

1. Verify folder location

   • Ensure EyeSort/ is inside eeglab/plugins/
   • Don't nest it in additional subdirectories
   • Check: eeglab/plugins/EyeSort/eegplugin_eyesort.m should exist

2. Check for duplicate installations

   • Run which eegplugin_eyesort -all in MATLAB
   • If multiple paths appear, remove duplicates
   • Keep only the one in your EEGLAB plugins directory

3. Restart EEGLAB completely

   • Close EEGLAB
   • Type clear all in MATLAB command window
   • Run eeglab again

4. Check MATLAB path

   • EyeSort automatically adds itself to path when EEGLAB starts
   • If issues persist, manually run: addpath(genpath('/path/to/eeglab/plugins/EyeSort'))

Interest Area Setup Issues

"EEG data is not properly processed with region information"

When this appears: When trying to label events before setting up interest areas.

Solution: Run Step 2: Setup Interest Areas first before attempting event labeling.

Missing or mismatched region columns

Error message: "Region column 'RegionName' not found in IA file"

Solutions:

1. Check column names in your IA file header
2. Verify spelling and case - EyeSort matches case-insensitively but names must match
3. Check for special characters - Column names with $ symbols are handled, but avoid other special characters
4. Use exact names in the "Region names" field in the GUI

Trigger code not found

Error message: "Trial start/end trigger not found" or "Condition/item triggers not found"

Solutions:

1. Check event types in your dataset:

   unique({EEG.event.type})
   

2. Verify trigger format:

   • Should match exactly (e.g., S254 not 254 or "S254")
   • Check if your events use strings or numbers

3. Check trigger ranges:

   • Item triggers support ranges: S1:S112
   • Condition triggers are comma-separated: S211, S213, S221, S223

Event Labeling Issues

"No labeled events found"

When this appears: After applying labels, no events match your criteria.

Solutions:

1. Relax your criteria:

   • Try "Any" for pass constraint
   • Try "Any" for fixation type
   • Remove previous/next region constraints

2. Check region assignments:

   % View events with region info
   events_with_regions = EEG.event(~cellfun(@isempty, {EEG.event.region}))
   

3. Verify IA setup completed:

   • Check that EEG.region_names exists
   • Check that EEG.eyesort_field_names exists

4. Check event field names:

   • Enable "Change default event field names" in Text IA GUI
   • Verify your dataset uses the expected field names

Labels not appearing on events

Symptoms: Labels are added in GUI but events don't have new codes.

Solutions:

1. Single dataset mode: Check current EEG structure in EEGLAB workspace
2. Batch mode: Labels are saved progressively to output directory
3. Verify event types:

   % Should see 6-digit codes like 011101
   {EEG.event.type}
   

Label codes overlap or conflict

Symptoms: Different labels produce the same code, or labels overwrite each other.

Cause: The label counter is shared across all labels for a given condition/region pair.

Solution: This is by design - label codes are unique within condition/region. If you need distinct codes, ensure labels target different regions or use different passes/fixation types.

Eye Event Field Name Issues

"Field 'fix_avgpos_x' not found"

Cause: Your dataset uses different field names for eye-tracking data.

Solution:

1. In Text IA GUI, enable "Change default event field names"

2. Specify your actual field names:

   • Fixation event name (default: R_fixation)
   • Saccade event name (default: R_saccade)
   • Fixation X position field (default: fix_avgpos_x)
   • Saccade start X field (default: sac_startpos_x)
   • Saccade end X field (default: sac_endpos_x)

3. To find your field names:

   % Look at a fixation event
   fixations = EEG.event(strcmp({EEG.event.type}, 'YOUR_FIXATION_TYPE'))
   fieldnames(fixations(1))
   

Batch Processing Issues

Batch mode doesn't process all files

Symptoms: Only first file is processed, others are skipped.

Solutions:

1. Check output directory - Files are saved with *_processed.set suffix
2. Verify file paths - Check workspace variables:

   eyesort_batch_file_paths
   eyesort_batch_filenames
   

3. Check for errors - Look in MATLAB command window for error messages
4. Memory issues - Large datasets may cause memory errors; process in smaller batches

Configuration not applied to all files

Symptoms: First file works but subsequent files fail or produce different results.

Solution: Ensure you're using saved configuration files:

1. Save Text IA configuration in Step 2
2. Save Label configuration in Step 3
3. Load these configurations at the start of each step for consistency

BDF Generation Issues

Empty or malformed BDF file

Symptoms: Generated BDF file is empty or ERPLAB can't read it.

Solutions:

1. Check labeled events exist:

   labeled = EEG.event(cellfun(@(x) length(x)==6, {EEG.event.type}))
   

2. Verify label descriptions - BDF uses your label description text

3. Check file permissions - Ensure you have write access to output directory

BDF bin descriptions are unclear

Solution: When creating labels, provide detailed Label Description text. This appears in the BDF and helps identify bins later.

Example:

• Good: "First fixation on target word during first pass"
• Bad: "fix1"

General Tips

Save your work frequently

• Save Text IA configurations
• Save Label configurations
• Save intermediate datasets (*_eyesort_ia.set)

Test with small samples first

Before batch processing:

1. Test your configuration on one file
2. Verify the output looks correct
3. Then apply to all files

Keep original files

Always process copies of your data. EyeSort modifies event types, so keep originals for reference.

Check MATLAB version

EyeSort is tested with MATLAB R2018b and later. Older versions may have compatibility issues.

Still Having Issues?

If you're still experiencing problems:

1. Check our FAQ for additional common questions

2. Search existing GitHub Issues

3. Open a new issue with:

   • EyeSort version
   • MATLAB and EEGLAB versions
   • Operating system
   • Steps to reproduce
   • Error messages
   • Screenshots if applicable

4. Contact the team at smilliga@usf.edu