Skip to main content

IDE4EEG

PyPI Python versions License: GPL-3.0 Pipeline Releases Windows installer macOS .dmg User Manual HTML manual Knowledge base

User-friendly interactive pipeline for EEG analysis. From preprocessing (including gaze detection in video-EEG) to publication-ready plots and interactive 3-D visualizations of advanced results (including matching pursuit, dipole localisation and connectivity).

Debugging and explainability: IDE4EEG visualizes incremental changes to the signal in each step of the pipeline.

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 Download Installed Includes Use if you...
lite ~875 MB ~1.8 GB EEG core, GUI, Svarog / empi / ConnectiVIS (Java bundled) Analyse EEG only
full ~1.3 GB ~2.7 GB lite + facetag, gaze, synced video (OpenCV, PyTorch, InsightFace, L2CS-Net, mpv + ffmpeg bundled) Run video-artifact detection

Sizes measured on the macOS Apple Silicon 0.9 builds; Windows is comparable (full installs to ~3 GB).

Click 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>-arm64.dmg — drag to /Applications —
macOS 12+ (Intel) IDE4EEG-lite-<version>-x86_64.dmg — drag to /Applications (lite only, see below) —

Why Intel Macs get lite only: PyTorch's last x86_64 macOS wheel (torch==2.2.2) predates NumPy 2 and was compiled against the NumPy 1.x C ABI, while IDE4EEG requires numpy>=2.0. The two cannot coexist, so a full bundle would ship a torch whose NumPy bridge never initialises — taking out ICLabel and L2CS gaze while appearing to install fine. The Intel lite build bundles onnxruntime, so ICA with ICLabel works; the video stack is not bundled, so the facetag / gaze panels stay disabled. Intel users who need gaze detection should pip install ide4eeg[video] instead, where InsightFace head-pose gaze runs on onnxruntime — L2CS eye-gaze is unavailable on Intel macOS either way, for the same torch reason.

macOS first-launch — macOS blocks it once. Four clicks, no Terminal:

  1. Drag the app from the .dmg window to Applications, then eject the .dmg.
  2. Double-click the app. macOS refuses to open it — click Done. (This step is required: the button in step 3 only appears after a blocked attempt.)
  3. Open System Settings → Privacy & Security, scroll down to the message naming the app, click Open Anyway and confirm with your password or Touch ID.
  4. Double-click the app again. It opens, and macOS will not ask again.

Depending on your macOS version, step 2's refusal reads as one of these — all the same block, none of them a defect in the app:

  • "…cannot be opened because Apple cannot check it for malicious software…"
  • "Launch error — See the py2app website for debugging launch issues" → not an application crash, despite how it reads: the launcher was stopped before it could start Python, and py2app reports any startup failure with this one generic dialog.
  • "…is damaged… Move to Trash" → the app is not damaged.

Why any of this happens: the app is ad-hoc signed but not notarized (no Apple Developer Program enrollment). Downloading the .dmg attaches macOS's quarantine flag to it, and mounting propagates it to all ~21 000 files inside; while it is set, macOS runs the app from a randomised read-only copy (App Translocation) and Gatekeeper stops it. The flag is what decides this, not where the app sits — it behaves identically from the mounted DMG, from /Applications and from the Desktop.

Terminal shortcut (optional)

Clearing the flag by hand does the same thing without the click-through. On the disk image, before mounting it, one command covers the whole bundle:

xattr -d com.apple.quarantine ~/Downloads/IDE4EEG-lite-<version>-arm64.dmg

(If it is already mounted, eject and mount again — the flag reaches the contents at mount time.) Or, on an app already copied out:

xattr -dr com.apple.quarantine /Applications/IDE4EEG.app   # or IDE4EEG-nogaze.app (lite)

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 detection and removal, ICA, algorithmic artifact rejection (peak-to-peak amplitude, slope, high-frequency/muscle, flat)
  • Time-domain analysis: grand-average ERPs, cluster permutation tests (MNE-Python catalog wrappers)
  • ERP data quality: ERP quality stats (effect size, single-trial AUC, window-free cluster mass) and SME (standardized measurement error), both per channel and condition
  • 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. Development happens on 3.14; the release tests (Linux and Windows CI) run on 3.13. 3.11 and 3.12 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). Python 3.15 is not supported yet: PySide6 has no release for it.

Java 17 LTS (11 is the minimum; required for Svarog, the integrated signal viewer). Svarog 4 compiles to class-file 55, so a Java 8 or 10 JVM cannot load it at all — it fails with UnsupportedClassVersionError. Java 13+ additionally enables AppCDS, which cuts roughly 380 ms off each Svarog / ConnectiVIS cold start by reusing a cached class archive. 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]
python -m ide4eeg.install_runner --repair-opencv   # run once, after the above

The second line is not optional housekeeping. insightface requires the non-headless opencv-python, and a pip extra cannot say "install this package but not its OpenCV", so the extra always ends with two distributions owning the same cv2/ — and the non-headless one wins. On Linux that build points QT_QPA_PLATFORM_PLUGIN_PATH at its own bundled Qt 5.15 plugins as soon as cv2 is imported. The repair uninstalls every variant and reinstalls the single headless one; it is safe to re-run and exits 0 when there is nothing to do. The GUI's Install missing button does this for you automatically, and a batch run warns if it detects the state.

The extra bundles OpenCV, PyAV, imageio, InsightFace and onnxruntime. L2CS-Net (the default eye-gaze backend, ~500 MB — the CPU PyTorch build, which is all IDE4EEG's gaze inference uses; the installer requests the CPU wheel on every platform) 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] (and ide4eeg[iclabel]) fails on one platform cell because onnxruntime doesn'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; 1.23.2 was the last release with Intel Mac wheels, for Python up to 3.13) 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. ICA is affected too: the ICLabel selector needs onnxruntime or PyTorch, and neither has a wheel for this cell, so ICA uses the find_bads selector.
Apple Silicon + any none Both pip install ide4eeg and pip install ide4eeg[video] work directly.
Linux + any Python (any arch) none Same as Apple Silicon. Python 3.14 was blocked here until 2026-07-31 (insightface / stringzilla had no cp314 wheels and built from sdist); upstream now ships a pure-Python insightface wheel and cp314 wheels for stringzilla / simsimd on x86_64 and aarch64, so no compiler is needed.
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, parallel-jobs and overwrite toggles.
  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 (strictly user-driven, default off; only the eye button force-flips them on). Two fixed signal-setup steps (Drop Channels, Montage) are configured on the Input tab. The reorderable cleaning steps — Trim, Reference, Resample, Detect Bad Channels, Filtering, MP Filter, ICA, Gaze, EEG Artifacts — default to this canonical order (Reference is default-early, right after Trim; MP Filter before ICA) and can be dragged (enable "Allow reordering"). MP Decomposition is available as a reorderable step too, but off by default. A fixed Segmentation-setup header always runs; 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 (continuous / 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 (~96 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).
    • ~/.obci/ide4eeg/logs/ide4eeg.log — rotating diagnostic log (the same messages the app's log panel shows, timestamped; keeps 3 rotated files, ≤ ~8 MB). Attach it to a bug report.
  • <venv>/lib/python3.X/site-packages/ — pip-installed Python packages including the eight video-stack libraries (cv2, av, imageio, insightface, onnxruntime, torch, torchvision, l2cs). Footprint ~250 MB core; the PyTorch + L2CS gaze stack adds ~500 MB (IDE4EEG installs the CPU PyTorch wheel on every platform — it never uses a GPU torch build). (For optional onnxruntime GPU acceleration of InsightFace — a separate subsystem — see "GPU acceleration for facetag" above.)

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 — Where IDE4EEG stores files 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) Fixed upstream — insightface 1.0.1 is a pure-Python wheel and stringzilla / simsimd ship cp314 wheels, so nothing compiles. If you still see this, pip is resolving older pinned versions: upgrade pip and let it pick current ones (pip install -U pip && pip install -U ide4eeg[video]). Confirm with pip install --dry-run --only-binary :all: insightface albumentations, which must succeed.
"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.
SVAROG fails with UnsupportedClassVersionError (…class file version 55.0…) Your Java is older than 11. Svarog 4 is compiled for Java 11; Java 8 and 10 cannot load it. Install Java 17 (see Prerequisites above) — IDE4EEG ≥ 0.9 refuses an older JVM up front instead of letting the launch fail.
onnxruntime install fails on Intel Mac with Python 3.14 Stay on the lite install (pip install ide4eeg). Two features need onnxruntime: video-based gaze detection, and the ICLabel selector of ICA (without it, ICA uses the find_bads selector). To get both, switch to Python 3.13, where the wheel exists.
Numbers won't enter into a GUI field (typed 0,5 rejected, 5.5 works) IDE4EEG uses . (period) as the decimal separator regardless of system locale — TOML and Python float() both require it. Use 0.5. Frequency / amplitude / scale fields also reject the - key at typing time (negative values are never valid there).
Desktop build (installer / portable) hangs or crashes at an analysis step Set Parallel jobs = 1 on the Config tab. Standalone builds run everything that uses joblib / MNE workers (filtering, resampling, the MNE catalog analyses, connectivity surrogates, dipole fitting) with one worker, because a frozen app cannot safely spawn parallel workers (most visibly on Windows); only MP decomposition (empi) and the IIR filter still use the field. A pip install is unaffected.
  • User Manual — full parameter reference and walkthrough. Read it online as HTML or PDF (the version + date print on the PDF's title page). Both are committed artifacts at version-free paths so their links stay stable across releases; the pages CI job only publishes them. Rebuild both with ./scripts/build_pdf.sh after editing the markdown, and commit them — nothing in CI renders the manual, so an unrebuilt edit never reaches the published copies. Requires pandoc + lualatex (brew install --cask mactex-no-gui on macOS, apt install texlive-luatex texlive-fonts-recommended on Linux — lualatex, not xelatex: it renders the GUI's color-emoji icons via HarfBuzz), and it must find a Python that can import ide4eeg (run it with the project venv active) or Appendix G is omitted.
  • Contributing — development setup
  • Maintainer wiki — the why, the failure history, and the bug-vs-feature behavioural contract; an LLM-maintained knowledge base (Karpathy's "LLM Wiki" pattern)
  • License — GPL-3.0

Metadata

Release files for ide4eeg 1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ide4eeg 1.0
File Size Uploaded Provenance Actions
ide4eeg-1.0.tar.gz 2.2 MB Without provenance Details for ide4eeg-1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ide4eeg 1.0
File Interpreter ABI Platform Actions
ide4eeg-1.0-py3-none-any.whl Python 3 none any Details for ide4eeg-1.0-py3-none-any.whl

Total release size: 3.6 MB

Release files / ide4eeg-1.0.tar.gz

Download URL ide4eeg-1.0.tar.gz
Size 2.2 MB
Tags Source
SHA-256 checksum
How to use checksums
0472a81b7932ff84457f70ab648a53b4e07759cb7360af24017e65fad94a504d
BLAKE2b-256 checksum
How to use checksums
9e4b37853a0e02e00b68ca51a7937d14d37dc49f0aa5006356ad6a540c789cd8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.17

Release files / ide4eeg-1.0-py3-none-any.whl

Download URL ide4eeg-1.0-py3-none-any.whl
Size 1.4 MB
Tags Python 3
SHA-256 checksum
How to use checksums
393f77a973131719dc25cf0324b8ef54f7ea77172fddd6d4cfc2ec5754c375fd
BLAKE2b-256 checksum
How to use checksums
1def296ded4b2c234eef6290271bc449bc5bbc77e4e640c438f3818e2dc43672
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.17

Security for ide4eeg 1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page