SpinFlowSim: dMRI signal synthesis from spins flowing in capillary networks

Introducing SpinFlowSim!

Here you'll find the code and essential data to simulate diffusion Magnetic Resonance Imaging (dMRI) signals arising from spins flowing in synthetic, realistic microvasculature networks obtained from histology.

The SpinFlowSim code was written by Francesco Grussu ([email protected]), Anna Voronova ([email protected]) and Athanasios Grigoriou ([email protected]). SpinFlowSim is distributed under the Attribution-NonCommercial-ShareAlike 4.0 International license (CC BY-NC-SA 4.0). Copyright (c) 2024, Fundació Privada Institut d’Investigació Oncològica de Vall d’Hebron (Vall d'Hebron Institute of Oncology (VHIO), Barcelona, Spain). All rights reserved. Link to license here.

The project that gave rise to these results received the support of a fellowship from ”la Caixa” Foundation (ID 100010434). The fellowship code is "LCF/BQ/PR22/11920010".

Foster open science by citing our preprint if you use SpinFlowSim in your research:

Anna Voronova, Athanasios Grigoriou, Kinga Bernatowicz, Sara Simonetti, Garazi Serna, Nuria Roson, Manuel Escobar, Maria Vieito, Paolo Nuciforo, Rodrigo Toledo, Elena Garralda, Roser Sala-Llonch, Els Fieremans, Dmitry S. Novikov, Marco Palombo, Raquel Perez-Lopez, Francesco Grussu. "SpinFlowSim: a blood flow simulation framework for histology-informed diffusion MRI microvasculature mapping in cancer". medRxiv 2024.07.15.24310335; doi: 10.1101/2024.07.15.24310335.

Requirements   |   Installation   |   Repository description   |   Usage   

Requirements

SpinFlowSim has been developed with python 3.10.8. To use SpinFlowSim and go through all its tutorials, the following third-party packages are required:

• numpy (developed with version 1.24.2)
• pandas (developed with version 1.5.3)
• Lcapy (developed with version 1.10)
• PySpice (developed with version 1.5)
• graph-tool (developed with version 2.45, commit b1a649d8)
• nibabel (developed with version '5.1.0')
• matplotlib (examples tested with version '3.7.1')
• mrtrix (developed with version '3.0.4').

Installation

Clone our repository as

git clone https://github.com/radiomicsgroup/SpinFlowSim

To perform flow simulations with SpinFlowSim and to go through all the tutorails, you will need all the dependencies listed above. As a bear minimum, to simply synthesise vascular dMRI signals with the syn.py tools, you will need graph-tool, Lcapy, PySpice and numpy. With Anaconda, run:

conda create --name spinflowsim -c conda-forge graph-tool python=3.10.8
conda activate spinflowsim
conda install -n spinflowsim numpy
conda install -n spinflowsim -c conda-forge pyspice
pip install lcapy

Repository description

The SpinFlowSim repository includes several sub-fodlers:

• The folder code stores the actual simulation and visualisation tools behind SpinFlowSim:
  • the file syn.py introduces the syn module, where the pipenet class is defined to work with vascular networks and to synthesise vascular dMRI signals. The manual of the syn module can be found here.
  • the file visu.py intrdocudes the visu module, where useful tools are defined to visualise spins flowing through vascular networks. The manual of the visu module can be found here.
• The folder examples contains some tutorials that illustrate how to use SpinFlowSim in practice.
• The folder networks contains the resolved vascular networks generated for our preprint. These can be used to synthesise vascular dMRI signals for any acquisition protocol of interest (find here how).

Usage

We have included some tutorials in the folder examples to illustrate how to use SpinFlowSim for your diffusion MRI analyses.

• In tutorial 1, we show how to create and initialise a SpinFlowSim pipenet object to resolve a vascular network drawn on histology, and to synthesise dMRI signals from the resolved vascular network.
• In tutorial 2, we show how synthetic signals can be used to inform microvasculature property inference, replicating the in silico parameter estimation experiments of our preprint.