Metadata-Version: 2.4
Name: ide4eeg
Version: 0.8.7
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
[![PyPI](https://img.shields.io/pypi/v/ide4eeg.svg)](https://pypi.org/project/ide4eeg/)
[![Python versions](https://img.shields.io/pypi/pyversions/ide4eeg.svg)](https://pypi.org/project/ide4eeg/)
[![License: GPL-3.0](https://img.shields.io/badge/License-GPL_v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Pipeline](https://gitlab.com/fuw_software/ide4eeg/badges/main/pipeline.svg)](https://gitlab.com/fuw_software/ide4eeg/-/pipelines)
[![Releases](https://img.shields.io/badge/releases-GitLab-fc6d26?logo=gitlab)](https://gitlab.com/fuw_software/ide4eeg/-/releases)
[![Windows installer](https://img.shields.io/badge/Windows-installer-0078d4)](https://gitlab.com/fuw_software/ide4eeg/-/releases/permalink/latest)
[![macOS .dmg](https://img.shields.io/badge/macOS-.dmg-000?logo=apple)](https://gitlab.com/fuw_software/ide4eeg/-/releases/permalink/latest)
[![User Manual](https://img.shields.io/badge/manual-GitLab%20Pages-fc6d26?logo=gitlab)](https://p3ace-de796c.gitlab.io)

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+

```bash
pip install ide4eeg 
```

After install, GUI offers installation of video tools on first use; 
see [Installation](#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](https://gitlab.com/fuw_software/ide4eeg/-/releases/permalink/latest)

| 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

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

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

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

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

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

```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` 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](ide4eeg/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](ide4eeg/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
