alinc66/gbm-latent-attractors-brats2020

Latent Attractor Landscape for GBM Morphodynamics

Reproducible Implementation (BraTS 2020)

This repository contains the complete source code and pretrained model weights for the latent-space framework introduced in our manuscript:

AI-Guided Inference of Morphodynamic Attractors-Like States in Glioblastoma
Authors: Simona Ruxandra Volovăț, Călin Gheorghe Buzea, Dragos Teodor Iancu, Maricel Agop, Lăcrămioara Ochiuz, Dragoș Ioan Rusu, Diana Ioana Panaite, Mădălina Raluca Ostafe and Cristian Constantin Volovăț
2024–2025

The framework includes:

• A 3-D convolutional autoencoder for morphologic embedding
• Case-level latent feature aggregation
• A latent stability metric derived from decoder sensitivity
• Static attractor discovery (K-means, K=3)
• Voxel-level attractor saliency maps (Shift / Flip)
• Neural-ODE latent dynamics and dynamic attractors
• Optional latent-space control simulations

All methods correspond exactly to Sections 2.3–2.16 of the manuscript and the mathematical derivations in Supplementary Section S6 + Algorithm S1.

---

🔗 Dataset

This work uses the public BraTS 2020 dataset (MRI only).
Due to licensing and size constraints:

We do not redistribute BraTS MRI data in this repository.

BraTS can be obtained from:

• The Cancer Imaging Archive (TCIA)
• Kaggle: https://www.kaggle.com/datasets/awsaf49/brats20-dataset-training-validation

You must preprocess the raw .nii.gz files using the script in src/preprocess_brats2020.py.

---

🚀 Pipeline Overview

Below is the full workflow implemented in this repository:

BraTS 2020 MRI (T1, T1Gd, T2, FLAIR) ↓ preprocessing (resample → normalize → npz) 3-D Autoencoder Training (64³ patches) ↓ Case-level Latent Embeddings z̄ ↓ Latent Stability s(z̄) ↓ Static Attractors (K=3) ↓ Voxel-level Attractor Saliency Maps ↓ Neural-ODE Latent Dynamics ↓ Dynamic Attractors (K=3)

All computations are fully reproducible through the scripts in /src.

---

📦 Installation

git clone https://huggingface.co/alinc66/gbm-latent-attractors-brats2020
cd <repo-name>
pip install -r requirements.txt

Requirements include:

torch>=2.0
torchvision
torchio>=0.18
numpy
pandas
scikit-learn
nibabel
tqdm
umap-learn
matplotlib
joblib
torchdiffeq

Repository Structure

repo/
│
├── README.md
├── requirements.txt
├── LICENSE
│
├── weights/
│   ├── ae3d_final.pth
│   ├── neural_ode_field.pth        (optional)
│   └── encoder_small.pth           (optional)
│
└── src/
    ├── preprocess_brats2020.py
    ├── train_autoencoder.py
    ├── embed_cases.py
    ├── compute_stability.py
    ├── compute_attractors.py
    ├── saliency_maps.py
    ├── train_neural_ode.py
    ├── models_ae3d.py
    ├── datasets_npz.py
    └── utils_*.py


Step-by-Step Instructions

1. Preprocess BraTS into .npz format

python src/preprocess_brats2020.py \
    --root /path/to/BraTS2020_raw \
    --out /path/to/preprocessed \
    --cube 128

Outputs:

/preprocessed/npz/*.npz

metadata_final.csv

2. Train the 3-D Autoencoder (or use provided weights)

python src/train_autoencoder.py \
    --base_dir /path/to/preprocessed \
    --epochs 80

Outputs:

models/ae3d_final.pth

You may skip this if using our pretrained weights.

3. Compute case-level latent embeddings (z̄)

python src/embed_cases.py \
    --base_dir /path/to/preprocessed

Outputs:

embeddings_caselevel.csv

4. Compute latent stability

python src/compute_stability.py \
    --base_dir /path/to/preprocessed

Outputs:

embeddings_caselevel_with_stability.csv

5. Compute static attractors (K = 3)

python src/compute_attractors.py \
    --base_dir /path/to/preprocessed

Outputs:

embeddings_with_attractor.csv
(contains attractor label for each subject)

6. (Optional) Voxel-level attractor saliency maps

python src/saliency_maps.py \
    --preprocessed_dir /path/to/preprocessed \
    --split train \
    --case_ids 1 2 3 \
    --n_perturbs 1200

Outputs per case:

flip_heat.npy

shift_heat.npy

meta.npy

Saved under:
/preprocessed/saliency_maps/


7. (Optional) Neural ODE latent dynamics + dynamic attractors

python src/train_neural_ode.py \
    --embeddings_csv /path/to/preprocessed/embeddings_caselevel_with_stability.csv \
    --output_dir /path/to/preprocessed/neural_ode

Outputs:

neural_ode_field.pth
embeddings_with_dynamic_attractors.csv
neural_ode_trajectories_pca2d.png (optional visualization)

📄 Mathematical Formulation

The complete mathematical derivation of the framework
(latent AE mapping, stability metric, basin geometry, saliency perturbations,
neural ODE field, and control objective) is provided in:

📘 Supplementary Section S6
📘 Algorithm S1

which correspond exactly to the implementation in this repository.


🔒 License and Data Usage

Code is released under MIT.

BraTS 2020 images are not included and must be downloaded separately from TCIA or Kaggle.

Any redistribution of MRI data must follow TCIA/BraTS licensing terms.

🙋 Support

If you have questions or find issues, please open an Issue on the repo or contact:

Calin Buzea
National Institute of Research and Development for Technical Physics
Email: [email protected]

🎉 Acknowledgments

We thank the BraTS 2020 organizers for providing a high-quality multimodal MRI dataset,
and the open-source ML/PyTorch community for enabling reproducible research.