brainnet-graph 0.2.0

Graph construction from BOLD signal time series

🧠 brainnet-graph

---

A lightweight, flexible Python package to construct brain connectivity graphs from ROI-level fMRI BOLD signals using multiple correlation-based methods.

---

🚀 Features

• Supports raw time-series inputs: .csv, .tsv, .pkl
• Build graphs using:
  • Pearson correlation
  • Partial correlation
  • Cosine similarity
• Outputs in .pt (PyTorch Geometric Data) or .csv (edge list)
• One-liner CLI usage
• Easily integrable in pipelines or tutorials
• Demo mode for quick testing
• Built-in input validation & flexible formatting

---

📦 Installation

pip install brainnet-graph

Requires Python 3.7+

---

🧠 Concept

Given ROI-level fMRI BOLD signal data ( X \in \mathbb{R}^{T \times N} ), where:

• ( T ) = number of time points
• ( N ) = number of brain regions (ROIs)

We construct an undirected, weighted graph ( G = (V, E, W) ) such that:

• Each node ( v_i \in V ) represents a brain region
• Edges ( (v_i, v_j) \in E ) are computed using a similarity or correlation measure between time series ( X_i ) and ( X_j )

---

🚀 Quick Start

🧪 Methods Supported

The following methods are supported to construct brain connectivity graphs from time-series data:

Method	Description
pearson_correlation	Classic Pearson correlation: linear association(\rho(X_i, X_j))
spearman_correlation	Rank-based Spearman correlation
kendall_correlation	Kendall’s tau correlation for ordinal association
partial_correlation	Removes the effect of other ROIs using inverse covariance
cosine_similarity	Measures angular similarity between ROI vectors
correlations_correlation	Second-order correlation: similarity between ROI correlation profiles
associated_high_order_fc	High-order FC using correlation of correlation vectors
euclidean_distance	Distance-based connectivity (low = more similar)
knn_graph	Builds graph using k-nearest neighbors (non-correlation)
mutual_information	Nonlinear dependency estimation via mutual information
cross_correlation	Temporal lagged correlation
granger_causality	Temporal causal inference using Granger's test
generalised_synchronisation_matrix	Dynamical systems synchrony —very slow
patels_conditional_dependence_measures_kappa	Conditional dependence metric (Patel’s(\kappa))
patels_conditional_dependence_measures_tau	Conditional dependence metric (Patel’s(\tau))
lingam	Causal inference using LiNGAM model —very slow

📌 Note:

• Some methods like lingam and generalised_synchronisation_matrix are computationally intensive.
• All methods return a connectivity matrix which is then converted to a PyTorch Geometric graph object or edge list CSV.
• You can plug in your own method via code if desired (ask in GitHub Issues and we’ll help).

---

🛠️ From CLI

construct-graph --input bold.csv --output graph.csv --method pearson_correlation

📦 With Demo Data

construct-graph --demo

Save demo as PyTorch Geometric .pt:

construct-graph --demo --format pt

---

🧰 CLI Arguments

Flag	Description
--input, -i	Path to input BOLD signal (.csv/.tsv/.pkl)
--output, -o	Output file path (.csv or .pt)
--method, -m	Method to use (see above)
--format, -f	Output format:csv or pt
--demo	Run using generated toy dataset

---

🧬 Python API

from brainnet_graph.construction import load_data, validate_data, construct_graph, save_graph

df = load_data("subject001.csv")
validate_data(df)
graph = construct_graph(df, method_name="pearson_correlation")
save_graph(graph, "subject001_graph.csv", fmt="csv")

---

📁 Example

Input CSV (ROI x Time):

ROI_1, ROI_2, ROI_3, ...
0.24,  0.42,  0.11
0.30,  0.39,  0.14
...

→ Graph → Edgelist or PyTorch Data object

---

📚 Output Format

🔹 CSV output

source,target,weight
0,1,0.82
0,2,0.57
...

🔹 PyTorch Geometric .pt

Data(x=[10, 1], edge_index=[2, 45], edge_attr=[45, 1])

---

📷 Visual Example

Use NetworkX + PyTorch Geometric to visualize the graph:

import torch
import networkx as nx
from torch_geometric.utils import to_networkx

graph = torch.load("demo_graph.pt")
G = to_networkx(graph)
nx.draw(G, with_labels=True)

---

📖 Docs

Full documentation available at: 👉 https://brainnet-graph.readthedocs.io/

---

🛡 License

MIT License. See LICENSE for details.

---

🤝 Contributing

Open to contributions, new methods, bug reports, or real data testing.

---

🔗 Related

• PyTorch Geometric
• NetworkX
• fMRIPrep
• Nilearn