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}, where n 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 set parameter_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 (see asldro.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 for series_type “structural”. Each series_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 of signal_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:

  1. control, PLD = 0.00s

  2. label, PLD = 0.00s

  3. control, PLD = 0.25s

  4. label, PLD = 0.25s

  5. control, PLD = 0.50s

  6. 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 to 3.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 see GkmFilter.

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 to 1000.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 then sat_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 to 0.0 for every entry in asl_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 in asl_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 in asl_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 in asl_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 in asl_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 in asl_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 and repetition_time have values that are defined for the types of entries in asl_context, and arrays of these values are constructed accordingly.

  • The rotation and translation (rot_* and transl_*) 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 and uniform 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 to 100.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 to 0.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 to 0.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"]