Graph Neural Network for predicting immunosuppressive spatial niches in glioblastoma from 10x Visium spatial transcriptomics.
Figure: Overview of DeepGraph-GBM spatial graph construction from 10x Visium hexagonal coordinates, multi-task graph encoder architecture (GraphSAGE / GAT), spatial cellular niche classification, mesenchymal (MES) state regression, and cross-cohort external validation.
Glioblastoma (GBM) is marked by extreme spatial heterogeneity. Within a single tumor, distinct cellular microenvironments govern tumor progression, treatment resistance, and immunosuppression:
| Niche | Cellular & Anatomical Composition | Clinical Prognosis |
|---|---|---|
| Immune Cold | Mesenchymal tumor cells, immunosuppressive myeloid cells, absent T cells | Poorest outcomes |
| Immune Hot | Infiltrating T lymphocytes, activated microglia/macrophages | Relatively improved (rare in GBM, ~9% of spots) |
| Normal Brain | Peritumoral non-neoplastic cortex and white matter | Baseline reference |
| Necrotic Core | Ischemic necrosis and perinecrotic pseudopalisading zones | Poor (hypoxic transition zone) |
DeepGraph-GBM models 10x Visium tissue slides as spatial graphs (spots as nodes with 3,000 highly variable gene expressions, physical neighbors as edges weighted by Euclidean distance decay) to predict spatial niches, continuous mesenchymal tumor states, and slide-level hazard scores.
A sequential suite of 6 documented Jupyter notebooks is provided in notebooks/:
| Notebook | Focus Area | Highlights & Outputs |
|---|---|---|
01_data_exploration.ipynb |
Dataset & Label Rules | SNUH atlas metadata (23 sections, 13 patients, 34,988 spots), niche priority rules, 3,000 HVG marker audit (EGFR, VEGFA, CHI3L1), MES state distribution. |
02_spatial_graphs_and_splits.ipynb |
Spatial Graphs & Splits | k = 6 kNN graph construction, Gaussian edge weights, PyG Data structures, patient-level train/val/test splits, 6-split benchmark design. |
03_model_architecture_and_training.ipynb |
Model & Loss Dynamics | GraphSAGE vs GAT encoder comparisons (~870k params), real section forward pass, multi-task loss decomposition with rare-class boosting, loss convergence curves. |
04_model_evaluation_and_inference.ipynb |
Evaluation & Spatial Maps | Checkpoint loading (best_model.pt), validation threshold tuning (τ_c), test metrics, confusion matrix, true vs predicted spatial niche & MES maps. |
05_external_and_survival_validation.ipynb |
External & Survival Analysis | 13 Greenwald Visium samples (Cell 2024), Neftel MES correlation (r = 0.30), TCGA-GBM (n = 166) Kaplan-Meier survival curves & Cox regression (p = 0.25). |
06_benchmarking_and_protocol_reversal.ipynb |
Benchmarks & Protocol Reversal | Table 1 matched baseline comparisons, paired t-tests, Protocol Reversal phenomenon (Fig. 4), 72-run multi-split variance decomposition (Fig. 5). |
flowchart TD
A["10x Visium Spatial Slide<br>(Spots = Nodes with 3,000 HVGs, k=6 Neighbors = Edges)"] --> B["Shared Graph Encoder<br>(GraphSAGE / GAT: 3000 → 256 → 256 → 128)"]
B --> C["128-dim Latent Spot Embedding (z_i)"]
C --> D["Head 1: Spatial Niche Classifier<br>(4 Classes per spot, Cross-Entropy Loss)"]
C --> E["Head 2: Mesenchymal State Regressor<br>(Continuous 0–1 probability, BCE Loss)"]
C --> F["Head 3: Slide Survival Risk Score<br>(Global Mean Pooling, MSE Loss)"]
Multi-Task Objective:
To mitigate severe class imbalance (immune_hot is ~9% of spots), loss weights are boosted for minority classes (3.0× for immune_hot, 1.5× for necrotic).
| Dataset | Role | Content |
|---|---|---|
| SNUH 2026 Atlas (Nat Commun 2026, PRJNA1337938) | Train / Val / Test | 23 sections, 13 IDH-wildtype GBM patients, 34,988 spots with anatomical features and single-cell metaprogram annotations. |
| Greenwald et al. (Cell 2024, Zenodo) | External Validation | 13 glioblastoma Visium sections, diverse tumor regions, Neftel single-cell meta-modules. |
| TCGA-GBM (NCI GDC) | Clinical Survival | Bulk RNA-seq + overall survival follow-up ( |
Niche Label Definition: Derived by audited rules in configs/labels.yaml:
necrotic: Perinecrotic and pseudopalisading zones.normal: Non-neoplastic cortical grey matter and white matter.immune_hot: Microglia / macrophage / myeloid infiltration signatures.immune_cold: Dense malignant cellular tumor core.- Ambiguous / discordant boundary spots are marked
excludeand masked out during loss calculation.
# Clone the repository
git clone https://github.com/hossainlab/deepgraph-gbm.git
cd deepgraph-gbm
# Install dependencies using pip or uv
pip install -e .# Download datasets (~4.0 GB)
bash scripts/01_download_data.sh data
# Build spatial kNN graphs and preprocessed bundles
python scripts/02_build_graphs.py --data-dir data/raw --out-dir data/preprocessed
# Train the multi-task model
python scripts/03_train.py --config configs/default.yaml
# Evaluate on held-out test patients with validation threshold tuning
python scripts/04_evaluate.py --data-dir data/preprocessed --ckpt results/models/best_model.pt
# Run external cohort validation (Greenwald et al.)
python scripts/05_external_validation.py --greenwald-dir data/raw/greenwald \
--ckpt results/models/best_model.pt --hvg data/preprocessed/hvg_genes.json
# Run TCGA clinical overall survival validation
python scripts/06_survival_validation.py --tcga-dir data/raw/tcga
# Generate publication figures and summary tables
python scripts/07_make_figures.pyWhen non-graph baselines (MLP, Logistic Regression) are trained under identical conditions (matched early stopping) and scored with identical validation-tuned decision thresholds, single-spot gene expression contains sufficient signal to achieve competitive or superior performance:
| Architecture | Macro-F1 (Mean ± Std) | Weighted-F1 | Accuracy | MES AUROC |
|---|---|---|---|---|
| MLP (No-Graph Baseline) | 0.578 ± 0.021 | 0.793 ± 0.003 | 0.789 ± 0.004 | 0.826 ± 0.016 |
| Logistic Regression | 0.554 | 0.761 | 0.748 | 0.751 |
| GAT (4-Head Attention) | 0.539 ± 0.038 | 0.768 ± 0.020 | 0.762 ± 0.022 | 0.760 ± 0.027 |
| GraphSAGE GNN | 0.489 ± 0.027 | 0.746 ± 0.025 | 0.750 ± 0.050 | 0.751 ± 0.041 |
Under mismatched scoring protocols (GNN evaluated with tuned thresholds while baselines used default argmax), the GNN appeared superior (
Across 6 patient-level splits and 3 random seeds (72 trained models), across-split variance is 3.6–8.1× larger than within-split seed variance. Robust conclusions in spatial biology necessitate repeated patient-level split resampling rather than single-split evaluations.
deepgraph-gbm/
├── assets/ # Graphical abstract and documentation images
├── configs/ # Hyperparameters, label rules, and patient splits
│ ├── default.yaml
│ ├── labels.yaml
│ ├── splits.json
│ └── splits_multisplit.json
├── data/ # Raw and preprocessed dataset directories
├── notebooks/ # Sequential interactive exploration notebooks (01 to 06)
├── results/ # Metrics tables, models, figures, and benchmark logs
├── scripts/ # Execution pipeline scripts (01_download to 14_fig_protocol_reversal)
├── src/deepgraph_gbm/ # Core Python library
│ ├── data/ # Dataset loaders, kNN graph builders, label rules
│ ├── models/ # GraphSAGE, GAT, multi-task architecture, baselines
│ ├── training/ # Training loop, multi-task loss, evaluation metrics
│ └── interpret/ # Spatial map rendering and neighbor importance
└── tests/ # Pytest test suite (labels, graphs, model shapes, splits)
- Silver-Standard Labels: Niche annotations are derived from algorithmic rule hierarchies on single-cell metaprograms and anatomical features rather than manual pathologist annotations.
- Discovery-Level Survival Validation: Spatial Visium datasets currently lack long-term clinical survival follow-up; the survival head is trained on a niche-composition pseudo-risk proxy and validated on bulk TCGA-GBM.
- Hardware Efficiency: Optimized for standard CPU and single GPU environments using PyTorch and PyG.
This project is licensed under the MIT License.