Metadata-Version: 2.4
Name: ide4eeg
Version: 0.8.8
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 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+

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