qsm_sb: Fast quantitative susceptibility mappingΒΆ

https://mybinder.org/badge_logo.svg

Contents

% This m-file has been automatically generated using qMRgenBatch(qsm_sb)
% Command Line Interface (CLI) is well-suited for automatization
% purposes and Octave.
%
% Please execute this m-file section by section to get familiar with batch
% processing for qsm_sb on CLI.
%
% Demo files are downloaded into qsm_sb_data folder.
%
% Written by: Agah Karakuzu, 2017
% =========================================================================

I- DESCRIPTION

qMRinfo('qsm_sb'); % Describe the model
  qsm_sb: Compute a T1 map using Variable Flip Angle

Assumptions:
Type/number of outputs will depend on the selected options.
(1) Case - Split-Bregman:
i)  W/ magnitude weighting:  chiSBM, chiL2M, chiL2, unwrappedPhase, maskOut
ii) W/O magnitude weighting: chiSM, chiL2, unwrappedPhase, maskOut
(2) Case - L2 Regularization:
i)  W/ magnitude weighting:  chiL2M, chiL2, unwrappedPhase, maskOut
ii) W/O magnitude weighting: chiL2, unwrappedPhase, maskOut
(3) Case - No Regularization:
i) Magnitude weighting is not enabled: nfm, unwrappedPhase, maskOut
Inputs:
PhaseGRE      3D GRE acquisition. Wrapped phase image
(MagnGRE)     3D GRE acquisition. Magnitude part of the image
Mask          Brain extraction mask.

Outputs:
chiSBM          Susceptibility map created using Split-Bregman method with magnitude weighting
chiSB           Susceptibility map created using Split-Bregman method without magnitude weighting.
chiL2M          Susceptibility map created using L2 regularization with magnitude weighting
chiL2           Susceptibility map created using L2 regularization without magnitude weighting
nfm             Susceptibility map created without regularization
unwrappedPhase  Unwrapped phase image using Laplacian-based method
maskOut         Binary mask (maskSharp, gradientMask or same as the input)

Options:
Derivative direction               Direction of the derivation
- forward
- backward
SHARP Filtering                    Sophisticated harmonic artifact reduction for phase data
- State: true/false
- Mode: once/iterative
- Padding Size: [1X3 array]
- Magnitude Weighting: on/off
L1-Regularization                  Apply L1-regularization
- State: true/false
- Reoptimize parameters:
true/false
- Lambda-L1: [double]
- L1-Range:  [1X2 array]
L2-Regularization                  Apply L2-regularization
- State: true/false
- Reoptimize parameters:
true/false
- Lambda-L2: [double]
- L2-Range:  [1X2 array]
Split-Bregman                       Apply Split-Bregman method
- State: true/false
- Reoptimize parameters:

Authors: Agah Karakuzu, 2018

References:
Please cite the following if you use this module:
Bilgic et al. (2014), Fast quantitative susceptibility mapping with
L1-regularization and automatic parameter selection. Magn. Reson. Med.,
72: 1444-1459. doi:10.1002/mrm.25029
In addition to citing the package:
Cabana J-F, Gu Y, Boudreau M, Levesque IR, Atchia Y, Sled JG, Narayanan S, Arnold DL, Pike GB,
Cohen-Adad J, Duval T, Vuong M-T and Stikov N. (2016), Quantitative magnetization transfer imaging
made easy with qMTLab: Software for data simulation, analysis, and visualization. Concepts Magn.
Reson.. doi: 10.1002/cmr.a.21357

Reference page in Doc Center
doc qsm_sb


II- MODEL PARAMETERS

a- create object

Model = qsm_sb;

b- modify options

         |- This section will pop-up the options GUI. Close window to continue.
|- Octave is not GUI compatible. Modify Model.options directly.
Model = Custom_OptionsGUI(Model); % You need to close GUI to move on.

III- FIT EXPERIMENTAL DATASET

a- load experimental data

         |- qsm_sb object needs 3 data input(s) to be assigned:
|-   PhaseGRE
|-   MagnGRE
|-   Mask
data = struct();

% PhaseGRE.mat contains [40  40  40] data.
load('qsm_sb_data/PhaseGRE.mat');
% MagnGRE.mat contains [40  40  40] data.
load('qsm_sb_data/MagnGRE.mat');
% Mask.mat contains [40  40  40] data.
load('qsm_sb_data/Mask.mat');
data.PhaseGRE= double(PhaseGRE);
data.MagnGRE= double(MagnGRE);
data.Mask= double(Mask);

b- fit dataset

           |- This section will fit data.
FitResults = FitData(data,Model,0);
Started   : Laplacian phase unwrapping ...
Completed : Laplacian phase unwrapping
-----------------------------------------------
Started   : SHARP background removal ...
Completed : SHARP background removal
-----------------------------------------------
Skipping reoptimization of Lambda L2.
Started   : Calculation of chi_L2 map without magnitude weighting...
Elapsed time is 0.019377 seconds.
Completed  : Calculation of chi_L2 map without magnitude weighting.
-----------------------------------------------
Started   : Calculation of chi_SB map without magnitude weighting.. ...
Iteration  1  -  Change in Chi: 100 %
Iteration  2  -  Change in Chi: 28.2724 %
Iteration  3  -  Change in Chi: 14.6621 %
Iteration  4  -  Change in Chi: 10.3776 %
Iteration  5  -  Change in Chi: 6.7868 %
Iteration  6  -  Change in Chi: 4.9906 %
Iteration  7  -  Change in Chi: 3.7381 %
Iteration  8  -  Change in Chi: 2.8073 %
Iteration  9  -  Change in Chi: 2.3136 %
Iteration  10  -  Change in Chi: 1.9299 %
Iteration  11  -  Change in Chi: 1.6742 %
Iteration  12  -  Change in Chi: 1.4638 %
Iteration  13  -  Change in Chi: 1.2977 %
Iteration  14  -  Change in Chi: 1.1512 %
Iteration  15  -  Change in Chi: 1.0556 %
Iteration  16  -  Change in Chi: 0.96335 %
Elapsed time is 1.106340 seconds.
Elapsed time is 1.116514 seconds.
Completed   : Calculation of chi_SB map without magnitude weighting.
-----------------------------------------------
Loading outputs to the GUI may take some time after fit has been completed.
...done

c- show fitting results

         |- Output map will be displayed.
|- If available, a graph will be displayed to show fitting in a voxel.
|- To make documentation generation and our CI tests faster for this model,
we used a subportion of the data (40X40X40) in our testing environment.
|- Therefore, this example will use FitResults that comes with OSF data for display purposes.
|- Users will get the whole dataset (384X336X224) and the script that uses it for demo
via qMRgenBatch(qsm_sb) command.
FitResults_old = load('FitResults/FitResults.mat');
qMRshowOutput(FitResults_old,data,Model);

d- Save results

         |-  qMR maps are saved in NIFTI and in a structure FitResults.mat
that can be loaded in qMRLab graphical user interface
|-  Model object stores all the options and protocol.
It can be easily shared with collaborators to fit their
own data or can be used for simulation.
FitResultsSave_nii(FitResults);
Model.saveObj('qsm_sb_Demo.qmrlab.mat');
Warning: Directory already exists.

V- SIMULATIONS

   |- This section can be executed to run simulations for qsm_sb.

a- Single Voxel Curve

         |- Simulates Single Voxel curves:
(1) use equation to generate synthetic MRI data
(2) add rician noise
(3) fit and plot curve
% Not available for the current model.

b- Sensitivity Analysis

         |-    Simulates sensitivity to fitted parameters:
(1) vary fitting parameters from lower (lb) to upper (ub) bound.
(2) run Sim_Single_Voxel_Curve Nofruns times
(3) Compute mean and std across runs
% Not available for the current model.