deepmriprep: A Python repository from Medical Machine Learning Lab - University of Münster - Medical Machine Learning Lab

deepmriprep runs all preprocessing steps needed for Voxel-based Morphometry (VBM) of T1w MR images:

brain extraction (via deepbet)
affine registration (via torchreg)
tissue segmentation
nonlinear registration
smoothing

Using neural networks, it only takes ~10 seconds on a GPU (~100 seconds without a GPU) per image 🔥

Additionally, deepmriprep can also run atlas registration needed for Region-based Morphometry (RBM).

Installation 🛠️

For GPU-acceleration (NVIDIA needed), PyTorch should be installed first via the proper install command 🔥

deepmriprep can be easily installed via

pip install deepmriprep

The deepmriprep-gui can look grainy in conda environments. To fix that run

conda install -c conda-forge tk=*=xft_*

Usage 💡

After installation, there are three ways to use deepmriprep

deepmriprep-gui runs the Graphical User Interface (GUI)

deepmriprep-cli runs the Command Line Interface (CLI)

deepmriprep-cli -bids path/to/bids

Run deepmriprep directly in Python

from deepmriprep import run_preprocess

# Apply to BIDS dir. (saves to 'path/to/bids/derivatives')
run_preprocess(bids_dir='path/to/bids')
# Apply to list of files and save to output directory
input_paths = ['path/to/input/sub-1_t1w.nii.gz', 'path/to/input/sub-2_t1w.nii.gz']
run_preprocess(input_paths, output_dir='path/to/output')
# Apply to list of files and save to custom output filepaths
output_paths = [{'tiv': 'outpath1/tivsub-1_t1w.csv', 'p0': 'outpath2/p0sub-1_t1w.nii'},
                {'tiv': 'outpath3/tivsub-2_t1w.csv', 'p0': 'outpath4/p0sub-2_t1w.nii'}]
run_preprocess(input_paths, output_paths=output_paths)

Besides the three shown options to specify input and output paths, run_preprocess has the arguments

outputs: Output modalities which can be either 'all', 'vbm', 'rbm' or a custom list of output strings
dir_format: Output directory structure which can be either 'sub', 'mod', 'cat' or 'flat'
no_gpu: Avoids GPU utilization if set to True (set to False per default for GPU-acceleration 🔥)

outputs set to

'all' all output modalities are saved
'vbm' the outputs tiv, mwp1, mwp2, s6mwp1 and s6mwp2 are saved
'rbm' results in all available atlases (including regions tissue volumes) are saved

If output_dir is set, dir_format set to

'sub' results in e.g. 'outpath/sub-1/tivsub-1.csv' and 'outpath/sub-1/p0sub-1.nii.gz'
'mod' results in e.g. 'outpath/tiv/tivsub-1.csv' and 'outpath/p0/p0sub-1.nii.gz'
'cat' results in e.g. 'outpath/sub-1/label/tivsub-1.csv' and 'outpath/sub-1/mri/p0sub-1.nii.gz'
'flat' results in e.g. 'outpath/tivsub-1.csv' and 'outpath/p0sub_1.nii.gz'

Tutorial 🧑‍🏫

In short, deepmriprep (consisting of only ~500 lines of code) internally calls the .run method of the Preprocess class, which sequentially calls the methods .run_bet to .run_atlas_register (see deepmriprep/preprocess.py).

A more detailed Tutorial-Notebook will soon be published on Google Colab!

Citation ©️

If you use deepmriprep in your research, please cite:

@inproceedings{deepmriprep,
Author = {Lukas Fisch, Nils R. Winter, Janik Goltermann, Carlotta Barkhau, Daniel Emden, Jan Ernsting, Maximilian Konowski, Ramona Leenings, Tiana Borgers, Kira Flinkenflügel, Dominik Grotegerd, Anna Kraus, Elisabeth J. Leehr, Susanne Meinert, Frederike Stein, Lea Teutenberg, Florian Thomas-Odenthal, Paula Usemann, Marco Hermesdorf, Hamidreza Jamalabadi, Andreas Jansen, Igor Nenadic, Benjamin Straube, Tilo Kircher, Klaus Berger, Benjamin Risse, Udo Dannlowski, Tim Hahn},
Title = {deepmriprep: Voxel-based Morphometry (VBM) Preprocessing via Deep Neural Networks},
Year = {2024},
eprint = {arXiv:2408.10656}
}

Outputs 📋

When "Output Modalities" is set to "custom" in the deepmriprep-gui, all output strings are shown:

Most output strings follow the CAT12 naming convention of output files.

Here are descriptions for all output strings:

Input

't1': T1-weighted MR image

Brain Extraction

'mask': Brain mask
'brain': 't1' after brain mask is applied
'tiv_bet': Total intracranial volume in cm³ based on brain extraction

Affine Registration

'affine': Affine matrix moving 'brain' into template space (compatible with F.affine_grid)
'translate', 'rotation', 'zoom', 'shear': Tranformation parameters the affine is composed of
'mask_large': Affine applied to 'mask' with 0.5mm resolution
'brain_large': Affine applied to 'brain' with 0.5mm resolution

Tissue Segmentation

'p0_large': Tissue segmentation map of 'brain_large'
'p0': Tissue segmentation map in 't1' image space (moved 'p0_large')

Tissue Probabilities

'nogm': Small area around the brain stem that is masked in subsequent GM output
'gmv': Gray matter (GM) volume in cm³
'wmv': White matter (WM) ""
'csfv': Cerebrospinal fluid (CSF) ""
'tiv': Total intracranial volume in cm³ based on tissue segmentation (gmv + wmv + csfv)
'rel_gmv': Proportion of GM volume relative to the total intracranial volume
'rel_wmv': Proportion of WM ""
'rel_csfv': Proportion of CSF ""
'p1': GM tissue probability in 't1' image space
'p2': WM ""
'p3': CSF ""
'p1_large': GM tissue probability based on 'p0_large'
'p2_large': WM ""
'p3_large': CSF ""
'p1_affine': GM tissue probability based on 'p0_large' in template resolution
'p2_affine': WM ""
'p3_affine': CSF ""

Nonlinear Registration

'wj_affine': Jacobian determinant of the affine matrix
'warp_xy': Forward warping field (compatible with F.grid_sample)
'warp_yx': Backward warping field (compatible with F.grid_sample)
'wj_': Jacobian determinant of forward warping field
'v_xy': Forward velocity field (compatible with F.grid_sample)
'v_yx': Backward velocity field (compatible with F.grid_sample)
'wp1': Forward warped 'p1'
'mwp1': Modulated (multiplied with 'wj_'), forward warped 'p1'
's6mwp1': Smoothed with 6mm kernel, modulated (multiplied with 'wj_'), forward warped 'p1'
...analogous for 'wp2', 'mwp2', 's6mwp2', 's8mwp1', ...

Atlases

'aal3': Registered AAL3 atlas in 't1' image space
'anatomy3': Registered Anatomy3 ""
'cobra': Registered Cobra atlas ""
'hammers': Registered Hammers atlas ""
'ibsr': Registered IBSR atlas ""
'julichbrain': Registered Julichbrain atlas ""
'lpba40': Registered LPBA40 atlas ""
'mori': Registered Mori atlas ""
'neuromorphometrics': Registered Neuromorphometrics ""
'suit': Registered SUIT ""
'thalamic_nuclei': Registered Thalamic Nuclei ""
'thalamus': Registered Thalamus ""
'Schaefer2018_100Parcels_17Networks_order': Registered Schaefer 100 ""
'Schaefer2018_200Parcels_17Networks_order': Registered Schaefer 200 ""
'Schaefer2018_400Parcels_17Networks_order': Registered Schaefer 400 ""
'Schaefer2018_600Parcels_17Networks_order': Registered Schaefer 600 ""

For each atlas, there also can be outputted two more modalities:

'aal3_affine': Registered AAL3 atlas in template space
'aal3_volumes': GM, WM and CSF volume in mm³ per region of the AAL3 atlas
...analogous 'anatomy3_affine', 'anatomy3_volumes', 'cobra_affine', 'cobra_volumes' ...

wwu-mmll/deepmriprep

Installation 🛠️

Usage 💡

Tutorial 🧑‍🏫

Citation ©️

Outputs 📋