brainnet-graph 0.2.2
Graph construction from BOLD signal time series
Requires Python: >=3.7

# 🧠 brainnet-graph

[![PyPI version](https://img.shields.io/pypi/v/brainnet-graph.svg)](https://pypi.org/project/brainnet-graph/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.7+-brightgreen.svg)](https://www.python.org/)
[![Docs](https://img.shields.io/badge/docs-online-blue)](https://brainnet-graph.readthedocs.io/)

---

> 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

```bash
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

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

### 📦 With Demo Data

```bash
construct-graph --demo
```

Save demo as PyTorch Geometric `.pt`:

```bash
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

```python
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

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

### 🔹 PyTorch Geometric `.pt`

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

---

## 📷 Visual Example

Use NetworkX + PyTorch Geometric to visualize the graph:

```python
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](LICENSE) for details.

---

## 🤝 Contributing

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

---

## 🔗 Related

- [PyTorch Geometric](https://pytorch-geometric.readthedocs.io/)
- [NetworkX](https://networkx.org/)
- [fMRIPrep](https://fmriprep.org/)
- [Nilearn](https://nilearn.github.io/)