ContextQMD
Back to Claude Scientific Skills

Electrooculography

skills/neurokit2/references/eog.md

2.55.05.2 KB
Original Source

Electrooculography

Checked 2026-07-23 against NeuroKit2 0.2.13 stable source/runtime and the official EOG API/example.

Scope and orientation

NeuroKit2's EOG pipeline is primarily a vertical EOG blink workflow. Stable eog_process() requires blinks to be positive-going peaks. Verify channel montage, polarity, reference, physical unit, sampling rate, hardware filters, amplifier range, clock, and synchronization before processing.

Do not use this module as a full gaze, saccade, fixation, or sleep-scoring system. Horizontal/vertical eye-movement interpretation and clinical/drowsiness monitoring need separate validated methods.

Optional MNE default

eog_peaks() and eog_findpeaks() default to method="mne". In the core 0.2.13 installation, MNE is optional; the default can therefore raise an ImportError. Either add MNE at a reviewed exact version to the project lock or choose a core method:

python
signals, info = nk.eog_process(
    veog,
    sampling_rate=200,
    method="neurokit",
)

eog_process() forwards **kwargs to cleaning and peak finding. Record the explicit method rather than relying on an environment-dependent default.

Stable schemas

The high-level return is (signals, info). Default columns are:

text
EOG_Raw, EOG_Clean, EOG_Blinks, EOG_Rate

info has EOG_Blinks (sample indices) and sampling_rate.

Low-level interfaces differ:

python
clean = nk.eog_clean(veog, sampling_rate=200, method="neurokit")

# Returns only an array of blink sample indices.
blink_indices = nk.eog_findpeaks(
    clean,
    sampling_rate=200,
    method="neurokit",
)

# Returns (same-length marker DataFrame, info dict).
blink_markers, blink_info = nk.eog_peaks(
    clean,
    sampling_rate=200,
    method="neurokit",
)

The 0.2.13 eog_peaks() docstring return section says array, while its tagged source returns (signals, info). The pinned source/runtime is authoritative for stable work.

Stable cleaning methods include neurokit, agarwal2019, mne, brainstorm, and kong1998. Peak methods include neurokit, mne, brainstorm, and blinker. MNE and some method paths need optional dependencies.

python
features = nk.eog_features(
    clean,
    blink_info["EOG_Blinks"],
    sampling_rate=200,
)

eog_features() needs both the cleaned signal and peak-index array. It returns a dict with event-level fields such as:

text
Blink_LeftZeros, Blink_RightZeros, Blink_pAVR,
Blink_nAVR, Blink_BAR, Blink_Duration

Do not pass the processed DataFrame as the only argument. Feature validity depends on positive orientation and accurate blink segmentation.

Sampling and artifacts

Choose a rate from the endpoint and hardware bandwidth, not a universal number. Basic blink timing may use lower rates than detailed eyelid velocity or saccade morphology. Validate temporal error against labeled data at the actual rate; 200–500 Hz is common in research but not a guarantee.

Inspect:

  • saturation and clipping during large eye movements;
  • baseline drift and electrode polarization;
  • frontal/facial EMG and movement/cable artifacts;
  • line noise and channel detachment;
  • polarity and montage changes across sessions; and
  • missing samples and synchronization with EEG/events.

Do not interpolate through a blink or across detachment. Preserve raw/clean overlays, blink markers, rejected segments, and manual review outcomes.

Event and interval analysis

python
epochs = nk.epochs_create(
    signals,
    events,
    sampling_rate=200,
    epochs_start=-0.5,
    epochs_end=2,
    baseline_correction=False,
)
event_features = nk.eog_eventrelated(epochs)
interval_features = nk.eog_intervalrelated(signals)

Documented event-related fields include EOG_Rate_Baseline, rate min/max/mean/SD and times, plus EOG_Blinks_Presence. Interval analysis returns EOG_Peaks_N and EOG_Rate_Mean in the official example. It does not universally return blink amplitude or duration summaries. Inspect columns at runtime.

Blink rate over short windows is unstable and task-dependent. A count/rate change does not uniquely identify attention, fatigue, stress, dry eye, dopamine, or a neurological condition.

EEG integration

EOG can help identify ocular contamination in EEG, but NeuroKit2 does not provide a complete validated correction pipeline here. With MNE:

  1. synchronize and preserve dedicated EOG channels;
  2. fit artifact identification/correction on appropriate data;
  3. verify component or regression selection without removing neural signal;
  4. compare raw and corrected ERPs/spectra/topographies; and
  5. report method, channels, filters, thresholds, components, and exclusions.

Avoid circularly selecting correction settings to maximize an experimental result.

Sources checked 2026-07-23