Metadata-Version: 2.4
Name: ide4eeg
Version: 0.8.1
Summary: Integrated Development Environment for EEG
Author-email: Piotr Durka <durka@fuw.edu.pl>
Maintainer-email: Piotr Durka <durka@fuw.edu.pl>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://gitlab.com/fuw_software/ide4eeg
Project-URL: Repository, https://gitlab.com/fuw_software/ide4eeg
Project-URL: Bug Tracker, https://gitlab.com/fuw_software/ide4eeg/-/issues
Keywords: eeg,neuroscience,signal-processing,mne
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Environment :: X11 Applications :: Qt
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: scipy<2.0,>=1.13
Requires-Dist: numpy<3.0,>=2.0
Requires-Dist: matplotlib<4.0,>=3.8
Requires-Dist: tqdm
Requires-Dist: Pillow
Requires-Dist: mne<2.0,>=1.7
Requires-Dist: nibabel
Requires-Dist: readmanager>=1.6.1
Requires-Dist: pandas
Requires-Dist: send2trash
Requires-Dist: certifi
Requires-Dist: joblib
Requires-Dist: threadpoolctl
Requires-Dist: python-picard
Requires-Dist: mne-icalabel
Requires-Dist: PySide6<7.0,>=6.6
Requires-Dist: py7zr; sys_platform == "win32"
Provides-Extra: video
Requires-Dist: opencv-contrib-python-headless; extra == "video"
Requires-Dist: imageio[pyav]; extra == "video"
Requires-Dist: av>=14.0; extra == "video"
Requires-Dist: insightface; extra == "video"
Requires-Dist: onnxruntime; extra == "video"
Dynamic: license-file

# 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](#java-required-for-normal-use) below).

```bash
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

```bash
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](#gui) for the full invocation list.

### From a checkout (development)

```bash
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:
```bash
# 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:

```bash
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](USER_MANUAL.md#121-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) | 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](https://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](USER_MANUAL.md) — 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](CONTRIBUTING.md) — development setup
- [License](LICENSE) — GPL-3.0
