diff --git a/mkdocs.yml b/mkdocs.yml index 5219216eeb..d773db36a5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -51,6 +51,7 @@ nav: - Entities: 99-appendices/09-entities.md - File collections: 99-appendices/10-file-collections.md - Quantitative MRI: 99-appendices/11-qmri.md + - Arterial Spin Labeling: 99-appendices/12-arterial-spin-labeling.md - Changelog: CHANGES.md - The BIDS Starter Kit: - GitHub repository: https://github.com/bids-standard/bids-starter-kit diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md index f876857dd4..aa7f3cee75 100644 --- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md +++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md @@ -10,21 +10,21 @@ by Ben Inglis: ### Scanner Hardware -| **Key name** | **Requirement level** | **Data type** | **Description** | -|-------------------------------|-----------------------|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Manufacturer | RECOMMENDED | [string][] | Manufacturer of the equipment that produced the composite instances. Corresponds to DICOM Tag 0008, 0070 `Manufacturer` | -| ManufacturersModelName | RECOMMENDED | [string][] | Manufacturer's model name of the equipment that produced the composite instances. Corresponds to DICOM Tag 0008, 1090 `Manufacturers Model Name` | -| DeviceSerialNumber | RECOMMENDED | [string][] | The serial number of the equipment that produced the composite instances. Corresponds to DICOM Tag 0018, 1000 `DeviceSerialNumber`. A pseudonym can also be used to prevent the equipment from being identifiable, so long as each pseudonym is unique within the dataset | -| StationName | RECOMMENDED | [string][] | Institution defined name of the machine that produced the composite instances. Corresponds to DICOM Tag 0008, 1010 `Station Name` | -| SoftwareVersions | RECOMMENDED | [string][] | Manufacturer's designation of software version of the equipment that produced the composite instances. Corresponds to DICOM Tag 0018, 1020 `Software Versions` | -| HardcopyDeviceSoftwareVersion | [DEPRECATED][] | [string][] | Manufacturer's designation of the software of the device that created this Hardcopy Image (the printer). Corresponds to DICOM Tag 0018, 101A `Hardcopy Device Software Version` | -| MagneticFieldStrength | RECOMMENDED | [number][] | Nominal field strength of MR magnet in Tesla. Corresponds to DICOM Tag 0018,0087 `Magnetic Field Strength` | -| ReceiveCoilName | RECOMMENDED | [string][] | Information describing the receiver coil. Corresponds to DICOM Tag 0018, 1250 `Receive Coil Name`, although not all vendors populate that DICOM Tag, in which case this field can be derived from an appropriate private DICOM field | -| ReceiveCoilActiveElements | RECOMMENDED | [string][] | Information describing the active/selected elements of the receiver coil. This doesn't correspond to a tag in the DICOM ontology. The vendor-defined terminology for active coil elements can go in this field. See an example below the table. | -| GradientSetType | RECOMMENDED | [string][] | It should be possible to infer the gradient coil from the scanner model. If not, for example because of a custom upgrade or use of a gradient insert set, then the specifications of the actual gradient coil should be reported independently | -| MRTransmitCoilSequence | RECOMMENDED | [string][] | This is a relevant field if a non-standard transmit coil is used. Corresponds to DICOM Tag 0018, 9049 `MR Transmit Coil Sequence` | -| MatrixCoilMode | RECOMMENDED | [string][] | (If used) A method for reducing the number of independent channels by combining in analog the signals from multiple coil elements. There are typically different default modes when using un-accelerated or accelerated (for example, GRAPPA, SENSE) imaging | -| CoilCombinationMethod | RECOMMENDED | [string][] | Almost all fMRI studies using phased-array coils use root-sum-of-squares (rSOS) combination, but other methods exist. The image reconstruction is changed by the coil combination method (as for the matrix coil mode above), so anything non-standard should be reported | +| **Key name** | **Requirement level** | **Data type** | **Description** | +|-------------------------------|------------------------------------------------------|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Manufacturer | RECOMMENDED | [string][] | Manufacturer of the equipment that produced the composite instances. Corresponds to DICOM Tag 0008, 0070 `Manufacturer` | +| ManufacturersModelName | RECOMMENDED | [string][] | Manufacturer's model name of the equipment that produced the composite instances. Corresponds to DICOM Tag 0008, 1090 `Manufacturers Model Name` | +| DeviceSerialNumber | RECOMMENDED | [string][] | The serial number of the equipment that produced the composite instances. Corresponds to DICOM Tag 0018, 1000 `DeviceSerialNumber`. A pseudonym can also be used to prevent the equipment from being identifiable, so long as each pseudonym is unique within the dataset | +| StationName | RECOMMENDED | [string][] | Institution defined name of the machine that produced the composite instances. Corresponds to DICOM Tag 0008, 1010 `Station Name` | +| SoftwareVersions | RECOMMENDED | [string][] | Manufacturer's designation of software version of the equipment that produced the composite instances. Corresponds to DICOM Tag 0018, 1020 `Software Versions` | +| HardcopyDeviceSoftwareVersion | [DEPRECATED][] | [string][] | Manufacturer's designation of the software of the device that created this Hardcopy Image (the printer). Corresponds to DICOM Tag 0018, 101A `Hardcopy Device Software Version` | +| MagneticFieldStrength | RECOMMENDED, but REQUIRED for Arterial Spin Labeling | [number][] | Nominal field strength of MR magnet in Tesla. Corresponds to DICOM Tag 0018,0087 `Magnetic Field Strength` | +| ReceiveCoilName | RECOMMENDED | [string][] | Information describing the receiver coil. Corresponds to DICOM Tag 0018, 1250 `Receive Coil Name`, although not all vendors populate that DICOM Tag, in which case this field can be derived from an appropriate private DICOM field | +| ReceiveCoilActiveElements | RECOMMENDED | [string][] | Information describing the active/selected elements of the receiver coil. This doesn't correspond to a tag in the DICOM ontology. The vendor-defined terminology for active coil elements can go in this field. See an example below the table. | +| GradientSetType | RECOMMENDED | [string][] | It should be possible to infer the gradient coil from the scanner model. If not, for example because of a custom upgrade or use of a gradient insert set, then the specifications of the actual gradient coil should be reported independently | +| MRTransmitCoilSequence | RECOMMENDED | [string][] | This is a relevant field if a non-standard transmit coil is used. Corresponds to DICOM Tag 0018, 9049 `MR Transmit Coil Sequence` | +| MatrixCoilMode | RECOMMENDED | [string][] | (If used) A method for reducing the number of independent channels by combining in analog the signals from multiple coil elements. There are typically different default modes when using un-accelerated or accelerated (for example, GRAPPA, SENSE) imaging | +| CoilCombinationMethod | RECOMMENDED | [string][] | Almost all fMRI studies using phased-array coils use root-sum-of-squares (rSOS) combination, but other methods exist. The image reconstruction is changed by the coil combination method (as for the matrix coil mode above), so anything non-standard should be reported | Example for `ReceiveCoilActiveElements`: @@ -52,6 +52,7 @@ that a given scan was collected with the intended coil elements selected | SequenceName | RECOMMENDED | [string][] | Manufacturer's designation of the sequence name. Corresponds to DICOM Tag 0018, 0024 `Sequence Name`. | | PulseSequenceDetails | RECOMMENDED | [string][] | Information beyond pulse sequence type that identifies the specific pulse sequence used (for example, "Standard Siemens Sequence distributed with the VB17 software," "Siemens WIP ### version #.##," or "Sequence written by X using a version compiled on MM/DD/YYYY"). | | NonlinearGradientCorrection | RECOMMENDED | [boolean][] | Boolean stating if the image saved has been corrected for gradient nonlinearities by the scanner sequence. | +| MRAcquisitionType | RECOMMENDED, but REQUIRED for Arterial Spin Labeling | [string][] | Possible values: `2D` or `3D`. Type of sequence readout. Corresponds to DICOM Tag 0018,0023 `MR Acquisition Type`. | | MTState | RECOMMENDED | [boolean][] | Boolean stating whether the magnetization transfer pulse is applied. Corresponds to DICOM tag (0018, 9020) `Magnetization Transfer`. | | MTOffsetFrequency | RECOMMENDED if the MTstate is `True`. | [number][] | The frequency offset of the magnetization transfer pulse with respect to the central H1 Larmor frequency in Hertz (Hz). | | MTPulseBandwidth | RECOMMENDED if the MTstate is `True`. | [number][] | The excitation bandwidth of the magnetization transfer pulse in Hertz (Hz). | @@ -90,20 +91,20 @@ and the center of the last "effective" echo, sometimes called the "FSL definitio ### Timing Parameters -| **Key name** | **Requirement level** | **Data type** | **Description** | -|------------------------|------------------------------------------------------------------------------------------------------------------|--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| EchoTime | RECOMMENDED, but REQUIRED if corresponding fieldmap data is present or the data comes from a multi echo sequence | [number][] | The echo time (TE) for the acquisition, specified in seconds. Corresponds to DICOM Tag 0018, 0081 `Echo Time` (please note that the DICOM term is in milliseconds not seconds). | -| InversionTime | RECOMMENDED | [number][] | The inversion time (TI) for the acquisition, specified in seconds. Inversion time is the time after the middle of inverting RF pulse to middle of excitation pulse to detect the amount of longitudinal magnetization. Corresponds to DICOM Tag 0018, 0082 `Inversion Time` (please note that the DICOM term is in milliseconds not seconds). | -| SliceTiming | RECOMMENDED, but REQUIRED for sparse sequences that do not have the `DelayTime` field set | [array][] of [numbers][] | The time at which each slice was acquired within each volume (frame) of the acquisition. Slice timing is not slice order -- rather, it is a list of times containing the time (in seconds) of each slice acquisition in relation to the beginning of volume acquisition. The list goes through the slices along the slice axis in the slice encoding dimension (see below). Note that to ensure the proper interpretation of the `SliceTiming` field, it is important to check if the OPTIONAL `SliceEncodingDirection` exists. In particular, if `SliceEncodingDirection` is negative, the entries in `SliceTiming` are defined in reverse order with respect to the slice axis, such that the final entry in the `SliceTiming` list is the time of acquisition of slice 0. Without this parameter slice time correction will not be possible. | -| SliceEncodingDirection | RECOMMENDED | [string][] | Possible values: `i`, `j`, `k`, `i-`, `j-`, `k-` (the axis of the NIfTI data along which slices were acquired, and the direction in which `SliceTiming` is defined with respect to). `i`, `j`, `k` identifiers correspond to the first, second and third axis of the data in the NIfTI file. A `-` sign indicates that the contents of `SliceTiming` are defined in reverse order - that is, the first entry corresponds to the slice with the largest index, and the final entry corresponds to slice index zero. When present, the axis defined by `SliceEncodingDirection` needs to be consistent with the ‘slice_dim' field in the NIfTI header. When absent, the entries in `SliceTiming` must be in the order of increasing slice index as defined by the NIfTI header. | -| DwellTime | RECOMMENDED | [number][] | Actual dwell time (in seconds) of the receiver per point in the readout direction, including any oversampling. For Siemens, this corresponds to DICOM field (0019,1018) (in ns). This value is necessary for the optional readout distortion correction of anatomicals in the HCP Pipelines. It also usefully provides a handle on the readout bandwidth, which isn't captured in the other metadata tags. Not to be confused with `EffectiveEchoSpacing`, and the frequent mislabeling of echo spacing (which is spacing in the phase encoding direction) as "dwell time" (which is spacing in the readout direction). | +| **Key name** | **Requirement level** | **Data type** | **Description** | +|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| EchoTime | RECOMMENDED, but REQUIRED if corresponding fieldmap data is present, or the data comes from a multi echo sequence or Arterial Spin Labeling | [number][] or [array][] of [numbers][] | The echo time (TE) for the acquisition, specified in seconds. Corresponds to DICOM Tag 0018, 0081 Echo Time (please note that the DICOM term is in milliseconds not seconds). The data type number may apply to files from any MRI modality concerned with a single value for this field, or to the files in a [file collection](../99-appendices/10-file-collections.md) where the value of this field is iterated using the [echo entity](../99-appendices/09-entities.md#echo). The data type array provides a value for each volume in a 4D dataset and should only be used when the volume timing is critical for interpretation of the data, such as in [ASL](#arterial-spin-labeling-perfusion-data) or variable echo time fMRI sequences. | +| InversionTime | RECOMMENDED | [number][] | The inversion time (TI) for the acquisition, specified in seconds. Inversion time is the time after the middle of inverting RF pulse to middle of excitation pulse to detect the amount of longitudinal magnetization. Corresponds to DICOM Tag 0018, 0082 `Inversion Time` (please note that the DICOM term is in milliseconds not seconds). | +| SliceTiming | RECOMMENDED, but REQUIRED for sparse sequences that do not have the `DelayTime` field set, and Arterial Spin Labeling with `MRAcquisitionType` set on `2D`. | [array][] of [numbers][] | The time at which each slice was acquired within each volume (frame) of the acquisition. Slice timing is not slice order -- rather, it is a list of times containing the time (in seconds) of each slice acquisition in relation to the beginning of volume acquisition. The list goes through the slices along the slice axis in the slice encoding dimension (see below). Note that to ensure the proper interpretation of the `SliceTiming` field, it is important to check if the OPTIONAL `SliceEncodingDirection` exists. In particular, if `SliceEncodingDirection` is negative, the entries in `SliceTiming` are defined in reverse order with respect to the slice axis, such that the final entry in the `SliceTiming` list is the time of acquisition of slice 0. Without this parameter slice time correction will not be possible. | +| SliceEncodingDirection | RECOMMENDED | [string][] | Possible values: `i`, `j`, `k`, `i-`, `j-`, `k-` (the axis of the NIfTI data along which slices were acquired, and the direction in which `SliceTiming` is defined with respect to). `i`, `j`, `k` identifiers correspond to the first, second and third axis of the data in the NIfTI file. A `-` sign indicates that the contents of `SliceTiming` are defined in reverse order - that is, the first entry corresponds to the slice with the largest index, and the final entry corresponds to slice index zero. When present, the axis defined by `SliceEncodingDirection` needs to be consistent with the ‘slice_dim' field in the NIfTI header. When absent, the entries in `SliceTiming` must be in the order of increasing slice index as defined by the NIfTI header. | +| DwellTime | RECOMMENDED | [number][] | Actual dwell time (in seconds) of the receiver per point in the readout direction, including any oversampling. For Siemens, this corresponds to DICOM field (0019,1018) (in ns). This value is necessary for the optional readout distortion correction of anatomicals in the HCP Pipelines. It also usefully provides a handle on the readout bandwidth, which isn't captured in the other metadata tags. Not to be confused with `EffectiveEchoSpacing`, and the frequent mislabeling of echo spacing (which is spacing in the phase encoding direction) as "dwell time" (which is spacing in the readout direction). | ### RF & Contrast -| **Key name** | **Requirement level** | **Data type** | **Description** | -| --------------------------- | --------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| FlipAngle | RECOMMENDED | [number][] | Flip angle for the acquisition, specified in degrees. Corresponds to: DICOM Tag 0018, 1314 `Flip Angle`. | -| NegativeContrast | OPTIONAL | [boolean][] | `true` or `false` value specifying whether increasing voxel intensity (within sample voxels) denotes a decreased value with respect to the contrast suffix. This is commonly the case when Cerebral Blood Volume is estimated via usage of a contrast agent in conjunction with a T2\* weighted acquisition protocol. | +| **Key name** | **Requirement level** | **Data type** | **Description** | +|------------------|---------------------------------------------------------|----------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| FlipAngle | RECOMMENDED, but REQUIRED if `LookLocker` is set `true` | [number][] or [array][] of [numbers][] | Flip angle (FA) for the acquisition, specified in degrees. Corresponds to: DICOM Tag 0018, 1314 `Flip Angle`. The data type number may apply to files from any MRI modality concerned with a single value for this field, or to the files in a [file collection](../99-appendices/10-file-collections.md) where the value of this field is iterated using the [flip entity](../99-appendices/09-entities.md#flip). The data type array provides a value for each volume in a 4D dataset and should only be used when the volume timing is critical for interpretation of the data, such as in [ASL](#arterial-spin-labeling-perfusion-data) or variable flip angle fMRI sequences. | +| NegativeContrast | OPTIONAL | [boolean][] | `true` or `false` value specifying whether increasing voxel intensity (within sample voxels) denotes a decreased value with respect to the contrast suffix. This is commonly the case when Cerebral Blood Volume is estimated via usage of a contrast agent in conjunction with a T2\* weighted acquisition protocol. | ### Slice Acceleration @@ -680,6 +681,149 @@ JSON example: } ``` +## Arterial Spin Labeling perfusion data + +Template: + +```Text +sub-