Magnetic Resonance Spectroscopy

Support for Magnetic Resonance Spectroscopy (MRS) was developed as a BIDS Extension Proposal. Please see Citing BIDS on how to appropriately credit this extension when referring to it in the context of the academic literature.

Example datasets

Several example MRS datasets have been formatted using this specification and can be used for practical guidance when curating a new dataset.

MRS data

Template:

sub-<label>/
    [ses-<label>/]
        mrs/
            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_nuc-<label>][_voi-<label>][_rec-<label>][_run-<index>][_echo-<index>][_inv-<index>]_mrsi.json
            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_nuc-<label>][_voi-<label>][_rec-<label>][_run-<index>][_echo-<index>][_inv-<index>]_mrsi.nii[.gz]
            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_nuc-<label>][_voi-<label>][_rec-<label>][_run-<index>][_echo-<index>][_inv-<index>]_mrsref.json
            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_nuc-<label>][_voi-<label>][_rec-<label>][_run-<index>][_echo-<index>][_inv-<index>]_mrsref.nii[.gz]
            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_nuc-<label>][_voi-<label>][_rec-<label>][_run-<index>][_echo-<index>][_inv-<index>]_svs.json
            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_nuc-<label>][_voi-<label>][_rec-<label>][_run-<index>][_echo-<index>][_inv-<index>]_svs.nii[.gz]
            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_nuc-<label>][_voi-<label>][_rec-<label>][_run-<index>][_echo-<index>][_inv-<index>]_unloc.json
            sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_nuc-<label>][_voi-<label>][_rec-<label>][_run-<index>][_echo-<index>][_inv-<index>]_unloc.nii[.gz]

Legend:

For more information about filename elements (for example, entities, suffixes, extensions), follow the links embedded in the filename template.
Filename entities or directories between square brackets (for example, [_ses-<label>]) are OPTIONAL.
Some entities may only allow specific values, in which case those values are listed in <>, separated by |.
_<suffix> means that there are several (>6) valid suffixes for this filename pattern.
.<extension> means that there are several (>6) valid extensions for this file type.
[.gz] means that both the unzipped and gzipped versions of the extension are valid.

MRS is a spectroscopic technique based on the phenomenon of nuclear magnetic resonance that allows for the noninvasive detection and quantification of molecules in biochemical samples, such as brain tissue. It can be conducted in humans using conventional MRI systems.

Due to the diversity in manufacturers' MRS data file formats, source data MUST be converted into the NIfTI-MRS format (*.nii[.gz]) (doi:10.1002/mrm.29418). This format is based on the NIfTI framework and is designed to accommodate the nuances of raw MRS data. All necessary information to parse this *.nii[.gz] file (for example, spectrometer frequency, echo time, repetition time, and so on) are stored in a JSON header extension. Conversion of proprietary MRS file formats to NIfTI-MRS and extraction of some (but not all) BIDS-compliant metadata can be performed using spec2nii. Note that the "rawness" of data stored in the NIfTI-MRS file will depend on the format of the source data. It is RECOMMENDED that users export their source data from the scanner in an appropriately raw format prior to conversion.

For MRSI data, "raw" signifies spatially reconstructed data (that is, data in image space rather than (k,t)-space), given the complexity and diversity of sampling approaches. Note that NIfTI-MRS is not designed to store data that has not been spatially reconstructed.

Regarding source data, each manufacturer has its own file format (sometimes multiple formats) for exporting MRS data from the MRI scanner console for offline processing. GE exports a P-file (*.7) that stores unprocessed, un-coil-combined data with metadata embedded in a proprietary data header. Philips has multiple export formats, the most common being the SDAT/SPAR format. The *.sdat file contains either each coil-combined transient stored separately or all transients summed into a signal average. The *.spar file is a plaintext file describing acquisition parameters. It is also possible to export raw data as *.data/*.list or DICOM files. Siemens scanners allow data export in four formats: i) a proprietary DICOM-structured file known as IMA (*.ima); ii) a conventional DICOM MR Spectroscopy Storage format (*.dcm); iii) RDA (*.rda), a proprietary file format with a text-formatted header followed by the binary data points; and iv) TWIX (*.dat), a proprietary file format designed for storing unreconstructed, unprocessed MRS data from each individual coil element. The IMA, DICOM MRS, and RDA formats are typically used to export reconstructed and processed data; however, the sequence designer may choose to also allow the export of un-averaged transients or data from individual coil elements. Bruker data are are exported as two binary files: one file stores each transient separately, while the other stores the sum of the transients. A separate plaintext file stores the sequence name, voxel position, voxel orientation, and other metadata. All of these files are considered source data and, if present, MUST be stored in the sourcedata directory.

Single-voxel spectroscopy and MRS imaging

Name	`suffix`	Description
Single-voxel spectroscopy	svs	MRS acquisitions where the detected MR signal is spatially localized to a single volume.
Magnetic resonance spectroscopic imaging	mrsi	MRS acquisitions where additional imaging gradients are used to detect the MR signal from 1, 2, or 3 spatial dimensions.
Unlocalized spectroscopy	unloc	MRS acquisitions run without localization. This includes signals detected using coil sensitivity only.
Concentration or calibration reference	mrsref	An MRS acquisition collected to serve as a concentration reference for absolute quantification or as a calibration reference for preprocessing (for example, eddy-current correction).

A major distinction between MRS acquisitions is whether the acquisition technique probes spectral information from a single volume (single-voxel spectroscopy, SVS) or encodes this information along 1, 2, or 3 spatial dimensions resulting in multiple sub-volumes (MRS imaging, MRSI). To avoid confusion, the suffixes svs and mrsi MUST be used to distinguish the two techniques. For cases where localization is not used, the suffix unloc MUST be used.

Furthermore, it is common to acquire an additional MRS dataset that may serve as a reference for scaling metabolite signal levels (for example, to obtain concentrations) and/or for preprocessing steps (such as eddy-current correction, RF coil combination, phasing, and frequency calibration). This could be either an external reference (for example, a phantom or a synthetic signal) or, more typically, an internal tissue water reference. For such datasets, the suffix mrsref MUST be used. Should multiple references exist for a given dataset, the user MAY use the acq-<label> entity to distinguish the files. For example, sub-01_acq-conc_mrsref.nii.gz and sub-01_acq-ecc_mrsref.nii.gz could be used to name two references to be used for concentration scaling and eddy-current correction, respectively.

MRS sequences

Given the large variety of MRS sequences, there will be times when providing sufficient detail of acquisition parameters in filenames is helpful or necessary to distinguish datasets in a given study.

Here we present a set of labels that can be used when using the acq-<label> entity in the filename. These are based on the most commonly used in vivo MRS sequences/techniques, and are OPTIONAL to use. Users are free to choose any label they wish as long as they are consistent across participants and sessions and use only legal label characters. If used, the chosen label SHOULD also be described in the PulseSequenceType field in the sidecar JSON file.

Name	`label`	Description
PRESS	press	A double spin-echo sequence that achieves spatial localization by employing three slice-selective RF pulses: 90°–180°–180°–acq.
STEAM	steam	A stimulated-echo sequence that uses three 90° slice-selective pulses for spatial localization.
LASER	laser	LASER uses three pairs of slice-selective 180° adiabatic full-passage (AFP) refocusing pulses for localization. These are preceded by a non-slice-selective adiabatic half-passage (AHP) excitation pulse.
sLASER	slaser	sLASER is a modification of LASER where the AHP and first pair of AFP pulses are replaced with a non-adiabatic slice-selective 90° excitation pulse, typically employed to reduce the minimum TE.
SPECIAL	special	SPECIAL is a two-shot experiment. In the first shot, a pre-excitation slice-selective 180° AFP inversion pulse precedes a spin-echo acquisition with slice selection (90°–180°–acq). In the second shot, the adiabatic pulse is not applied. The 3D localized signal is derived by subtracting the two shots.
MEGA	mega	MEGA is a spectral editing technique that applies narrowband frequency-selective 180° pulses to refocus J-coupled spins at a specific frequency without affecting the spins of metabolites with resonances beyond the frequency range. Applying these pulses in alternating scans (for example, edit ON and edit OFF) and then subtracting the ON/OFF pairs results in a J-difference-edited spectrum that removes the unedited signals, leaving only those signals that were affected by the editing pulses.
HERMES	hermes	HERMES is an extension of MEGA editing whereby the two-step experiment becomes a four-step experiment. This permits multiple metabolites to be edited in a multiplexed manner. By employing Hadamard combination of the four edited sub-spectra, HERMES can reveal several metabolites unambiguously.
HERCULES	hercules	HERCULES is a different flavor of HERMES that targets more metabolites using the same four-step experiment.
Multiple quantum coherence (MQC) editing	mqc	MQC editing targets J-coupled resonances by selecting desired coherence pathways using MQ gradients and frequency-selective RF pulses.
Localized correlation spectroscopy (L-COSY)	lcosy	L-COSY is a 2D MRS technique whereby one of the interpulse durations is changed sequentially. A 2D Fourier transform produces a 2D spectrum that displays singlets on the diagonal and J-coupled metabolites on the off-diagonal, with the offsets equal to the J-coupling constants.
J-resolved spectroscopy	j	Another 2D technique, where in a J-resolved acquisition, a series of transients are collected at different TEs. A 2D Fourier transform is applied to generate a 2D spectrum where one dimension characterizes both chemical shift and J-coupling and the other only J-coupling.
Diffusion-weighted (DW) spectroscopy	dw	The diffusion of intracellular metabolites can be characterized using DW spectroscopy. In such acquisitions, the strength of gradients in a conventional MRS sequence is modulated to sensitize the metabolite signals to diffusion.
FID spectroscopy	fid	FID spectroscopy is a pulse-acquire acquisition where an excitation pulse is followed by direct acquisition of the FID. This approach is most often used in MRSI (that is, FID-MRSI) when combined with slice- or slab-selection.
Metabolite-cycled (MC) spectroscopy	mc	MC spectroscopy involves the use of asymmetric adiabatic inversion of the upfield and downfield parts of the MR spectrum, allowing for simultaneous acquisition of water and metabolite spectra.
Spin-echo spectroscopy	spinecho	An MRS experiment whereby the MR signal is detected using a spin-echo acquisition: 90°–180°–acq.

Each <label> in the table above MAY be combined with another to better describe the acquisition used. For example, megaspecial, jpress, dwslaser, mcdwsteam, and so on.

The OPTIONAL nuc-<label> entity can be used to distinguish acquisitions tuned to detect different nuclei. The label is the name of the nucleus or nuclei, which corresponds to DICOM Tag 0018, 9100. For example, nuc-1H, nuc-31P, nuc-1H13C. If used, the field ResonantNucleus MUST also be included in the corresponding sidecar JSON file, using the same label.

Similarly, the OPTIONAL voi-<label> entity can be used to distinguish between acquisitions localized to different regions (that is, acquisitions with different VOI). The label SHOULD be the name of the body region or part scanned. If used, the fields BodyPart and BodyPartDetails MUST also be included in the corresponding sidecar JSON file. BodyPartDetailsOntology is OPTIONAL to also include.

Key name	Requirement Level	Data type	Description
InstitutionName	RECOMMENDED	string	The name of the institution in charge of the equipment that produced the measurements.
InstitutionAddress	RECOMMENDED	string	The address of the institution in charge of the equipment that produced the measurements.
InstitutionalDepartmentName	RECOMMENDED	string	The department in the institution in charge of the equipment that produced the measurements.
Manufacturer	RECOMMENDED	string	Manufacturer of the equipment that produced the measurements.
ManufacturersModelName	RECOMMENDED	string	Manufacturer's model name of the equipment that produced the measurements.
DeviceSerialNumber	RECOMMENDED	string	The serial number of the equipment that produced the measurements. 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 measurements.
SoftwareVersions	RECOMMENDED	string	Manufacturer's designation of software version of the equipment that produced the measurements.
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 does not correspond to a tag in the DICOM ontology. The vendor-defined terminology for active coil elements can go in this field.
NumberReceiveCoilActiveElements	OPTIONAL	integer	The number of active RF elements used by the receive coil.
NumberTransmitCoilActiveElements	OPTIONAL	integer	The number of active RF elements used by the transmit coil.

Sequence specifics

Key name	Requirement Level	Data type	Description
PulseSequenceType	RECOMMENDED	string	A general description of the pulse sequence used for the scan. For example, `"sLASER"`, `"MEGA-PRESS"`, `"EPSI"`, `"Metabolite-cycled MRSI"`.
ScanningSequence	RECOMMENDED	string	Description of the type of data acquired. Must be one of: `"SVS"`, `"MRSI"`, `"Unlocalized MRS"`.
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"`).
MRAcquisitionType	OPTIONAL, but RECOMMENDED for MRSI	string	Type of sequence readout. Corresponds to DICOM Tag 0018, 0023 `MR Acquisition Type`. Must be one of: `"1D"`, `"2D"`, `"3D"`.
WaterSuppression	RECOMMENDED	boolean	Boolean indicating whether water suppression was used prior to acquisition. Must be one of: `"true"`, `"false"`.
WaterSuppressionTechnique	OPTIONAL	string	The name of the pulse sequence used for water suppression (for example, `"CHESS"`, `"VAPOR"`).
OuterVolumeSuppression	OPTIONAL	boolean	Boolean indicating whether outer-volume suppression was used prior to acquisition. Must be one of: `"true"`, `"false"`.
B0ShimmingTechnique	OPTIONAL	string	The technique used to shim the B₀ field (for example, `"Dynamic shim updating"` or `"FASTMAP"`).
B1ShimmingTechnique	OPTIONAL	string	The technique used to shim the B₁ field (for example, `"Simple phase align"` or `"Pre-saturated TurboFLASH"`).

Tissue description

Key name	Requirement Level	Data type	Description
BodyPart	OPTIONAL	string	Body part of the organ / body region scanned. Corresponds to DICOM Tag 0018, 0015 `Body Part Examined`.
BodyPartDetails	OPTIONAL	string	Additional details about body part or location (for example: `"corpus callosum"`).
BodyPartDetailsOntology	OPTIONAL	string	URI of ontology used for BodyPartDetails (for example: `"https://www.ebi.ac.uk/ols/ontologies/uberon"`).

MRS-relevant fields

Metadata fields that MUST be present:

Key name	Requirement Level	Data type	Description
ResonantNucleus	REQUIRED	string or array of strings	The isotope of interest of an MR experiment (for example, `"1H"`, `"13C"`, `"31P"`). For multi-nuclei experiments such as ¹H-[¹³C] MR, an array can be used: `["1H", "13C"]`. Corresponds to DICOM Tag 0018, 9100 `Resonant Nucleus`.
SpectrometerFrequency	REQUIRED	number or array of numbers	The frequency of the spectrometer, specified in MHz. For example, this could be `127.764` for a 3T scanner tuned to the resonant frequency of ¹H. For multi-nuclei experiments such as ¹H-[¹³C] MR at 3T, an array can be used: `[127.731, 32.125]`.
SpectralWidth	REQUIRED	number	The spectral bandwidth of the MR signal that is sampled, specified in Hz. Corresponds to DICOM Tag 0018, 9052 `Spectral Width`.
EchoTime	REQUIRED	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 where the value of this field is iterated using the `echo` entity.

SHOULD be present:

Key name	Requirement Level	Data type	Description
NumberOfSpectralPoints	RECOMMENDED	integer	The number of complex data points in each recorded transient of the detected time-domain MR signal, equivalent to the number of points in a single spectrum.
RepetitionTime	RECOMMENDED	number or array of numbers	The time between repetitions (TR), specified in seconds. For dynamic acquisitions, such as cardiac-triggered acquisitions where the TR may differ over the scan, an array of numbers can be used.
MixingTime	RECOMMENDED	number	In the context of a stimulated- and spin-echo 3D EPI sequence for B1+ mapping or a stimulated-echo MRS sequence, corresponds to the interval between spin- and stimulated-echo pulses. In the context of a diffusion-weighted double spin-echo sequence, corresponds to the interval between two successive diffusion sensitizing gradients, specified in seconds.
InversionTime	RECOMMENDED for inversion recovery data	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). Must be a number greater than 0.
FlipAngle	RECOMMENDED	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 where the value of this field is iterated using the `flip` entity.
AcquisitionVoxelSize	RECOMMENDED	array of numbers	An array of numbers with a length of 3, in millimeters. This field denotes the original acquisition voxel size, excluding any inter-slice gaps and before any interpolation or resampling within reconstruction or image processing. Any point spread function effects, for example due to T2-blurring, that would decrease the effective resolution are not considered here.
MatrixSize	RECOMMENDED for MRSI	array of integers	An array of integers with a length of 3 denoting the matrix size of the acquisition slab. This should be specified as, for example, `[32, 32, 1]` for a 2D acquisition or `[32, 1, 1]` for a 1D acquisition.
VolumeAffineMatrix	RECOMMENDED for MRSI	array of arrays	A 4-by-4 matrix using identical conventions and coordinate system to the {qs}form NIfTI affine matrix to define the orientation, position, and size of an additional VOI. This VOI defines a spatial region in addition to the primary method of localization (encoded in the NIfTI header {qs}form). Typically not defined for data stored with a single spatial voxel or FID-MRSI. For example: `[[30, 0, 0, -30], [0, 30, -2.27, -72.67], [0, 2.27, 29.91, 5.47], [0, 0, 0, 1]]`.
EncodingTechnique	RECOMMENDED for MRSI	string	The encoding technique used during readout. For example, `"Cartesian"`, `"EPSI"`, `"Spiral"`, or `"Density-weighted concentric ring trajectory"`.
ReferenceSignal	RECOMMENDED if MRS reference data are present	string or array of strings	The path(s) to the MRS reference file(s), if present, to which the associated MRS data file corresponds. Contains one or more BIDS URIs.
NumberOfTransients	RECOMMENDED	integer	The number of single applications of the pulse sequence recorded during an MRS acquisition.
AnatomicalImage	RECOMMENDED	string or array of strings	The path(s) to the anatomical MR image file(s), if present, to which the associated MRS data file corresponds. Contains one or more BIDS URIs.
MRAcquisitionType	RECOMMENDED	string	Type of sequence readout. Corresponds to DICOM Tag 0018, 0023 `MR Acquisition Type`. Must be one of: `"1D"`, `"2D"`, `"3D"`.

MAY be present:

Key name	Requirement Level	Data type	Description
ChemicalShiftOffset	OPTIONAL	number	The chemical shift at the center of `SpectralWidth` corresponding to 0 Hz, specified in ppm (for example, `4.65`).
ChemicalShiftReference	OPTIONAL	number	The chemical shift at the transmitter frequency, specified in ppm (for example, `2.68`). Corresponds to DICOM Tag 0018, 9053 `Chemical Shift Reference`.
EditTarget	OPTIONAL	string or array of strings	If spectral editing was applied, this describes the metabolites that were selectively targeted (for example, `"GABA"` or `"Lac"`). If multiple metabolites were targeted (for example, in a HERMES acquisition), an array can be used: `["GABA", "GSH"]`.
EditPulse	OPTIONAL	object of objects	If spectral editing was applied, this details the editing parameters. For example: `{"ON": {"FrequencyOffset": 1.9, "PulseDuration": 16}, "OFF": {"FrequencyOffset": 7.5, "PulseDuration": 16}}`.
EditCondition	OPTIONAL	string or array of strings	If spectral editing was applied, this lists the application order of `"EditPulse"`. For example, `["ON", "OFF"]` for a MEGA-edited experiment or `["A", "B", "C", "D"]` for a HERMES-edited experiment.
EchoAcquisition	OPTIONAL	string	How the detected echo was acquired when the analog-to-digital converter was turned on. For example, `"Half echo"`, `"Full echo"`.
ParallelReductionFactorInPlane	OPTIONAL	number	The parallel imaging (for instance, GRAPPA) factor in plane. 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	OPTIONAL	string	The type of parallel imaging used (for example `"GRAPPA"`, `"SENSE"`). Corresponds to DICOM Tag 0018, 9078 `Parallel Acquisition Technique`.
MultibandAccelerationFactor	OPTIONAL	number	The multiband factor, for multiband acquisitions.
PulseSequenceTiming	OPTIONAL	array of numbers	The time when each RF pulse of the pulse sequence was played out relative to the beginning of the pulse sequence (that is, the top of the excitation RF pulse), specified in seconds.
PulseSequencePulses	OPTIONAL	array of strings	The list of pulses used in the pulse sequence. If this field is specified, the array size MUST equal the array size of `"PulseSequenceTiming"`. The strings MAY be of the format `<pulse_name>_R<time-bandwidth_product>`. For example, a sLASER sequence may be described as such: `["P10_R6", "HS4_R25", "HS4_R25", "HS4_R25", "HS4_R25"]`.
ReceiveGain	OPTIONAL	number or array of numbers	The gain of the receive coil.

Example `*_svs.json`

{
  "InstitutionName": "Weill Cornell Medicine",
  "InstitutionAddress": "1300 York Avenue, New York, NY 10065, USA",
  "Manufacturer": "GE",
  "ManufacturersModelName": "Discovery MR750",
  "MagneticFieldStrength": 3,
  "PulseSequenceType": "PRESS",
  "ResonantNucleus": "1H",
  "SpectrometerFrequency": 127.771,
  "SpectralWidth": 2000,
  "EchoTime": 0.035,
  "NumberOfSpectralPoints": 2048,
  "NumberOfTransients": 64,
  "RepetitionTime": 2,
  "AcquisitionVoxelSize": [40, 20, 30],
  "BodyPart": "BRAIN",
  "BodyPartDetails": "Anterior cingulate cortex",
  "ReferenceSignal": "bids::sub-01/mrs/sub-01_acq-press_mrsref.nii.gz",
  "AnatomicalImage": "bids::sub-01/anat/sub-01_T1w.nii.gz"
}

Combining MRS with anatomical MRI

For combining MRS data with anatomical MRI data, see MRS-MRI correspondence in the Appendix.