EEGTrust

EEGTrust is a pediatric EEG seizure detection project with:

• data preprocessing and windowing utilities,
• deep-learning training pipelines,
• real-time inference and alerting,
• explainability helpers,
• performance and integration test scripts.

This README focuses on getting the repository running quickly and reliably.

Quick Start

1) Create a Python environment

Use Python 3.9-3.11 for best dependency compatibility.

python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -r requirements.txt

For real-time-only dependencies:

pip install -r requirements_realtime.txt

2) Prepare data

Most training/testing scripts expect preprocessed NumPy files in prepared_data/, for example:

• prepared_data/chb01_windows.npy
• prepared_data/chb01_labels.npy
• prepared_data/chb02_windows.npy
• prepared_data/chb02_labels.npy

Optional helpers:

python scripts/download_data.py
python scripts/prepare_training_data.py
python scripts/prepare_training_data_v2.py

3) Train

Primary training entrypoint:

python scripts/train_with_existing_data.py

Small/smoke mode (requires prepared_data/small_windows.npy and prepared_data/small_labels.npy):

python scripts/train_with_existing_data.py small

4) Run tests

python scripts/run_all_tests.py

Or run individual suites:

python scripts/test_accuracy.py
python scripts/test_latency.py
python scripts/test_integration.py
python scripts/test_metadata.py

5) Real-time inference

python scripts/run_realtime_detection.py

With dashboard:

python scripts/run_realtime_with_dashboard.py

Standalone dashboard tools:

python scripts/realtime_dashboard.py
python scripts/simple_dashboard.py

Project Layout

EEGtrust/
├── eegtrust/                      # Core package (data, model, train, inference, utils)
├── scripts/                       # Training, evaluation, realtime and utility scripts
├── dashboard/                     # Dashboard app code
├── requirements.txt
├── requirements_realtime.txt
├── README_REALTIME.md             # Detailed realtime system docs
└── TESTING_GUIDE.md               # Detailed testing docs

Core Commands

# Quick sanity check
python scripts/quick_test.py

# Full system test
python scripts/test_system.py

# Export ONNX
python scripts/export_onnx.py

Notes on Current Training Paths

• scripts/train_with_existing_data.py is the maintained practical training path.
• eegtrust/train.py contains reusable training functions and legacy code paths; its default prepare_data() flow is intentionally guarded and not the primary entrypoint.

Additional Documentation

• Real-time system details: README_REALTIME.md
• Testing details and interpretation: TESTING_GUIDE.md