ide4eeg 0.8

Integrated Development Environment for EEG

IDE4EEG

Environment for design and debugging of EEG analysis pipelines

Integrated Development Environment for EEG

IDE4EEG reads raw EEG recordings, applies a configurable preprocessing pipeline (filtering, artifact rejection, ICA), and produces time-domain, frequency-domain, and time-frequency analyses with publication-ready plots.

Features

• Multi-format input: .raw (BrainTech), .vhdr (BrainVision), .fif (MNE), .set (EEGLAB), .edf (EDF/EDF+), .bdf (BDF/BDF+)
• Preprocessing: re-referencing, filtering, bad-channel interpolation, ICA, algorithmic artifact rejection (outliers, slopes, muscles, amplitude)
• Time-domain analysis: grand-average ERPs, cluster permutation tests (MNE-Python catalog wrappers)
• Frequency-domain analysis: PSD via Welch or multitaper methods (MNE-Python catalog wrappers)
• Time-frequency analysis: TFR via Morlet / multitaper, ERD/S topographic maps (MNE-Python catalog wrappers)
• Matching Pursuit analysis: Gabor atom decomposition via empi, Wigner time-frequency energy maps, nonlinear signal reconstruction
• Connectivity analysis: 13 measures (DTF, PDC, Coherence, GCI, AEC, etc.) via MVAR models
• EEG structure profiles: FASP-based graphoelement detection (spindles, alpha, delta, K-complexes)
• Source estimation: MMP macroatom dipoles, classical ERP dipole fit, MNE/dSPM/sLORETA/eLORETA distributed inverse, LCMV beamformer, MxNE sparse — discrete-source methods feed ConnectiVIS natively; distributed methods opt-in via n_peaks
• Video artifact detection: face recognition (InsightFace) + gaze estimation (InsightFace or L2CS-Net) to flag intervals where the subject is not looking at the screen
• Qt6 graphical interface (PySide6) with interactive signal preview, MP Book Viewer, and 3D source visualization
• Config-free script export: GUI generates a standalone Python script with only non-default parameters
• Public API (ide4eeg.api): run_file() for programmatic pipeline execution, plus individual step wrappers
• Batch-friendly CLI driven by a single TOML config file

Quick Start

Prerequisites: Python 3.11+ and Java 17 LTS (or 8+; required for Svarog, the integrated signal viewer — see Java below).

python3 -m venv .venv && source .venv/bin/activate
pip install ide4eeg            # add [video] for face / gaze artifact tagging
ide4eeg                         # launch GUI

No config file is needed to start — the GUI provides sensible defaults and lets you configure everything interactively. For CLI batch processing, save a config from the GUI and run ide4eeg --run path/to/config.toml.

Developed on Python 3.14 (current target). Supported range is Python 3.11–3.14: 3.11 is the de facto floor (the input loader uses the stdlib tomllib module, added in 3.11) and 3.14 is what active development happens on. Tested on 3.12 and 3.14; 3.11 and 3.13 are expected to work but not currently exercised.

Installation

pip install ide4eeg always succeeds: the default wheel ships only the EEG core, so wheel-resolution failures on edge platforms (Intel Mac + Py3.14, bare Linux + Py3.14) can't kill the install. The video stack (face detection + gaze artifact tagging) is opt-in — either as a pip extra at install time, or installed in-app from the Config tab on first launch (the same flow that fetches Svarog / empi / ConnectiVIS).

Scope	Command	Adds
Lite (recommended for first install)	pip install ide4eeg	EEG core, GUI, all analyses
+ Video (face / gaze artifact tagging)	pip install ide4eeg[video]	OpenCV, PyAV, imageio, InsightFace, onnxruntime
Dev (editable + video)	git clone … && pip install -r requirements.txt	-e .[video] from the checkout

L2CS-Net (the default eye-gaze backend, ~500 MB on CPU and up to ~2 GB on Linux with CUDA wheels) is always installed via the GUI's Download recent button on the Config tab, regardless of which scope above. PyPI bans direct VCS dependencies, so L2CS — which lives at a GitHub URL — can't be a regular pip dep.

Quick start

python3 -m venv .venv
source .venv/bin/activate       # Linux / macOS
# .venv\Scripts\activate        # Windows
pip install ide4eeg             # or: pip install ide4eeg[video]
ide4eeg                         # launch GUI

The ide4eeg console script lands on PATH inside the venv. python -m ide4eeg works as well. See Launch for the full invocation list.

From a checkout (development)

git clone https://gitlab.com/fuw_software/ide4eeg.git
cd ide4eeg
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt   # = pip install -e .[video]
ide4eeg                            # editable; edits to ide4eeg/*.py go live

Known wheel gaps (and how the in-app installer covers them)

The [video] extra includes onnxruntime and insightface, which don't ship wheels on every (Python, OS, arch) cell. pip install ide4eeg[video] fails on those cells; pip install ide4eeg (lite) always works.

Cell	Affected dep	Resolution
Intel Mac + Python 3.14	onnxruntime (no cp314 x86_64 wheel)	Use lite install. To get the video stack, either downgrade to Python 3.13 (cp313 wheels exist) or use the GUI's Install all video tools button on the Config tab — it pip-installs in-process with the same constraint, so you'll see the same error in a friendlier dialog. There's no workaround that produces working video on this cell with cp314 today; the recommendation is Python 3.13.
Linux + Python 3.14 (any arch)	insightface, stringzilla (no cp314 wheels — pip falls back to building from sdist)	Install build tools once, then either install the extra or use the in-app installer: sudo apt install build-essential (Debian/Ubuntu) or sudo dnf groupinstall "Development Tools" (Fedora). Python 3.13 ships cp313 wheels and avoids the build entirely.
Apple Silicon + any	none	Both pip install ide4eeg and pip install ide4eeg[video] work directly.
Linux x86_64 + Python ≤ 3.13	none	Same as Apple Silicon — both install scopes work.
Windows + any	none	Same.

The in-app installer (Config tab → Tool Paths → Video stack → Install all video tools) shows pip's actual output in a streaming log dialog with a Cancel button. Cell-blocked packages produce a labelled "X package(s) platform-blocked" status with copy-paste remediation text instead of an opaque pip wheel-resolution error.

Python version

• Python 3.11–3.14 supported. 3.14 is the active development target; 3.12 is also tested. 3.11 and 3.13 are expected to work but not exercised.
• Python < 3.11 will not work: the config loader uses tomllib (added to the stdlib in 3.11). Older versions fail at import with ModuleNotFoundError: No module named 'tomllib'. The fix is to upgrade Python, not to install a third-party TOML library.

Java (required for normal use)

Java is a hard requirement for the typical IDE4EEG workflow. SVAROG (the integrated EEG signal viewer / MP Book Viewer) and ConnectiVIS (3D dipole + connectivity viewer) are standalone Java applications, and SVAROG drives all the interactive review surfaces:

• View Step Result (👁 buttons on every preprocessing step) — synchronised before/after signal viewer.
• Bad Channels review — interactive channel picker (Svarog → MNE fallback).
• ICA component review — interactive component selector with pre-rendered topomap PNGs (Svarog → MNE fallback).
• Drop Segments review — bad-epoch picker with optional video sync (Svarog → MNE fallback).
• MP Book Viewer — Matching Pursuit atom inspection (Svarog only — no fallback).
• Output tab — open saved .fif / .raw files in Svarog from the file browser.
• ConnectiVIS — 3D dipole sources and directed connectivity arrows.

The headless CLI (ide4eeg --run config.toml) is the one path that runs without Java — useful for cluster batch jobs once parameters are dialled in via the GUI. Everything else assumes a JVM is on PATH.

• Minimum: Java 8 (JDK/JRE 8 or later). SVAROG is a Swing application that runs on any modern JVM.
• Recommended: Java 17 LTS (OpenJDK 17 or Eclipse Temurin 17). Best tested, available on all platforms.
• Java 16 or later: IDE4EEG automatically adds the required --add-opens flags so SVAROG's internal Swing reflection does not crash with InaccessibleObjectException. No manual configuration needed.
• Java 21 LTS also works.

Quick install:

# macOS (Homebrew)
brew install openjdk@17

# Ubuntu / Debian
sudo apt install openjdk-17-jdk

# Windows / cross-platform
# Download from https://adoptium.net (Eclipse Temurin, free)

The Svarog and ConnectiVIS jars themselves are fetched on demand by the GUI's Download recent button (Config tab) — you don't need to install them manually, only the JVM to run them.

Python dependencies are declared in pyproject.toml ([project.dependencies] for the EEG core, [project.optional-dependencies.video] for the video extra). requirements.txt is a thin alias (-e .[video]) for the editable dev install.

Optional: GPU acceleration for facetag (video face detection)

By default IDE4EEG uses ONNXRuntime's CPU provider, plus CoreML on Apple Silicon Macs (automatic — no config needed). For significant speedup on NVIDIA or DirectX 12 hardware, swap the stock onnxruntime package for a hardware-specific variant:

pip uninstall -y onnxruntime
pip install onnxruntime-gpu       # NVIDIA (Linux/Windows)
# or
pip install onnxruntime-directml  # any DX12 GPU on Windows 10+
# or
pip install onnxruntime-openvino  # Intel CPU/iGPU/VPU

Expected facetag speedup on face detection/recognition versus the CPU baseline:

Hardware	Provider	Speedup
Apple Silicon Mac	CoreML	3–8×
Intel Mac	CPU	1×
Linux/Windows NVIDIA	CUDA	5–20×
Windows DX12 GPU	DirectML	3–10×
CPU only	CPU	1×

Requirements for the GPU variants:

• onnxruntime-gpu: CUDA Toolkit + cuDNN matching the package version
• onnxruntime-directml: Windows 10+ with a DirectX 12 GPU

IDE4EEG code is unchanged — InsightFace's provider list automatically picks up whichever ExecutionProvider your installed ORT variant supports. Check the Run log at pipeline start for InsightFace detection session using: ... to verify which backend activated.

Architecture

GUI or config.toml
    |
    v
 input/          -- load raw EEG data (metadata-only for GUI preview)
    |
    v
 preprocessing/  -- filter, re-reference, ICA, artifact rejection
    |
    v
 analysis/       -- time, frequency, and time-frequency analysis
    |
    v
 plots/          -- generate figures
    |
    v
 IDE4EEG_OUT_<filename>/      -- all results in one folder

GUI

Launch with ide4eeg (or python -m ide4eeg). Pass an optional path — ide4eeg myconfig.toml — to preload a saved pipeline config into the form.

The interface has seven tabs:

1. Config — tool paths (Svarog, 3D view / connectivis, empi, mpv video backend) with Download recent button for one-click install from GitLab plus Homebrew-assisted mpv install on macOS, preprocessing step constraints, overwrite toggle.
2. Input — input signal, video, output paths; signal info (auto-read from headers); example data with reproducible figures from published papers.
3. Preprocess — collapsible step rows with per-step Save checkboxes (auto-sync to step-enable state — checking a step also flips its save on; unchecking flips save off). Steps in canonical fixed order: Segmentation setup, Trim, Bad Channels, Montage & Reference, Filtering & Resampling, ICA, MP Decomposition, MP Filter. Reorderable steps: Drop Channels, Gaze, EEG Artifacts. Postamble (always runs): Cut Segments, Drop Segments.
4. Analysis — IDE4EEG-native: EEG Profiles (FASP), MP-book viewers, Connectivity, Source estimation (MMP dipoles + classical ERP fit + MNE/dSPM/sLORETA/eLORETA + LCMV + MxNE). MNE-Python catalog wrappers grouped into six category panels: ERP, Spectra, Time-frequency, Spatial, Comparison, Source estimation. Each with a Run button that executes via the Run tab.
5. Run — pipeline execution with compact stage status, progress bar, real-time log, and Stop button.
6. Output — browse output folders, preview images/CSV/FIF files, open in MNE or SVAROG.
7. Help — embedded reference with scientific citations.

A persistent top bar (visible on Config through Analysis tabs) provides Segments (timed windows / event-locked) and Viewer (SVAROG/MNE) selection.

Where IDE4EEG stores files

Two top-level filesystem locations cover everything installed at runtime:

• ~/.obci/ — external binaries (Svarog jar, empi, mpv portable, ConnectiVIS jar) plus IDE4EEG-managed runtime data under ~/.obci/ide4eeg/:
  • ~/.obci/ide4eeg/models/L2CSNet_gaze360.pkl — L2CS-Net gaze checkpoint (~91 MB, downloaded on first L2CS use).
  • ~/.obci/ide4eeg/insightface/models/buffalo_l/ — InsightFace face-detection / identity models (~200 MB, downloaded by InsightFace on first use; redirected from upstream's ~/.insightface/ default).
• <venv>/lib/python3.X/site-packages/ — pip-installed Python packages including the seven video-stack libraries (cv2, av, imageio, insightface, onnxruntime, torch, torchvision, l2cs). Footprint ~250 MB minimum, up to ~2 GB on Linux with PyTorch CUDA wheels.

Existing installs with files in legacy locations (~/.insightface/, <package>/preprocessing/facetag/models/) are migrated automatically to ~/.obci/ide4eeg/ on first launch via same-disk renames — no re-downloads required when migration succeeds. See USER_MANUAL §1.2.1 for the full table and uninstall instructions.

Troubleshooting

Problem	Solution
ModuleNotFoundError: No module named 'tomllib'	Python < 3.11 is not supported. Upgrade to Python 3.11 or later.
ModuleNotFoundError after install	Make sure the virtual environment is activated (source .venv/bin/activate).
L2CS-Net won't install	Use the Download recent button on the Config tab next to "L2CS-Net (gaze detection)" — it installs torch + l2cs + the Gaze360 weights in one shot (the canonical, tested install path).
Failed building wheel for insightface / stringzilla (Linux, Python 3.14)	These packages don't ship cp314 wheels yet, so pip falls back to building from sdist, which needs a C/C++ compiler. Install one: sudo apt install build-essential (Debian/Ubuntu), sudo dnf groupinstall "Development Tools" (Fedora). Alternatively, use Python 3.13 (wheels available) or stay on the lite install (pip install ide4eeg) — facetag will be unavailable but everything else works.
"Where are my results?"	Output goes to IDE4EEG_OUT_<filename>/ next to your input file (or under the directory set in output path).
Qt platform plugin "xcb" error (Linux)	Install libxcb-cursor0: sudo apt install libxcb-cursor0 (Debian/Ubuntu) or sudo dnf install xcb-util-cursor (Fedora).
SVAROG doesn't open / "Java not found"	Install Java 17: brew install openjdk@17 (macOS) or sudo apt install openjdk-17-jdk (Linux) or download from adoptium.net.
SVAROG crashes with InaccessibleObjectException	You are running Java 16+ without the required module-open flags. Update IDE4EEG — recent versions add these flags automatically.
onnxruntime install fails on Intel Mac with Python 3.14	Stay on the lite install (pip install ide4eeg) — facetag is the only feature that needs onnxruntime. Alternatively, switch to Python 3.13 where the wheel exists.

Links

• User Manual — full parameter reference and walkthrough. A polished PDF (IDE4EEG_user_manual_v<version>.pdf) is committed alongside; rebuild it with ./scripts/build_pdf.sh after editing the markdown (requires pandoc + xelatex — brew install --cask basictex on macOS, apt install texlive-xetex texlive-fonts-recommended on Linux).
• Contributing — development setup
• License — GPL-3.0