ide4eeg 0.8.4

Integrated Development Environment for EEG

IDE4EEG

User-friendly interactive pipeline for EEG analysis: from filtering, artifact detection (including gaze detection in video-EEG) and ICA correction, to publication-ready plots and interactive 3-D visualizations of advanced analyses including matching pursuit, dipole localisation and connectivity.

For the sake of explainability, IDE4EEG offers custom display of signal features incrementally changed in each step, allowing for debugging of complex pipelines.

Install

If you have Python 3.11+

pip install ide4eeg 

After install, GUI offers installation of video tools on first use; see Installation for prerequisites (Java) and edge-case platforms.

Pythonless simplified (Windows / macOS)

Variant	Size	Includes	Use if you...
lite	~800 MB	EEG core, GUI, Svarog / empi / ConnectiVIS (Java bundled)	Analyse EEG only
full	~2.5 GB (Windows ~3 GB)	lite + facetag, gaze, synced video (OpenCV, PyTorch, InsightFace, L2CS-Net, mpv + ffmpeg bundled)	Run video-artifact detection

Cick here for latest releases

Platform	Installer	Portable
Windows 10/11 (x64)	Ide4eegSetup-{lite,full}.exe — double-click to install	ide4eeg-{lite,full}-<tag>.zip — unzip + run
macOS 12+ (Apple Silicon)	IDE4EEG-{lite,full}-<version>.dmg — drag to /Applications	—

macOS first-launch: the .dmg is unsigned (no Apple Developer Program enrollment yet). Right-click the .app → Open → confirm. macOS remembers the choice; subsequent launches go straight in.

Windows first-launch: SmartScreen shows "Windows protected your PC". Click More info → Run anyway. (Code signing pending on a future release.)

Features

• Qt6 graphical interface (PySide6) with interactive signal preview, MP Book Viewer, 3D source visualization and integrated SVAROG viewer
• EEG data formats: .raw (BrainTech), .vhdr (BrainVision), .fif (MNE), .set (EEGLAB), .edf (EDF/EDF+), .bdf (BDF/BDF+)
• Matching Pursuit in Gabor dictionaries, Wigner time-frequency energy maps, nonlinear signal filtering
• Connectivity analysis: 13 measures (DTF, PDC, Coherence, GCI, AEC, etc.) via MVAR models
• EEG profiles: FASP-based graphoelements (spindles, alpha, delta, K-complexes) visualized over time
• 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
• 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)
• 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

python3 -m venv .venv && source .venv/bin/activate   # Linux / macOS
# .venv\Scripts\activate                              # Windows
pip install ide4eeg
ide4eeg                         # launch GUI — auto-prompts for video tools on first use

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.

Installation

Prerequisites

Python 3.11–3.14. 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).

Java 17 LTS (or 8+; required for Svarog, the integrated signal viewer). SVAROG (signal viewer / MP Book Viewer) and ConnectiVIS (3D dipole + connectivity viewer) are standalone Java applications, and SVAROG drives every interactive review surface: View Step Result (👁), Bad Channels review, ICA component review, Drop Segments review, MP Book Viewer, opening saved .fif / .raw files in the Output tab. The headless CLI (ide4eeg --run config.toml) is the one path that runs without Java.

# macOS
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. Java 16+ needs --add-opens flags for SVAROG's Swing reflection; IDE4EEG adds these automatically. Java 21 LTS also works.

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

The [video] extra (headless / scripted / CI)

pip install ide4eeg always succeeds (lite). The video stack (face / gaze artifact tagging) is normally installed in-app from the Config tab the first time you use video features — the GUI auto-prompts with a streaming-log dialog and a Cancel button.

For headless / scripted / CI setups where the GUI's auto-prompt never fires, install everything up-front:

pip install ide4eeg[video]

The extra bundles OpenCV, PyAV, imageio, InsightFace, and onnxruntime. 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 — PyPI bans direct VCS dependencies and L2CS lives at a GitHub URL.

Known wheel gaps

pip install ide4eeg[video] fails on a few platform cells because onnxruntime and insightface don't ship wheels everywhere. 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: 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 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.

Optional: GPU acceleration for facetag

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 needs CUDA Toolkit + cuDNN matching the package version; onnxruntime-directml needs 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