This repository contains several scripts and routines that one may find useful for the analysis of Magnetic Resonance Imaging (MRI) - mainly diffusion MRI (dMRI) - and histological data in body applications, as for example in liver imaging. The tools have been developed by Francesco Grussu as part of a ”la Caixa” Foundation Junior Leader fellowship at the Vall d'Hebron Institute of Oncology (VHIO), Barcelona (Spain). Contact: fgrussu@vhio.net.
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".
If you use bodymritools for your research, please cite our preprint:
Francesco Grussu, Kinga Bernatowicz, Marco Palombo, Irene Casanova-Salas, Ignasi Barba, Sara Simonetti, Garazi Serna, Athanasios Grigoriou, Anna Voronova, Valezka Garay, Juan Francisco Corral, Marta Vidorreta, Pablo Garcia-Polo Garcia, Xavier Merino, Richard Mast, Nuria Roson, Manuel Escobar, Maria Vieito, Rodrigo Toledo, Paolo Nuciforo, Joaquin Mateo, Elena Garralda, Raquel Perez-Lopez. "Histology-informed liver diffusion MRI: biophysical model design and demonstration in cancer immunotherapy". medRxiv 2024: 2024.04.26.24306429, doi: 10.1101/2024.04.26.24306429.
This repository 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 use of bodymritools MUST also comply with the individual licenses of all of its dependencies.
To get bodymritools, simply clone this GitHub repository:
git clone https://github.com/fragrussu/bodymritools
bodymritools has been written in python 3.10.9 (anaconda distribution). It relies on the following third-party packages:
- pandas (developed with version '1.5.3')
- nibabel (developed with version '5.1.0')
- numpy (developed with version '1.23.5')
- scipy (developed with version '1.10.1')
- pynrrd (developed with version '1.0.0')
- Pillow (developed with Pillow (the friendly PIL fork by Jeffrey A. Clark and contributors) version '9.4.0')
Third-party packages have been developed by different authors and have their own licenses. The use of bodymritools MUST also comply with the individual licenses of all of its dependencies.
bodymritools scripts are stored within the mrifittools, histotools and misctools folders. Each tool contains a detailed help manual. Manuals are stored in the manuals folder.
To print a script's manual on your terminal, simply navigate to the script and type:
python <SCRIPT_NAME> -h
For example:
cd mrifittools
python pgse2sphereinex.py -h
mrifittools enable voxel-wise fitting of several MRI signal models or representations (mainly dMRI) from scans in NIFTI format, given sequence parameters stored as text files. These are:
- getAdcAkc.py: tool fitting a mono-dimensional Diffusion Kurtosis Imaging signal representation (Jensen JH et al, Magn Res Med 2005, 53(6): 1432-1440, doi: 10.1002/mrm.20508) to Pulsed-Gradient Spin Echo (PGSE) dMRI data. Manual here.
- getT2ivimkurtReg.py: tool fitting the two-pool, diffusion-T2 relaxation "T2-IVIM-Kurtosis" model, disentangling tissue vs vascular signals, to Pulsed-Gradient Spin Echo (PGSE) dMRI data. The model extends the approach of Jerome NP et al, Phys Med Biol 2016, 61(24): N667–N680, doi: 10.1088/1361-6560/61/24/N667 to account for non-Gaussian diffusion in the tissue signal component, through a diffusion excess kurtosis parameter. Manual here.
- pgse2sphereinex.py: tool fitting a two-compartment model of intra-cellular, restricted diffusion within spherical cells, and extra-cellular hindered diffusion to Pulsed-Gradient Spin Echo (PGSE) dMRI data. Popular techniques such as VERDICT (Panagiotaki E et al, Cancer Res 2014, 74(7): 1902-1912, doi: 10.1158/0008-5472.CAN-13-2511) and IMPULSED (Jiang X et al, Magn Res Med 2016, 75(3): 1076-1085, doi: 10.1002/mrm.25684) rely on a similar diffusion model. In our tool, an option enables the selection of various, practical implementations of the intra-/extra-cellular two-pool model. We compared them systematically in our preprint Grussu F et al, medRxiv 2024: 2024.04.26.24306429, doi: 10.1101/2024.04.26.24306429 (i.e., models Diff-in, Diff-in-ex, Diff-in-exFast, Diff-in-exTD, Diff-in-exTDFast - see preprint for details). Manual here.
- pgse2cylperpinex.py: tool fitting a two-compartment model similar to the above to Pulsed-Gradient Spin Echo (PGSE) dMRI data. Here, cylinders are used in place of spheres. No gradient direction modelling is done - it is assumed that the diffusion gradients are always perfectly perpendicular to the cylinder longitudinal axis. Manual here.
- pgse2sandi.py: tool fitting the SANDI dMRI model for brain grey matter to Pulsed-Gradient Spin Echo (PGSE) dMRI data, via regularised, non-linear maximum-likelihood fitting. Details on SANDI can be found in Palombo M et al, NeuroImage 2020, 215: 116835, doi: 10.1016/j.neuroimage.2020.116835. Manual here.
- mTE2maps.py: tool fitting a mono-exponential T2star decay on multi-gradient echo (MGE) signal measurements, or a two-pool or three-pool implementation of the Susceptibility Perturbation MRI technique by Santiago I et al, Cancer Res 2019, 79(9): 2435-2444, doi: 10.1158/0008-5472.CAN-18-3682. Manual here.
- mri2micro_dictml.py: tool fitting any desired MRI signal model given examples of simulated signals and corresponding tissue parameters. These are used to learn a forward signal representation mapping tissue parameters to the MRI signal for the specific input acquisition protocol. This representation is then plugged into standard maximum-likelihood non-linear fitting. The approach was used in Grussu F et al, medRxiv 2024: 2024.04.26.24306429, doi: 10.1101/2024.04.26.24306429, where examples of signals and tissue parameters were obtained through Monte Carlo diffusion simulations. Manual here.
histotools facilitate the comparison between histological and MRI data. These are:
- getPatchMapFromQuPath.py: tool transforming a list of cell detection measurements obtained from QuPath into patch-wise 2D histological NIFTI maps. The computation of patch-wise maps from histology follows the methodology shown in Grussu F et al, Magn Res Med 2022, 88(1): 365-379, doi: 10.1002/mrm.29174. The same metrics as in that paper are computed. Manual here.
- getHistoDensity.py: tool similar to the above, but including the calculation of additional 2D patch-wise histological metrics (e.g., cell counts, etc), as detailed in the manual here.
misctools may be useful to MRI researchers in their day-to-day life. These are:
- ArtworkResample.py: a tool resizing Bitmap images to a specific width in inches and resolution in DPI. Different journals typically require paper figures with sizes/resolutions that vary from journal to journal - this tool enables quick, painless conversion and resampling for the most common file formats (e.g., PNG, TIFF, JPEG, etc). Manual here.
-
unbiasSphMeanDWI.py: a tool mitigating the noise floor bias in spherical mean (SM) diffusion-weighted signals, using the analytical expression of Pieciak T. et al, Proc ISMRM 2022, p.3900, i.e.,
$\bar{s}_{unbiased} = \bar{s} - \frac{1}{2}\frac{\sigma^2}{\bar{s}}$ . Manual here. - segnrrd2nii.py: a tool converting a NRRD segmentation to NIFTI. For example, the tool can be used to convert segments drawn in 3D Slicer and stored in NRRD format (.nrrd) into a NIFTI (.nii) label mask, given a reference NIFTI file. Manual here.