Magnetic Resonance Imaging
Common metadata fields
MR Data described in sections 8.3.x 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" by Ben Inglis:
Scanner Hardware
Field name | Definition |
---|---|
Manufacturer | RECOMMENDED. Manufacturer of the equipment that produced the composite instances. Corresponds to DICOM Tag 0008, 0070 Manufacturer |
ManufacturersModelName | RECOMMENDED. Manufacturer's model name of the equipment that produced the composite instances. Corresponds to DICOM Tag 0008, 1090 Manufacturers Model Name |
DeviceSerialNumber | RECOMMENDED. 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. Institution defined name of the machine that produced the composite instances. Corresponds to DICOM Tag 0008, 1010 Station Name |
SoftwareVersions | RECOMMENDED. Manufacturer’s designation of software version of the equipment that produced the composite instances. Corresponds to DICOM Tag 0018, 1020 Software Versions |
HardcopyDeviceSoftwareVersion | (Deprecated) 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. Nominal field strength of MR magnet in Tesla. Corresponds to DICOM Tag 0018,0087 Magnetic Field Strength |
ReceiveCoilName | RECOMMENDED. 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. 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. As an example, 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 (e.g., 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 |
GradientSetType | RECOMMENDED. It should be possible to infer the gradient coil from the scanner model. If not, e.g. 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. 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. (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 (e.g. GRAPPA, SENSE) imaging |
CoilCombinationMethod | RECOMMENDED. 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 |
Sequence Specifics
Field name | Definition |
---|---|
PulseSequenceType | RECOMMENDED. A general description of the pulse sequence used for the scan (i.e. MPRAGE, Gradient Echo EPI, Spin Echo EPI, Multiband gradient echo EPI). |
ScanningSequence | RECOMMENDED. Description of the type of data acquired. Corresponds to DICOM Tag 0018, 0020 Scanning Sequence . |
SequenceVariant | RECOMMENDED. Variant of the ScanningSequence. Corresponds to DICOM Tag 0018, 0021 Sequence Variant . |
ScanOptions | RECOMMENDED. Parameters of ScanningSequence. Corresponds to DICOM Tag 0018, 0022 Scan Options . |
SequenceName | RECOMMENDED. Manufacturer’s designation of the sequence name. Corresponds to DICOM Tag 0018, 0024 Sequence Name . |
PulseSequenceDetails | RECOMMENDED. Information beyond pulse sequence type that identifies the specific pulse sequence used (i.e. "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 stating if the image saved has been corrected for gradient nonlinearities by the scanner sequence. |
MTState | RECOMMENDED. Boolean value (true or false ), specifying whether the magnetization transfer pulse is applied. This parameter is REQUIRED by all the anatomical images grouped by MTR , MTS and MPM suffixes. This field originally corresponds to DICOM tag 0018, 9020 Magnetization Transfer . |
MTOffsetFrequency | RECOMMENDED. The frequency offset of the magnetization transfer pulse with respect to the central H1 Larmor frequency in Hertz (Hz). |
MTPulseBandwidth | RECOMMENDED. The excitation bandwidth of the magnetization transfer pulse in Hertz (Hz). |
MTNumberOfPulses | RECOMMENDED. Number of magnetization transfer RF pulses applied before the readout. |
MTPulseShape | RECOMMENDED. Shape of the magnetization transfer RF pulse waveform. Accepted values: HARD , GAUSSIAN , GAUSSHANN (gaussian pulse with Hanning window), SINC , SINCHANN (sinc pulse with Hanning window), SINCGAUSS (sinc pulse with Gaussian window), FERMI . |
MTPulseDuration | RECOMMENDED. Duration of the magnetization transfer RF pulse in seconds. |
SpoilingState | RECOMMENDED. Boolean value (true or false ), specifying whether the pulse sequence uses any type of spoiling stratey to suppress transverse magnetization remaining after the readout. |
SpoilingType | RECOMMENDED. Specifies which spoiling method(s) are used by a spoiled sequence. Accepted values: RF , GRADIENT or COMBINED . |
SpoilingRFPhaseIncrement | RECOMMENDED. The amount of incrementation described in degrees, which is applied to the phase of the excitation pulse at each TR period for achieving RF spoiling. |
SpoilingGradientMoment | RECOMMENDED. Zeroth moment of the spoiler gradient lobe in millitesla times second per meter (mT.s/m). |
SpoilingGradientDuration | RECOMMENDED. The duration of the spoiler gradient lobe in seconds. The duration of a trapezoidal lobe is defined as the summation of ramp-up and plateu times. |
In-Plane Spatial Encoding
Field name | Definition |
---|---|
NumberShots | RECOMMENDED. The number of RF excitations need to reconstruct a slice or volume. Please mind that this is not the same as Echo Train Length which denotes the number of lines of k-space collected after an excitation. |
ParallelReductionFactorInPlane | RECOMMENDED. The parallel imaging (e.g, GRAPPA) factor. Use the denominator of the fraction of k-space encoded for each slice. For example, 2 means half of k-space is encoded. Corresponds to DICOM Tag 0018, 9069 Parallel Reduction Factor In-plane . |
ParallelAcquisitionTechnique | RECOMMENDED. The type of parallel imaging used (e.g. GRAPPA, SENSE). Corresponds to DICOM Tag 0018, 9078 Parallel Acquisition Technique . |
PartialFourier | RECOMMENDED. The fraction of partial Fourier information collected. Corresponds to DICOM Tag 0018, 9081 Partial Fourier . |
PartialFourierDirection | RECOMMENDED. The direction where only partial Fourier information was collected. Corresponds to DICOM Tag 0018, 9036 Partial Fourier Direction . |
PhaseEncodingDirection | RECOMMENDED. Possible values: i , j , k , i- , j- , k- . The letters i , j , k correspond to the first, second and third axis of the data in the NIFTI file. The polarity of the phase encoding is assumed to go from zero index to maximum index unless - sign is present (then the order is reversed - starting from the highest index instead of zero). PhaseEncodingDirection is defined as the direction along which phase is was modulated which may result in visible distortions. Note that this is not the same as the DICOM term InPlanePhaseEncodingDirection which can have ROW or COL values. This parameter is REQUIRED if corresponding fieldmap data is present or when using multiple runs with different phase encoding directions (which can be later used for field inhomogeneity correction). |
EffectiveEchoSpacing | RECOMMENDED. The "effective" sampling interval, specified in seconds, between lines in the phase-encoding direction, defined based on the size of the reconstructed image in the phase direction. It is frequently, but incorrectly, referred to as "dwell time" (see DwellTime parameter below for actual dwell time). It is required for unwarping distortions using field maps. Note that beyond just in-plane acceleration, a variety of other manipulations to the phase encoding need to be accounted for properly, including partial fourier, phase oversampling, phase resolution, phase field-of-view and interpolation.2 This parameter is REQUIRED if corresponding fieldmap data is present. |
TotalReadoutTime | RECOMMENDED. This is actually the "effective" total readout time , defined as the readout duration, specified in seconds, that would have generated data with the given level of distortion. It is NOT the actual, physical duration of the readout train. If EffectiveEchoSpacing has been properly computed, it is just EffectiveEchoSpacing * (ReconMatrixPE - 1) .3 . This parameter is REQUIRED if corresponding "field/distortion" maps acquired with opposing phase encoding directions are present (see 8.9.4). |
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 here and
here
3We use the "FSL definition", i.e, the time between the center of the first "effective" echo and the center of the last "effective" echo.
Timing Parameters
Field name | Definition |
---|---|
EchoTime | RECOMMENDED. The echo time (TE) for the acquisition, specified in seconds. This parameter is REQUIRED if corresponding fieldmap data is present or the data comes from a multi echo sequence. Corresponds to DICOM Tag 0018, 0081 Echo Time (please note that the DICOM term is in milliseconds not seconds). |
InversionTime | RECOMMENDED. 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. 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 (in JSON format) 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 (i.e., the final entry in the SliceTiming list is the time of acquisition of slice 0). This parameter is REQUIRED for sparse sequences that do not have the DelayTime field set. In addition without this parameter slice time correction will not be possible. |
SliceEncodingDirection | RECOMMENDED. 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. 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
Field name | Definition |
---|---|
FlipAngle | RECOMMENDED. Flip angle for the acquisition, specified in degrees. Corresponds to: DICOM Tag 0018, 1314 Flip Angle . |
MultibandAccelerationFactor | RECOMMENDED. The multiband factor, for multiband acquisitions. |
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
Field name | Definition |
---|---|
MultibandAccelerationFactor | RECOMMENDED. The multiband factor, for multiband acquisitions. |
Anatomical landmarks
Useful for multimodal co-registration with MEG, (S)EEG, TMS, etc.
Field name | Definition |
---|---|
AnatomicalLandmarkCoordinates | RECOMMENDED. Key:value pairs of any number of additional anatomical landmarks and their coordinates in voxel units (where first voxel has index 0,0,0) relative to the associated anatomical MRI, (e.g. {"AC": [127,119,149], "PC": [128,93,141], "IH": [131,114,206]}, or {"NAS": [127,213,139], "LPA": [52,113,96], "RPA": [202,113,91]} ). |
Institution information
Field name | Definition |
---|---|
InstitutionName | RECOMMENDED. The name of the institution in charge of the equipment that produced the composite instances. Corresponds to DICOM Tag 0008, 0080 InstitutionName . |
InstitutionAddress | RECOMMENDED. The address of the institution in charge of the equipment that produced the composite instances. Corresponds to DICOM Tag 0008, 0081 InstitutionAddress . |
InstitutionalDepartmentName | RECOMMENDED. The department in the institution in charge of the equipment that produced the composite instances. Corresponds to DICOM Tag 0008, 1040 Institutional Department Name . |
When adding additional metadata please use the CamelCase version of DICOM ontology terms whenever possible. See also recommendations on JSON files.
Anatomy imaging data
Template:
sub-<label>/[ses-<label>/]
anat/
sub-<label>[_ses-<label>][_acq-<label>][_part-<label>][_echo-<index>][_fa-<index>][_inv-<index>][_mt-<on/off>][_ce-<label>][_rec-<label>][_run-<index>]_<suffix>.nii[.gz]
sub-<label>[_ses-<label>][_acq-<label>][_part-<label>][_echo-<index>][_fa-<index>][_inv-<index>][_mt-<on/off>][_ce-<label>][_rec-<label>][_run-<index>][_mod-<suffix>]_defacemask.nii[.gz]
The term anatomical imaging data pertains to a broad range of MRI applications that provide structural information about (brain) anatomy, but differ by the nature of the data they contain. Anatomical (structural) data for a participant may refer to three types of data: 1. a single image with specific weighting on an arbitrary scale (e.g. a 3D high resolution T1-weighted image). This type is most commonly used in neuroimaging applications. 2. a group of images acquired within a single protocol for the purpose of improving contrast characteristics (e.g., a set of multi-echo anatomical GRE images) or calculating quantitative maps (e.g. four 3D volumes provided as an input to an MP2RAGE calculation) 3. a quantitative map of which the intensities are put on an absolute scales (e.g., seconds for a T1 map). These images are generally produced by some mathematical operation on images from class 2.
Conventional structural acquisitions
Anatomical images of this type typically refer to a volumetric high-resolution
dataset, representing the measured MRI signal in an arbitrary scale of "gray
shades". Contrast factor of these grayscale images depend on the relative contribution
of inherent tissue parameters (e.g. T1
, T2
and PD
) to the measured signal.
Contribution weights of these parameters are determined by the type of acquisition
sequence (e.g. spin-
or gradient-echo
) and the setting of various parameters
(e.g. Repetition Time
, Echo Time
, Inversion Time
and Flip Angle
). For
example, in a spoiled gradient-echo scan, keeping the repetition and the echo time
short with a relatively large flip angle increases the contribution of T1
effects
to the image contrast, yielding a primarily T1-weighted image.
Grouped scan collections for contrast improvement or quantitative map calculation
A group of anatomical scans may be collected to enhance certain contrast features,
such as to calculate a weighted average of multi-echo gradient echo (MEGRE
) images,
which is known to improve segmentation algorithm outputs.
Quantitative MRI (qMRI) methods mathematically characterize the signal changes observed
in a collection of parametrically altered scans under certain biophysical model assumptions.
These grouped scan collections
can then be processed to derive a qMRI map
, representing
anatomical features in a physically meaningful parameter range.
In both cases, the contrast characteristics change with varying acquisition parameters across
grouped scan collections
. Therefore, it is not tenable to name all the members
of a grouped scan collection
with one conventional MRI suffix label (e.g., T1w
)
or any other label that implies interchangeability among its instances.
To circumvent this problem, the _<suffix>
entity is adaptively used according
to the intended application of anatomical imaging data. For conventional MRI
applications, the suffixes will correspond to common anatomical contrasts T1w
,
T2w
, T2starw
etc. For groups of scans acquired for contrast improvement or
qMRI processing, the _<suffix>
indicates the collection that the scans belong to.
The _suffix
entity
To ensure an comprehensible, human readable directory that contains anatomical
imaging data, the _<suffix>
entity can be used in one of three ways:
- Conventional MRI suffixes
- Grouping suffixes
- Quantitative MRI (qMRI) map suffixes
This distinction was added to the specification on acceptance of the BEP001
proposal in version 1.x.x
. However, as a result, some suffixes that were introduced
into BIDS at an earlier point time are inconsistent with this typology: for example
because they are linked to a readout-sequence rather than a contrast, or because
they don't clearly distinguish between a quantitative map or a contrast-weighted
image. These legacy
-suffixes are no longer recommended but remain part of the
specification in order to maintain backwards compatability with previous versions
of the specification.
These can be found in the legacy suffixes subsection.
Previous versions of the specification used the term modality_label
instead of
_suffix
to represent this entity. The change in term was introduced in version
1.x.x.
to accodomate a broad definition of anatomical imaging applications.
Conventional MRI suffixes
Function:
Denotes the type of the predominant contrast conveyed by an individual file of
a conventional anatomical image.
One of the _<suffix>
entries listed in the table below
is REQUIRED (with additional entities where applicable) to provide a self-explanatory
file name.
A change to the specification is REQUIRED to expand or to modify the following table.
Name | _suffix | _suffix type | Description |
---|---|---|---|
T1 weighted images | T1w | Conventional | Denotes images with predominant T1 contribution. |
T2 weighted images | T2w | Conventional | Denotes images with predominant T2 contribution. |
Proton density weighted images | PDw | Conventional | Denotes images with predominant proton density (PD) contribution. |
T2 star weighted images | T2starw | Conventional | Denotes images with predominant T2* contribution. Please note that this suffix is not a surrogate for T2starmap . |
Fluid Attenuated Inversion Recovery Images | FLAIR | Conventional | Denotes images with predominant T2 contribution (a.k.a T2-FLAIR), in which signal from fluids (e.g. CSF) is nulled out by adjusting inversion time, coupled with notably long repetition and echo times. |
Inplane T1 | inplaneT1 | Conventional | T1-weighted anatomical image matched to functional acquisition |
Inplane T2 | inplaneT2 | Conventional | T2-weighted anatomical image matched to functional acquisition |
PDw and T2w images obtained using dual-echo FSE | PDT2 | Conventional | PDw and T2w images acquired using a dual-echo FSE sequence through view sharing process (Johnson et al. 1994). |
Example use for conventional T1 weighted images:
sub-01_run-1_T1w.nii.gz
sub-01_run-1_T1w.json
sub-01_run-2_T1w.nii.gz
sub-01_run-2_T1w.json
The run
entity in the example above denotes the index of the acquisition
repeated with the identical scan parameters (e.g., to achieve a higher SNR by averaging the scans together).
Note that changing parameters between multiple acquisitions of the same sequence
creates a different use case: grouped scan collections. For more information see
the grouping suffixes subsection.
Important:
If an anatomical image is defaced for anonymization, one MAY provide
the binary mask that was used to remove facial features. In the specific case of
naming this binary mask, the _<suffix>
entity is replaced by _<defacemask>
entry.
Therefore, to contain the original _<suffix>
entry, the OPTIONAL mod-<suffix>
entity is used. For example, deface mask image belonging to a T1 weighted image is named as follows:
sub-01_mod-T1w_defacemask.nii.gz
sub-01_mod-T1w_defacemask.json
Grouping suffixes
Function:
Files that belong to a grouped scan collection are part of a single scan
protocol that acquires multiple images with similar acquisition parameters
that are systematically altered. Grouped scan collections are intended to
a) increase contrast by combining multiple similar images (e.g., a multi-echo
GRE), or b) to estimate physical parameters on an absolute scale, within a
qMRI analysis framework (e.g., a T1-map using a MP2RAGE-protocol). The
quantitative maps that are output from these calculations (e.g., T1map
,
T2map
etc) are described in the qMRI map suffixes
section below. A change to the specification is REQUIRED to expand or to
modify the following table.
Name | Suffix | Type | Description |
---|---|---|---|
Variable flip angle | VFA | Grouping | The VFA method involves at least two spoiled gradient echo (SPGR) of steady-state free precession (SSFP) images acquired at different flip angles. Depending on the provided metadata fields and the sequence type, data may be eligible for DESPOT1, DESPOT2 and their variants (Deoni et al. 2005). Please visit the qMRI appendix for details. Associated output suffixes: T1map, T2map, R1map, R2map |
Inversion recovery (for T1 mapping) | IRT1 | Grouping | The IRT1 method involves multiple inversion recovery spin-echo images acquired at different inversion times (Barral et al. 2010). Associated output suffixes: T1map, R1map |
Magnetization prepared two gradient echoes | MP2RAGE | Grouping | The MP2RAGE method is a special protocol that collects several images at different flip angles and inversion times to create a parametric T1map by combining the magnitude and phase images (Marques et al. 2010). Associated output suffixes: T1map, R1map, UNIT1 |
Multi-echo spin echo | MESE | Grouping | The MESE method involves multiple spin echo images acquired at different echo times and is primarily used for T2 mapping. Associated output suffixes: T2map, R2map, MWFmap |
Multi-echo gradient echo | MEGRE | Grouping | Anatomical gradient echo images acquired at different echo times. Associated output suffixes: T2starmap, R2starmap |
Magnetization transfer ratio | MTR | Grouping | Anatomical images for calculating a semi-quantitative magnetization transfer ratio map. Associated output suffixes: MTRmap |
Magnetization transfer saturation | MTS | Grouping | Anatomical images for calculating a semi-quantitative magnetization transfer saturation index map. The MTS method involves three sets of anatomical images that differ in terms of application of a magnetization transfer RF pulse (MTon or MToff) and flip angle (Helms et al. 2008). Associated output suffixes: T1map, MTsat |
Multi-parametric mapping | MPM | Grouping | Anatomical images for multiparametric mapping (a.k.a hMRI). The MPM approaches involves the acquisition of highly-similar anatomical images that differ in terms of application of a magnetization transfer RF pulse (MTon or MToff), flip angle and (optionally) echo time and magnitue/phase parts (Weiskopf et al. 2013). See here for suggested MPM acquisition protocols.,Associated output suffixes:R1map, R2starmap, MTsat, PDmap, T1map, T2starmap |
For example:
sub-01_fa-1_VFA.nii.gz
sub-01_fa-1_VFA.json
sub-01_fa-2_VFA.nii.gz
sub-01_fa-2_VFA.json
Please see the entity table appendix for the REQUIRED and OPTIONAL entities
for each grouping suffix
.
Note that every image in a grouped scan collection has the same _<suffix>
as they are supposed to be used together. Although the acquisitions will have
many identical acquisition parameters, only one-to-one-mapping is allowed
between a .json
-sidecar file and an image in a grouped scan collection.
This follows directly from the
inheritance principles of BIDS:
parameter values that are identical across a set of grouped scans will still
have to be stored separately in each .json
-sidecar file.
qMRI map suffixes
Function:
Denotes the parameter contained within an individual file of a quantitative parametric image.
Changes to the specification is REQUIRED to expand or to modify the following table.
Name | _suffix | _suffix type | Description |
---|---|---|---|
Longitudinal relaxation time map | T1map | Parametric | In seconds (s). T1 maps are REQUIRED to use this suffix irrespective of the method they are related to. Can be generated from: VFA , IRT1 , MP2RAGE , MTS ,MPM . See this interactive book on T1 mapping for further reading on T1-mapping. |
True transverse relaxation time map | T2map | Parametric | In seconds (s). T2 maps are REQUIRED to use this suffix irrespective of the method they are related to. Can be generated from: MESE , MPM |
Observed transverse relaxation time map | T2starmap | Parametric | In seconds (s). T2* maps are REQUIRED to use this suffix irrespective of the method they are related to.Can be generated from: MEGRE , MPM |
Longitudinal relaxation rate map | R1map | Parametric | In seconds-1 (1/s). R1 maps are REQUIRED to use this suffix irrespective of the method they are related to. Can be generated from: VFA , IRT1 , MP2RAGE , MTS , MPM |
True transverse relaxation rate map | R2map | Parametric | In seconds-1 (1/s). R2 maps are REQUIRED to use this suffix irrespective of the method they are related to. Can be generated from: MESE , MPM |
Observed transverse relaxation rate map | R2starmap | Parametric | In seconds-1 (1/s). R2* maps are REQUIRED to use this suffix irrespective of the method they are related to. Can be generated from:MEGRE , MPM |
Proton density map | PDmap | Parametric | In arbitrary units (a.u.). PD maps are REQUIRED to use this suffix irrespective of the method they are related to. Can be generated from: MPM |
Magnetization transfer ratio map | MTRmap | Parametric | In percentage (%). MTR maps are REQUIRED to use this suffix irrespective of the method they are related to. Can be generated from: MTR |
Magnetization transfer saturation index map | MTsat | Parametric | In arbitrary units (a.u.). MTsat maps are REQUIRED to use this suffix irrespective of the method they are related to. Can be generated from: MTS , MPM |
Homogeneous (flat) T1-weighted image by MP2RAGE | UNIT1 | Parametric | In arbitrary units (a.u.). UNIT1 images are REQUIRED to use this suffix irrespective of the method they are related to. Note that although this image is T1-weighted, regions without MR signal will contain white salt-and-pepper noise that most segmentation algorithms will fail on. Therefore, it is important to dissociate it from from _T1w Can be generated from: MP2RAGE |
Longutidunal relaxation in rotating frame (T1 rho) map | T1rho | Parametric | In seconds (s). T1-rho maps are REQUIRED to use this suffix irrespective of the method they are related to. Can be generated from: N/A |
Myelin water fraction map | MWFmap | Parametric | In percentage (%). MWF maps are REQUIRED to use this suffix irrespective of the method they are related to. Can be generated from: MESE |
Combined PD/T2 map | PDT2map | Parametric | In arbitrary units (a.u.). Combined PD/T2 maps are REQUIRED to use this suffix irrespective of the method they are related to. N/A |
RF transmit field map | TB1map | Parametric | In percent units (p.u.). Radio frequency (RF) transmit field maps are REQUIRED to use this suffix irrespective of the method they are related to. Please see the qMRI appendix for associated inputs and further details |
RF receive sensitivity map | RB1map | Parametric | In percent units (p.u.). Radio frequency (RF) receive sensitivity maps are REQUIRED to use this suffix irrespective of the method they are related to. Please see the qMRI appendix for associated inputs and further details |
Observed signal amplitude map | S0map | Parametric | In arbitrary units (a.u.). For a multi-echo sequence, S0 maps index the baseline signal before exponential (T2*) signal decay. In other words: the exponential of the intercept for a linear decay model across log-transformed echos. For more information, please see, for example, the tedana documentation. S0 maps are REQUIRED to use this suffix irrespective of the method they are related to. Associated suffixes: T2starmap. |
Quantitative susceptibility map (QSM) | Chimap | Parametric | In parts per million (ppm). QSM allows for determining the underlying magnetic susceptibility of tissue (Chi). Chi-maps are usually constructed from the phase images of GRE sequences. Chi-maps are quantitative and are reconstructed by solving the magnetic field to susceptibility source inverse problem (Wang & Liu, 2014). |
Quantitative maps can be obtained right off the scanner or by processing files
belonging to a grouped scan collection
. Regardless of the method they are
obtained by, one of the _suffix
entries listed in the table above is REQUIRED
for a proper naming. For example:
sub-01_T1map.nii.gz
sub-01_T1map.json
Quantitative unit of the parameter contained by a quantitative map MUST comply
with the unit description provided for its respective _suffix
entry.
For example, a T1 map in milliseconds unit (ms) is not valid, given that the
description of the T1map
suffix requires the parameter to be in seconds (s).
The part
entity
This entity shall be used to indicate which component of the complex representation
of the MRI signal is represented in voxel data. The part-<label>
key/value pair 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 mag/phase
or real/imag
pairs. For example:
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: radians
or
a.u.
for grayscale images. For example:
sub-01_part-phase.json
{
"Units": "radians"
}
If the part
key/value pair is absent from a filename, the image SHOULD be a
magnitude image.
The run
entity
If several scans of the same modality are acquired they MUST be indexed with a
key-value pair: _run-1
, _run-2
, _run-3
etc. (only integers are allowed as
run labels). When there is only one scan of a given type the run key MAY be
omitted. Please note that diffusion imaging data is stored elsewhere (see
below).
The acq
entity
The OPTIONAL acq-<label>
key/value pair corresponds to a custom label the user
MAY use to distinguish a different set of parameters used for acquiring the same
modality. For example this should be used when a study includes two T1w images -
one full brain low resolution and and one restricted field of view but high
resolution. In such case two files could have the following names:
sub-01_acq-highres_T1w.nii.gz
and sub-01_acq-lowres_T1w.nii.gz
, however the
user is free to choose any other label than highres
and lowres
as long as
they are consistent across subjects and sessions. In case different sequences
are used to record the same modality (e.g. RARE and FLASH for T1w) this field
can also be used to make that distinction. At what level of detail to make the
distinction (e.g. just between RARE and FLASH, or between RARE, FLASH, and
FLASHsubsampled) remains at the discretion of the researcher.
The echo
entity
If the value of EchoTime
metadata field varies at least once across a collection
of anatomical images having a common grouping suffix
, the use of echo-<index>
key/value pair is REQUIRED. Note that only integers (from 1 to N) are allowed as
values to this entity for N different EchoTime
parameter values. The actual
EchoTime
parameter values MUST NOT be explicitly declared by the entity. Instead,
the parameter values are stored in sidecar json files and indexed by the echo
entity
in ascending order. For example:
sub-01_echo-1_MEGRE.nii.gz
sub-01_echo-1_MEGRE.json (`EchoTime` = 0.0005)
sub-01_echo-2_MEGRE.nii.gz
sub-01_echo-2_MEGRE.json (`EchoTime` = 0.0015)
sub-01_echo-3_MEGRE.nii.gz
sub-01_echo-3_MEGRE.json (`EchoTime` = 0.0025)
The fa
entity
If the value of FlipAngle
metadata field varies at least once across a collection
of anatomical images having a common grouping suffix
, the use of fa-<index>
key/value pair is REQUIRED. Note that only integers from 1 to N are allowed as
values to this entity for N different FlipAngle
parameter values. The actual
FlipAngle
parameter values MUST NOT be explicitly declared by the entity. Instead,
the parameter values are stored in sidecar json files and indexed by the fa
entity
in ascending order. For example:
sub-01_fa-1_VFA.nii.gz
sub-01_fa-1_VFA.json (`FlipAngle` = 5)
sub-01_fa-2_VFA.nii.gz
sub-01_fa-2_VFA.json (`FlipAngle` = 25)
The inv
entity
If the value of InversionTime
metadata field varies at least once across a
collection of anatomical images having a common grouping suffix
, the use of
inv-<index>
key/value pair is REQUIRED. Note that only integers from 1 to N
are allowed as values to this entity for N different InversionTime
parameter
values. The actual InversionTime
parameter values MUST NOT be explicitly declared
by the entity. Instead, the parameter values are stored in sidecar json files and
indexed by the inv
entity in ascending order. For example:
sub-01_inv-1_IRT1.nii.gz
sub-01_inv-1_IRT1.json (`InversionTime` = 0.0050)
sub-01_inv-2_IRT1.nii.gz
sub-01_inv-2_IRT1.json (`InversionTime` = 0.0100)
sub-01_inv-3_IRT1.nii.gz
sub-01_inv-4_IRT1.json (`InversionTime` = 0.0150)
The mt
entity
If a collection of anatomical images having a common grouping suffix
includes
at least one scan in which a magnetization transfer pulse is applied, the
mt-<on/off>
key/value pair MUST BE used. The value of this entity can be either
on
or off
(in lowercase), as determined by the MTState
metadata. For example:
sub-01_mt-on_MTR.nii.gz
sub-01_mt-on_MTR.json (`MTState` = On)
sub-01_mt-off_MTR.nii.gz
sub-01_mt-off_MTR.json (`MTState` = Off)
The ce
entity
Similarly the OPTIONAL ce-<label>
key/value can be used to distinguish
sequences using different contrast enhanced images. The label is the name of the
contrast agent. The key ContrastBolusIngredient
MAY be also be added in the
JSON file, with the same label.
The rec
entity
Similarly the OPTIONAL rec-<label>
key/value can be used to distinguish
different reconstruction algorithms (for example ones using motion correction).
If the structural images included in the dataset were defaced (to protect
identity of participants) one CAN provide the binary mask that was used to
remove facial features in the form of _defacemask
files. In such cases the
OPTIONAL mod-<label>
key/value pair corresponds to modality label for eg: T1w,
inplaneT1, referenced by a defacemask image. E.g.,
sub-01_mod-T1w_defacemask.nii.gz
.
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:
Field name | Definition |
---|---|
ContrastBolusIngredient | OPTIONAL. Active ingredient of agent. Values MUST be one of: IODINE, GADOLINIUM, CARBON DIOXIDE, BARIUM, XENON Corresponds to DICOM Tag 0018,1048. |
RepetitionTimeExcitation | OPTIONAL. The time in seconds between successive excitation pulses that excite the same tissue. The DICOM tag that best refers to this parameter is (0018, 0080). This field may be superseded by RepetitionTimePreparation for certain use cases, such as MP2RAGE. Use RepetitionTimeExcitation (in combination with RepetitionTimePreparation if needed) for anatomy imaging data rather than RepetitionTime as it is already defined as the amount of time that it takes to acquire a single volume in section 4.1.x. |
RepetitionTimePreparation | OPTIONAL. The period of time in seconds that it takes a preparation pulse block to re-appear at the beginning of the succeeding (essentially identical) pulse sequence. |
Legacy suffixes (to be deprecated)
Some suffixes that were available in versions of the specification prior to 1.x.x. have been identified as legacy suffixes. The legacy sufficies generate inconsistencies and/or ambiguities with additional sufficies added in version 1.x.x and so are therefore not recommended for use in new datasets. They are, however, still valid sufixxes, to maintain backwards compatibility.
The following suffixes are valid, but SHOULD NOT be used for new BIDS compatible datasets (created after version 1.x.x.):
Name | Suffix | Description | Reason to deprecate |
---|---|---|---|
T2* | T2star | Not provided. | Ambiguous, may refer to a parametric image or to a conventional image. Change: Replaced by T2starw or T2starmap . |
FLASH | FLASH | Not provided. | FLASH (Fast-Low-Angle-Shot) is a vendor specific implementation for spoiled gradient echo acquisition. It is commonly used for rapid anatomical imaging and also for many different qMRI applications. Given the versatility and the popularity of the FLASH sequence, it can easily obfuscate purpose of a grouped scan collection when used as a grouping suffix . Change: Removed from suffixes. |
Proton Density | PD | Not provided. | Ambiguous, may refer to a parametric image or to a conventional image. Change: Replaced by PDw or PDmap . |
Task (including resting state) imaging data
Currently supported image contrasts include:
Name | contrast_label |
Description |
---|---|---|
BOLD | bold | Blood-Oxygen-Level Dependent contrast (specialized T2* weighting) |
CBV | cbv | Cerebral Blood Volume contrast (specialized T2* weighting or difference between T1 weighted images) |
Phase | phase | Phase information associated with magnitude information stored in BOLD contrast |
Template:
sub-<label>/[ses-<label>/]
func/
sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_dir-<label>][_rec-<label>][_run-<index>][_echo-<index>]_<contrast_label>.nii[.gz]
sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_dir-<label>][_rec-<label>][_run-<index>][_echo-<index>]_sbref.nii[.gz]
Imaging data acquired during functional imaging (i.e. imaging which supports
rapid temporal repetition). This includes but is not limited to task based fMRI
as well as resting state fMRI (i.e. rest is treated as another 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 as
type sbref
(e.g. sub-control01_task-nback_sbref.nii.gz
).
Each task has a unique label that MUST only consist of letters and/or numbers (other characters, including spaces and underscores, are not allowed). Those labels MUST be consistent across subjects and sessions.
If more than one run of the same task has been acquired a key/value pair:
_run-1
, _run-2
, _run-3
etc. MUST be used. If only one run was acquired the
run-<index>
can be omitted. In the context of functional imaging a run is
defined as the same task, but in some cases it can mean different set of stimuli
(for example randomized order) and participant responses.
The OPTIONAL acq-<label>
key/value pair corresponds to a custom label one may
use to distinguish different set of parameters used for acquiring the same task.
For example this should be used when a study includes two resting state images -
one single band and one multiband. In such case two files could have the
following names: sub-01_task-rest_acq-singleband_bold.nii.gz
and
sub-01_task-rest_acq-multiband_bold.nii.gz
, however the user is MAY choose any
other label than singleband
and multiband
as long as they are consistent
across subjects and sessions and consist only of the legal label characters.
Similarly the OPTIONAL ce-<label>
key/value can be used to distinguish
sequences using different contrast enhanced images. The label is the name of the
contrast agent. The key ContrastBolusIngredient MAY be also be added in the JSON
file, with the same label.
Similarly the OPTIONAL rec-<label>
key/value can be used to distinguish
different reconstruction algorithms (for example ones using motion correction).
Similarly the OPTIONAL dir-<label>
and rec-<label>
key/values
can be used to distinguish different phase-encoding directions and
reconstruction algorithms (for example ones using motion correction).
See fmap
Case 4
for more information on dir
field specification.
Multi-echo data MUST be split into one file per echo. Each file shares the same
name with the exception of the _echo-<index>
key/value. For 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 a form of an
integer) of the echo not the echo time value which needs to be stored in the
field EchoTime of the separate JSON file (see also
here).
Some meta information about the acquisition MUST be provided in an additional JSON file.
Required fields
Field name | Definition |
---|---|
RepetitionTime | REQUIRED. The time in seconds between the beginning of an |
acquisition of one volume and the beginning of acquisition of the volume | |
following it (TR). When used in the context of functional acquisitions this | |
parameter best corresponds to | |
DICOM Tag 0020,0110: | |
the "time delta between images in a dynamic of functional set of images" but | |
may also be found in DICOM Tag 0018, 0080: | |
"the period of time in msec between the beginning of a pulse sequence and | |
the beginning of the succeeding (essentially identical) pulse sequence". | |
This definition includes time between scans (when no data has been acquired) | |
in case of sparse acquisition schemes. This value MUST be consistent with the | |
'pixdim[4] ' field (after accounting for units stored in 'xyzt_units ' field) |
|
in the NIfTI header. This field is mutually exclusive with VolumeTiming . |
|
VolumeTiming | REQUIRED. The time at which each volume was acquired during the |
acquisition. It is described using a list of times (in JSON format) referring to the onset of each volume in the BOLD series. The list must have the same length as the BOLD series, and the values must be non-negative and monotonically increasing. This field is mutually exclusive with RepetitionTime and DelayTime . If defined, this requires acquisition time (TA) be defined via either SliceTiming or AcquisitionDuration be defined. |
|
TaskName | REQUIRED. Name of the task. No two tasks should have the same name. The task label included in the file name is derived from this TaskName field by removing all non-alphanumeric ([a-zA-Z0-9] ) characters. For example TaskName faces n-back will correspond to task label facesnback . A RECOMMENDED convention is to name resting state task using labels beginning with rest . |
For the fields described above and in the following section, the term "Volume" refers to a reconstruction of the object being imaged (e.g., 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.
Other RECOMMENDED metadata
Timing Parameters
Field name | Definition |
---|---|
NumberOfVolumesDiscardedByScanner | RECOMMENDED. Number of volumes ("dummy scans") discarded by the scanner (as opposed to those discarded by the user post hoc) before saving the imaging file. For example, a sequence that automatically discards the first 4 volumes before saving would have this field as 4. A sequence that doesn't discard dummy scans would have this set to 0. Please note that the onsets recorded in the _event.tsv file should always refer to the beginning of the acquisition of the first volume in the corresponding imaging file - independent of the value of NumberOfVolumesDiscardedByScanner field. |
NumberOfVolumesDiscardedByUser | RECOMMENDED. Number of volumes ("dummy scans") discarded by the user before including the file in the dataset. If possible, including all of the volumes is strongly recommended. Please note that the onsets recorded in the _event.tsv file should always refer to the beginning of the acquisition of the first volume in the corresponding imaging file - independent of the value of NumberOfVolumesDiscardedByUser field. |
DelayTime | RECOMMENDED. User specified time (in seconds) to delay the acquisition of data for the following volume. If the field is not present it is assumed to be set to zero. Corresponds to Siemens CSA header field lDelayTimeInTR . This field is REQUIRED for sparse sequences using the RepetitionTime field that do not have the SliceTiming field set to allowed for accurate calculation of "acquisition time". This field is mutually exclusive with VolumeTiming . |
AcquisitionDuration | RECOMMENDED. Duration (in seconds) of volume acquisition. Corresponds to DICOM Tag 0018,9073 Acquisition Duration . This field is REQUIRED for sequences that are described with the VolumeTiming field and that do not have the SliceTiming field set to allow for accurate calculation of "acquisition time". This field is mutually exclusive with RepetitionTime . |
DelayAfterTrigger | RECOMMENDED. Duration (in seconds) from trigger delivery to scan onset. This delay is commonly caused by adjustments and loading times. This specification is entirely independent of NumberOfVolumesDiscardedByScanner or NumberOfVolumesDiscardedByUser , as the delay precedes the acquisition. |
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 ] --> has to be filled
- [ ] --> has to be left empty
- empty cell --> can be specified but not required
fMRI task information
Field name | Definition |
---|---|
Instructions | RECOMMENDED. Text of the instructions given to participants before the scan. This is especially important in context of resting state fMRI and distinguishing between eyes open and eyes closed paradigms. |
TaskDescription | RECOMMENDED. Longer description of the task. |
CogAtlasID | RECOMMENDED. URL of the corresponding Cognitive Atlas Task term. |
CogPOID | RECOMMENDED. URL of the corresponding CogPO term. |
See Common metadata fields for a list of additional terms and their definitions.
Example:
sub-control01/
func/
sub-control01_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"
}
If this information is the same for all participants, sessions and runs it can
be provided in task-<label>_bold.json
(in the root directory of the
dataset). However, if the information differs between subjects/runs it can be
specified in the
sub-<label>/func/sub-<label>_task-<label>[_acq-<label>][_run-<index>]_bold.json
file.
If both files are specified fields from the file corresponding to a particular
participant, task and run takes precedence.
Diffusion imaging data
Template:
sub-<label>/[ses-<label>/]
dwi/
sub-<label>[_ses-<label>][_acq-<label>][_dir-<label>][_run-<index>]_dwi.nii[.gz]
sub-<label>[_ses-<label>][_acq-<label>][_dir-<label>][_run-<index>]_dwi.bval
sub-<label>[_ses-<label>][_acq-<label>][_dir-<label>][_run-<index>]_dwi.bvec
sub-<label>[_ses-<label>][_acq-<label>][_dir-<label>][_run-<index>]_dwi.json
sub-<label>[_ses-<label>][_acq-<label>][_dir-<label>][_run-<index>]_sbref.nii[.gz]
sub-<label>[_ses-<label>][_acq-<label>][_dir-<label>][_run-<index>]_sbref.json
Diffusion-weighted imaging data acquired for that participant. The OPTIONAL
acq-<label>
key/value pair corresponds to a custom label the user may use to
distinguish different set of parameters. For example this should be used when a
study includes two diffusion images - one single band and one multiband. In such
case two files could have the following names:
sub-01_acq-singleband_dwi.nii.gz
and sub-01_acq-multiband_dwi.nii.gz
,
however the user is free to choose any other label than singleband
and
multiband
as long as they are consistent across subjects and sessions. For
multiband acquisitions, one can also save the single-band reference image as
type sbref
(e.g. dwi/sub-control01_sbref.nii[.gz]
) The bvec and bval files
are in the FSL format:
The bvec files contain 3 rows with n space-delimited floating-point numbers
(corresponding to the n volumes in the relevant NIfTI file). The first row
contains the x elements, the second row contains the y elements and 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 volumes. Inherent to
the FSL format for bvec specification is the fact that the coordinate system of
the bvecs is with respect to the participant (i.e., defined by the axes of the
corresponding dwi.nii file) and not the magnet’s coordinate system, which means
that any rotations applied to dwi.nii also need to be applied to the
corresponding bvec file.
bvec example:
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 bval file contains the b-values (in s/mm2) corresponding to the volumes in the relevant NIfTI file), with 0 designating non-diffusion-weighted volumes, space-delimited.
bval example:
0 0 2000 2000 1000 1000
.bval
and .bvec
files can be saved on any level of the directory structure
and thus define those values for all sessions and/or subjects in one place (see
Inheritance principle).
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
}
Fieldmap data
All three of B0 (static magnetic field strength pattern), B1+ (transmit field pattern), and B1- (receive field pattern) maps can be useful in post-processing raw functional and anatomical data.
B0 maps are primarily used to correct for spatial distortions in functional data acquired with EPI sequences.
B1+ and B1- maps are mostly used in anatomical imaging, especially in quantitative MRI applications. Further information about these radiofrequency (RF) field maps are available in the qMRI appendix.
B0 fieldmaps
Data acquired to correct for B0 inhomogeneities can come in different forms. The current version of this standard considers four different scenarios. Please note that in all cases fieldmap data can be linked to a specific scan(s) it was acquired for by filling the IntendedFor field in the corresponding JSON file. For example:
{
"IntendedFor": "func/sub-01_task-motor_bold.nii.gz"
}
The IntendedFor field may contain one or more filenames with paths relative to the subject subfolder. The path needs to use forward slashes instead of backward slashes. Here’s an example with multiple target scans:
{
"IntendedFor": ["ses-pre/func/sub-01_ses-pre_task-motor_run-1_bold.nii.gz",
"ses-post/func/sub-01_ses-post_task-motor_run-1_bold.nii.gz"]
}
The IntendedFor field is OPTIONAL and in case the fieldmaps do not correspond to any particular scans it does not have to be filled.
Multiple fieldmaps can be stored. In such case the _run-1
, _run-2
should be
used. The OPTIONAL acq-<label>
key/value pair corresponds to a custom label
the user may use to distinguish different set of parameters.
Case 1: Phase difference image and at least one magnitude image
Template:
sub-<label>/[ses-<label>/]
fmap/
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phasediff.nii[.gz]
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phasediff.json
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_magnitude1.nii[.gz]
OPTIONAL
sub-<label>/[ses-<label>/]
fmap/
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_magnitude2.nii[.gz]
This is a common output for build in fieldmap sequence on Siemens scanners. In
this particular case the sidecar JSON file has to define the Echo Times of the
two phase images used to create the difference image. EchoTime1
corresponds to
the shorter echo time and EchoTime2
to the longer echo time. Similarly
_magnitude1
image corresponds to the shorter echo time and the OPTIONAL
_magnitude2
image to the longer echo time. For example:
{
"EchoTime1": 0.00600,
"EchoTime2": 0.00746,
"IntendedFor": "func/sub-01_task-motor_bold.nii.gz"
}
Case 2: Two phase images and two magnitude images
Template:
sub-<label>/[ses-<label>/]
fmap/
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phase1.nii[.gz]
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phase1.json
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phase2.nii[.gz]
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phase2.json
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_magnitude1.nii[.gz]
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_magnitude2.nii[.gz]
Similar to the case above, but instead of a precomputed phase difference map two
separate phase images are presented. The two sidecar JSON files need to specify
corresponding EchoTime
values. For example:
{
"EchoTime": 0.00746,
"IntendedFor": "func/sub-01_task-motor_bold.nii.gz"
}
Case 3: A real fieldmap image
Template:
sub-<label>/[ses-<label>/]
fmap/
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_magnitude.nii[.gz]
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_fieldmap.nii[.gz]
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_fieldmap.json
In some cases (for example GE) the scanner software will output a precomputed
fieldmap denoting the B0 inhomogeneities along with a magnitude image used for
coregistration. In this case the sidecar JSON file needs to include the units of
the fieldmap. The possible options are: Hz
, rad/s
, or Tesla
. For example:
{
"Units": "rad/s",
"IntendedFor": "func/sub-01_task-motor_bold.nii.gz"
}
Case 4: Multiple phase encoded directions ("pepolar")
Template:
sub-<label>/[ses-<label>/]
fmap/
sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>]_dir-<label>[_run-<index>]_epi.nii[.gz]
sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>]_dir-<label>[_run-<index>]_epi.json
The phase-encoding polarity (PEpolar) technique combines two or more Spin Echo
EPI scans with different phase encoding directions to estimate the underlying
inhomogeneity/deformation map. Examples of tools using this kind of images are
FSL TOPUP, AFNI 3dqwarp and SPM. In such a case, the phase encoding direction is
specified in the corresponding JSON file as one of: i
, j
, k
, i-
, j-
,
k-
. For these differentially phase encoded sequences, one also needs to
specify the Total Readout Time defined as the time (in seconds) from the center
of the first echo to the center of the last echo (aka "FSL definition" - see
here and
here how to calculate it). For
example
{
"PhaseEncodingDirection": "j-",
"TotalReadoutTime": 0.095,
"IntendedFor": "func/sub-01_task-motor_bold.nii.gz"
}
label
value of _dir-
can be set to arbitrary alphanumeric label ([a-zA-Z0-9]+
for
example LR
or AP
) that can help users to distinguish between different
files, but should not be used to infer any scanning parameters (such as phase
encoding directions) of the corresponding sequence. Please rely only on the JSON
file to obtain scanning parameters. _epi files can be a 3D or 4D - in the
latter case all timepoints share the same scanning parameters. To indicate which
run is intended to be used with which functional or diffusion scan the
IntendedFor field in the JSON file should be used.