EEGraph is a Python library to model electroencephalograms (EEGs) as graphs, enabling the analysis of brain connectivity between different brain areas. It has applications in the study of neurological diseases like Parkinson's or epilepsy. The graph can be exported as a NetworkX graph-like object or graphically visualized as an interactive HTML plot.

Citation

If you use this library, please cite:

Maitin, A. M., Nogales, A., Chazarra, P., & García-Tejedor, Á. J. (2023). EEGraph: An open-source Python library for modeling electroencephalograms using graphs. Neurocomputing, 519, 127–134. https://doi.org/10.1016/j.neucom.2022.11.050

Getting Started

Dependencies

Library	Purpose
NumPy	FFT, frequency band division, threshold
Pandas	DataFrame handling, electrode montage CSV reading
MNE	Reading EEG files in all supported formats
NetworkX	Graph creation, manipulation, adjacency matrix
Plotly	Interactive HTML graph visualisation
SciPy	Pearson correlation, cross-correlation, coherence, CSD, Hilbert transform, Shannon entropy
SCoT	DTF computation (MVAR model)
AntroPy	Spectral entropy (Welch method)
Kaleido	PNG export

Installing EEGraph

pip install EEGRAPH

Functions

Documentation

EEGraph documentation is available online. Examples of usage are also available.

Importing EEG data

Format	Extension
Brainvision	.vhdr
Neuroscan CNT	.cnt
European data format	.edf
Biosemi data format	.bdf
General data format	.gdf
EGI simple binary	.egi
EGI MFF format	.mff
eXimia	.nxe

Connectivity Measures

Measure	Key	Domain	Bands
Cross Correlation	cross_correlation	Time	No
Pearson Correlation	pearson_correlation	Time	No
Corrected Cross Correlation	corr_cross_correlation	Time	No
Phase Lag Index	pli	Time	No
Shannon Entropy	shannon_entropy	Time	No
Squared Coherence	squared_coherence	Frequency	Yes
Imaginary Coherence	imag_coherence	Frequency	Yes
Phase Locking Value (PLV)	plv	Frequency	Yes
Phase Lag Index (bands)	pli_bands	Frequency	Yes
Weighted Phase Lag Index (WPLI)	wpli	Frequency	Yes
Directed Transfer Function (DTF)	dtf	Frequency	Yes
Power Spectrum	power_spectrum	Frequency	Yes
Spectral Entropy	spectral_entropy	Frequency	Yes

Visit the documentation for default thresholds and detailed parameter descriptions.

Usage

Load data

import eegraph
G = eegraph.Graph()
G.load_data(path='eeg_sample.edf', exclude=['EEG EKG1-EKG2'])

With electrode montage

G.load_data(path='eeg_sample.gdf', electrode_montage_path='electrodemontage.set.ced')

The montage file must contain at least two columns (electrode number and label), separated by whitespace, ;, or :.

Modelate data

Without frequency bands

graphs, connectivity_matrix = G.modelate(window_size=2, connectivity='pearson_correlation')

With frequency bands

graphs, connectivity_matrix = G.modelate(
    window_size=2,
    connectivity='squared_coherence',
    bands=['delta', 'theta', 'alpha']
)

Custom threshold

graphs, connectivity_matrix = G.modelate(
    window_size=2,
    connectivity='pearson_correlation',
    threshold=0.8
)

Window size

• int: uniform window length in seconds — window_size=2 splits the EEG into 2-second segments.
• list: explicit interval boundaries in seconds — window_size=[0, 3, 8] creates two intervals: [0–3 s] and [3–8 s]. The first value must be 0.

Compute graph metrics

metrics = G.compute_metrics(graphs)

for key, m in metrics.items():
    print(f"Graph {key}: density={m['density']:.3f}, "
          f"avg_clustering={m['average_clustering']:.3f}, "
          f"edges={m['edges']}")

Visualize graph

G.visualize_html(graphs[0], 'graph_1')   # saves graph_1_plot.html and opens in browser
G.visualize_png(graphs[0], 'graph_1')    # saves graph_1.png

Channel names must be in one of these formats:

• Standard: Fp1, Fp2, C3, Cz
• Dash-separated: Fp1-EEG (electrode name on the left)
• Space-separated: EEG Fp1 (electrode name on the right)

Output

• graphs — dict of NetworkX Graph (or DiGraph for DTF) objects, one per time window (×bands for band measures).
• connectivity_matrix — np.ndarray of shape (G, N, N), all connectivity values regardless of threshold.

# Save matrix to CSV
import numpy as np
np.savetxt('connectivity.csv', connectivity_matrix[0], delimiter=',')

Execution example video

Video_EEGraph.mp4

EEGraph Workflow

Frequency Bands

Band	Range
Delta	1–4 Hz
Theta	4–8 Hz
Alpha	8–13 Hz
Beta	13–30 Hz
Gamma	30–45 Hz

Contributing

See Contribution guidelines for more information.

Versioning

See CHANGELOG.txt for major/breaking updates and version history.

Known Issues

• DTF + SciPy ≥ 1.10: scot 0.2.1 relies on scipy.shape which was removed. DTF connectivity is unavailable until a compatible scot release.
• NumPy ≥ 1.25 deprecation: array-to-scalar assignments have been updated in this branch.

Contact

Centro de Estudios e Innovación en Gestión del Conocimiento (CEIEC), Universidad Francisco de Vitoria.

• Responsible: Ana María Maitín (a.maitin@ceiec.es), Alberto Nogales (alberto.nogales@ceiec.es)
• Main developer: Pedro Chazarra
• Contributor: Fernando Pérez (@FernandoPerezLara)

License

This project is licensed under the GPL-3.0 License.