Skip to content

Commit 9ccbe0f

Browse files
author
Luke Edwards
committed
Merge branch 'master' into add_separate-MT-B1map
2 parents 4292e68 + f299d4d commit 9ccbe0f

31 files changed

+1997
-867
lines changed

‎CHANGELOG.md

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,20 +11,26 @@ Most recent version numbers *should* follow the [Semantic Versioning](https://se
1111
- spatial processing: add explicit mask creation and fix implicit mask (0 to NaN in float images)
1212
- update FIL seste seq parameters in get_metadata_val_classic
1313
- denoising module-first part: Java-Matlab interface for LCPCA denoising
14+
- read EffectiveEchoTime in new TerraX Dicom format
15+
- save LCPCA-denoising supplementary files as nifti instead of .mat
16+
- parameter error maps
17+
- robust combination of two runs using error maps
1418
- option to use a separate B1 map for B1 correction of MTsat; useful if pTx used for excitation pulses and CP mode for the MT pulse
1519

1620
### Fixed
1721
- replace `datestr(now)` with `datetime('now')` in line with [MATLAB recommendation](https://mathworks.com/help/matlab/matlab_prog/replace-discouraged-instances-of-serial-date-numbers-and-date-strings.html)
1822
- fix crash if input images have different matrix sizes, and warn
19-
- modify the filenames as files are copied to RFsensCalc to prevent overwriting in further processing
20-
- batch interface now enforces the number of B1 input images correctly for B1 mapping methods which only need two images.
21-
- fix error if optimization toolbox not present during NLLS R2* calculation
2223
- make B1-map creation using 3DEPI SE/STE and AFI methods fall back to defaults without sidecar files, rather than crash
24+
- modify the filenames as files are copied to RFsensCalc to prevent overwriting in further processing
25+
- batch interface now enforces the number of B1 input images correctly for B1 mapping methods which only need two images
26+
- more informative error if optimization toolbox not present during NLLS R2* calculation
27+
- fix 3D-EPI B1 mapping not using b1defaults for Triotim scanner
28+
- use cell- instead of char-array to accommodate filenames of unequal length in RFsens
2329

2430
## [v0.6.1]
2531
### Fixed
2632
- local config files have been converted to scripts for compatibility with compiled version
27-
- function-evaluate SPM-struct (preproc8.val) for SPM development version compatibility.
33+
- function-evaluate SPM-struct (preproc8.val) for SPM development version compatibility
2834
- copy acquisition metadata to TE=0 volumes in Results/Supplementary folder after map creation so they can be used as input to the toolbox if needed
2935

3036
## [v0.6.0]

‎README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ These pages are work-in-progress and updated on a regular basis.
3131

3232
For a reference on the scientific background, methods and concepts please use this [paper](https://doi.org/10.1016/j.neuroimage.2019.01.029) (formerly available as a [pre-print paper](http://dx.doi.org/10.20347/WIAS.PREPRINT.2527)) and cite it when publishing results compiled with the hMRI-toolbox.
3333

34-
A full example dataset is available [here](https://owncloud.gwdg.de/index.php/s/iv2TOQwGy4FGDDZ) to try out the hMRI toolbox. The description of the example dataset is also available in this [paper](https://doi.org/10.1016/j.dib.2019.104132).
34+
A full example dataset can be `git clone`ed or downloaded from one of the following links: ([Github](https://github.com/hMRI-group/hMRI-toolbox-demodata) | [OwnCloud](https://owncloud.gwdg.de/index.php/s/znxsMrPUB2TJsLz) | [Mega](https://mega.nz/folder/OnxDALZa#bFe0xKJTuuUeGXrYnlX8dA)). The description of the example dataset is also available in this [paper](https://doi.org/10.1016/j.dib.2019.104132).
3535

3636
## Licence
3737

‎config/hmri_defaults.m

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -434,7 +434,6 @@
434434
% directory.
435435

436436
hmri_b1_standard_defaults;
437-
438437
%==========================================================================
439438
% Maps processing parameters
440439
%==========================================================================
@@ -461,4 +460,32 @@
461460
% Number of Gaussians per tissue class
462461
hmri_def.proc.nGauss = [2 2 2 3 4 2]; % originally in SPM [1 1 2 3 4 2]
463462

463+
%==========================================================================
464+
% Generation of error maps
465+
%==========================================================================
466+
% errormaps
467+
hmri_def.errormaps = false;
468+
469+
% lower bounds on R1, PD and MTsat to avoid dividing by small numbers
470+
% in parameter-wise SNR estimates of R1/dR1, PD/dPD and MTsat/dMTsat
471+
hmri_def.qMRI_maps_thresh.dR1 = 1e-4;
472+
hmri_def.qMRI_maps_thresh.dPD = 1e-2;
473+
hmri_def.qMRI_maps_thresh.dMT = 1e-4;
474+
475+
% upper bounds on SNR maps dR1/R1, dPD/PD and dMTsat/MTsat
476+
hmri_def.qMRI_maps_thresh.SNR_R1= 1e3;
477+
hmri_def.qMRI_maps_thresh.SNR_PD= 1e3;
478+
hmri_def.qMRI_maps_thresh.SNR_MT= 1e3;
479+
480+
% weighted combination - see Mohammadi et al., NeuroImage, 2022 for details
481+
% might have to be adjusted for different dataset
482+
hmri_def.wcombparams.kt = 10; % This parameter is relevant and might have to be adjusted per protocol (defined in percent).
483+
% Examples can be found in Mohammadi et al., NeuroImage, 2022, Supplementary Materials: S1: Efficiency of robust combination and the Fermi function
484+
hmri_def.wcombparams.am = true; % True: arithmetic mean is written out, in addition to robust combination
485+
hmri_def.wcombparams.errormaps = true; % True: robust combination of error maps is generated and written out
486+
% The following parameters are for experts only.
487+
hmri_def.wcombparams.res = -4; % Resampling factor, determines interpolation method (details can be found in spm_slice_vol.m)
488+
hmri_def.wcombparams.smthk = 0; % If larger than zero, the error maps will be spatially smoothed with a Gaussian kernel of FWHM = smthk
489+
hmri_def.wcombparams.dim = 3; % Dimension along which slices will be taken; weights will be smoothed perpendicular to this
490+
464491
end

‎config/hmri_denoising_defaults.m

Lines changed: 40 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,46 @@
11
function hmri_denoising_defaults
2+
% Sets the defaults parameters which are used by the denoising module of the
3+
% hMRI toolbox.
4+
%!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5+
% DON'T MODIFY THIS FILE, IT CONTAINS THE REFERENCE DEFAULTS PARAMETERS.
6+
% Please refer to hMRI-Toolbox\config\local\hmri_local_denoising_defaults.m
7+
% to customise defaults parameters.
8+
%!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
9+
%
10+
% FORMAT hmri_denoising_defaults
11+
%__________________________________________________________________________
12+
%
13+
% THIS FILE SHOULD NOT BE MODIFIED.
14+
% To customize the hMRI-Toolbox defaults parameters so they match your own
15+
% site- or protocol-specific setup, please refer to the defaults files in
16+
% hMRI-Toolbox\config\local. In particular, use
17+
% "hmri_local_denoising_defaults.m".Make a copy with meaningful name,
18+
% modify as desired and select it in the hMRI toolbox denoising GUI.
19+
%
20+
% The structure and content of this file are largely inspired by the
21+
% equivalent file in SPM.
22+
%
23+
% DOCUMENTATION
24+
% A brief description of each parameter is provided together with
25+
% guidelines and recommendations to modify these parameters. With few
26+
% exceptions, parameters should ONLY be MODIFIED and customized BY ADVANCED
27+
% USERS, having a good knowledge of the underlying algorithms and
28+
% implementation. Please refer to the documentation in the github WIKI for
29+
% more details.
30+
%__________________________________________________________________________
31+
% Written by B. Ugurcan, 2024.
232

3-
%init the global variable which carries the params
33+
% init the global variable which carries the params
434
global hmri_def;
535

6-
%Enter denoising default values as: hmri_def.denoising.(denoising-protocol).(default-value)
36+
% Enter denoising default values as: hmri_def.denoising.(denoising-protocol).(denoising-parameter)
37+
38+
% The default values for lcpca denoising protocol
39+
hmri_def.denoising.lcpca_denoise.min_dimension = 0; % minimum number of kept PCA components
40+
hmri_def.denoising.lcpca_denoise.max_dimension = -1; % maximum number of kept PCA components (-1 for all components)
41+
hmri_def.denoising.lcpca_denoise.unwrap = true; % whether to unwrap the phase data or keep it as is
42+
hmri_def.denoising.lcpca_denoise.rescale_phs = true; % whether to rescale the phase data or keep it as is, assuming radians
43+
hmri_def.denoising.lcpca_denoise.process_2d = false; % whether to denoise in 2D, for instance when acquiring a thin slab of data
44+
hmri_def.denoising.lcpca_denoise.use_rmt = false; % whether to use random matrix theory rather than noise fitting to estimate the noise threshold
745

8-
%The default values for lcpca denoising protocol
9-
%all optional parameters turned off
10-
hmri_def.denoising.lcpca_denoise.mag_input = {}; %%required-null initialize here input with GUI
11-
hmri_def.denoising.lcpca_denoise.phase_input = {}; %%optional-null initialize here input with GUI
12-
hmri_def.denoising.lcpca_denoise.output_path=''; %%required-null initialize here input with GUI
13-
hmri_def.denoising.lcpca_denoise.min_dimension= 0; %%required-initialize here
14-
hmri_def.denoising.lcpca_denoise.max_dimension = -1; %%required-initialize here
15-
hmri_def.denoising.lcpca_denoise.unwrap = false; %%optional
16-
hmri_def.denoising.lcpca_denoise.rescale_phs = false; %%optional
17-
hmri_def.denoising.lcpca_denoise.process_2d=false; %%optional
18-
hmri_def.denoising.lcpca_denoise.use_rmt=false; %%optional
1946
end

‎config/local/hmri_local_defaults.m

Lines changed: 27 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -460,4 +460,30 @@
460460
% Number of Gaussians per tissue class
461461
hmri_def.proc.nGauss = [2 2 2 3 4 2]; % originally in SPM [1 1 2 3 4 2]
462462

463-
463+
%==========================================================================
464+
% Generation of error maps
465+
%==========================================================================
466+
% errormaps
467+
hmri_def.errormaps = false;
468+
469+
% lower bounds on R1, PD and MTsat to avoid dividing by small numbers
470+
% in parameter-wise SNR estimates of R1/dR1, PD/dPD and MTsat/dMTsat
471+
hmri_def.qMRI_maps_thresh.dR1 = 1e-4;
472+
hmri_def.qMRI_maps_thresh.dPD = 1e-2;
473+
hmri_def.qMRI_maps_thresh.dMT = 1e-4;
474+
475+
% upper bounds on SNR maps dR1/R1, dPD/PD and dMTsat/MTsat
476+
hmri_def.qMRI_maps_thresh.SNR_R1= 1e3;
477+
hmri_def.qMRI_maps_thresh.SNR_PD= 1e3;
478+
hmri_def.qMRI_maps_thresh.SNR_MT= 1e3;
479+
480+
% weighted combination - see Mohammadi et al., NeuroImage, 2022 for details
481+
% might have to be adjusted for different dataset
482+
hmri_def.wcombparams.kt = 10; % This parameter is relevant and might have to be adjusted per protocol (defined in percent).
483+
% Examples can be found in Mohammadi et al., NeuroImage, 2022, Supplementary Materials: S1: Efficiency of robust combination and the Fermi function
484+
hmri_def.wcombparams.am = true; % True: arithmetic mean is written out, in addition to robust combination
485+
hmri_def.wcombparams.errormaps = true; % True: robust combination of error maps is generated and written out
486+
% The following parameters are for experts only.
487+
hmri_def.wcombparams.res = -4; % Resampling factor, determines interpolation method (details can be found in spm_slice_vol.m)
488+
hmri_def.wcombparams.smthk = 0; % If larger than zero, the error maps will be spatially smoothed with a Gaussian kernel of FWHM = smthk
489+
hmri_def.wcombparams.dim = 3; % Dimension along which slices will be taken; weights will be smoothed perpendicular to this

‎config/local/hmri_local_denoising_defaults.m

Lines changed: 17 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,20 @@
1-
%init the global variable which carries the params
1+
% PURPOSE
2+
% To set user-defined (site- or protocol-specific) defaults parameters
3+
% which are used by the denoising module in the hMRI toolbox. Customized
4+
% processing parameters can be defined, overwriting defaults from
5+
% hmri_local_denoising defaults.
6+
%__________________________________________________________________________
7+
% Written by B. Ugurcan, 2024.
8+
9+
% init the global variable which carries the params
210
global hmri_def;
311

4-
%Enter denoising default values as: hmri_def.denoising.(denoising-protocol).(default-value)
12+
% Enter denoising default values as: hmri_def.denoising.(denoising-protocol).(denoising-parameter)
513

6-
%The default values for lcpca denoising protocol
7-
%all optional parameters turned off
8-
hmri_def.denoising.lcpca_denoise.mag_input = {}; %%required-null initialize here input with GUI
9-
hmri_def.denoising.lcpca_denoise.phase_input = {}; %%optional-null initialize here input with GUI
10-
hmri_def.denoising.lcpca_denoise.output_path=''; %%required-null initialize here input with GUI
11-
hmri_def.denoising.lcpca_denoise.min_dimension= 0; %%required-initialize here
12-
hmri_def.denoising.lcpca_denoise.max_dimension = -1; %%required-initialize here
13-
hmri_def.denoising.lcpca_denoise.unwrap = false; %%optional
14-
hmri_def.denoising.lcpca_denoise.rescale_phs = false; %%optional
15-
hmri_def.denoising.lcpca_denoise.process_2d=false; %%optional
16-
hmri_def.denoising.lcpca_denoise.use_rmt=false; %%optional
14+
% The default values for lcpca denoising protocol
15+
hmri_def.denoising.lcpca_denoise.min_dimension = 0; % minimum number of kept PCA components
16+
hmri_def.denoising.lcpca_denoise.max_dimension = -1; % maximum number of kept PCA components (-1 for all components)
17+
hmri_def.denoising.lcpca_denoise.unwrap = true; % whether to unwrap the phase data or keep it as is
18+
hmri_def.denoising.lcpca_denoise.rescale_phs = true; % whether to rescale the phase data or keep it as is, assuming radians
19+
hmri_def.denoising.lcpca_denoise.process_2d = false; % whether to denoise in 2D, for instance when acquiring a thin slab of data
20+
hmri_def.denoising.lcpca_denoise.use_rmt = false; % whether to use random matrix theory rather than noise fitting to estimate the noise threshold

‎docs/index.html

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -71,9 +71,9 @@ <h3>
7171
<h3>
7272
<a id="hmri-example-data-and-mri-protocol" class="anchor" href="#hmri-example-data-and-mri-protocol" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Sample Dataset and MRI Acquisition Protocols</h3>
7373
<p>A sample dataset is provided as reference and material for exploring the possibilities and functionalities of the hMRI-toolbox.
74-
It is publicly available for download <a href="https://owncloud.gwdg.de/index.php/s/iv2TOQwGy4FGDDZ">here</a> (<a href="#Callaghan.2019">Callaghan et al., 2019</a>).
74+
The public dataset (<a href="#Callaghan.2019">Callaghan et al., 2019</a>) can be downloaded from one of the following links: <a href="https://github.com/hMRI-group/hMRI-toolbox-demodata">GitHub</a> | <a href="https://owncloud.gwdg.de/index.php/s/znxsMrPUB2TJsLz">OwnCloud</a> | <a href="https://mega.nz/folder/OnxDALZa#bFe0xKJTuuUeGXrYnlX8dA">Mega</a>.
7575
Several example MRI protocols (standard MPM protocol using customised Siemens sequences, as well MPM protocol implemented using Siemens and Philips product sequences)
76-
as well as a setup (for Siemens 3T MRI) and usage tutorial are available at the same URL.
76+
as well as a setup (for Siemens 3T MRI) and usage tutorial are available at the download links.
7777
Please be aware that we provide these protocols and information without any warranty.
7878
They must be considered work-in-progress, possibly non-optimal protocols and information.</p>
7979
<h3>

‎examples/hmri_local_defaults_errormaps.m

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
% PURPOSE
2+
% To set user-defined (site- or protocol-specific) defaults parameters
3+
% which are used by the hMRI toolbox. Customized processing parameters can
4+
% be defined, overwriting defaults from hmri_defaults. Acquisition
5+
% protocols can be specified here as a fallback solution when no metadata
6+
% are available. Note that the use of metadata is strongly recommended.
7+
%
8+
% RECOMMENDATIONS
9+
% Parameters defined in this file are identical, initially, to the ones
10+
% defined in hmri_defaults.m. It is recommended, when modifying this file,
11+
% to remove all unchanged entries and save the file with a meaningful name.
12+
% This will help you identifying the appropriate defaults to be used for
13+
% each protocol, and will improve the readability of the file by pointing
14+
% to the modified parameters only.
15+
%
16+
% WARNING
17+
% Modification of the defaults parameters may impair the integrity of the
18+
% toolbox, leading to unexpected behaviour. ONLY RECOMMENDED FOR ADVANCED
19+
% USERS - i.e. who have a good knowledge of the underlying algorithms and
20+
% implementation. The SAME SET OF DEFAULT PARAMETERS must be used to
21+
% process uniformly all the data from a given study.
22+
%
23+
% HOW DOES IT WORK?
24+
% The modified defaults file can be selected using the "Configure toolbox"
25+
% branch of the hMRI-Toolbox. For customization of B1 processing
26+
% parameters, type "help hmri_b1_standard_defaults.m".
27+
%
28+
% DOCUMENTATION
29+
% A brief description of each parameter is provided together with
30+
% guidelines and recommendations to modify these parameters. With few
31+
% exceptions, parameters should ONLY be MODIFIED and customized BY ADVANCED
32+
% USERS, having a good knowledge of the underlying algorithms and
33+
% implementation.
34+
% Please refer to the documentation in the github WIKI for more details.
35+
%__________________________________________________________________________
36+
% This is an example defaults file for the error map calculation.
37+
% S.Mohammadi 12/07/2022
38+
39+
% Global hmri_def variable used across the whole toolbox
40+
global hmri_def
41+
42+
%==========================================================================
43+
% Generation of error maps
44+
%==========================================================================
45+
% errormaps
46+
hmri_def.errormaps = true;
47+
48+
% lower bounds on R1, PD and MTsat to avoid dividing by small numbers
49+
% in parameter-wise SNR estimates of R1/dR1, PD/dPD and MTsat/dMTsat
50+
hmri_def.qMRI_maps_thresh.dR1 = 1e-4;
51+
hmri_def.qMRI_maps_thresh.dPD = 1e-2;
52+
hmri_def.qMRI_maps_thresh.dMT = 1e-4;
53+
54+
% upper bounds on SNR maps dR1/R1, dPD/PD and dMTsat/MTsat
55+
hmri_def.qMRI_maps_thresh.SNR_R1= 1e3;
56+
hmri_def.qMRI_maps_thresh.SNR_PD= 1e3;
57+
hmri_def.qMRI_maps_thresh.SNR_MT= 1e3;
58+
59+
% weighted combination - see Mohammadi et al., NeuroImage, 2022 for details
60+
% might have to be adjusted for different dataset
61+
hmri_def.wcombparams.kt = 10; % This parameter is relevant and might have to be adjusted per protocol (defined in percent).
62+
% Examples can be found in Mohammadi et al., NeuroImage, 2022, Supplementary Materials: S1: Efficiency of robust combination and the Fermi function
63+
hmri_def.wcombparams.am = true; % True: arithmetic mean is written out, in addition to robust combination
64+
hmri_def.wcombparams.errormaps = true; % True: robust combination of error maps is generated and written out
65+
% The following parameters are for experts only.
66+
hmri_def.wcombparams.res = -4; % Resampling factor, determines interpolation method (details can be found in spm_slice_vol.m)
67+
hmri_def.wcombparams.smthk = 0; % If larger than zero, the error maps will be spatially smoothed with a Gaussian kernel of FWHM = smthk
68+
hmri_def.wcombparams.dim = 3; % Dimension along which slices will be taken; weights will be smoothed perpendicular to this

‎hmri_calc_A.m

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -47,8 +47,11 @@
4747
end
4848

4949
assert(all(size(PDw.data)==size(T1w.data)),'hmri:inputArraySize','PDw.data and T1w.data must be the same size!')
50-
assert(PDw.TR>0,'hmri:TR','PDw.TR must be positive!')
51-
assert(T1w.TR>0,'hmri:TR','T1w.TR must be positive!')
50+
51+
% Sanity check TR
52+
% Use "isAlways" so that hmri_calc_A.m can be called using symbolic variables
53+
assert(isAlways(PDw.TR>0),'hmri:TR','PDw.TR must be positive!')
54+
assert(isAlways(T1w.TR>0),'hmri:TR','T1w.TR must be positive!')
5255

5356
A=T1w.data.*PDw.data.*( T1w.TR.*PDw.t./T1w.t - PDw.TR.*T1w.t./PDw.t )...
5457
./ ( PDw.data.*T1w.TR.*PDw.t - T1w.data.*PDw.TR.*T1w.t );

‎hmri_calc_R1.m

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -47,8 +47,11 @@
4747
end
4848

4949
assert(all(size(PDw.data)==size(T1w.data)),'hmri:inputArraySize','PDw.data and T1w.data must be the same size!')
50-
assert(PDw.TR>0,'hmri:TR','PDw.TR must be positive!')
51-
assert(T1w.TR>0,'hmri:TR','T1w.TR must be positive!')
50+
51+
% Sanity check TR
52+
% Use "isAlways" so that hmri_calc_R1.m can be called using symbolic variables
53+
assert(isAlways(PDw.TR>0),'hmri:TR','PDw.TR must be positive!')
54+
assert(isAlways(T1w.TR>0),'hmri:TR','T1w.TR must be positive!')
5255

5356
R1=0.5*( PDw.data.*PDw.t/PDw.TR - T1w.data.*T1w.t/T1w.TR )...
5457
./( T1w.data./T1w.t - PDw.data./PDw.t );

0 commit comments

Comments
 (0)