Parameters¶
This page describes the input parameters for ASL DRO. These should all be supplied over the command-line-interface as a json file. This file has two top-level objects. A “global_configuration” object, in which settings that apply to othe running of the instance of ASLDRO are set, and an image_series” object which defines the settings for each set of reference data that is generated.
Below is an example input parameter file, giving its overall structure.
{
"global_configuration": {
"ground_truth": "hrgt_icbm_2009a_nls_3t",
"image_override": {},
"parameter_override": {},
"subject_label": "001"
},
"image_series": [
{
"series_type": "asl",
"series_description": "an asl image series",
"series_parameters": {
}
},
{
"series_type": "structural",
"series_description": "a structural image series",
"series_parameters": {
}
},
{
"series_type": "ground_truth",
"series_description": "a ground truth image series",
"series_parameters": {
}
}
]
}
Global Configuration¶
The “global_configuration” object is describes key-value pairs that configure how the instance of ASLDRO will run:
- ground_truth
(string) Determines which ground truth to be used. See Input Ground Truth for more information. At present the following are supported:
“hrgt_icbm_2009a_nls_3t” - based on MNI ICBM 2009a Nonlinear Symmetric template, 3T relaxation times.
“hrgt_icbm_2009a_nls_1.5t” - based on MNI ICBM 2009a Nonlinear Symmetric template, 1.5T relaxation times.
- image_override
(object) Contains key/value pairs which will override any of the ground truth images with a given value. For example, if you wish to use a constant “m0”, the
image_override
should be set to{"m0": n}
, wheren
is the floating point or integer value required.- parameter_override
(object) Contains key/value pairs which will override any of the ground truth parameters. For example, you might want to change
lambda_blood_brain
to 0.85, in which case you would setparameter_override
to{"lambda_blood_brain": 0.85}
.
- ground_truth_modulate
(object) Contains key/value pairs which will modulate any of the ground truth images with a given scale and/or offset (i.e. \(y = sx + c\) where \(s\) is the scaling factor, \(c\) is the \(x\) is the input voxel value, and \(y\) is the modulated voxel value and For example, you might want to apply a scale of 0.9 and an offset of 1 to the ‘m0’ image, therefore, the required dictionary input for ‘ground_truth_modulate’ would be:
{"m0":{"scale": 0.9, "offset": 1}}
. Note that the scaling is applied before the offset (seeasldro.filters.scale_offset_filter.ScaleOffsetFilter
for more details).
- subject_label
(string) Corresponds to the BIDS entity
subject
. Files will be saved within a sub-directory named ‘sub-<subject_label>’, and will be prefixed with ‘sub-<subject_label>’. If not supplied will default to “001”
A more complete example is given below:
{
"global_configuration": {
"ground_truth": "hrgt_icbm_2009a_nls_3t",
"image_override": {"m0": 5.2},
"parameter_override": {"lambda_blood_brain": 0.85},
"ground_truth_modulate": {
"m0": {"scale": 0.9, "offset": 1},
"t1": {"offset": 0.5},
"t2": {"scale": 1.1}
},
"subject_label": "asldro01"
}
}
Image Series¶
The “image_series” object is an array, with each entry an object that describes images to generate. This object has three key-value entries:
- series_type
(string) Specifies which image generation pipeline to run, see below for more details.
- series_description
(string, optional) A string that can be used to describe the image series. The value here is added to the field “descrip” in the output NIFTI header, and the BIDS field “Description” in the output .json sidecar of any files generated corresponding to the image series.
- series_parameters
(object, optional) An object containing key-value pairs that configure the image series. Some of these parameters are image series specific, for example the parameters that must be supplied as arrays for
series_type
“asl” are all singleton values forseries_type
“structural”. Eachseries_type
has its own set of default parameters. This is field is omitted then the pipeline will be run using the complete set of default values.
There are three different image generation pipelines built into ASLDRO:
- asl
The full ASL generation pipeline, constructing a time-series of m0, control and label volumes with perfusion signal generated by the General Kinetic Model, which is then encoded into gradient or spin echo contrast, motion is optionally applied, and an image is acquired at the specified acquisition resolution.
- structural
A single volume is generated using gradient echo, spin echo, or inversion recovery contrast, motion optionally applied and an image acquired at the specified acquisition resolution. Typically this is used togenerate the structural images such as T1w or FLAIR that ASL images are registered to.
- ground_truth
This pipeline simply resamples the input ground truth images to a specified resolution.
Parameters for each series_type
are described below:
Series Type: ASL¶
The full ASL generation pipeline, comprises of constructing a time-series of m0, control and label volumes with perfusion signal generated by the General Kinetic Model, which is then encoded into gradient or spin echo contrast, motion is optionally applied, and an image is acquired at the specified acquisition resolution.
All strings are case-insensitive, for example “pcasl”, “pCASL” and “PCASL” are all valid.
Images generated by the ASL pipeline will be stored in a subdirectory names “perf”.
All parameters have defaults if omitted; the default parameters result in a “White Paper” style acquisition using the full General Kinetic Model [2] to generate the perfusion signal:
pCASL, 1.8s label duration, 1.8s PLD.
One M0, one Control and one Label volume.
SNR 1000 (this results in a perfusion signal SNR of ~10).
Acquisition matrix of [64, 64, 40], gives a voxel size of ~[3.1, 3.6, 4.7] mm
Background suppression applied to the Control and Label volumes, with pulse times optimised for the T1 values in the ground truth, based on four pulses and a saturation time of 3.9 seconds, however the actual saturation time is 4.0 seconds to ensure all magnetisation is positive.
Single or Multiphase ASL¶
Single or multiphase ASL data can be generated using the parameter signal_time, depending on the values supplied:
If
signal_time
is a single value, then single phase ASL data will be generated in accordance with the volumes in asl_context, i.e. a single post labelling delay.If
signal_time
is an array of values, then multiphase ASL data will be generated, where a set of volumes according to asl_context will be generated for each value ofsignal_time
, i.e. a set of data for each post labelling delay. These images will be
In the ASL series pipeline, signal_time
is iterated over in the outer loop,
and asl_context
is iterated over in the inner loop. All images are concatenated
into a single 4D timeseries in the order of acquisition. For example:
{
"series_type": "asl",
"series_description": "multiphase asl",
"series_parameters": {
"label_duration": 1.0,
"signal_time": [1.0, 1.25, 1.5],
"asl_context": "control label"
}
}
Will produce a 4D timeseries with volumes in this order:
control, PLD = 0.00s
label, PLD = 0.00s
control, PLD = 0.25s
label, PLD = 0.25s
control, PLD = 0.50s
label, PLD = 0.50s
- signal_time
(float or array, optional) The time in seconds after labelling at which the ASL signal should be generated. Note that this is equal to the
label_duration
+ Post Label Delay, however the latter is not a defined input parameter. Defaults to3.6
.
Single value parameters¶
The following parameters are applied to every volume that is generated by the DRO.
- gkm_model
(string, optional) Defines which model to use to generate the perfusion signal.
- ‘full’
Uses the full “Buxton” General Kinetic Model [2]
- ‘whitepaper’
Uses a simplified model derived from the single subtraction quantification equations [1]
Defaults to
"full"
. For implementation details seeGkmFilter
.- label_type
(string, optional) Defines the type of ASL labelling: “pcasl”, “casl” or “pasl”. See
GkmFilter
for implementation details. Defaults to"pcasl"
.- label_duration
(float, optional) The temporal duration in seconds of the labelled bolus of blood. Defaults to
1.8
.- label_efficiency
(float, optional): The degree of inversion of the magnetisation by the labelling pulses. Defaults to
0.85
.- acq_matrix
(array of integers, optional) A 3-entry array defining the acquisition matrix size [Ni, Nj, Nk]. Defaults to
[64, 64, 20]
.- interpolation
(string, optional) The type of interpolation to use when resampling the ‘acquired’ image. See :class:’.ResampleFilter’ for implementation details. Can be:
- ‘continuous’
order 3 spline interpolation
- ‘linear’
order 1 linear interpolation
- ‘nearest’
nearest neighbour interpolation
Default value for an asl image series is
"linear"
.- acq_contrast
(string, optional): Defines the MRI signal model to use. “ge” for Gradient Echo, “se” for Spin Echo. See
MriSignalFilter
for implementation details. Defaults to"se"
.- desired_snr
(float, optional) The signal-to-noise ratio of the acquired image. Note this is the base SNR of the image, not the SNR of the perfusion signal. A value of approximately 100 is comparable to the sort of SNR in a single ASL control-label pair. If this has value of 0, then no noise will be added. See
AddComplexNoiseFilter
for implementation details. Defaults to1000.0
, which provides acceptable SNR for a single subtraction.- random_seed
(int, optional) Seed to control the determinism of any pseudo-random behaviour in the pipeline, for example the noise added to images. Defaults to
0
.- output_image_type
(string, optional) Specifies the image type of the output image: “magnitude”, “complex”. Defaults to
"magnitude"
.- background_supppression
(object or boolean, optional) Defines whether background suppression is used. Background suppression comprises of a saturation pulse followed by multiple inversion pulses with inversion times chosen so that the magnetisation of tissues with different T1’s are nulled at the point that the imaging excitation pulse is played out. Can take the form:
- true
Background suppression is used, with the default parameters.
- false
No background suppression is used.
- object
An object with key/value pairs defining parmaeters for the background suppression.
The default value for
background_suppression
is:{ "sat_pulse_time": 4.0, "sat_pulse_time_opt": 3.98, "pulse_efficiency": "ideal", "num_inv_pulses": 4, "apply_to_asl_context": ["label", "control"] }
Background Suppression Parameters
Below are the valid background suppression parameters for when an object is used as the value
for the parameter key background_suppression
. For more information about the
implementation of background suppression see BackgroundSuppressionFilter
. Note that
due to the way these parameters are validated, the values returned if an empty object
is provided for the parameter background_suppression
will differ
to those listed in the default value above. Instead they will take the defaults listed
below.
- sat_pulse_time
(float) The time in seconds between the saturation pulse and the imaging excitation pulse. Defaults to
4.0
.- inv_pulse_times
(array of floats, optional) Array of the inversion times for each inversion pulse. Defined as the spacing between the inversion pulse and the imaging excitation pulse in seconds. If omitted then optimal inversion times will be calculated.
- pulse_efficiency
(string or float, optional) Defines the efficiency of the excitation pulse. Can take the values:
“realistic” Pulse efficiencies are calculated according to a model based on their T1.
“ideal” Inversion pulses are 100% efficient.
A numeric value between -1.0 and 0.0, inclusive, explicitly defining the inversion efficiency. -1.0 is full inversion, and 0.0 is no inversion.
The default value is “ideal”.
- t1_opt
(array of floats, optional) The T1 relaxation times, in seconds, to optimise the inversion times for. If omitted then the unique T1 values in the ground truth image for T1 will be used.
- sat_pulse_time_opt
(float, optional) If present, this value will be used in the pulse timing optimisation. This enables the use of a slightly longer
sat_pulse_time
, to ensure that the magnetisation is positive at the point of excitation. If omitted thensat_pulse_time
will be used for the optimisation (default)- num_inv_pulses
(int) The number of inversion pulses to generate optimised times for. Defaults to 4.
- apply_to_asl_context
A list defining which asl contexts should have background suppression applied for. The entries can either be
"control"
,"label"
, or"m0scan"
. Defaults to["label", "control]
.
Array Parameters¶
The following parameters are all supplied as arrays, with each entry corresponding with the volumes
defined in asl_context
.
- asl_context
(string, optional): A list of the ASL volumes to simulate, any combination of “m0scan”, “control” and “label”, separated by a space. Defaults to
"m0scan control label".
- echo_time
(array of floats or object, optional): The time in seconds after the excitation pulse that the MRI signal is acquired. This parameter generally affects the T2 or T2* contrast. Default values are given for the value of
asl_context
:- “m0scan”
0.01
- “control”
0.01
- “label”
0.01
- repetition_time
(array of floats or object, optional): The time in seconds between successive excitation pulses. This parameter affects the T1 contrast. Default values are given for the value of
asl_context
:- “m0scan”
10.0
- “control”
5.0
- “label”
5.0
- rot_z
(array of floats or object, optional): Rotation of the ground truth model in world space about the z-axis in degrees. See
TransformResampleImageFilter
for implementation details. Defaults to0.0
for every entry inasl_context
.- rot_y
(array of floats or object, optional): Rotation of the ground truth model in world space about the y-axis in degrees. Defaults to
0.0
for every entry inasl_context
.- rot_x
(array of floats or object, optional): Rotation of the ground truth model in world space about the x-axis in degrees. Defaults to
0.0
for every entry inasl_context
.- transl_x
(array of floats or object, optional): Translation of the ground truth model in world space along the x-axis in mm. Defaults to
0.0
for every entry inasl_context
.- transl_y
(array of floats or object, optional): Translation of the ground truth model in world space along the y-axis in mm. Defaults to
0.0
for every entry inasl_context
.- transl_z
(array of floats or object, optional): Translation of the ground truth model in world space along the z-axis in mm. Defaults to
0.0
for every entry inasl_context
.
Array parameters can also be specified dynamically and generated automatically based on the
entries in asl_context
. This is handled in two different ways:
echo_time
andrepetition_time
have values that are defined for the types of entries inasl_context
, and arrays of these values are constructed accordingly.The rotation and translation (
rot_*
andtransl_*
) values are drawn from probability distributions:- gaussian
Values are drawn from a normal/gaussian distribution with defined mean and standard deviation.
- uniform
Values are drawn from a uniform distribution with defined minimum and maximum values.
These are defined by an object with the following entries:
- distribution
(string, defaults to
gaussian
): The probability distribution.gaussian
for normal distribution anduniform
for a uniform distribution.- mean
(float, defaults to 0.0, required if
distribution=='gaussian'
). The mean value of the gaussian distribution.- sd
(float, defaults to 0.0, required if
distribution=='gaussian'
). The standard deviation of the gaussian distribution.- min
(float, required if
distribution=='uniform'
). The minimum value of the uniform distribution.- max
(float, required if
distribution=='uniform'
). The maximum value of the uniform distribution.- seed
(int, defaults to 0): The seed for the random number generator. Note this is independent of the
random_seed
. Each parameter will have its own random number generator assigned, which means they will have identical values if the same seed is assigned.
Generated values are rounded to four decimal places so that if the parameter file is saved as a JSON file the results can be reproduced.
For example:
{
"asl_context": "m0scan m0scan control label control label control label",
"echo_time": {
"m0scan": 0.012,
"control": 0.012,
"label": 0.012
},
"repetition_time": {
"m0scan": 10.0,
"control": 4.5,
"label": 4.5
},
"rot_x": {
"distribution": "gaussian",
"mean": 1.0,
"sd": 0.1,
"seed": 12345
},
"transl_y": {
"distribution": "uniform",
"min": 1.0,
"max": 0.1,
"seed": 12345
}
}
Dynamically generates the following array parameters:
{
"asl_context": "m0scan m0scan control label control label control label",
"echo_time": [0.12, 0.12, 0.12, 0.12, 0.12, 0.12, 0.12, 0.12],
"repetition_time": [10.0, 10.0, 4.5, 4.5, 4.5, 4.5, 4.5, 4.5],
"rot_x": [0.8576, 1.1264, 0.9129, 0.9741, 0.9925, 0.9259, 0.8632, 1.0649],
"rot_y": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
"rot_z": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
"transl_x": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
"transl_y": [0.7954, 0.7149, 0.2824, 0.3914, 0.648, 0.7005, 0.4615, 0.8319],
"transl_z": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
}
Series Type: Structural¶
The structural pipeline simulates the acquisition of a single volume using gradient echo, spin echo, or inversion recoverycontrast, motion optionally applied and an image acquired at the specified acquisition resolution. Typically this is used togenerate the structural images such as T1w or FLAIR that ASL images are registered to.
All parameters have defaults if omitted; the default parameters result in spin echo contrast with TE=5ms and TR=300m and an acquisition voxel size of 1x1x1mm.
All strings are case-insensitive, for example “ge”, “GE” and “Ge” are all valid.
Images generated by the structural pipeline will be stored in a subdirectory names “anat”.
Single value parameters¶
The following parameters are applied to every volume that is generated by the DRO.
- acq_matrix
(array of integers, optional) A 3-entry array defining the acquisition matrix size [Ni, Nj, Nk]. Defaults to
[197, 233, 189]
.- acq_contrast
(string, optional) Defines the MRI signal model to use. “ge” for Gradient Echo, “se” for Spin Echo. See
MriSignalFilter
for implementation details. Defaults to"se"
.- desired_snr
(float, optional) The signal-to-noise ratio. If this has value of 0, then no noise will be added. See
AddComplexNoiseFilter
for implementation details. Defaults to100.0
.- random_seed
(int, optional) Seed to control the determinism of any pseudo-random behaviour in the pipeline, for example the noise added to images. Defaults to
0
.- echo_time
(float, optional) The time in seconds after the excitation pulse that the MRI signal is acquired. This parameter generally affects the T2 or T2* contrast. Defaults to
0.005
.- repetition_time
(float, optional) The time in seconds between successive excitation pulses. This parameter affects the T1 contrast. Defaults to
0.3
.- rot_z
(float, optional) Rotation of the ground truth model in world space about the z-axis in degrees. See
TransformResampleImageFilter
for implementation details. Defaults to0.0
.- rot_y
(float, optional) Rotation of the ground truth model in world space about the y-axis in degrees. Defaults to
0.0
.- rot_x
(float, optional) Rotation of the ground truth model in world space about the x-axis in degrees. Defaults to
0.0
.- transl_x
(float, optional) Translation of the ground truth model in world space along the x-axis in mm. Defaults to
0.0
.- transl_y
(float, optional) Translation of the ground truth model in world space along the y-axis in mm. Defaults to
0.0
.- transl_z
(float, optional) Translation of the ground truth model in world space along the z-axis in mm. Defaults to
0.0
.- interpolation
(string, optional) The type of interpolation to use when resampling the ‘acquired’ image. See :class:’.ResampleFilter’ for implementation details. Can be:
- ‘continuous’
order 3 spline interpolation
- ‘linear’
order 1 linear interpolation
- ‘nearest’
nearest neighbour interpolation
Default value for a structural image series is
"linear"
.- output_image_type
(string, optional) Specifies the image type of the output image: “magnitude”, “complex”. Defaults to
"magnitude"
.- modality
(string, optional) Describes the intent of the generated image, for example “T1w”, “T2w”, “FLAIR”, “anat”. The actual image contrast may or may not actually be representative of this as it is dependent on other parameters. Output BIDS files are names according to this field. Defaults to
"anat"
.
Series Type: Ground Truth¶
The ground truth pipeline simply resamples the input ground truth images to a specified resolution. Individual NIFTI images are output for each ground truth quantity in the input image.
All parameters have defaults if omitted; the default parameters result no motion and a resampled matrix of [64, 64, 40].
Images generated by the Ground Truth pipeline will be stored in a subdirectory names “ground_truth”.
Single value parameters¶
The following parameters are applied to every volume that is generated by the DRO.
- acq_matrix
(array of integers, optional) A 3-entry array defining the acquisition matrix size [Ni, Nj, Nk]. Defaults to
[197, 233, 189]
.- rot_z
(float, optional) Rotation of the ground truth model in world space about the z-axis in degrees. See
TransformResampleImageFilter
for implementation details. Defaults to0.0
.- rot_y
(float, optional) Rotation of the ground truth model in world space about the y-axis in degrees. Defaults to
0.0
.- rot_x
(float, optional) Rotation of the ground truth model in world space about the x-axis in degrees. Defaults to
0.0
.- transl_x
(float, optional) Translation of the ground truth model in world space along the x-axis in mm. Defaults to``0.0``.
- transl_y
(float, optional) Translation of the ground truth model in world space along the y-axis in mm. Defaults to
0.0
.- transl_z
(float, optional) Translation of the ground truth model in world space along the z-axis in mm. Defaults to
0.0
.- interpolation
(array of strings, optional) The type of interpolation to use when resampling the ‘acquired’ image. The first entry defines the type of interpolation for all ground truth volumes except for the
"seg_label"
volume. The second entry is the interpolation type for the"seg_label"
volume. See :class:’.ResampleFilter’ for implementation details. Each entry can be:- ‘continuous’
order 3 spline interpolation
- ‘linear’
order 1 linear interpolation
- ‘nearest’
nearest neighbour interpolation
Default value is
["linear", "nearest"]