usage: __main__.py [-h] [--out_prefix OUT_PREFIX] [--mask MASK] --in_altnp
IN_ALTNP [IN_ALTNP ...] --in_altpn IN_ALTPN [IN_ALTPN ...]
--in_negative IN_NEGATIVE [IN_NEGATIVE ...] --in_positive
IN_POSITIVE [IN_POSITIVE ...] --in_mtoff_pd IN_MTOFF_PD
[IN_MTOFF_PD ...]
[--in_mtoff_t1 IN_MTOFF_T1 [IN_MTOFF_T1 ...]] [--extended]
[--filtering]
[--in_jsons PD_json T1_json | --in_acq_parameters PD flip angle T1 flip angle PD repetition time T1 repetition time]
[--in_B1_map IN_B1_MAP]
[--B1_correction_method {empiric,model_based}]
[--B1_fitvalues B1_FITVALUES [B1_FITVALUES ...]]
[--B1_nominal B1_NOMINAL] [--B1_smooth_dims B1_SMOOTH_DIMS]
[-v [{DEBUG,INFO,WARNING}]] [-f]
out_dir
This script computes four myelin indices maps from the Magnetization Transfer
(MT) and inhomogeneous Magnetization Transfer (ihMT) images. Magnetization
Transfer is a contrast mechanism in tissue resulting from the proton exchange
between non-aqueous protons (from macromolecules and their closely associated
water molecules, the "bound" pool) and protons in the free water pool called
aqueous protons. This exchange attenuates the MRI signal, introducing
microstructure-dependent contrast. MT's effect reflects the relative density
of macromolecules such as proteins and lipids, it has been associated with
myelin content in white matter of the brain.
Different contrasts can be done with an off-resonance pulse prior to image
acquisition (a prepulse), saturating the protons on non-aqueous molecules,
by applying different frequency irradiation. The two MT maps and two ihMT maps
are obtained using six contrasts: single positive frequency image, single
negative frequency image, dual alternating positive/negative frequency image,
dual alternating negative/positive frequency image (saturated images);
and two unsaturated contrasts as reference. These two references should be
acquired with predominant PD (proton density) and T1 weighting at different
excitation flip angles (a_PD, a_T1) and repetition times (TR_PD, TR_T1).
Input Data recommendation:
- it is recommended to use dcm2niix (v1.0.20200331) to convert data
https://github.com/rordenlab/dcm2niix/releases/tag/v1.0.20200331
- dcm2niix conversion will create all echo files for each contrast and
corresponding json files
- all contrasts must have a same number of echoes and coregistered
between them before running the script
- Mask must be coregistered to the echo images
- ANTs can be used for the registration steps (http://stnava.github.io/ANTs/)
The output consists of a ihMT_native_maps folder containing the 4 myelin maps:
- MTR.nii.gz : Magnetization Transfer Ratio map
- ihMTR.nii.gz : inhomogeneous Magnetization Transfer Ratio map
The (ih)MT ratio is a measure reflecting the amount of bound protons.
- MTsat.nii.gz : Magnetization Transfer saturation map
- ihMTsat.nii.gz : inhomogeneous Magnetization Transfer saturation map
The (ih)MT saturation is a pseudo-quantitative maps representing
the signal change between the bound and free water pools.
As an option, the Complementary_maps folder contains the following images:
- altnp.nii.gz : dual alternating negative and positive frequency image
- altpn.nii.gz : dual alternating positive and negative frequency image
- positive.nii.gz : single positive frequency image
- negative.nii.gz : single negative frequency image
- mtoff_PD.nii.gz : unsaturated proton density weighted image
- mtoff_T1.nii.gz : unsaturated T1 weighted image
- MTsat_d.nii.gz : MTsat computed from the mean dual frequency images
- MTsat_sp.nii.gz : MTsat computed from the single positive frequency image
- MTsat_sn.nii.gz : MTsat computed from the single negative frequency image
- R1app.nii.gz : Apparent R1 map computed for MTsat.
- B1_map.nii.gz : B1 map after correction and smoothing (if given).
The final maps from ihMT_native_maps can be corrected for B1+ field
inhomogeneity, using either an empiric method with
--in_B1_map option, suffix *B1_corrected is added for each map.
--B1_correction_method empiric
or a model-based method with
--in_B1_map option, suffix *B1_corrected is added for each map.
--B1_correction_method model_based
--B1_fitValues 3 .mat files, obtained externally from
https://github.com/TardifLab/OptimizeIHMTimaging/tree/master/b1Correction,
and given in this order: positive frequency saturation, negative frequency
saturation, dual frequency saturation.
For both methods, the nominal value of the B1 map can be set with
--B1_nominal value
>>> scil_mti_maps_ihMT.py path/to/output/directory
--in_altnp path/to/echo*altnp.nii.gz --in_altpn path/to/echo*altpn.nii.gz
--in_mtoff_pd path/to/echo*mtoff.nii.gz
--in_negative path/to/echo*neg.nii.gz --in_positive path/to/echo*pos.nii.gz
--in_mtoff_t1 path/to/echo*T1w.nii.gz --mask path/to/mask_bin.nii.gz
--in_jsons path/to/echo*mtoff.json path/to/echo*T1w.json
By default, the script uses all the echoes available in the input folder.
If you want to use a single echo, replace the * with the specific number of
the echo.
positional arguments:
out_dir Path to output folder.
options:
-h, --help show this help message and exit
--out_prefix OUT_PREFIX
Prefix to be used for each output image.
--mask MASK Path to the binary brain mask.
--extended If set, outputs the folder Complementary_maps.
--filtering Gaussian filtering to remove Gibbs ringing. Not recommended.
-v [{DEBUG,INFO,WARNING}]
Produces verbose output depending on the provided level.
Default level is warning, default when using -v is info.
-f Force overwriting of the output files.
Contrast maps:
Path to echoes corresponding to contrast images. All constrasts must have
the same number of echoes and coregistered between them. Use * to include all echoes.
--in_altnp IN_ALTNP [IN_ALTNP ...]
Path to all echoes corresponding to the alternation of
negative and positive frequency saturation pulse.
--in_altpn IN_ALTPN [IN_ALTPN ...]
Path to all echoes corresponding to the alternation of
positive and negative frequency saturation pulse.
--in_negative IN_NEGATIVE [IN_NEGATIVE ...]
Path to all echoes corresponding to the negative frequency
saturation pulse.
--in_positive IN_POSITIVE [IN_POSITIVE ...]
Path to all echoes corresponding to the positive frequency
saturation pulse.
--in_mtoff_pd IN_MTOFF_PD [IN_MTOFF_PD ...]
Path to all echoes corresponding to the predominant PD
(proton density) weighting images with no saturation pulse.
--in_mtoff_t1 IN_MTOFF_T1 [IN_MTOFF_T1 ...]
Path to all echoes corresponding to the predominant T1
weighting images with no saturation pulse. This one is optional,
since it is only needed for the calculation of MTsat and ihMTsat.
Acquisition parameters should also be set with this image.
Acquisition parameters:
Acquisition parameters required for MTsat and ihMTsat calculation.
These are the excitation flip angles (a_PD, a_T1), in DEGREES, and
repetition times (TR_PD, TR_T1) of the PD and T1 images, in SECONDS.
Can be given through json files (--in_jsons) or directly (--in_acq_parameters).
--in_jsons PD_json T1_json
Path to MToff PD json file and MToff T1 json file, in that order.
The acquisition parameters will be extracted from these files.
Must come from a Philips acquisition, otherwise, use in_acq_parameters.
--in_acq_parameters PD flip angle T1 flip angle PD repetition time T1 repetition time
Acquisition parameters in that order: flip angle of mtoff_PD,
flip angle of mtoff_T1, repetition time of mtoff_PD,
repetition time of mtoff_T1
B1 correction:
--in_B1_map IN_B1_MAP
Path to B1 coregister map to MT contrasts.
--B1_correction_method {empiric,model_based}
Choice of B1 correction method. Choose between empiric and model-based.
Note that the model-based method requires a B1 fitvalues file.
Both method will only correct the saturation measures. [empiric]
--B1_fitvalues B1_FITVALUES [B1_FITVALUES ...]
Path to B1 fitvalues files obtained externally. Should be one .mat
file per input MT-on image, given in this specific order:
positive frequency saturation, negative frequency saturation.
--B1_nominal B1_NOMINAL
Nominal value for the B1 map. For Philips, should be 100. [100]
--B1_smooth_dims B1_SMOOTH_DIMS
Dimension of the squared window used for B1 smoothing, in number of voxels. [5]