MR Data described in the following sections share the following RECOMMENDED metadata fields (stored in sidecar JSON files). MRI acquisition parameters are divided into several categories based on "A checklist for fMRI acquisition methods reporting in the literature" (article) by Ben Inglis.
When adding additional metadata please use the CamelCase version of DICOM ontology terms whenever possible. See also recommendations on JSON files.
{{ MACROS___make_sidecar_table("mri.MRIHardware") }}
Example for ReceiveCoilActiveElements:
For Siemens, coil channels are typically not activated/selected individually,
but rather in pre-defined selectable "groups" of individual channels,
and the list of the "groups" of elements that are active/selected in any
given scan populates the Coil String entry in Siemens' private DICOM fields
(for example, HEA;HEP for the Siemens standard 32 ch coil
when both the anterior and posterior groups are activated).
This is a flexible field that can be used as most appropriate for a given
vendor and coil to define the "active" coil elements.
Since individual scans can sometimes not have the intended coil elements selected,
it is preferable for this field to be populated directly from the DICOM
for each individual scan, so that it can be used as a mechanism for checking
that a given scan was collected with the intended coil elements selected.
{{ MACROS___make_sidecar_table("mri.MRIInstitutionInformation") }}
{{ MACROS___make_sidecar_table("mri.MRISequenceSpecifics") }}
{{ MACROS___make_sidecar_table(["mri.MRISpatialEncoding", "mri.PhaseEncodingDirectionRec"]) }}
2Conveniently, for Siemens data, this value is easily obtained as
1 / (BWPPPE * ReconMatrixPE), where BWPPPE is the
"BandwidthPerPixelPhaseEncode" in DICOM Tag 0019, 1028 and ReconMatrixPE is
the size of the actual reconstructed data in the phase direction (which is NOT
reflected in a single DICOM Tag for all possible aforementioned scan
manipulations). See
Acquiring and using field maps - LCNI
and TotalReadoutTime - dcm_qa.
3We use the time between the center of the first "effective" echo and the center of the last "effective" echo, sometimes called the "FSL definition".
{{ MACROS___make_sidecar_table(["mri.MRITimingParameters", "mri.SliceTimingMRI"]) }}
{{ MACROS___make_sidecar_table(["mri.MRIFlipAngleLookLockerFalse", "mri.MRIRFandContrast" ]) }}
{{ MACROS___make_sidecar_table("mri.MRISliceAcceleration") }}
Useful for multimodal co-registration with MEG, (S)EEG, TMS, and so on.
{{ MACROS___make_sidecar_table("mri.MRIAnatomicalLandmarks") }}
Echo-Planar Imaging (EPI) schemes typically used in the acquisition of
diffusion and functional MRI may also be intended for estimating the
B0 field nonuniformity inside the scanner (in other words,
mapping the field) without the acquisition of additional MRI schemes
such as gradient-recalled echo (GRE) sequences that are stored under the
fmap/ directory of the BIDS structure.
The modality labels dwi (under dwi/), bold (under func/),
asl (under perf/), sbref (under dwi/, func/ or perf/), and
any modality under fmap/ are allowed to encode the MR protocol intent for
fieldmap estimation using the following metadata:
{{ MACROS___make_sidecar_table([ "mri.MRIB0FieldIdentifier", "mri.MRIEchoPlanarImagingAndB0FieldSource", ]) }}
{{ MACROS___make_sidecar_table("mri.MRISample") }}
Anatomy MRI sequences measure static, structural features of the brain.
This datatype is divided into two groups: non-parametric and parametric.
Non-parametric structural images have an arbitrary scale. For example, T1w data are T1-weighted, but the values do not correspond to actual T1 value estimates.
Parametric structural imaging, on the other hand, use a non-arbitrary scale. For example, a T1map file contains T1 value estimates, in seconds.
{{ MACROS___make_filename_template("raw", datatypes=["anat"], suffixes=[ "T1w", "T2w", "PDw", "T2starw", "FLAIR", "inplaneT1", "inplaneT2", "PDT2", "UNIT1", "angio", ]) }}
Currently supported non-parametric structural MR images include the following:
{{ MACROS___make_suffix_table( [ "T1w", "T2w", "PDw", "T2starw", "FLAIR", "inplaneT1", "inplaneT2", "PDT2", "UNIT1", "angio", ] ) }}
The part-<label> entity is
used to indicate which component of the complex representation of the MRI
signal is represented in voxel data.
This entity is associated with the DICOM Tag 0008, 9208.
Allowed label values for this entity are phase, mag, real and imag,
which are typically used in part-mag/part-phase or part-real/part-imag
pairs of files.
For example:
{{ MACROS___make_filetree_example( { "sub-01": { "anat": { "sub-01_part-mag_T1w.nii.gz": "", "sub-01_part-mag_T1w.json": "", "sub-01_part-phase_T1w.nii.gz": "", "sub-01_part-phase_T1w.json": "", }, } } ) }}
Phase images MAY be in radians or in arbitrary units.
The sidecar JSON file MUST include the units of the phase image.
The possible options are rad or arbitrary.
For example, for sub-01_part-phase_T1w.json:
{
"Units": "rad"
}
When there is only a magnitude image of a given type, the part entity MAY be omitted.
Structural MR images whose intensity is represented in a non-arbitrary scale constitute parametric maps.
{{ MACROS___make_filename_template("raw", datatypes=["anat"], suffixes=[ "T1map", "R1map", "T2map", "R2map", "T2starmap", "R2starmap", "PDmap", "MTRmap", "MTsat", "T1rho", "MWFmap", "MTVmap", "Chimap", "TB1map", "RB1map", "S0map", "M0map", ]) }}
Parametric images listed in the table below are typically generated by processing a file collection. Please visit the file collections appendix to see the list of suffixes available for quantitative MRI (qMRI) applications associated with these maps (for example, MPM, MP2RAGE, and MTR).
Currently supported parametric maps include:
{{ MACROS___make_suffix_table( [ "T1map", "R1map", "T2map", "R2map", "T2starmap", "R2starmap", "PDmap", "MTRmap", "MTsat", "T1rho", "MWFmap", "MTVmap", "Chimap", "TB1map", "RB1map", "S0map", "M0map", ] ) }}
For any other details on the organization of parametric maps, their recommended metadata fields, and the application specific entity or metadata requirement levels of file collections that can generate them, visit the qMRI appendix.
If the structural images included in the dataset were defaced (to protect
identity of participants) one MAY provide the binary mask that was used to
remove facial features in the form of _defacemask files.
In such cases, the OPTIONAL mod-<label>
entity corresponds to modality suffix,
such as T1w or inplaneT1, referenced by the defacemask image.
For example, sub-01_mod-T1w_defacemask.nii.gz.
{{ MACROS___make_filename_template("raw", datatypes=["anat"], suffixes=[ "defacemask", ]) }}
The OPTIONAL task-<label> entity can be used
in order to allow tasks during structural MR acquisitions,
for example pre-described motion paradigms such as nodding, to be described.
{{ MACROS___make_sidecar_table("anat.TaskMetadata") }}
Some meta information about the acquisition MAY be provided in an additional JSON file. See Common metadata fields for a list of terms and their definitions. There are also some OPTIONAL JSON fields specific to anatomical scans:
{{ MACROS___make_sidecar_table("anat.MRIAnatomyCommonMetadataFields") }}
Some suffixes that were available in versions of the specification prior to 1.5.0 have been deprecated. These suffixes are ambiguous and have been superseded by more precise conventions. Therefore, they are not recommended for use in new datasets. They are, however, still valid suffixes, to maintain backwards compatibility.
The following suffixes are valid, but SHOULD NOT be used for new BIDS compatible datasets (created after version 1.5.0.):
{{ MACROS___make_suffix_table( [ "T2star", "FLASH", "PD", ] ) }}
Currently supported image contrasts include:
{{ MACROS___make_suffix_table( [ "bold", "cbv", "phase", ] ) }}
{{ MACROS___make_filename_template("raw", datatypes=["func"]) }}
Functional imaging consists of techniques that support rapid temporal repetition.
This includes, but is not limited to, task based fMRI, as well as resting state fMRI, which is treated like any other task.
For task based fMRI, a corresponding task events file (see below) MUST be provided
(please note that this file is not necessary for resting state scans).
For multiband acquisitions, one MAY also save the single-band reference image with the sbref suffix
(for example, sub-control01_task-nback_sbref.nii.gz).
Multi-echo data MUST be split into one file per echo using the
echo-<index> entity. For example:
{{ MACROS___make_filetree_example( { "sub-01": { "func": { "sub-01_task-cuedSGT_run-1_echo-1_bold.nii.gz": "", "sub-01_task-cuedSGT_run-1_echo-1_bold.json": "", "sub-01_task-cuedSGT_run-1_echo-2_bold.nii.gz": "", "sub-01_task-cuedSGT_run-1_echo-2_bold.json": "", "sub-01_task-cuedSGT_run-1_echo-3_bold.nii.gz": "", "sub-01_task-cuedSGT_run-1_echo-3_bold.json": "", }, } } ) }}
Please note that the <index> denotes the number/index (in the form of a
nonnegative integer) of the echo not the echo time value which needs to be stored in the
field EchoTime of the separate JSON file.
Complex-valued data MUST be split into one file for each data type.
For BOLD data, there are separate suffixes for magnitude (_bold) and phase
(_phase) data, but the _phase suffix is deprecated.
Newly generated datasets SHOULD NOT use the _phase suffix, and the suffix will be removed
from the specification in the next major release.
For backwards compatibility, _phase is considered equivalent to _part-phase_bold.
When the _phase suffix is not used, each file shares the same
name with the exception of the part-<mag|phase> or part-<real|imag> entity.
For example:
{{ MACROS___make_filetree_example( { "sub-01": { "func": { "sub-01_task-cuedSGT_part-mag_bold.nii.gz": "", "sub-01_task-cuedSGT_part-mag_bold.json": "", "sub-01_task-cuedSGT_part-phase_bold.nii.gz": "", "sub-01_task-cuedSGT_part-phase_bold.json": "", "sub-01_task-cuedSGT_part-mag_sbref.nii.gz": "", "sub-01_task-cuedSGT_part-mag_sbref.json": "", "sub-01_task-cuedSGT_part-phase_sbref.nii.gz": "", "sub-01_task-cuedSGT_part-phase_sbref.json": "", }, }, } ) }}
Some meta information about the acquisition MUST be provided in an additional JSON file.
{{ MACROS___make_sidecar_table([ "func.MRIFuncRepetitionTime", "func.MRIFuncVolumeTiming", "func.MRIFuncRequired", ]) }}
For the fields described above and in the following section, the term "Volume" refers to a reconstruction of the object being imaged (for example, brain or part of a brain). In case of multiple channels in a coil, the term "Volume" refers to a combined image rather than an image from each coil.
{{ MACROS___make_sidecar_table("func.MRIFuncTimingParameters") }}
The following table recapitulates the different ways that specific fields have to be populated for functional sequences. Note that all these options can be used for non sparse sequences but that only options B, D and E are valid for sparse sequences.
RepetitionTime |
SliceTiming |
AcquisitionDuration |
DelayTime |
VolumeTiming |
|
|---|---|---|---|---|---|
| option A | [ X ] | [ ] | [ ] | ||
| option B | [ ] | [ X ] | [ ] | [ X ] | |
| option C | [ ] | [ X ] | [ ] | [ X ] | |
| option D | [ X ] | [ X ] | [ ] | [ ] | |
| option E | [ X ] | [ ] | [ X ] | [ ] |
Legend
- [ X ] --> MUST be defined
- [ ] --> MUST NOT be defined
- empty cell --> MAY be specified
{{ MACROS___make_sidecar_table("func.MRIFuncTaskInformation") }}
See Common metadata fields for a list of additional terms and their definitions.
Example:
{{ MACROS___make_filetree_example( { "sub-01": { "func": { "sub-01_task-nback_bold.json": "", }, } } ) }}
{
"TaskName": "N Back",
"RepetitionTime": 0.8,
"EchoTime": 0.03,
"FlipAngle": 78,
"SliceTiming": [0.0, 0.2, 0.4, 0.6, 0.0, 0.2, 0.4, 0.6, 0.0, 0.2, 0.4, 0.6, 0.0, 0.2, 0.4, 0.6],
"MultibandAccelerationFactor": 4,
"ParallelReductionFactorInPlane": 2,
"PhaseEncodingDirection": "j",
"InstitutionName": "Stanford University",
"InstitutionAddress": "450 Serra Mall, Stanford, CA 94305-2004, USA",
"DeviceSerialNumber": "11035",
"B0FieldSource": ["phasediff_fmap0", "pepolar_fmap0"]
}!!! example "Example datasets"
Several [example datasets](https://github.com/bids-standard/bids-examples)
contain diffusion imaging data formatted using this specification
and that can be used for practical guidance when curating a new dataset:
- [`genetics_ukbb`](https://github.com/bids-standard/bids-examples/tree/master/genetics_ukbb)
- [`eeg_rest_fmri`](https://github.com/bids-standard/bids-examples/tree/master/eeg_rest_fmri)
- [`ds114`](https://github.com/bids-standard/bids-examples/tree/master/ds114)
- [`ds000117`](https://github.com/bids-standard/bids-examples/tree/master/ds000117)
Diffusion-weighted imaging data acquired for a participant. Currently supported image types include:
{{ MACROS___make_suffix_table(["dwi", "sbref"]) }}
Additionally, the following suffixes are used for scanner-generated images:
{{ MACROS___make_suffix_table(["ADC", "TRACE"]) }}
{{ MACROS___make_filename_template("raw", datatypes=["dwi"]) }}
The run-<index> entity is RECOMMENDED
to encode the splits of multipart DWI scans
(see below for more information on multipart DWI schemes).
Combining multi- and single-band acquisitions.
The single-band reference image MAY be stored with suffix sbref (for example,
dwi/sub-control01_sbref.nii[.gz]) as long as the image has no corresponding
gradient information ([*_]dwi.bval and [*_]dwi.bvec sidecar files)
to be stored.
Otherwise, if some gradient information is associated to the single-band diffusion
image and a multi-band diffusion image also exists, the acq-<label> entity
MUST be used to distinguish both images.
In such a case, two files could have the following names:
sub-01_acq-singleband_dwi.nii.gz and sub-01_acq-multiband_dwi.nii.gz.
The user is free to choose any other label than singleband and
multiband, as long as they are consistent across subjects and sessions.
Scanner-generated TRACE and ADC volumes MAY be included using the
TRACE and ADC suffixes.
If TRACE or ADC volume filenames match a diffusion series with all applicable entities,
such volumes SHOULD be computed from that series.
Otherwise, some entity, such as acq-<label>,
SHOULD be used to indicate that the files are unrelated.
The REQUIRED gradient orientation information corresponding to a DWI acquisition
MUST be stored using [*_]dwi.bval and [*_]dwi.bvec pairs of files.
The [*_]dwi.bval and [*_]dwi.bvec files MAY be saved on any level of the directory structure
and thus define those values for all sessions and/or subjects in one place (see
the inheritance principle).
As an exception to the common principles
that parameters are constant across runs, the gradient table information (stored
within the [*_]dwi.bval and [*_]dwi.bvec files) MAY change across DWI runs.
Gradient orientation file formats.
The [*_]dwi.bval and [*_]dwi.bvec files MUST follow the
FSL format:
The [*_]dwi.bvec file contains 3 rows with N space-delimited floating-point numbers
(corresponding to the N volumes in the corresponding NIfTI file.)
The first row contains the x elements, the second row contains the y elements and
the third row contains the z elements of a unit vector in the direction of the applied
diffusion gradient, where the i-th elements in each row correspond together to
the i-th volume, with [0,0,0] for non-diffusion-weighted (also called b=0 or low-b)
volumes.
Following the FSL format for the [*_]dwi.bvec specification, the coordinate system of
the b vectors MUST be defined with respect to the coordinate system defined by
the header of the corresponding _dwi NIfTI file and not the scanner's device
coordinate system (see Coordinate systems).
The most relevant limitation imposed by this choice is that the gradient information cannot
be directly stored in this format if the scanner generates b-vectors in scanner coordinates.
Example of [*_]dwi.bvec file, with N=6, with two b=0 volumes in the beginning:
0 0 0.021828 -0.015425 -0.70918 -0.2465
0 0 0.80242 0.22098 -0.00063106 0.1043
0 0 -0.59636 0.97516 -0.70503 -0.96351
The [*_]dwi.bval file contains the b-values (in s/mm2) corresponding to the
volumes in the relevant NIfTI file), with 0 designating b=0 volumes, space-delimited.
Example of [*_]dwi.bval file, corresponding to the previous [*_]dwi.bvec example:
0 0 2000 2000 1000 1000
Some MR schemes cannot be acquired directly by some scanner devices, requiring to generate several DWI runs that were originally meant to belong in a single one. For instance, some GE scanners cannot collect more than ≈160 volumes in a single run under fast-changing gradients, so acquiring HCP-style diffusion images will require splitting the DWI scheme in several runs. Because researchers will generally optimize the data splits, these will likely not be able to be directly concatenated. BIDS permits defining arbitrary groupings of these multipart scans with the following metadata:
{{ MACROS___make_sidecar_table("dwi.MRIDiffusionMultipart") }}
JSON example:
{
"MultipartID": "dwi_1"
}For instance, if there are two phase-encoding directions (AP, PA), and
two runs each, and the intent of the researcher is that all of them are
part of a unique multipart scan, then they will tag all four runs with the
same MultipartID (shown at the right-hand side of the file listing):
{{ MACROS___make_filetree_example( { "sub-1": { "dwi # MultipartID": { "sub-1_dir-AP_run-1_dwi.nii.gz": " # dwi_1", "sub-1_dir-AP_run-2_dwi.nii.gz": " # dwi_1", "sub-1_dir-PA_run-1_dwi.nii.gz": " # dwi_1", "sub-1_dir-PA_run-2_dwi.nii.gz": " # dwi_1", } } } ) }}
If, conversely, the researcher wanted to store two multipart scans, one possibility is to combine matching phase-encoding directions:
{{ MACROS___make_filetree_example( { "sub-1": { "dwi # MultipartID":{ "sub-1_dir-AP_run-1_dwi.nii.gz": " # dwi_1", "sub-1_dir-AP_run-2_dwi.nii.gz": " # dwi_1", "sub-1_dir-PA_run-1_dwi.nii.gz": " # dwi_2", "sub-1_dir-PA_run-2_dwi.nii.gz": " # dwi_2", }, } } ) }}
Alternatively, the researcher's intent could be combining opposed phase-encoding runs instead:
{{ MACROS___make_filetree_example( { "sub-1": { "dwi # MultipartID":{ "sub-1_dir-AP_run-1_dwi.nii.gz": " # dwi_1", "sub-1_dir-AP_run-2_dwi.nii.gz": " # dwi_2", "sub-1_dir-PA_run-1_dwi.nii.gz": " # dwi_1", "sub-1_dir-PA_run-2_dwi.nii.gz": " # dwi_2", }, } } ) }}
The MultipartID metadata MAY be used with the
acq-<label> entity, for example:
{{ MACROS___make_filetree_example( { "sub-1": { "dwi # MultipartID":{ "sub-1_acq-shell1_run-1_dwi.nii.gz": " # dwi_1", "sub-1_acq-shell1_run-2_dwi.nii.gz": " # dwi_2", "sub-1_acq-shell2_run-1_dwi.nii.gz": " # dwi_1", "sub-1_acq-shell2_run-2_dwi.nii.gz": " # dwi_2", }, } } ) }}
The PhaseEncodingDirection and TotalReadoutTime metadata
fields are RECOMMENDED to enable the correction of geometrical distortions
with fieldmap information.
See Common metadata fields for a list of
additional terms that can be included in the corresponding JSON file.
JSON example:
{
"PhaseEncodingDirection": "j-",
"TotalReadoutTime": 0.095,
"B0FieldSource": ["phasediff_fmap0", "pepolar_fmap0"]
}!!! example "Example datasets"
Several [example ASL datasets](https://bids-standard.github.io/bids-examples/#asl)
have been formatted using this specification
and can be used for practical guidance when curating a new dataset.
{{ MACROS___make_filename_template("raw", datatypes=["perf"]) }}
The complete ASL time series should be stored as a 4D NIfTI file in the original acquisition order,
accompanied by two ancillary files: *_asl.json and *_aslcontext.tsv.
The *_aslcontext.tsv table consists of a single column of labels identifying the
volume_type of each volume in the corresponding *_asl.nii[.gz] file.
Volume types are defined in the following table, based on DICOM Tag 0018, 9257 ASL Context.
Note that the volume_types control and label within BIDS only serve
to specify the magnetization state of the blood and thus the ASL subtraction order.
See the ASL Appendix
for more information on control and label.
| volume_type | Definition |
|---|---|
| control | The control image is acquired in the exact same way as the label image, except that the magnetization of the blood flowing into the imaging region has not been inverted. |
| label | The label image is acquired in the exact same way as the control image, except that the blood magnetization flowing into the imaging region has been inverted. |
| m0scan | The M0 image is a calibration image, used to estimate the equilibrium magnetization of blood. |
| deltam | The deltaM image is a perfusion-weighted image, obtained by the subtraction of control - label. |
| cbf | The cerebral blood flow (CBF) image is produced by dividing the deltaM by the M0, quantified into mL/100g/min (See also doi:10.1002/mrm.25197). |
If the control and label images are not available,
their derivative deltam should be stored within the *_asl.nii[.gz]
and specified in the *_aslcontext.tsv instead.
If the deltam is not available,
cbf should be stored within the *_asl.nii[.gz] and specified in the *_aslcontext.tsv.
When cbf is stored within the *_asl.nii[.gz],
its units need to be specified in the *_asl.json as well.
Note that the raw images, including the m0scan, may also be used for quality control.
See the ASL Appendix
for examples of the three possible cases, in order of decreasing preference.
The *_asl.nii.gz and *_m0scan.nii.gz should contain appropriately scaled data,
and no additional scaling factors are allowed other than the scale slope in the respective
NIfTI headers.
A deidentified screenshot of the planning of the labeling slab/plane with respect to the imaging slab or slices. This screenshot is based on DICOM macro C.8.13.5.14.
See LabelingLocationDescription for more details.
The m0scan can either be stored inside the 4D ASL time-series NIfTI file
or as a separate NIfTI file,
depending on whether it was acquired within the ASL time-series or as a separate scan.
These and other M0 options are specified in the REQUIRED M0Type field of the *_asl.json file.
It can also be stored under
fmap/sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>]_dir-<label>[_run-<index>]_m0scan.nii[.gz],
when the pepolar approach is used.
Depending on the method used for ASL acquisition ((P)CASL or PASL)
different metadata fields are applicable.
Additionally, some common metadata fields are REQUIRED for the *_asl.json:
MagneticFieldStrength, MRAcquisitionType, EchoTime,
SliceTiming in case MRAcquisitionType is defined as 2D,
RepetitionTimePreparation, and FlipAngle in case LookLocker is true.
See the ASL Appendix
for more information on the most common ASL sequences.
{{ MACROS___make_sidecar_table(["asl.MRIASLCommonMetadataFields", "asl.MRIASLCommonMetadataFieldsM0TypeRec", "asl.MRIASLCommonMetadataFieldsBackgroundSuppressionOpt", "asl.MRIASLCommonMetadataFieldsVascularCrushingOpt", ]) }}
These fields can only be used when ArterialSpinLabelingType is "CASL" or "PCASL". See the ASL Appendix for more information on the (P)CASL sequence and the Labeling Pulse fields.
{{ MACROS___make_sidecar_table([ "asl.MRIASLPcaslSpecific", "asl.MRIASLCaslSpecific", "asl.MRIASLCaslPcaslSpecific", ]) }}
These fields can only be used when ArterialSpinLabelingType is PASL.
See the ASL Appendix
for more information on the PASL sequence and the BolusCutOff fields.
{{ MACROS___make_sidecar_table(["asl.MRIASLPaslSpecific", "asl.MRIASLPASLSpecificBolusCutOffFlagFalse"]) }}
Some common metadata fields are REQUIRED for the *_m0scan.json: EchoTime, RepetitionTimePreparation, and FlipAngle in case LookLocker is true.
{{ MACROS___make_sidecar_table("asl.MRIASLM0Scan") }}
The following table recapitulates the ASL field dependencies. If Source field (column 1) contains the Value specified in column 2, then the Requirements in column 4 are imposed on the Dependent fields in column 3. See the ASL Appendix for this information in the form of flowcharts.
| Source field | Value | Dependent field | Requirements |
|---|---|---|---|
| MRAcquisitionType | 2D / 3D | SliceTiming | [X] / [] |
| LookLocker | true | FlipAngle | [X] |
| ArterialSpinLabelingType | PCASL | LabelingDuration | [X] |
| ArterialSpinLabelingType | PASL | BolusCutOffFlag | [X] |
| BolusCutOffFlag | true / false | BolusCutOffDelayTime | [X] / [] |
| BolusCutOffFlag | true / false | BolusCutOffTechnique | [X] / [] |
| M0Type | Separate | */perf/ | contains *_m0scan.nii[.gz] and *_m0scan.json |
| M0Type | Included | *_aslcontext.tsv | contains m0scan |
| M0Type | Estimate | M0Estimate | [X] |
*_aslcontext.tsv |
cbf | Units | [X] |
Legend
- [ X ] --> MUST be defined
- [ ] --> MUST NOT be defined
Data acquired to correct for B0 inhomogeneities can come in different forms. The current version of this standard considers four different scenarios:
These four different types of field mapping strategies can be encoded using the following image types:
{{ MACROS___make_suffix_table( [ "magnitude", "magnitude1", "magnitude2", "phase1", "phase2", "phasediff", "fieldmap", "epi", ] ) }}
Fieldmaps are typically acquired with the purpose of correcting one or more EPI
scans under dwi/, func/, or perf/ for distortions derived from B0
nonuniformity.
The general purpose B0FieldIdentifier MRI metadata
is RECOMMENDED for the prescription of the B0 field estimation intent of the
original acquisition protocol.
B0FieldIdentifier and B0FieldSource duplicate the capabilities of
the original IntendedFor approach (see below), while permitting more
complex use cases.
It is RECOMMENDED to use both approaches to maintain compatibility with
tools that support older datasets.
Fieldmap data MAY be linked to the specific scan(s) it was acquired for by
filling the IntendedFor field in the corresponding JSON file.
{{ MACROS___make_sidecar_table("fmap.MRIFieldmapIntendedFor") }}
For example:
{
"IntendedFor": [
"bids::sub-01/ses-pre/func/sub-01_ses-pre_task-motor_run-1_bold.nii.gz",
"bids::sub-01/ses-pre/func/sub-01_ses-pre_task-motor_run-2_bold.nii.gz"
]
}!!! example "Example datasets"
[Example datasets](https://bids-standard.github.io/bids-examples/#dataset-index)
containing that type of fieldmap can be found here:
- [`7t_trt`](https://github.com/bids-standard/bids-examples/tree/master/7t_trt)
- [`genetics_ukbb`](https://github.com/bids-standard/bids-examples/tree/master/genetics_ukbb)
- [`ds000117`](https://github.com/bids-standard/bids-examples/tree/master/ds000117)
{{ MACROS___make_filename_template("raw", datatypes=["fmap"], suffixes=["phasediff", "magnitude1", "magnitude2"]) }}
where
the REQUIRED _phasediff image corresponds to the phase-drift map between echo times,
the REQUIRED _magnitude1 image corresponds to the shorter echo time, and
the OPTIONAL _magnitude2 image to the longer echo time.
Required fields:
{{ MACROS___make_sidecar_table("fmap.MRIFieldmapPhaseDifferencePhasediff") }}
In this particular case, the sidecar JSON file
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phasediff.json
MUST define the time of two echos used to map the phase and finally calculate
the phase-difference map.
For example:
{
"EchoTime1": 0.00600,
"EchoTime2": 0.00746,
"B0FieldIdentifier": "phasediff_fmap0"
}Similar to case 1, but instead of a precomputed phase-difference map, two separate phase images and two magnitude images corresponding to first and second echos are available.
{{ MACROS___make_filename_template("raw", datatypes=["fmap"], suffixes=["phase1", "phase2", "magnitude1", "magnitude2"]) }}
Required fields:
{{ MACROS___make_sidecar_table("fmap.MRIFieldmapTwoPhase") }}
Each phase map has a corresponding sidecar JSON file to specify its corresponding EchoTime.
For example, sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phase2.json may read:
{
"EchoTime": 0.00746,
"B0FieldIdentifier": "phases_fmap0"
}In some cases (for example GE), the scanner software will directly reconstruct a B0 field map along with a magnitude image used for anatomical reference.
{{ MACROS___make_filename_template("raw", datatypes=["fmap"], suffixes=["fieldmap", "magnitude"]) }}
Required fields:
{{ MACROS___make_sidecar_table("fmap.MRIFieldmapDirectFieldMapping") }}
For example:
{
"Units": "rad/s",
"IntendedFor": "bids::sub-01/func/sub-01_task-motor_bold.nii.gz",
"B0FieldIdentifier": "b0map_fmap0"
}See Using IntendedFor metadata
for details on the IntendedFor field.
!!! example "Example datasets"
An [example dataset](https://github.com/bids-standard/bids-examples)
containing that type of fieldmap can be found here:
- [`ieeg_visual_multimodal`](https://github.com/bids-standard/bids-examples/tree/master/ieeg_visual_multimodal)
The phase-encoding polarity (PEpolar) technique combines two or more Spin Echo
EPI scans with different phase encoding directions to estimate the distortion
map corresponding to the nonuniformities of the B0 field.
These *_epi.nii[.gz] - or *_m0scan.nii[.gz] for arterial spin labeling perfusion data - files can be 3D or 4D --
in the latter case, all timepoints share the same scanning parameters.
Some 4D scans intended for correcting DWIs may have accompanying *_epi.bval and *_epi.bvec files.
Examples of software tools using these kinds of images are FSL TOPUP and
AFNI 3dqwarp.
{{ MACROS___make_filename_template("raw", datatypes=["fmap"], suffixes=["epi"]) }}
The dir-<label> entity is REQUIRED
for these files.
This entity MUST be used in addition to
the REQUIRED PhaseEncodingDirection metadata field
(see Filename structure).
Required fields:
{{ MACROS___make_sidecar_table("fmap.MRIFieldmapPepolar") }}
For example:
{
"PhaseEncodingDirection": "j-",
"TotalReadoutTime": 0.095,
"IntendedFor": "bids::sub-01/func/sub-01_task-motor_bold.nii.gz",
"B0FieldIdentifier": "pepolar_fmap0"
}See Using IntendedFor metadata
for details on the IntendedFor field.
As for other EPI sequences, these field mapping sequences may have any of the
in-plane spatial encoding metadata keys.
However, please note that PhaseEncodingDirection and TotalReadoutTime keys
are REQUIRED for these field mapping sequences.