LaBraM-DGVF

Minimal open-source implementation of LaBraM-DGVF, a DK80 80-ROI EEG-to-SEEG source-reconstruction and epileptogenic-region localization pipeline.

The repository contains the model, DGVF losses, subject-independent CV runners, DK80 schema utilities, HFO/FR label integration, and post-processing/evaluation code used by the paper experiments. It intentionally does not include private clinical data, intermediate results, checkpoints, or local machine paths.

What Is Included

• labram_dgvf/run_train.py: single-fold training/evaluation entry point.
• labram_dgvf/model_and_losses.py: LaBraM EEG encoder, BrainBERT-style SEEG encoder, GCN/ROI decoder, and DGVF losses.
• labram_dgvf/labram_wrapper.py: Braindecode LaBraM feature wrapper.
• labram_dgvf/cli/run_cv.py: subject-independent CV runner.
• labram_dgvf/cli/run_cv_multigpu.py: multi-GPU CV orchestration.
• labram_dgvf/cli/postprocess.py: ROI ranking and subject-level focus decision.
• labram_dgvf/cli/compare_physical.py: comparison against physical inverse baselines.
• labram_dgvf/cli/run_ablation_suite.py: leave-one-module-out ablation runner.
• labram_dgvf/dk80/roi_schema.py: DK80 ROI schema builder.
• docs/DATA_FORMAT.md: required local data layout.

Installation

git clone <your-github-url>/LaBraM-DGVF.git
cd LaBraM-DGVF
python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .

For GPU training, install a PyTorch build that matches your CUDA driver before pip install -e ..

Expected Data Layout

Private data are not distributed in this repository. Prepare local data as:

data/
  spike_bank_dk80/
  inverse_prior_dk80/subject_roi_maps/
  labels/subject_focus_dk80_master.csv
  labels/hfo_fr_dk80_labels.csv
  physical_inverse_predictions/
outputs/
  graph_artifacts/
  labram_dgvf_dk80/

See docs/DATA_FORMAT.md for exact file and array conventions.

Quick Smoke Test

The model code supports a mock mode that checks the model/loss stack without clinical data:

python -m labram_dgvf.run_train \
  --mode mock \
  --out-dir outputs/mock_run \
  --max-epochs 1 \
  --steps-per-epoch 1 \
  --device cpu

DK80 Graph Artifacts

python -m labram_dgvf.data_prep \
  --out-dir outputs/graph_artifacts \
  --n-roi 80 \
  --n-channels 64

Main CV Run

python -m labram_dgvf.cli.run_cv_multigpu \
  --data-dir data/spike_bank_dk80 \
  --inverse-prior-dir data/inverse_prior_dk80/subject_roi_maps \
  --focus-master-csv data/labels/subject_focus_dk80_master.csv \
  --hfo-label-path data/labels/hfo_fr_dk80_labels.csv \
  --out-dir outputs/labram_dgvf_dk80/formal_cv21 \
  --devices cuda:0,cuda:1,cuda:2,cuda:3 \
  --max-epochs 12 \
  --steps-per-epoch 24 \
  --launch

Third-Party Components

This repository uses the Braindecode LaBraM implementation and can load pretrained weights with:

braindecode/labram-pretrained

The pretrained model and Braindecode package are governed by their own licenses. No pretrained weights are redistributed here.

Citation

If this code is useful, please cite the associated LaBraM-DGVF paper and the upstream LaBraM/Braindecode resources used by the implementation.