integration of Baudrexel's imperfect spoiling correction, SDAM B1mapping, and visual quality tool

EPG_for_hmri_tbx/Unit_Test_Protocol.m

@@ -0,0 +1,8 @@
+global_hrmi_def
+hmri_def.MPMacq_set.name = 'Unit_Test_Protocol';
+hmri_def.MPMacq_set.tag  = 'Unit_Test_Protocol';
+hmri_def.MPMacq_set.val  = [25  25   6  21];
+hmri_def.imperfectSpoilCorr.Unit_Test_Protocol.tag = 'Unit_Test_Protocol';
+hmri_def.imperfectSpoilCorr.Unit_Test_Protocol.P2_a = [41.5044     -56.2888      28.6704];
+hmri_def.imperfectSpoilCorr.Unit_Test_Protocol.P2_b = [-0.0972      0.0973      0.9649];
+hmri_def.imperfectSpoilCorr.Unit_Test_Protocol.enabled = hmri_def.imperfectSpoilCorr.enabled;

config/hmri_b1_standard_defaults.m

@@ -47,6 +47,12 @@
 hmri_def.b1map.i3D_AFI.b1acq.TR2TR1ratio = 5;
 hmri_def.b1map.i3D_AFI.b1acq.alphanom = 60;
 
+% 'SDAM'
+hmri_def.b1map.SDAM.b1type = 'SDAM'; 
+hmri_def.b1map.SDAM.b1avail = true;
+hmri_def.b1map.SDAM.procreq = true;
+hmri_def.b1map.SDAM.b1acq.alphanom = 60;
+
 % 'pre_processed_B1'
 hmri_def.b1map.pre_processed_B1.b1type = 'pre_processed_B1'; 
 hmri_def.b1map.pre_processed_B1.b1avail   = true;
@@ -100,4 +106,4 @@
 hmri_def.b1map.rf_map.b1avail   = true; 
 hmri_def.b1map.rf_map.procreq = true; 
 
-end
+end

config/hmri_defaults.m

@@ -59,7 +59,7 @@
 % text. The following settings are recommended. No modification currently
 % foreseen as useful...
 hmri_def.json = struct('extended',false,'separate',true,'anonym','none',...
-    'overwrite',true, 'indent','\t'); 
+    'overwrite',true, 'indent','\t');
 % recommended TPM for segmentation and spatial processing. The hMRI toolbox
 % provides a series of tissue probability maps. These TPMs could be
 % replaced by other TPMs, to better match the population studied. 
@@ -280,116 +280,50 @@
 hmri_def.MPMacq.fa_pdw = 6;    % [deg]
 hmri_def.MPMacq.tag    = 'v2k';
 
-% IMPREFECT RF SPOILING CORRECTION PARAMETERS 
-% (Preibisch and Deichmann, MRM 61:125-135 (2009))
-% No run-time calculation of the correction parametes is currently
-% performed in the toolbox. They've been calculated and stored here for a
-% series of standard protocols, and are selected at run-time according to
-% effective TR and FA values (more precisely: [TR_pdw TR_t1w fa_pdw
-% fa_t1w]). If the used TR and FA values don't match any of the predefined
-% types, no correction is applied. Additional protocol types and correction
-% factors can be computed off-line (see more details below) and added to
-% the local defaults file to apply proper RF correction.
-% ADVANCED USER ONLY.
-
-% A) Defining the MPMacq parameters distinguishing the different protocols
-%--------------------------------------------------------------------------
-% Using the following parameter order: [TR_pdw TR_t1w fa_pdw fa_t1w]
-% NOTE: all tags MUST 
-% - start with a letter, and 
-% - include only letters, numbers or underscore, i.e. NO space.
-% as these names are used to define a structure fieldname with the protocol 
-% parameters.
-%
-% 1) classic FIL protocol (Weiskopf et al., Neuroimage 2011):
-% PD-weighted: TR=23.7ms; a=6deg; T1-weighted: TR=18.7ms; a=20deg
-hmri_def.MPMacq_set.names{1} = 'Classic FIL protocol';
-hmri_def.MPMacq_set.tags{1}  = 'ClassicFIL';
-hmri_def.MPMacq_set.vals{1}  = [23.7 18.7 6 20];
-% 2) new FIL/Helms protocol
-% PD-weighted: TR=24.5ms; a=5deg; T1-weighted: TR=24.5ms; a=29deg
-hmri_def.MPMacq_set.names{2} = 'New FIL/Helms protocol';
-hmri_def.MPMacq_set.tags{2}  = 'NewFILHelms';
-hmri_def.MPMacq_set.vals{2}  = [24.5 24.5 5 29];
-% 3) Siemens product sequence protocol used in Lausanne (G Krueger)
-% PD-weighted: TR=24ms; a=6deg; T1-weighted: TR=19ms; a=20deg
-hmri_def.MPMacq_set.names{3} = 'Siemens product Lausanne (GK) protocol';
-hmri_def.MPMacq_set.tags{3}  = 'SiemPrLausGK';
-hmri_def.MPMacq_set.vals{3}  = [24.0 19.0 6 20];
-% 4) High-res (0.8mm) FIL protocol:
-% PD-weighted: TR=23.7ms; a=6deg; T1-weighted: TR=23.7ms; a=28deg
-hmri_def.MPMacq_set.names{4} = 'High-res FIL protocol';
-hmri_def.MPMacq_set.tags{4}  = 'HResFIL';
-hmri_def.MPMacq_set.vals{4}  = [23.7 23.7 6 28];
-% 5)NEW  High-res (0.8mm) FIL protocol:
-% PD-weighted: TR=25.25ms; a=5deg; T1-weighted: TR=TR=25.25ms; a=29deg
-hmri_def.MPMacq_set.names{5} = 'New High-res FIL protocol';
-hmri_def.MPMacq_set.tags{5}  = 'NHResFIL';
-hmri_def.MPMacq_set.vals{5}  = [25.25 25.25 5 29];
-% 6)NEW  1mm protocol - seq version v2k:
-% PD-weighted: TR=24.5ms; a=6deg; T1-weighted: TR=24.5ms; a=21deg
-hmri_def.MPMacq_set.names{6} = 'v2k protocol';
-hmri_def.MPMacq_set.tags{6}  = 'v2k';
-hmri_def.MPMacq_set.vals{6}  = [24.5 24.5 6 21];
-% 7) 800um protocol - seq version v3* released used by MEG group:
-% TR = 25ms for all volumes; flipAngles = [6, 21 deg] for PDw and T1w
-% Correction parameters below were determined via Bloch-Torrey 
-% simulations but end result agrees well with EPG-derived correction 
-% for this RF spoiling increment of 137 degrees.
-% See: Callaghan et al. ISMRM, 2015, #1694
-hmri_def.MPMacq_set.names{7} = 'v3star protocol';
-hmri_def.MPMacq_set.tags{7}  = 'v3star';
-hmri_def.MPMacq_set.vals{7}  = [25 25 6 21];
-
-% B) Defining the imperfect spoiling correction parameters for the
-% different protocols 
-%--------------------------------------------------------------------------
-% Antoine Lutti 15/01/09
-% The following correction parameters are based on 
-% [Preibisch and Deichmann, Magn Reson Med 61:125-135 (2009)]. The values
-% for P2_a and P2_b below were obtained using the code supplied by R.
-% Deichmann with the experimental parameters used for the standard MPM
-% protocol and assuming T2 = 64 ms at 3T.
-
-% Given the possible confusion and resulting mistake (imperfect spoiling
-% correction applied to the wrong sequence), when TR and FA values match
-% one of the listed cases below, the option is disabled by default. 
+% IMPREFECT RF SPOILING CORRECTION 
+% The RF- and gradient-spoiled gradient echo sequences used to acquire the
+% multiparametric mapping (MPM) data apply RF and gradient spoiling to
+% destroy unwanted transverse magnetisation. Imperfect spoiling can leave
+% residual bias in the apparent R1 map if no further correction is applied
+% [Preibisch and Deichmann, MRM 61:125-135, 2009]. 
+% Correction coefficients are sequence-specific and can be determined by 
+% simulation [Preibisch and Deichmann 2009] to account for deviation from 
+% the Ernst equation.
+% Since no run-time calculation of the correction parametes is currently
+% performed in the toolbox, they've been calculated and stored for a
+% series of standard protocols in a separate folder:
+%   config/local/ISC_parameters
+% Additional protocol types and correction factors can be computed on-line
+% (see more details below) and added to the local defaults file to apply 
+% proper RF correction, respectively.
+% For the most standard MPM protocols using customised FLASH sequences on Siemens
+% scanners, the above mentioned files folder contains files with spoiling correction coefficients 
+% The correction values P2_a and P2_b were obtained using the code supplied by R. Deichmann with the experimental 
+% parameters used for the standard MPM protocol and assuming T2 = 64 ms at 3T.
 % When enabling the imperfect spoiling correction, make sure the
-% coefficients retrieved in the list below are definitely calculated for
+% coefficients used by choosing the appropriate file are definitely calculated for
 % the protocol used!
+% WARNING: although the TR and FA values are key parameters in simulating the 
+% imperfect spoiling, correction coefficients cannot be chosen based on TR 
+% and FA only. Amplitude and duration of gradient spoilers, phase increment 
+% for RF spoiling and diffusion effects must be taken into account.
+% Therefore, two different sequences using identical TR anf FA are unlikely to
+% use identical correction coefficients.
+% Instead, the coefficients can be calculated seperately for other protocols
+% by the additional hMRI module 'Imperfect Spoiling Calc.' that efficiently
+% calculates the protocol-specific correction parameters required to account for
+% imperfect spoiling. The produced output file can then be set in the local
+% defaults file to be incorporated in the processing.
+% If not all acquisition parameters are known and vendor sequences at 3 T MRI are
+% used, an alternative correction according to Baudrexel et al., 79:3082–3092, 
+% 2018 can be applied by specifying the RF spoiling phase increment, which
+% differs per vendor. Please consult the paper for assumptions and full set
+% of correction parameters.
+% By default the spoiling correction is disabled. For enabling please set
+% up the method of choice in the local defaults file.
+% ADVANCED USER ONLY.
 hmri_def.imperfectSpoilCorr.enabled = false;
 
-% 1) classic FIL protocol (Weiskopf et al., Neuroimage 2011):
-hmri_def.imperfectSpoilCorr.ClassicFIL.tag = 'Classic FIL protocol';
-hmri_def.imperfectSpoilCorr.ClassicFIL.P2_a = [78.9228195006542,-101.113338489192,47.8783287525126];
-hmri_def.imperfectSpoilCorr.ClassicFIL.P2_b = [-0.147476233142129,0.126487385091045,0.956824374979504];
-% 2) new FIL/Helms protocol
-hmri_def.imperfectSpoilCorr.NewFILHelms.tag = 'New FIL/Helms protocol';
-hmri_def.imperfectSpoilCorr.NewFILHelms.P2_a = [93.455034845930480,-120.5752858196904,55.911077913369060];
-hmri_def.imperfectSpoilCorr.NewFILHelms.P2_b = [-0.167301931434861,0.113507432776106,0.961765216743606];
-% 3) Siemens product sequence protocol used in Lausanne (G Krueger)
-hmri_def.imperfectSpoilCorr.SiemPrLausGK.tag = 'Siemens product Lausanne (GK) protocol';
-hmri_def.imperfectSpoilCorr.SiemPrLausGK.P2_a = [67.023102027100880,-86.834117103841540,43.815818592349870];
-hmri_def.imperfectSpoilCorr.SiemPrLausGK.P2_b = [-0.130876849571103,0.117721807209409,0.959180058389875];
-% 4) High-res (0.8mm) FIL protocol:
-hmri_def.imperfectSpoilCorr.HResFIL.tag = 'High-res FIL protocol';
-hmri_def.imperfectSpoilCorr.HResFIL.P2_a = [1.317257319014170e+02,-1.699833074433892e+02,73.372595677371650];
-hmri_def.imperfectSpoilCorr.HResFIL.P2_b = [-0.218804328507184,0.178745853134922,0.939514554747592];
-% 5)NEW  High-res (0.8mm) FIL protocol:
-hmri_def.imperfectSpoilCorr.NHResFIL.tag = 'New High-res FIL protocol';
-hmri_def.imperfectSpoilCorr.NHResFIL.P2_a = [88.8623036106612,-114.526218941363,53.8168602253166];
-hmri_def.imperfectSpoilCorr.NHResFIL.P2_b = [-0.132904017579521,0.113959390779008,0.960799295622202];
-% 6)NEW  1mm protocol - seq version v2k:
-hmri_def.imperfectSpoilCorr.v2k.tag = 'v2k protocol';
-hmri_def.imperfectSpoilCorr.v2k.P2_a = [71.2817617982844,-92.2992876164017,45.8278193851731];
-hmri_def.imperfectSpoilCorr.v2k.P2_b = [-0.137859046784839,0.122423212397157,0.957642744668469];
-% 7) 800um protocol - seq version v3* released used by MEG group:
-hmri_def.imperfectSpoilCorr.v3star.tag = 'v3star protocol';
-hmri_def.imperfectSpoilCorr.v3star.P2_a = [57.427573706259864,-79.300742898810441,39.218584751863879];
-hmri_def.imperfectSpoilCorr.v3star.P2_b = [-0.121114060111119,0.121684347499374,0.955987357483519];
-% Unknwon protocol
-hmri_def.imperfectSpoilCorr.Unknown.tag = 'Unknown protocol. No spoiling correction defined.';
-
 %--------------------------------------------------------------------------
 % B1 mapping processing parameters 
 %--------------------------------------------------------------------------

config/local/ISC_parameters/README.txt

@@ -0,0 +1,14 @@
+IMPREFECT RF SPOILING (ISC) CORRECTION PARAMETERS 
+(Preibisch and Deichmann, MRM 61:125-135 (2009))
+Correction parameters formerly calculated by Antoine Lutti (15/01/09)
+for a series of standard protocols can be selected manually. 
+Effective TR and FA values (more precisely: [TR_pdw TR_t1w fa_pdw
+fa_t1w]) are stored within each ISC file. 
+Additional protocol types and correction factors can be computed online 
+and directly chosen as dependency input file to apply proper RF correction.
+The stored values for P2_a and P2_b were obtained using the code supplied 
+by R. Deichmann with the experimental parameters used for the standard 
+MPM protocol and assuming T2 = 64 ms at 3T.
+When enabling the imperfect spoiling correction, make sure the
+calculated coefficients are definitely calculated for the protocol used!
+ADVANCED USER ONLY.

config/local/ISC_parameters/protocol_01_classic_FIL.m

@@ -0,0 +1,9 @@
+% 1) classic FIL protocol (Weiskopf et al., Neuroimage 2011):
+% PD-weighted: TR=23.7ms; a=6deg; T1-weighted: TR=18.7ms; a=20deg
+global hmri_def
+hmri_def.MPMacq_set.name = 'Classic FIL protocol';
+hmri_def.MPMacq_set.tag  = 'ClassicFIL';
+hmri_def.MPMacq_set.val  = [23.7 18.7 6 20];
+hmri_def.imperfectSpoilCorr.ClassicFIL.tag = 'Classic FIL protocol';
+hmri_def.imperfectSpoilCorr.ClassicFIL.P2_a = [78.9228195006542,-101.113338489192,47.8783287525126];
+hmri_def.imperfectSpoilCorr.ClassicFIL.P2_b = [-0.147476233142129,0.126487385091045,0.956824374979504];

config/local/ISC_parameters/protocol_02_new_FIL_Helms.m

@@ -0,0 +1,9 @@
+% 2) new FIL/Helms protocol
+% PD-weighted: TR=24.5ms; a=5deg; T1-weighted: TR=24.5ms; a=29deg
+global hmri_def
+hmri_def.MPMacq_set.name = 'New FIL/Helms protocol';
+hmri_def.MPMacq_set.tag  = 'NewFILHelms';
+hmri_def.MPMacq_set.val  = [24.5 24.5 5 29];
+hmri_def.imperfectSpoilCorr.NewFILHelms.tag = 'New FIL/Helms protocol';
+hmri_def.imperfectSpoilCorr.NewFILHelms.P2_a = [93.455034845930480,-120.5752858196904,55.911077913369060];
+hmri_def.imperfectSpoilCorr.NewFILHelms.P2_b = [-0.167301931434861,0.113507432776106,0.961765216743606];

config/local/ISC_parameters/protocol_03_Siemens_product_sequence_Lausanne.m

@@ -0,0 +1,9 @@
+% 3) Siemens product sequence protocol used in Lausanne (G Krueger)
+% PD-weighted: TR=24ms; a=6deg; T1-weighted: TR=19ms; a=20deg
+global hmri_def
+hmri_def.MPMacq_set.name = 'Siemens product Lausanne (GK) protocol';
+hmri_def.MPMacq_set.tag  = 'SiemPrLausGK';
+hmri_def.MPMacq_set.val  = [24.0 19.0 6 20];
+hmri_def.imperfectSpoilCorr.SiemPrLausGK.tag = 'Siemens product Lausanne (GK) protocol';
+hmri_def.imperfectSpoilCorr.SiemPrLausGK.P2_a = [67.023102027100880,-86.834117103841540,43.815818592349870];
+hmri_def.imperfectSpoilCorr.SiemPrLausGK.P2_b = [-0.130876849571103,0.117721807209409,0.959180058389875];

config/local/ISC_parameters/protocol_04_high_res_0.8mm_FIL.m

@@ -0,0 +1,9 @@
+% 4) High-res (0.8mm) FIL protocol:
+% PD-weighted: TR=23.7ms; a=6deg; T1-weighted: TR=23.7ms; a=28deg
+global hmri_def
+hmri_def.MPMacq_set.name = 'High-res FIL protocol';
+hmri_def.MPMacq_set.tag  = 'HResFIL';
+hmri_def.MPMacq_set.val  = [23.7 23.7 6 28];
+hmri_def.imperfectSpoilCorr.HResFIL.tag = 'High-res FIL protocol';
+hmri_def.imperfectSpoilCorr.HResFIL.P2_a = [1.317257319014170e+02,-1.699833074433892e+02,73.372595677371650];
+hmri_def.imperfectSpoilCorr.HResFIL.P2_b = [-0.218804328507184,0.178745853134922,0.939514554747592];

config/local/ISC_parameters/protocol_05_NEW_High_res_0.8mm_FIL.m

@@ -0,0 +1,9 @@
+% 5)NEW  High-res (0.8mm) FIL protocol:
+% PD-weighted: TR=25.25ms; a=5deg; T1-weighted: TR=TR=25.25ms; a=29deg
+global hmri_def
+hmri_def.MPMacq_set.name = 'New High-res FIL protocol';
+hmri_def.MPMacq_set.tag  = 'NHResFIL';
+hmri_def.MPMacq_set.val  = [25.25 25.25 5 29];
+hmri_def.imperfectSpoilCorr.NHResFIL.tag = 'New High-res FIL protocol';
+hmri_def.imperfectSpoilCorr.NHResFIL.P2_a = [88.8623036106612,-114.526218941363,53.8168602253166];
+hmri_def.imperfectSpoilCorr.NHResFIL.P2_b = [-0.132904017579521,0.113959390779008,0.960799295622202];

config/local/ISC_parameters/protocol_06_NEW_1mm_v2k.m

@@ -0,0 +1,10 @@
+% 6)NEW  1mm protocol - seq version v2k:
+% PD-weighted: TR=24.5ms; a=6deg; T1-weighted: TR=24.5ms; a=21deg
+global hmri_def
+hmri_def.MPMacq_set.name = 'v2k protocol';
+hmri_def.MPMacq_set.tag  = 'v2k';
+hmri_def.MPMacq_set.val  = [24.5 24.5 6 21];
+hmri_def.imperfectSpoilCorr.v2k.tag = 'v2k protocol';
+hmri_def.imperfectSpoilCorr.v2k.P2_a = [71.2817617982844,-92.2992876164017,45.8278193851731];
+hmri_def.imperfectSpoilCorr.v2k.P2_b = [-0.137859046784839,0.122423212397157,0.957642744668469];
+

config/local/ISC_parameters/protocol_07_800um_v3star.m

@@ -0,0 +1,13 @@
+% 7) 800um protocol - seq version v3* released used by MEG group:
+% TR = 25ms for all volumes; flipAngles = [6, 21 deg] for PDw and T1w
+% Correction parameters below were determined via Bloch-Torrey 
+% simulations but end result agrees well with EPG-derived correction 
+% for this RF spoiling increment of 137 degrees.
+% See: Callaghan et al. ISMRM, 2015, #1694
+global hmri_def
+hmri_def.MPMacq_set.names{7} = 'v3star protocol';
+hmri_def.MPMacq_set.tags{7}  = 'v3star';
+hmri_def.MPMacq_set.vals{7}  = [25 25 6 21];
+hmri_def.imperfectSpoilCorr.v3star.tag = 'v3star protocol';
+hmri_def.imperfectSpoilCorr.v3star.P2_a = [57.427573706259864,-79.300742898810441,39.218584751863879];
+hmri_def.imperfectSpoilCorr.v3star.P2_b = [-0.121114060111119,0.121684347499374,0.955987357483519];