.. _supportedmodels-MCRMWI:
.. role::  raw-html(raw)
    :format: html

MCRMWI
======

Multi-compartment relaxometry for (diffusion informed) myelin water imaging (MCR-MWI). 

gpuMCRMWI
---------

Usage
^^^^^

.. code-block::

    obj = gpuMCRMWI(te,tr,fa,fixed_params);
    [out] = obj.estimate( data, mask, extraData, fitting);

Model parameters
^^^^^^^^^^^^^^^^

.. code-block::
    
    % S0        : T1w signal [a.u.] 
    % MWF       : myelin water fraction [0,1]
    % IWF       : intracellular volume ratio (=Vic or ICVF in DWI) [0,1]
    % R2sMW     : R2* MW [1/s]
    % R2sIW     : R2* IW [1/s] 
    % R2sEW     : R2* EW [1/s] 
    % freqMW    : frequency MW [ppm]
    % freqIW    : frequency IW [ppm]
    % dfreqBKG  : background frequency in addition to the one provided [ppm]
    % dpini     : B1 phase offset in addition to the one provided [rad]
    model_params    = { 'S0';   'MWF';  'IWF'; 'R1IEW'; 'kIEWM'; 'R2sMW';'R2sIW';'R2sEW'; 'freqMW';'freqIW';'dfreqBKG';'dpini'};
    ub              = [    2;     0.3;      1;       2;      10;     200;     50;     50;     0.25;    0.05;       0.4;   pi/2];
    lb              = [    0;       0;      0;    0.25;       0;      50;      2;      2;    -0.05;    -0.1;      -0.4;  -pi/2];
    startpoint      = [    1;     0.1;    0.8;       1;       0;     100;     15;     21;     0.04;       0;         0;      0];

I/O overview
------------

``obj = gpuMCRMWI(te,tr,fa,fixed_params);``

+---------------------------+--------------------------------------------------------------------------------------------------------------+
| Input                     | Description                                                                                                  |
+===========================+==============================================================================================================+
| te                        | 1xNte echo time [s]                                                                                          |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| tr                        | repetition time [s]                                                                                          |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fa                        | 1xNfa flip angle vector [degree]                                                                             |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fixed_params              | parameters to be fixed (Optional)                                                                            |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fixed_params.x_i          | isotropic susceptibility of myelin [ppm], default = 0.1                                                      |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fixed_params.x_a          | anisotropic susceptibility of myelin [ppm], default = 0.1                                                    |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fixed_params.E            | exchange induced frequency shift [ppm], default = 0.02                                                       |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fixed_params.rho_mw       | myelin water proton ratio, default = 0.4186                                                                  |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fixed_params.B0           | main magnetic field strength [T], default = 3                                                                |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fixed_params.B0_dir       | main magnetic field direction, [x,y,z], default = [0;0;1]                                                    |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| fixed_params.t1_mw        | myelin (water) T1 [s], default = 234e-3                                                                      |
+---------------------------+--------------------------------------------------------------------------------------------------------------+

``[out] = obj.estimate( data, mask, extraData, fitting);``

+---------------------------+--------------------------------------------------------------------------------------------------------------+
| Input                     | Description                                                                                                  |
+===========================+==============================================================================================================+
| data                      | 5D MRI data, [x,y,z,t,fa]                                                                                    |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| mask                      | 3D mask, [x,y,z]                                                                                             |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| extraData                 | Structure array with additional data                                                                         |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| extraData.b1              | 3D B1+ map [ratio], [x,y,z]                                                                                  |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| extraData.freqBKG         | 3D/4D initial estimation of total field [Hz] (highly recommended), [x,y,z,fa]                                |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| extraData.pini            | 3D initial estimation of B1 offset [rad]  (highly recommended), [x,y,z]                                      |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| extraData.ff              | 3D/4D fibre fraction map, [x,y,z,Nfibre] (for DIMWI only)                                                    |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| extraData.theta           | 3D/4D angle between B0 and fibre orientation, [x,y,z,Nfibre] (for DIMWI only)                                |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| extraData.fo              | 4D/5D fibre orientation vector map, [x,y,z,Nfibre,3] (for DIMWI only)                                        |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| extraData.IWF             | 3D volume fraction Intracellular/(Intracellular+extracellular), [x,y,z] (for DIMWI only)                     |
+---------------------------+--------------------------------------------------------------------------------------------------------------+
| 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,                                                       |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting.TVmode            | Mode for total variation (TV) regularisation, '2D' | '3D'                                                    |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting.lossFunction      | loss function, 'L1' | 'L2' | 'huber' | 'mse'                                                                 |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting.isWeighted        | is cost weighted, true|false, default = true                                                                 |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting.weightMethod      | Weighting method, '1stecho' (default) | 'norm'                                                               |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting.weightPower       | power order of the weight, default = 2                                                                       |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting.isFitExchange     | exchange is a free parameter, default = true                                                                 |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting.isEPG             | use EPG-X signal instead of BM analytical solution for exchange, default = true                              |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting.DIMWI             | Structure variable for DIMWI options                                                                         |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting.DIMWI.isFitIWF    | 'IWF' is a free parameter, default = true                                                                    |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting.DIMWI.isFitFreqMW | Myelin water frequency is a free parameter, default = true                                                   |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting.DIMWI.isFitFreqIW | Intracellular water frequency is a free parameter, default = true                                            |
+---------------------------+--------------------------------------------------------------------------------------------------------------+ 
| fitting.DIMWI.isFitR2sEW  | Extracellular water R2* is a free parameter, default = true                                                  |
+---------------------------+--------------------------------------------------------------------------------------------------------------+