README.md

qMRINet user guide

This page contains useful information on qMRINet.

qMRINet classes

qMRINet is based on 3 different python classes: qmrisig, qmripar and qmriinterp, which are defined in the deepqmri.py file.

• qmrisig allows you to train a qMRINet to fit a signal model by minimising a loss function measuring the mean squared error (MSE, or L2 error norm) between measured MRI signals and qMRINet signal predictions. Methods in qmrisig objects are:
  • __init__(): the constructor, to define the hidden layers and tissue parameter ranges;
  • getparams(): to map input qMRI measurements to tissue parameters. It relies on two additional methods that implement intermediate normalisation steps:
    • getneurons(): to calculate output neuron activations;
    • getnorm(): to normalise output neuron activations so that they can be mapped to tissue parameters;
  • getsignals(): to predict qMRI signals from tissue parameters;
  • changelim(): to change the range of tissue parameters from the default settings;
  • forward(): to pass data through the entire qmrisig network, essentially implementing forward(s) = getsignals( getparams (s) ), where s are input qMRI measurements. The network is trained by minimising the loss function L = | s - forward(s) |², as shown in the figure above.

• qmripar allows you to train a qMRINet to fit a signal model by minimising a loss function measuring the MSE between ground truth tissue parameters and qMRINet tissue parameter predictions. Methods in qmripar objects are:
  • __init__(): the constructor, to define the hidden layers and tissue parameter ranges;
  • getparams(): to map input qMRI measurements to tissue parameters;
  • getsignals(): to predict qMRI signals from tissue parameters;
  • changelim(): to change the range of tissue parameters from the default settings;
  • forward(): to pass data through the entire qmripar network, essentially implementing forward(s) = getparams(s), where s are input qMRI measurements. The network is trained by minimising the loss function L = | p - forward(s) |², where p are ground truth tissue parameters, as illustrated in the figure above.

• qmriinterp allows you to train a qMRINet to learn a resampling between two different qMRI protocols. A qmriinterp network is essentially equivalent to the predictor sub-network of a SARDU-Net. Methods in qmriinterp objects are:
  • __init__(): the constructor, to define the hidden layers;
  • resample(): to map an input qMRI protocol to an output qMRI protocol;
  • forward(): to pass data through the entire qmriinterp network, essentially implementing forward(sA) = resample(sA), where sA are qMRI measurements obtained from protocol A. The network is trained by minimising the loss function L = | sB - forward(sA) |², where sB are qMRI measurements from the same voxels but performed with protocol B. Essentially, the trained qmriinterp network will learn to map measurements from protocol A to measurements from protocol B, as illustrated in the figure above.

Each class has a detailed help manual. From a Jupyter notebook or in your python interpreter prompt, you can check the manual by typing something like:

>>> import deepqmri
>>> help(deepqmri.qmrisig)

to print the manual (in this example of the qmrisig class).

qMRINet command-line tools

qMRINet includes a number of command-line tools that provide handy interfaces to train and deploy objects from the 3 qmrisig, qmripar and qmriinterp classes.

• syndata_deepqmri.py enables synthesis of qMRI measurements from uniformly distributed tissue parameters, which could be useful for training and testing qmrisig, qmripar and qmriinterp networks;
• par2sig_deepqmri.py enables synthesis of qMRI measurements from pre-computed tisssue parameters;
• extractvoxels_deepqmri.py enables extraction of voxel measurements from qMRI scans in NIFTI1 format, which could be used to train a qmrinetsig network;
• sigsubset_deepqmri.py enables extraction of subsets of qMRI measurements, which could be used to train a qmriinterp network;
• seqsubset_deepqmri.py enables extraction of subsets of qMRI sequence parmeters from text files;
• trainsig_deepqmri.py enables training of a qmrinetsig network (at present only on CPU);
• trainpar_deepqmri.py enables training of a qmripar network (at present only on CPU);
• traininterp_deepqmri.py enables training of a qmriinterp network (at present only on CPU);
• sig2par_qmrisig_deepqmri.py enables the use of a trained qmrisig network to estimate tissue parameters;
• sig2par_qmripar_deepqmri.py enables the use of a trained qmripar network to estimate tissue parameters;
• sig2sig_qmriinterp_deepqmri.py enables the use of a trained qmriinterp network to resample qMRI protocols.

All tools listed above also have a detailed help manual, which you can print by simply typing in your terminal python </PATH/TO/TOOL> --help (e.g. python trainsig_deepqmri.py --help to read the manual of trainsig_deepqmri.py).

qMRINet signal models

A signal model is identified by a unique string. At present, the following signal models are available:

- Hybrid multi-dimensional MRI

Hybrid multi-dimensional MRI for prostate diffusion-T2 relaxation imaging.

• It is identified by string 'pr_hybriddwi' and can be used to model prostate qMRI data acquired with multi echo time diffusion-weighted sequences.
• Sequence parameters are specified using text files containing a matrix where the 1st row stores b-values in s/mm², while 2nd row echo times in ms (use spaces to separate different entries). Below you find the signal model, sequence parameters and tissue parameters in the same order as outputted by fitting routines.

- T1-weighted spherical mean diffusion tensor

T1-weighted diffusion tensor modelling of directionally-averaged signals for brain diffusion-T1 relaxation imaging.

• It is identified by string 'br_sirsmdt' and can be used to model brain qMRI data acquired with diffusion-weighted inversion recovery or diffusion-weighted saturation inversion recovery sequences.
• Sequence parameters are specified using text files containing a matrix where the 1st row stores preparation times (saturation-inversion delay) in ms, the 2nd row inversion times (inversion-excitation delay) in ms, the 3rd row b-values in s/mm². For a pure inversion recovery (i.e. no saturation pulse), use a very large number for the saturation-inversion delay (at least 5 times the maximum expected T1); use spaces to separate different entries. Below you find the signal model, sequence parameters and tissue parameters in the same order as outputted by fitting routines.

- Generic two-pool diffusion-T2 relaxation

Two-compartment diffusion-relaxation for a generic two-pool diffusion-T2 relaxation imaging model without anisotropy, with optional intra-compartmental non-zero diffusion kurtosis excess in one of the two compartments.

• It is identified by string 'twocompdwite' and can be used to model prostate qMRI data acquired with multi echo time diffusion-weighted sequences.
• Sequence parameters are specified using text files containing a matrix where the 1st row stores b-values in s/mm², while 2nd row echo times in ms (use spaces to separate different entries). Below you find the signal model, sequence parameters and tissue parameters in the same order as outputted by fitting routines.