.. _supportedmodels-NEXI:
.. role:: raw-html(raw)
:format: html
NEXI
====
Neurite EXchange Imaging based on diffusion MRI (dMRI).
gpuNEXI
-------
NEXI with askAdam solver.
Usage
^^^^^
.. code-block::
obj = gpuNEXI(bval, BDELTA);
out = obj.estimate(dwi, mask, extradata, fitting);
Model parameters
^^^^^^^^^^^^^^^^
.. code-block::
% fa : Neurite volume fraction
% Da : longitudinal diffusivity of neurite [ms/us^2]
% De : diffusivity of extracellular water [ms/us^2]
% ra : exchange rate from neurite to extracellular space [1/s]
% p2 : non-linear neurite dispersion index
model_params = {'fa','Da','De','ra','p2'};
ub = [ 1, 3, 3, 1, 1];
lb = [ eps, eps, eps,1/250, eps];
startpoint = [ 0.4, 2, 1, 0.05, 0.2];
I/O overview
^^^^^^^^^^^^
``obj = gpuNEXI(bval, BDELTA);``
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| Input | Description |
+===========================+==============================================================================================================+
| bval | 1xNshell b-values vector [ms/um2] |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| BDELTA | 1xNshell diffusion time, same size as 'bval' [ms] |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
``out = obj.estimate(dwi, mask, extradata, fitting);``
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| Input | Description |
+===========================+==============================================================================================================+
| dwi | 4D dMRI data, can be either full acquisition or SMT signal [x,y,z,diffusion] |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| mask | 3D mask, [x,y,z] |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| extradata | Structure array with additional data (Optional) |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| extradata.bval | 1D b-values [1xdiffusion], same order as 'dwi' [ms/um2] (Optional, only if 'dwi' is full acquisition) |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| extradata.bvec | 2D b-vector [3xdiffusion], same order as 'dwi' (Optional, only if 'dwi' is full acquisition) |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| extradata.ldelta | 1D gradient duration [1xdiffusion], same order as 'dwi' [ms] (Optional, only if 'dwi' is full acquisition) |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| extradata.BDELTA | 1D diffusion time [1xdiffusion], same order as 'dwi' [ms] (Optional, only if 'dwi' is full acquisition) |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fitting | Structure array for model parameter estimation |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fitting.optimiser | Algorithm for parameter update, 'adam' (default) | 'sgdm' | 'rmsprop' |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fitting.isdisplay | boolean, display optimisation process in graphic plot |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fitting.convergenceValue | tolerance in loss gradient to stop the optimisation |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fitting.convergenceWindow | # of elements in which 'convergenceValue' is computed |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fitting.iteration | maximum # of optimisation iterations |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fitting.initialLearnRate | initial learn rate of Adam optimiser |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fitting.tol | tolerance in loss |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fitting.lambda | regularisation parameter(s) |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fitting.regmap | model parameter(s) in which regularisation is applied, 'fa'|'ra'|'Da'|'De' |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fitting.TVmode | Mode for total variation (TV) regularisation, '2D'|'3D' |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fitting.lossFunction | loss function, 'L1'|'L2'|'huber'|'mse' |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fitting.lmax | Maximum order of rotational invariant, 0|2, default = 0 |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fitting.isPrior | Starting point estimated based on likelihood method instead of fix/random location |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
+-------------------------------+--------------------------------------------------------------------------------------------------------------+
| Output | Description |
+===============================+==============================================================================================================+
| out | structure contains optimisation result |
+-------------------------------+--------------------------------------------------------------------------------------------------------------+
| out.final | output structure at final iteration |
+-------------------------------+--------------------------------------------------------------------------------------------------------------+
| out.final.loss | total loss = loss_fidelity + loss_reg |
+-------------------------------+--------------------------------------------------------------------------------------------------------------+
| out.final.loss_fidelity | loss of data consistency term |
+-------------------------------+--------------------------------------------------------------------------------------------------------------+
| out.final.loss_reg | loss of regularisation term |
+-------------------------------+--------------------------------------------------------------------------------------------------------------+
| out.final.(model_params{k}) | estimated model parameter(s) |
+-------------------------------+--------------------------------------------------------------------------------------------------------------+
| out.min | output structure at loss is minimum |
+-------------------------------+--------------------------------------------------------------------------------------------------------------+
See example here.
gpuNEXImcmc
-----------
NEXI with MCMC solver.
Usage
^^^^^
.. code-block::
obj = gpuNEXImcmc(bval, BDELTA);
out = obj.estimate(dwi, mask, extradata, fitting);
Model parameters
^^^^^^^^^^^^^^^^
.. code-block::
% fa : Intraneurite volume fraction
% Da : Intraneurite diffusivity (um2/ms)
% De : Extraneurite diffusivity (um2/ms)
% ra : exchange rate from intra- to extra-neurite compartment
% p2 : dispersion index (if fitting.lmax=2)
% default model parameters and estimation boundary
model_params = { 'fa'; 'Da'; 'De'; 'ra';'p2'; 'noise'};
ub = [ 1; 3; 3; 1; 1; 0.1];
lb = [ 0; 0.002; 0.001; 1/250; 0; 0.01];
step = [ 0.05; 0.15; 0.15; 0.005;0.05; 0.005];
startpoint = [ 0.2; 2; 0.5; 0.05; 0.2; 0.05];
I/O overview
^^^^^^^^^^^^
``obj = gpuNEXImcmc(bval, BDELTA);``
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| Input | Description |
+===========================+==============================================================================================================+
| bval | 1xNshell unique b-values vector [ms/um2] |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| BDELTA | 1xNshell diffusion time, same size as 'bval' [ms] |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
``out = obj.estimate(dwi, mask, extradata, fitting);``
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| Input | Description |
+===========================+==============================================================================================================+
| dwi | 4D dMRI data, can be either full acquisition or SMT signal [x,y,z,diffusion] |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| mask | 3D mask, [x,y,z] |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| extradata | Structure array with additional data (Optional) |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| extradata.bval | 1D b-values [1xdiffusion], same order as 'dwi' [ms/um2] (Optional, only if 'dwi' is full acquisition) |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| extradata.bvec | 2D b-vector [3xdiffusion], same order as 'dwi' (Optional, only if 'dwi' is full acquisition) |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| extradata.ldelta | 1D gradient duration [1xdiffusion], same order as 'dwi' [ms] (Optional, only if 'dwi' is full acquisition) |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| extradata.BDELTA | 1D diffusion time [1xdiffusion], same order as 'dwi' [ms] (Optional, only if 'dwi' is full acquisition) |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fitting | Structure array for model parameter estimation |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fitting.algorithm | MCMC algorithm, 'MH' (Metropolis-Hastings)|'GW' (Affline-invariant ensemble) |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fitting.iteration | # MCMC iterations |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fitting.repetition | # repetition of MCMC proposal |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fitting.thinning | sampling interval between iterations |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fitting.burnin | iterations to be discarded at the beginning, if >1, the exact number will be used; else iteration*burnin |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fitting.xStepSize | step size of model parameter in MCMC proposal, same size and order as 'model_params' ('MH' only) |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fitting.StepSize | step size for 'GW' in MCMC proposal ('GW' only) |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fitting.Nwalker | # random walkers ('GW' only) |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fitting.metric | cell variable, metric(s) derived from posterior distribution, 'mean'|'std'|'median'|'iqr' (can be multiple) |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fitting.start | Starting point methods, 'likelihood'|'default'|1xM parameters array |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
+-----------------------------------+--------------------------------------------------------------------------------------------------------------+
| Output | Description |
+===================================+==============================================================================================================+
| out | structure contains optimisation result |
+-----------------------------------+--------------------------------------------------------------------------------------------------------------+
| out.posterior | structure contains MCMC posterior samples |
+-----------------------------------+--------------------------------------------------------------------------------------------------------------+
| out.posterior.(model_params{k}) | Model parameter MCMC posterior samples, masked and unshaped for memory preservation |
+-----------------------------------+--------------------------------------------------------------------------------------------------------------+
| out.{metric}.(model_params{k}) | Posterior statistics chosen in fitting.metric |
+-----------------------------------+--------------------------------------------------------------------------------------------------------------+
See example here.