README.md

Geometric Basis Functions (GBFs) - constrained EEG/MEG Source Imaging

Abstract

Non invasive electrophysiology lacks methods that accurately reconstruct whole brain spatiotemporal dynamics while incorporating individual cortical geometry, leaving current electroencephalography and magnetoencephalography source imaging limited by simplistic or biologically implausible priors. Here, we show that embedding patient-specific Geometric Basis Function (GBF), eigenmodes derived from each individual’s cortical surface, provides a powerful anatomic constraint that resolves the inverse problem and improves reconstruction fidelity. The method allows reconstruction of the sources as linear combinations of geometric organization of neural dynamics. We validate GBF across the Meta-Source Benchmark, task-evoked data, resting-state networks, intracranial stimulation, and epilepsy data. The results demonstrate that GBF yields high localization accuracy and captures fast spatiotemporal dynamics consistent with anatomical pathways. These findings suggest that both spontaneous and evoked whole-brain activity can be described by hundreds of geometric modes, providing a compact yet accurate representation of neural sources. By linking cortical geometry to electrophysiological dynamics, GBF offers a versatile source imaging tool for both scientific and clinical applications.

Introduction

Brain waves reflect synchronized neural oscillations underlying cognitive functions and are best studied with high spatiotemporal resolution imaging. While fMRI provides whole-brain coverage but lacks temporal precision, invasive recordings like ECoG and SEEG offer high temporal accuracy but limited spatial scope. EEG/MEG balance these factors but suffer from poor spatial resolution, making EEG/MEG source imaging (ESI) essential. However, traditional ESI methods rely on simplistic priors, limiting accuracy. Since brain wave propagation is shaped by brain geometry, we propose a geometric basis function (GBF) framework that integrates individualized anatomical constraints from MRI. This method enhances source localization, improves reconstruction of resting-state connectome, and reveals that neural dynamics propagate along structural pathways, offering a novel framework for understanding large-scale brain waves in cognitive and clinical contexts.

Auditory Task:

sub-006_run-01_Auditory_i15.mp4

CCEP:

sub07_run05_merge_i15-o30fps.mp4

Requirements

• Python: $\geq$ 3.12

• PyPI packages:

  invertmeeg
  lapy
  matplotlib
  mne
  neuromaps
  nibabel
  numpy
  pandas
  pyvista
  scikit_learn
  scipy
  tqdm
  wordcloud
  

Installation

First, clone the repository:

git clone https://github.com/ncclab-sustech/GBFs.git
cd GBFs

Option 1: Using uv

uv is the fastest way to get started. It automatically manages Python versions and virtual environments.

1. Install uv: Follow the official guide.
2. Sync Environment: Run the following command in the project root: uv sync

Option 2: Using conda

Suitable for users who prefer Anaconda / Miniconda environments.

1. Create & Activate Environment:

   conda create -n gbfs python=3.12 -y
   conda activate gbfs

2. Install Dependencies: pip install pygeodesic lapy "mne[full]" neuromaps wordcloud

It will take a few minutes depending on the computer and network.

Option 3: Using pip

Standard installation for existing environments.

pip install -r requirements.txt

Data

• The benchmark (data.7z) contains 200 clustered functional maps derived from fMRI meta-analysis data, all aligned to the MNI152 standard space. For details on the generation process, please refer to the associated paper and demo_benchmark.py. Additionally, we provide corresponding Neurosynth term vector word clouds and 2D visualizations (see the figs folder). Usage instructions can be found in demo_simulation.py.
• Cognitive task uses data from VEPCON dataset
• IES dataset is from CCEP dataset
• Other data could be found in our article

Contact

For any questions/comments, please contact NCC Lab.

Copyright

Copyright © 2025 NCC Lab, Southern University of Science and Technology, Shenzhen, China.