From fc31bac9d47d4506bd65705b68a837fc317f289f Mon Sep 17 00:00:00 2001
From: markmikkelsen <mark.mikkelsen@gmail.com>
Date: Tue, 25 Oct 2022 19:41:56 -0400
Subject: [PATCH 01/70] First commit of bep022 into BIDS

Adding and changing files to introduce MRS to the BIDS specification.
---
 mkdocs.yml                                    |   1 +
 .../12-magnetic-resonance-spectroscopy.md     | 102 ++++++++++++++++++
 src/schema/objects/common_principles.yaml     |   2 +
 src/schema/objects/datatypes.yaml             |   4 +
 src/schema/objects/entities.yaml              |  11 ++
 src/schema/objects/modalities.yaml            |   3 +
 src/schema/objects/suffixes.yaml              |  24 +++++
 src/schema/rules/entities.yaml                |   1 +
 src/schema/rules/files/raw/mrs.yaml           |  19 ++++
 src/schema/rules/modalities.yaml              |   3 +
 src/schema/rules/sidecars/mrs.yaml            |  32 ++++++
 11 files changed, 202 insertions(+)
 create mode 100644 src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md
 create mode 100644 src/schema/rules/files/raw/mrs.yaml
 create mode 100644 src/schema/rules/sidecars/mrs.yaml

diff --git a/mkdocs.yml b/mkdocs.yml
index 0bb0d57ede..765955ded1 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -66,6 +66,7 @@ nav:
         - Positron Emission Tomography: 04-modality-specific-files/09-positron-emission-tomography.md
         - Microscopy: 04-modality-specific-files/10-microscopy.md
         - Near-Infrared Spectroscopy: 04-modality-specific-files/11-near-infrared-spectroscopy.md
+        - Magnetic Resonance Spectroscopy: 04-modality-specific-files/12-magnetic-resonance-spectroscopy.md
       - Derivatives:
         - BIDS Derivatives: 05-derivatives/01-introduction.md
         - Common data types and metadata: 05-derivatives/02-common-data-types.md
diff --git a/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md b/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md
new file mode 100644
index 0000000000..e1b828b743
--- /dev/null
+++ b/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md
@@ -0,0 +1,102 @@
+# Magnetic Resonance Spectroscopy
+
+Support for Magnetic Resonance Spectroscopy (MRS) was developed as a
+[BIDS Extension Proposal](../07-extensions.md#bids-extension-proposals).
+Please see [Citing BIDS](../01-introduction.md#citing-bids)
+on how to appropriately credit this extension when referring to it in the
+context of the academic literature.
+
+Several [example MRS datasets](https://github.com/bids-standard/bids-examples#mrs-datasets)
+have been formatted using this specification and can be used for practical guidance when curating a new dataset.
+
+## MRS data
+
+<!--
+This block generates filename templates.
+The inputs for this macro can be found in the directory
+  src/schema/rules/files
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filename_template(
+   "raw",
+   datatypes=["mrs"],
+   suffixes=["svs", "mrsi", "ref", "unloc"])
+}}
+
+Each manufacturer has its own file format (sometimes multiple formats) for exporting MRS data from the scanner console for offline processing.
+GE exports a P-file 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 average stored separately or all averages 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 and DICOM files.
+Siemens scanners allow data export in 4 formats:
+1) a proprietary DICOM structured file known as IMA (`*.ima`);
+2) a conventional DICOM MR Spectroscopy Storage format (`*.dcm`);
+3) RDA (`*.rda`) a proprietary file format with a text formatted header followed by the binary data points and
+4) TWIX (`*.dat`) a proprietary file format designed for storing unreconstructed and unprocessed MRS data from each individual coil element.
+IMA, DICOM MRS and RDA formats are typically used to export the 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.
+Contrarily, Bruker stores two binary files: one file stores each average separately,
+while the other file stores the sum of the average.
+Bruker stores the sequence, voxel position, and voxel orientation;
+other metadata are stored in a separate plaintext file.
+
+Due to the diversity in manufacturer MRS data formats, we define a single standardized format for storing MRS data.
+For compliance, data MUST be converted to the [NIfTI-MRS format](https://onlinelibrary.wiley.com/doi/10.1002/mrm.29418) (`*.nii.gz`),
+a data format based on the NIfTI framework designed to accommodate the nuances of raw MRS data.
+All necessary information to parse this `*.nii.gz` file (e.g., spectrometer frequency,
+echo time, repetition time, etc.) will be stored in a sidecar JSON (`*.json`) file.
+Conversion of proprietary MRS file formats to NIfTI-MRS and extraction of
+some (but not all) BIDS-compliant metadata can be performed using [spec2nii](https://github.com/wtclarke/spec2nii).
+Note that the "rawness" of data stored in the NIfTI-MRS file will depend
+on what format the source data are in.
+It is RECOMMENDED that users export their source data in an appropriately raw format
+prior to conversion.
+
+For MRSI data, "raw" signifies spatially reconstructed data
+(i.e., in image space rather than (k,t)-space),
+given the complexity and diversity of sampling approaches.
+NIfTI-MRS is not designed to store data that has not been spatially reconstructed.
+
+### Single-voxel spectroscopy and MRS imaging
+
+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 subvolumes (MRS imaging, MRSI).
+To avoid confusion, a suffix MUST be included in the filename and MUST be denoted as `svs` or `mrsi`.
+For cases where localization is not used, the suffix `unloc` SHOULD be used.
+
+Furthermore, it is common to acquire an additional MRS dataset that may serve
+as a reference for scaling metabolite levels (e.g., to obtain concentrations)
+and/or aid preprocessing steps such as eddy-current correction, RF coil combination, phasing, and frequency calibration.
+This could be either an external reference (e.g., a phantom or a synthetic signal) or,
+more typically, an internal tissue water reference.
+For such datasets, the suffix ref 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_ref.nii.gz` and `sub-01_acq-ecc_ref.nii.gz` could be used
+to name two references to be used for concentration scaling and eddy-current correction, respectively.
+
+| **Name**                                        | **`label`**         | **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.                          |
+| Concentration or calibration reference | ref                   | A separate MRS acquisition acquired to detect a signal to serve as a concentration reference for absolute quantification or for preprocessing (e.g., eddy-current correction).                          |
+| Unlocalized spectroscopy | unloc                   | MRS acquisitions run without localization. This includes signals detected using coil sensitivity only.                           |
+
+### MRS metadata JSON sidecar
+
+#### Scanner Hardware
+
+<!-- This block generates a metadata table.
+These tables are defined in
+  src/schema/rules/sidecars
+The definitions of the fields specified in these tables may be found in
+  src/schema/objects/metadata.yaml
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_sidecar_table("mri.MRIScannerHardware") }}
+
+#### Example `*_svs.json`
diff --git a/src/schema/objects/common_principles.yaml b/src/schema/objects/common_principles.yaml
index a418b74004..876286cfe8 100644
--- a/src/schema/objects/common_principles.yaml
+++ b/src/schema/objects/common_principles.yaml
@@ -41,6 +41,8 @@ data_type:
         11. `micr` (microscopy)
 
         12. `nirs` (near infrared spectroscopy)
+
+        13. `mrs` (magnetic resonance spectroscopy)
 dataset:
   name: Dataset
   display_name: Dataset
diff --git a/src/schema/objects/datatypes.yaml b/src/schema/objects/datatypes.yaml
index af82185bf0..a66bf90b9c 100644
--- a/src/schema/objects/datatypes.yaml
+++ b/src/schema/objects/datatypes.yaml
@@ -43,6 +43,10 @@ micr:
   value: micr
   display_name: Microscopy
   description: Microscopy
+mrs:
+  value: mrs
+  display_name: Magnetic Resonance Spectroscopy
+  description: Magnetic resonance spectroscopy data
 perf:
   value: perf
   display_name: Perfusion imaging
diff --git a/src/schema/objects/entities.yaml b/src/schema/objects/entities.yaml
index 2f97f01c8b..822d020186 100644
--- a/src/schema/objects/entities.yaml
+++ b/src/schema/objects/entities.yaml
@@ -186,6 +186,17 @@ mtransfer:
   enum:
     - 'on'
     - 'off'
+nucleus:
+  name: nuc
+  display_name: Nucleus
+  description: |
+    The `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`.
+    If present in the filename, `"ResonantNucleus"` MUST also be included in
+    the associated metadata.
+  type: string
+  format: label
 part:
   name: part
   display_name: Part
diff --git a/src/schema/objects/modalities.yaml b/src/schema/objects/modalities.yaml
index 16c7d5474d..631824cc9e 100644
--- a/src/schema/objects/modalities.yaml
+++ b/src/schema/objects/modalities.yaml
@@ -31,3 +31,6 @@ micr:
 nirs:
   display_name: Near-Infrared Spectroscopy
   description: Data acquired with NIRS.
+mrs:
+  display_name: Magnetic Resonance Spectroscopy
+  description: Data acquired with MRS.
diff --git a/src/schema/objects/suffixes.yaml b/src/schema/objects/suffixes.yaml
index 4c376d45ca..25a64e00bf 100644
--- a/src/schema/objects/suffixes.yaml
+++ b/src/schema/objects/suffixes.yaml
@@ -669,6 +669,12 @@ meg:
   description: |
     Unprocessed MEG data stored in the native file format of the MEG instrument
     with which the data was collected.
+mrsi:
+  value: mrsi
+  display_name: Magnetic resonance spectroscopy imaging
+  description: |
+    MRS acquisitions where additional imaging gradients are used
+    to detect the MR signal from 1, 2, or 3 spatial dimensions.
 nirs:
   value: nirs
   display_name: Near Infrared Spectroscopy
@@ -737,6 +743,13 @@ probseg:
     A probabilistic segmentation.
 
     This suffix may only be used in derivative datasets.
+ref:
+  value: ref
+  display_name: MRS
+  description: |
+    An MRS acquisition acquired to detect a signal to serve
+    as a concentration reference for absolute quantification
+    or for preprocessing (e.g., eddy-current correction).
 sbref:
   value: sbref
   display_name: Single-band reference image
@@ -776,8 +789,19 @@ stim:
   display_name: Continuous recording
   description: |
     Continuous measures, such as parameters of a film or audio stimulus.
+svs:
+  value: svs
+  display_name: Single-voxel spectroscopy
+  description: |
+    MRS acquisitions where the detected MR signal is spatially localized to a single volume.
 uCT:
   value: uCT
   display_name: Micro-CT
   description: |
     Micro-CT imaging data
+unloc:
+  value: unloc
+  display_name: Unlocalized spectroscopy
+  description: |
+    MRS acquisitions run without localization.
+    This includes signals detected using coil sensitivity only.
diff --git a/src/schema/rules/entities.yaml b/src/schema/rules/entities.yaml
index 08209723e5..f8c884fbb6 100644
--- a/src/schema/rules/entities.yaml
+++ b/src/schema/rules/entities.yaml
@@ -6,6 +6,7 @@
 - sample
 - task
 - acquisition
+- nucleus
 - ceagent
 - tracer
 - stain
diff --git a/src/schema/rules/files/raw/mrs.yaml b/src/schema/rules/files/raw/mrs.yaml
new file mode 100644
index 0000000000..f579fa4c9d
--- /dev/null
+++ b/src/schema/rules/files/raw/mrs.yaml
@@ -0,0 +1,19 @@
+---
+mrs:
+  suffixes:
+    - svs
+    - mrsi
+    - ref
+    - unloc
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+  datatypes:
+    - mrs
+  entities:
+    subject: required
+    session: optional
+    task: optional
+    acquisition: optional
+    run: optional
diff --git a/src/schema/rules/modalities.yaml b/src/schema/rules/modalities.yaml
index 9c9c15eb0d..3a01de1528 100644
--- a/src/schema/rules/modalities.yaml
+++ b/src/schema/rules/modalities.yaml
@@ -28,3 +28,6 @@ micr:
 nirs:
   datatypes:
     - nirs
+mrs:
+  datatypes:
+    - mrs
diff --git a/src/schema/rules/sidecars/mrs.yaml b/src/schema/rules/sidecars/mrs.yaml
new file mode 100644
index 0000000000..f3ac875ed2
--- /dev/null
+++ b/src/schema/rules/sidecars/mrs.yaml
@@ -0,0 +1,32 @@
+#
+# Groups of related metadata fields
+#
+# Assumptions: never need disjunction of selectors
+# Assumptions: top-to-bottom overrides is sufficient logic
+
+---
+# MRS Common metadata fields
+MRSScannerHardware:
+  selectors:
+    - modality == "mrs"
+  fields:
+    Manufacturer:
+      level: recommended
+      description_addendum: Corresponds to DICOM Tag 0008, 0070 `Manufacturer`.
+    ManufacturersModelName:
+      level: recommended
+      description_addendum: Corresponds to DICOM Tag 0008, 1090 `Manufacturers Model Name`.
+    DeviceSerialNumber:
+      level: recommended
+      description_addendum: Corresponds to DICOM Tag 0018, 1000 `DeviceSerialNumber`.
+    StationName:
+      level: recommended
+      description_addendum: Corresponds to DICOM Tag 0008, 1010 `Station Name`.
+    SoftwareVersions:
+      level: recommended
+      description_addendum: Corresponds to DICOM Tag 0018, 1020 `Software Versions`.
+    HardcopyDeviceSoftwareVersion: DEPRECATED
+    MagneticFieldStrength:
+      level: recommended
+    ReceiveCoilName: recommended
+    ReceiveCoilActiveElements: recommended

From 3f7b06fc3f7468348b43282bf46f05bb551419a9 Mon Sep 17 00:00:00 2001
From: markmikkelsen <mark.mikkelsen@gmail.com>
Date: Thu, 27 Oct 2022 20:46:47 -0400
Subject: [PATCH 02/70] More additions for bep022

- Added future publication ref in 01-introduction.md
- Added table of MRS sequences
- Starting to add new details for the MRS JSON sidecar
- Added MRS-MRI correspondence in Appendix
- Added volume as a new entity
- Changed order of MRS suffixes in src/schema/rulesfiles/raw/mrs.yaml
---
 src/01-introduction.md                        |  4 ++
 .../12-magnetic-resonance-spectroscopy.md     | 62 ++++++++++++++---
 .../cross-modality-correspondence.md          |  7 ++
 src/schema/objects/entities.yaml              |  9 +++
 src/schema/rules/entities.yaml                |  1 +
 src/schema/rules/files/raw/mrs.yaml           | 67 ++++++++++++++++++-
 src/schema/rules/sidecars/mrs.yaml            | 14 ++++
 7 files changed, 154 insertions(+), 10 deletions(-)

diff --git a/src/01-introduction.md b/src/01-introduction.md
index 9cfd3fe5ef..ff9c8be99a 100644
--- a/src/01-introduction.md
+++ b/src/01-introduction.md
@@ -160,6 +160,10 @@ For example:
 
 -   (publication forthcoming)
 
+#### MRS
+
+-   (publication forthcoming)
+
 ### Research Resource Identifier (RRID)
 
 BIDS has also a
diff --git a/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md b/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md
index e1b828b743..2a1e0c7dc3 100644
--- a/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md
+++ b/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md
@@ -43,9 +43,9 @@ Bruker stores the sequence, voxel position, and voxel orientation;
 other metadata are stored in a separate plaintext file.
 
 Due to the diversity in manufacturer MRS data formats, we define a single standardized format for storing MRS data.
-For compliance, data MUST be converted to the [NIfTI-MRS format](https://onlinelibrary.wiley.com/doi/10.1002/mrm.29418) (`*.nii.gz`),
+For compliance, data MUST be converted to the [NIfTI-MRS format](https://onlinelibrary.wiley.com/doi/10.1002/mrm.29418) (`*.nii[.gz]`),
 a data format based on the NIfTI framework designed to accommodate the nuances of raw MRS data.
-All necessary information to parse this `*.nii.gz` file (e.g., spectrometer frequency,
+All necessary information to parse this `*.nii[.gz]` file (e.g., spectrometer frequency,
 echo time, repetition time, etc.) will be stored in a sidecar JSON (`*.json`) file.
 Conversion of proprietary MRS file formats to NIfTI-MRS and extraction of
 some (but not all) BIDS-compliant metadata can be performed using [spec2nii](https://github.com/wtclarke/spec2nii).
@@ -55,7 +55,7 @@ It is RECOMMENDED that users export their source data in an appropriately raw fo
 prior to conversion.
 
 For MRSI data, "raw" signifies spatially reconstructed data
-(i.e., in image space rather than (k,t)-space),
+(i.e., in image space rather than (*k*,*t*)-space),
 given the complexity and diversity of sampling approaches.
 NIfTI-MRS is not designed to store data that has not been spatially reconstructed.
 
@@ -73,21 +73,65 @@ as a reference for scaling metabolite levels (e.g., to obtain concentrations)
 and/or aid preprocessing steps such as eddy-current correction, RF coil combination, phasing, and frequency calibration.
 This could be either an external reference (e.g., a phantom or a synthetic signal) or,
 more typically, an internal tissue water reference.
-For such datasets, the suffix ref MUST be used.
+For such datasets, the suffix `ref` 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_ref.nii.gz` and `sub-01_acq-ecc_ref.nii.gz` could be used
 to name two references to be used for concentration scaling and eddy-current correction, respectively.
 
-| **Name**                                        | **`label`**         | **Description**                                                                                                                                                                                      |
+| **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.                          |
 | Concentration or calibration reference | ref                   | A separate MRS acquisition acquired to detect a signal to serve as a concentration reference for absolute quantification or for preprocessing (e.g., eddy-current correction).                          |
 | Unlocalized spectroscopy | unloc                   | MRS acquisitions run without localization. This includes signals detected using coil sensitivity only.                           |
 
-### MRS metadata JSON sidecar
+### MRS sequences
+
+Given the large variety of MRS sequences, there will be times when
+providing sufficient detail of acquisition parameters is helpful
+or indeed necessary to distinguish between datasets in a given study.
+Thus, it is beneficial to provide sufficient detail in each sidecar JSON file.
+
+The following labels for the most commonly used in vivo MRS sequences/techniques are
+OPTIONAL to use when using the `acq-<label>` entity in the filename.
+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/sLASER                       | laser/slaser           | 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. In sLASER, 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° degree 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                   | This spectral editing technique employs a pair of frequency-selective 180° pulses to refocus *J*-coupled spins at a narrowband frequency without affecting the spins of metabolites with resonances beyond the frequency range. Applying these pulses in alternating scans (e.g., 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/HERCULES                    | hermes/hercules        | 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 is a different flavor of HERMES that targets more metabolites using the same four-step experiment.                |
+| Multiple-quantum coherence editing | mqc                    | Multiple-quantum coherence (MQC) editing targets *J*-coupled resonances by selecting desired coherence pathways using MQ gradients and frequency-selective RF pulses.                |
+| L-COSY                             | lcosy                  | Localized correlation spectroscopy (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, 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 the *J*-coupling constant.                              |
+| Diffusion-weighted spectroscopy    | dw                     | The diffusion of intracellular metabolites can be characterized using diffusion-weighted MRS. 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. When combined with slice- or slab-selection, , this approach is most often used in MRSI (i.e., FID-MRSI).         |
+| Spin-echo spectroscopy             | spinecho               | An MRS experiment whereby the MR signal is detected using a spin-echo acquisition: e.g., 90°–180°–acq.          |
+
+Each `<label>` in the table MAY be combined with another to, for instance,
+describe the localization approach used for more specific description of the acquisition.
+For example, `megaspecial`, `jpress`, `dwslaser`, and so on.
+
+## MRS metadata JSON sidecar
+
+### Scanner Hardware
+
+<!-- This block generates a metadata table.
+These tables are defined in
+  src/schema/rules/sidecars
+The definitions of the fields specified in these tables may be found in
+  src/schema/objects/metadata.yaml
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_sidecar_table("mrs.MRSScannerHardware") }}
 
-#### Scanner Hardware
+### Sequence Specifics
 
 <!-- This block generates a metadata table.
 These tables are defined in
@@ -97,6 +141,6 @@ The definitions of the fields specified in these tables may be found in
 A guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
-{{ MACROS___make_sidecar_table("mri.MRIScannerHardware") }}
+{{ MACROS___make_sidecar_table("mrs.MRSSequenceSpecifics") }}
 
-#### Example `*_svs.json`
+### Example `*_svs.json`
diff --git a/src/appendices/cross-modality-correspondence.md b/src/appendices/cross-modality-correspondence.md
index f77598d147..3d789fea40 100644
--- a/src/appendices/cross-modality-correspondence.md
+++ b/src/appendices/cross-modality-correspondence.md
@@ -12,3 +12,10 @@ The reason for this is that the MRI needs to be corrected for nonlinear gradient
 in order to fit the accompanying PET scans for co-registration
 (Knudsen et al. 2020, [doi:10.1177/0271678X20905433](https://doi.org/10.1177/0271678X20905433);
 Norgaard et al. 2019, [doi:10.1016/j.neuroimage.2019.05.055](https://doi.org/10.1016/j.neuroimage.2019.05.055)).
+
+## MRS-MRI correspondence
+
+It is typical to acquire a high-resolution 3D anatomical MR image alongside MRS data for
+voxel/slab placement, co-registration, and partial volume tissue correction of metabolite concentrations.
+To avoid incorrectly matching an MRS dataset with a corresponding anatomical MR image,
+it is RECOMMENDED that the field `AnatomicalImage` be included in the MRS sidecar JSON file.
diff --git a/src/schema/objects/entities.yaml b/src/schema/objects/entities.yaml
index 822d020186..d709b394b9 100644
--- a/src/schema/objects/entities.yaml
+++ b/src/schema/objects/entities.yaml
@@ -416,3 +416,12 @@ tracer:
     Please note that the `<label>` does not need to match the actual value of the field.
   type: string
   format: label
+volume:
+  name: voi
+  display_name: Volume of Interest
+  description: |
+    The `voi-<label>` entity can be used to distinguish sequences localized to different regions.
+    The label SHOULD be the name of the body region or part scanned.
+    If used, the entities `"BodyPart"` and `"BodyPartDetails"` MUST also be defined in the JSON file.
+  type: string
+  format: label
diff --git a/src/schema/rules/entities.yaml b/src/schema/rules/entities.yaml
index f8c884fbb6..9abda87d39 100644
--- a/src/schema/rules/entities.yaml
+++ b/src/schema/rules/entities.yaml
@@ -7,6 +7,7 @@
 - task
 - acquisition
 - nucleus
+- volume
 - ceagent
 - tracer
 - stain
diff --git a/src/schema/rules/files/raw/mrs.yaml b/src/schema/rules/files/raw/mrs.yaml
index f579fa4c9d..0b55a0206e 100644
--- a/src/schema/rules/files/raw/mrs.yaml
+++ b/src/schema/rules/files/raw/mrs.yaml
@@ -1,9 +1,69 @@
 ---
-mrs:
+svs:
   suffixes:
     - svs
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+  datatypes:
+    - mrs
+  entities:
+    subject: required
+    session: optional
+    task: optional
+    acquisition: optional
+    reconstruction: optional
+    run: optional
+    echo: optional
+    inversion: optional
+    nucleus: optional
+    volume: optional
+
+mrsi:
+  suffixes:
     - mrsi
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+  datatypes:
+    - mrs
+  entities:
+    subject: required
+    session: optional
+    task: optional
+    acquisition: optional
+    reconstruction: optional
+    run: optional
+    echo: optional
+    inversion: optional
+    nucleus: optional
+    volume: optional
+
+references:
+  suffixes:
     - ref
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+  datatypes:
+    - mrs
+  entities:
+    subject: required
+    session: optional
+    task: optional
+    acquisition: optional
+    reconstruction: optional
+    run: optional
+    echo: optional
+    inversion: optional
+    nucleus: optional
+    volume: optional
+
+unlocalized:
+  suffixes:
     - unloc
   extensions:
     - .nii.gz
@@ -16,4 +76,9 @@ mrs:
     session: optional
     task: optional
     acquisition: optional
+    reconstruction: optional
     run: optional
+    echo: optional
+    inversion: optional
+    nucleus: optional
+    volume: optional
diff --git a/src/schema/rules/sidecars/mrs.yaml b/src/schema/rules/sidecars/mrs.yaml
index f3ac875ed2..363967b940 100644
--- a/src/schema/rules/sidecars/mrs.yaml
+++ b/src/schema/rules/sidecars/mrs.yaml
@@ -30,3 +30,17 @@ MRSScannerHardware:
       level: recommended
     ReceiveCoilName: recommended
     ReceiveCoilActiveElements: recommended
+
+MRSSequenceSpecifics:
+  selectors:
+    - modality == "mrs"
+  fields:
+    PulseSequenceType:
+      level: recommended
+      description_addendum: A general description of the pulse sequence used for the scan (for example, "sLASER”, “MEGA-PRESS", "EPSI", "Metabolite-cycled MRSI").
+    ScanningSequence: recommended
+    SequenceVariant: recommended
+    ScanOptions: recommended
+    SequenceName: recommended
+    PulseSequenceDetails: recommended
+    MRAcquisitionType: recommended

From 04541ecf556f20907837799be3e24d5bf56684da Mon Sep 17 00:00:00 2001
From: markmikkelsen <mark.mikkelsen@gmail.com>
Date: Wed, 7 Dec 2022 11:52:50 -0500
Subject: [PATCH 03/70] Further updates for bep022

---
 .../12-magnetic-resonance-spectroscopy.md     | 172 +++++++++++-------
 src/schema/objects/metadata.yaml              |  44 ++++-
 src/schema/rules/sidecars/mri.yaml            |   4 +-
 src/schema/rules/sidecars/mrs.yaml            |  12 +-
 4 files changed, 160 insertions(+), 72 deletions(-)

diff --git a/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md b/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md
index 2a1e0c7dc3..3ef091b253 100644
--- a/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md
+++ b/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md
@@ -6,8 +6,9 @@ Please see [Citing BIDS](../01-introduction.md#citing-bids)
 on how to appropriately credit this extension when referring to it in the
 context of the academic literature.
 
-Several [example MRS datasets](https://github.com/bids-standard/bids-examples#mrs-datasets)
-have been formatted using this specification and can be used for practical guidance when curating a new dataset.
+Several [example MRS datasets](https://github.com/bids-standard/bids-examples#mrs-datasets) have
+been formatted using this specification and can be used for practical guidance when curating a new
+dataset.
 
 ## MRS data
 
@@ -24,59 +25,54 @@ and a guide for using macros can be found at
    suffixes=["svs", "mrsi", "ref", "unloc"])
 }}
 
-Each manufacturer has its own file format (sometimes multiple formats) for exporting MRS data from the scanner console for offline processing.
-GE exports a P-file 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 average stored separately or all averages 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 and DICOM files.
-Siemens scanners allow data export in 4 formats:
-1) a proprietary DICOM structured file known as IMA (`*.ima`);
-2) a conventional DICOM MR Spectroscopy Storage format (`*.dcm`);
-3) RDA (`*.rda`) a proprietary file format with a text formatted header followed by the binary data points and
-4) TWIX (`*.dat`) a proprietary file format designed for storing unreconstructed and unprocessed MRS data from each individual coil element.
-IMA, DICOM MRS and RDA formats are typically used to export the 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.
-Contrarily, Bruker stores two binary files: one file stores each average separately,
-while the other file stores the sum of the average.
-Bruker stores the sequence, voxel position, and voxel orientation;
-other metadata are stored in a separate plaintext file.
-
-Due to the diversity in manufacturer MRS data formats, we define a single standardized format for storing MRS data.
-For compliance, data MUST be converted to the [NIfTI-MRS format](https://onlinelibrary.wiley.com/doi/10.1002/mrm.29418) (`*.nii[.gz]`),
-a data format based on the NIfTI framework designed to accommodate the nuances of raw MRS data.
-All necessary information to parse this `*.nii[.gz]` file (e.g., spectrometer frequency,
-echo time, repetition time, etc.) will be stored in a sidecar JSON (`*.json`) file.
-Conversion of proprietary MRS file formats to NIfTI-MRS and extraction of
-some (but not all) BIDS-compliant metadata can be performed using [spec2nii](https://github.com/wtclarke/spec2nii).
-Note that the "rawness" of data stored in the NIfTI-MRS file will depend
-on what format the source data are in.
-It is RECOMMENDED that users export their source data in an appropriately raw format
-prior to conversion.
-
-For MRSI data, "raw" signifies spatially reconstructed data
-(i.e., in image space rather than (*k*,*t*)-space),
-given the complexity and diversity of sampling approaches.
-NIfTI-MRS is not designed to store data that has not been spatially reconstructed.
+Each manufacturer has its own file format (sometimes multiple formats) for exporting MRS data from
+the scanner console for offline processing. GE exports a P-file 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 average stored separately or all averages 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` and 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 and unprocessed MRS data from each individual coil element. 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. Contrarily, Bruker stores two binary files: one file stores each average separately, while
+the other file stores the sum of the average. Bruker stores the sequence name, voxel position, voxel
+orientation, and other metadata in a separate plaintext file. These files are considered source data
+and, if present, MUST be stored x.
+
+Due to the diversity in manufacturers' MRS data formats, raw data MUST be converted into the
+[NIfTI-MRS format](https://onlinelibrary.wiley.com/doi/10.1002/mrm.29418) (`*.nii[.gz]`). 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 (e.g., spectrometer frequency, echo time,
+repetition time, etc.) are stored in an JSON header extension. Conversion of proprietary MRS file
+formats to NIfTI-MRS and extractiaon of some (but not all) BIDS-compliant metadata can be performed
+using [spec2nii](https://github.com/wtclarke/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, 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.
 
 ### Single-voxel spectroscopy and MRS imaging
 
-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 subvolumes (MRS imaging, MRSI).
-To avoid confusion, a suffix MUST be included in the filename and MUST be denoted as `svs` or `mrsi`.
-For cases where localization is not used, the suffix `unloc` SHOULD be used.
-
-Furthermore, it is common to acquire an additional MRS dataset that may serve
-as a reference for scaling metabolite levels (e.g., to obtain concentrations)
-and/or aid preprocessing steps such as eddy-current correction, RF coil combination, phasing, and frequency calibration.
-This could be either an external reference (e.g., a phantom or a synthetic signal) or,
-more typically, an internal tissue water reference.
-For such datasets, the suffix `ref` 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_ref.nii.gz` and `sub-01_acq-ecc_ref.nii.gz` could be used
-to name two references to be used for concentration scaling and eddy-current correction, respectively.
+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 subvolumes (MRS imaging, MRSI). To avoid
+confusion, the suffixes `svs` amd `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 levels (e.g., to obtain concentrations) and/or aid preprocessing steps such as
+eddy-current correction, RF coil combination, phasing, and frequency calibration. This could be
+either an external reference (e.g., a phantom or a synthetic signal) or, more typically, an internal
+tissue water reference. For such datasets, the suffix `ref` 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_ref.nii.gz` and `sub-01_acq-ecc_ref.nii.gz` could be used to name two
+references to be used for concentration scaling and eddy-current correction, respectively.
 
 | **Name**                                        | **`suffix`**         | **Description**                                                                                                                                                                                      |
 | ------------------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -87,16 +83,15 @@ to name two references to be used for concentration scaling and eddy-current cor
 
 ### MRS sequences
 
-Given the large variety of MRS sequences, there will be times when
-providing sufficient detail of acquisition parameters is helpful
-or indeed necessary to distinguish between datasets in a given study.
-Thus, it is beneficial to provide sufficient detail in each sidecar JSON file.
+Given the large variety of MRS sequences, there will be times when providing sufficient detail of
+acquisition parameters is helpful or indeed necessary to distinguish between datasets in a given
+study. Thus, it is beneficial to provide sufficient detail in each sidecar JSON file.
 
-The following labels for the most commonly used in vivo MRS sequences/techniques are
-OPTIONAL to use when using the `acq-<label>` entity in the filename.
-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.
+The following labels for the most commonly used in vivo MRS sequences/techniques are OPTIONAL to use
+when using the `acq-<label>` entity in the filename. 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**                                                                                                                                                                                      |
 | ------------------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -113,13 +108,20 @@ If used, the chosen label SHOULD also be described in the `PulseSequenceType` fi
 | FID spectroscopy                   | fid                    | FID spectroscopy is a pulse-acquire acquisition where an excitation pulse is followed by direct acquisition of the FID. When combined with slice- or slab-selection, , this approach is most often used in MRSI (i.e., FID-MRSI).         |
 | Spin-echo spectroscopy             | spinecho               | An MRS experiment whereby the MR signal is detected using a spin-echo acquisition: e.g., 90°–180°–acq.          |
 
-Each `<label>` in the table MAY be combined with another to, for instance,
-describe the localization approach used for more specific description of the acquisition.
-For example, `megaspecial`, `jpress`, `dwslaser`, and so on.
+Each `<label>` in the table MAY be combined with another to describe the localization approach used
+for more specific description of the acquisition. For example, `megaspecial`, `jpress`, `dwslaser`,
+and so on.
 
-## MRS metadata JSON sidecar
+## MRS metadata
 
-### Scanner Hardware
+MRS data MUST be described by metadata fields, stored in sidecar JSON files (`*.json`).
+
+### Common metadata fields
+
+Metadata described in the following sections are shared with other MR modalities
+and SHOULD be present in sidecar JSON files.
+
+#### Scanner hardware
 
 <!-- This block generates a metadata table.
 These tables are defined in
@@ -131,7 +133,7 @@ A guide for using macros can be found at
 -->
 {{ MACROS___make_sidecar_table("mrs.MRSScannerHardware") }}
 
-### Sequence Specifics
+#### Sequence specifics
 
 <!-- This block generates a metadata table.
 These tables are defined in
@@ -143,4 +145,40 @@ A guide for using macros can be found at
 -->
 {{ MACROS___make_sidecar_table("mrs.MRSSequenceSpecifics") }}
 
+### MRS-specific fields
+
+Metadata fields that MUST be present:
+
+<!-- This block generates a metadata table.
+These tables are defined in
+  src/schema/rules/sidecars
+The definitions of the fields specified in these tables may be found in
+  src/schema/objects/metadata.yaml
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_sidecar_table("mrs.MRSRequiredFields") }}
+
+SHOULD be present:
+
+<!-- This block generates a metadata table.
+These tables are defined in
+  src/schema/rules/sidecars
+The definitions of the fields specified in these tables may be found in
+  src/schema/objects/metadata.yaml
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+
+MAY be present:
+
+<!-- This block generates a metadata table.
+These tables are defined in
+  src/schema/rules/sidecars
+The definitions of the fields specified in these tables may be found in
+  src/schema/objects/metadata.yaml
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+
 ### Example `*_svs.json`
diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index 8d83d4cef8..8c482a9b99 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -2116,6 +2116,12 @@ NumberOfVolumesDiscardedByUser:
     `"NumberOfVolumesDiscardedByUser"` field.
   type: integer
   minimum: 0
+NumberReceiveCoilActiveElements:
+  name: NumberReceiveCoilActiveElements
+  display_name: Number of Receive Coil Active Elements
+  description: |
+    The number of active RF elements used by the receive coil.
+  type: integer
 NumberShots:
   name: NumberShots
   display_name: Number Shots
@@ -2389,9 +2395,7 @@ PulseSequenceType:
   name: PulseSequenceType
   display_name: Pulse Sequence Type
   description: |
-    A general description of the pulse sequence used for the scan
-    (for example, `"MPRAGE"`, `"Gradient Echo EPI"`, `"Spin Echo EPI"`,
-    `"Multiband gradient echo EPI"`).
+    A general description of the pulse sequence used for the scan.
   type: string
 Purity:
   name: Purity
@@ -2606,6 +2610,19 @@ Resolution:
     - type: object
       additionalProperties:
         type: string
+ResonantNucleus:
+  name: ResonantNucleus
+  display_name: Resonant Nucleus
+  description: |
+    The isotope of interest of an MR experiment (for example, `"1H"`, `"13C"`, `"31P"`).
+    For multi-nuclei experiments such as <sup>1</sup>H-[<sup>13</sup>C] MR,
+    an array can be used: `["1H", "13C"]`.
+    Corresponds to DICOM Tag 0018, 9100 `Resonant Nucleus`.
+  anyOf:
+    - type: string
+    - type: array
+      items:
+        type: string
 SEEGChannelCount:
   name: SEEGChannelCount
   display_name: SEEG Channel Count
@@ -3037,6 +3054,27 @@ SpecificRadioactivityUnits:
     - type: string
       enum:
         - n/a
+SpectralWidth:
+  name: SpectralWidth
+  display_name: Spectral Width
+  description: |
+    The spectral bandwidth of the MR signal (in Hz) that is sampled (for example, `2000`).
+    Corresponds to DICOM Tag 0018, 9052 `Spectral Width`.
+  type: number
+SpectrometerFrequency:
+  name: SpectrometerFrequency
+  display_name: Spectrometer Frequency
+  description: |
+    The frequency of the spectrometer (in MHz).
+    For example, this could be `127.764` for a 3T scanner tuned
+    to the resonant frequency of <sup>1</sup>H.
+    For multi-nuclei experiments such as <sup>1</sup>H-[<sup>13</sup>C] MR at 3T,
+    an array can be used: `[127.731, 32.125]`.
+  anyOf:
+    - type: number
+    - type: array
+      items:
+        type: number
 SpoilingGradientDuration:
   name: SpoilingGradientDuration
   display_name: Spoiling Gradient Duration
diff --git a/src/schema/rules/sidecars/mri.yaml b/src/schema/rules/sidecars/mri.yaml
index e07a514ff0..887b5b13b2 100644
--- a/src/schema/rules/sidecars/mri.yaml
+++ b/src/schema/rules/sidecars/mri.yaml
@@ -47,7 +47,9 @@ MRISequenceSpecifics:
   selectors:
     - modality == "mri"
   fields:
-    PulseSequenceType: recommended
+    PulseSequenceType:
+      level: recommended
+      description_addendum: For example, `"MPRAGE"`, `"Gradient Echo EPI"`, `"Spin Echo EPI"`, `"Multiband gradient echo EPI"`.
     ScanningSequence: recommended
     SequenceVariant: recommended
     ScanOptions: recommended
diff --git a/src/schema/rules/sidecars/mrs.yaml b/src/schema/rules/sidecars/mrs.yaml
index 363967b940..30ea55a090 100644
--- a/src/schema/rules/sidecars/mrs.yaml
+++ b/src/schema/rules/sidecars/mrs.yaml
@@ -30,6 +30,7 @@ MRSScannerHardware:
       level: recommended
     ReceiveCoilName: recommended
     ReceiveCoilActiveElements: recommended
+    NumberReceiveCoilActiveElements: recommended
 
 MRSSequenceSpecifics:
   selectors:
@@ -37,10 +38,19 @@ MRSSequenceSpecifics:
   fields:
     PulseSequenceType:
       level: recommended
-      description_addendum: A general description of the pulse sequence used for the scan (for example, "sLASER”, “MEGA-PRESS", "EPSI", "Metabolite-cycled MRSI").
+      description_addendum: For example, `"sLASER"`, `"MEGA-PRESS"`, `"EPSI"`, `"Metabolite-cycled MRSI"`.
     ScanningSequence: recommended
     SequenceVariant: recommended
     ScanOptions: recommended
     SequenceName: recommended
     PulseSequenceDetails: recommended
     MRAcquisitionType: recommended
+
+MRSRequiredFields:
+  selectors:
+    - modality == "mrs"
+  fields:
+    ResonantNucleus: required
+    SpectrometerFrequency: required
+    SpectralWidth: required
+    EchoTime: required

From 7a8a3af466acb85cb5e6e464efa51ceb1d90328d Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Wed, 7 Dec 2022 17:38:55 -0500
Subject: [PATCH 04/70] Further updates

---
 .../12-magnetic-resonance-spectroscopy.md     | 97 +++++++------------
 src/schema/rules/sidecars/mrs.yaml            | 28 +++++-
 2 files changed, 64 insertions(+), 61 deletions(-)

diff --git a/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md b/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md
index 3ef091b253..d1b3280e36 100644
--- a/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md
+++ b/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md
@@ -41,7 +41,8 @@ designer may choose to also allow the export of un-averaged transients or data f
 elements. Contrarily, Bruker stores two binary files: one file stores each average separately, while
 the other file stores the sum of the average. Bruker stores the sequence name, voxel position, voxel
 orientation, and other metadata in a separate plaintext file. These files are considered source data
-and, if present, MUST be stored x.
+and, if present, MUST be stored in the
+[`/sourcedata`](../02-common-principles.md#source-vs-raw-vs-derived-data) directory.
 
 Due to the diversity in manufacturers' MRS data formats, raw data MUST be converted into the
 [NIfTI-MRS format](https://onlinelibrary.wiley.com/doi/10.1002/mrm.29418) (`*.nii[.gz]`). This
@@ -74,12 +75,12 @@ exist for a given dataset, the user MAY use the `acq-<label>` entity to distingu
 example, `sub-01_acq-conc_ref.nii.gz` and `sub-01_acq-ecc_ref.nii.gz` could be used to name two
 references to be used for concentration scaling and eddy-current correction, respectively.
 
-| **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.                          |
-| Concentration or calibration reference | ref                   | A separate MRS acquisition acquired to detect a signal to serve as a concentration reference for absolute quantification or for preprocessing (e.g., eddy-current correction).                          |
-| Unlocalized spectroscopy | unloc                   | MRS acquisitions run without localization. This includes signals detected using coil sensitivity only.                           |
+| **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.                                                       |
+| Concentration or calibration reference   | ref          | A separate MRS acquisition acquired to detect a signal to serve as a concentration reference for absolute quantification or for preprocessing (e.g., eddy-current correction). |
+| Unlocalized spectroscopy                 | unloc        | MRS acquisitions run without localization. This includes signals detected using coil sensitivity only.                                                                         |
 
 ### MRS sequences
 
@@ -93,24 +94,32 @@ long as they are consistent across participants and sessions and use only legal
 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/sLASER                       | laser/slaser           | 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. In sLASER, 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° degree 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                   | This spectral editing technique employs a pair of frequency-selective 180° pulses to refocus *J*-coupled spins at a narrowband frequency without affecting the spins of metabolites with resonances beyond the frequency range. Applying these pulses in alternating scans (e.g., 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/HERCULES                    | hermes/hercules        | 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 is a different flavor of HERMES that targets more metabolites using the same four-step experiment.                |
-| Multiple-quantum coherence editing | mqc                    | Multiple-quantum coherence (MQC) editing targets *J*-coupled resonances by selecting desired coherence pathways using MQ gradients and frequency-selective RF pulses.                |
-| L-COSY                             | lcosy                  | Localized correlation spectroscopy (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, 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 the *J*-coupling constant.                              |
-| Diffusion-weighted spectroscopy    | dw                     | The diffusion of intracellular metabolites can be characterized using diffusion-weighted MRS. 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. When combined with slice- or slab-selection, , this approach is most often used in MRSI (i.e., FID-MRSI).         |
-| Spin-echo spectroscopy             | spinecho               | An MRS experiment whereby the MR signal is detected using a spin-echo acquisition: e.g., 90°–180°–acq.          |
-
-Each `<label>` in the table MAY be combined with another to describe the localization approach used
-for more specific description of the acquisition. For example, `megaspecial`, `jpress`, `dwslaser`,
-and so on.
+| **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/sLASER                       | laser/slaser    | 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. In sLASER, 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° degree 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            | This spectral editing technique employs a pair of frequency-selective 180° pulses to refocus *J*-coupled spins at a narrowband frequency without affecting the spins of metabolites with resonances beyond the frequency range. Applying these pulses in alternating scans (e.g., 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/HERCULES                    | hermes/hercules | 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 is a different flavor of HERMES that targets more metabolites using the same four-step experiment.                                                                                |
+| Multiple-quantum coherence editing | mqc             | Multiple-quantum coherence (MQC) editing targets *J*-coupled resonances by selecting desired coherence pathways using MQ gradients and frequency-selective RF pulses.                                                                                                                                                                                                                                                                                                                            |
+| L-COSY                             | lcosy           | Localized correlation spectroscopy (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, 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 the *J*-coupling constant.                                                                                                                                                                                                     |
+| Diffusion-weighted spectroscopy    | dw              | The diffusion of intracellular metabolites can be characterized using diffusion-weighted MRS. 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. When combined with slice- or slab-selection, , this approach is most often used in MRSI (i.e., FID-MRSI).                                                                                                                                                                                                                                                                |
+| Spin-echo spectroscopy             | spinecho        | An MRS experiment whereby the MR signal is detected using a spin-echo acquisition: e.g., 90°–180°–acq.                                                                                                                                                                                                                                                                                                                                                                                           |
+
+Each `<label>` in the table MAY be combined with another to better describe the acquisition used.
+For example, `megaspecial`, `jpress`, `dwslaser`, and so on.
+
+The OPTIONAL `nuc-<label>` key/value pair 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. The key `"ResonantNucleus"` MUST also be included in the JSON file, with the same label.
+
+Similarly, the OPTIONAL `voi-<label>` key/value pair can be used to distinguish between repeated
+acquisitions localized to different regions (i.e., acquisitions with different VOI). The label
+SHOULD be the name of the body region or part scanned. If used, the entities `"BodyPart"` and
+`"BodyPartDetails"` MUST also be included in the JSON file.
 
 ## MRS metadata
 
@@ -135,50 +144,18 @@ A guide for using macros can be found at
 
 #### Sequence specifics
 
-<!-- This block generates a metadata table.
-These tables are defined in
-  src/schema/rules/sidecars
-The definitions of the fields specified in these tables may be found in
-  src/schema/objects/metadata.yaml
-A guide for using macros can be found at
- https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
--->
 {{ MACROS___make_sidecar_table("mrs.MRSSequenceSpecifics") }}
 
 ### MRS-specific fields
 
 Metadata fields that MUST be present:
 
-<!-- This block generates a metadata table.
-These tables are defined in
-  src/schema/rules/sidecars
-The definitions of the fields specified in these tables may be found in
-  src/schema/objects/metadata.yaml
-A guide for using macros can be found at
- https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
--->
 {{ MACROS___make_sidecar_table("mrs.MRSRequiredFields") }}
 
-SHOULD be present:
+SHOULD be present
 
-<!-- This block generates a metadata table.
-These tables are defined in
-  src/schema/rules/sidecars
-The definitions of the fields specified in these tables may be found in
-  src/schema/objects/metadata.yaml
-A guide for using macros can be found at
- https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
--->
-
-MAY be present:
+{{ MACROS___make_sidecar_table("mrs.MRSRecommendedFields") }}
 
-<!-- This block generates a metadata table.
-These tables are defined in
-  src/schema/rules/sidecars
-The definitions of the fields specified in these tables may be found in
-  src/schema/objects/metadata.yaml
-A guide for using macros can be found at
- https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
--->
+MAY be present
 
 ### Example `*_svs.json`
diff --git a/src/schema/rules/sidecars/mrs.yaml b/src/schema/rules/sidecars/mrs.yaml
index 30ea55a090..1ed4b3fbad 100644
--- a/src/schema/rules/sidecars/mrs.yaml
+++ b/src/schema/rules/sidecars/mrs.yaml
@@ -44,7 +44,7 @@ MRSSequenceSpecifics:
     ScanOptions: recommended
     SequenceName: recommended
     PulseSequenceDetails: recommended
-    MRAcquisitionType: recommended
+    MRAcquisitionType: recommended for MRSI
 
 MRSRequiredFields:
   selectors:
@@ -54,3 +54,29 @@ MRSRequiredFields:
     SpectrometerFrequency: required
     SpectralWidth: required
     EchoTime: required
+
+MRSRecommendedFields:
+  selectors:
+    - modality == "mrs"
+  fields:
+    NumberOfSpectralPoints: recommended
+    NumberOfTransients: recommended for SVS
+    RepetitionTime: recommended
+    MixingTime: recommended
+    InversionTime: recommended for inversion recovery data
+    FlipAngle: recommended
+    AcquisitionVoxelSize: recommended
+    MatrixSize: recommended
+    VolumeAffineMatrix: recommended for MRSI
+    BodyPart: recommended
+    BodyPartDetails: recommended
+    EditTarget: recommended for edited data
+    EditCondition: recommended for edited data
+    EditPulse: recommended for edited data
+    WaterSuppressed: recommended
+    WaterSuppressionTechnique: recommended
+    EncodingTechnique: recommended for MRSI
+    B0ShimmingTechnique: recommended
+    OuterVolumeSuppression: recommended
+    ReferenceSignal: recommended
+    AnatomicalImage: recommended in anatomical imaging data are present

From 2a644aa24b0b040c5c063dedd5ff1dcd83f67d75 Mon Sep 17 00:00:00 2001
From: markmikkelsen <mark.mikkelsen@gmail.com>
Date: Thu, 8 Dec 2022 09:56:54 -0500
Subject: [PATCH 05/70] Adding more metadata to MRS-specific fields

---
 .../12-magnetic-resonance-spectroscopy.md     |   6 +-
 src/schema/objects/metadata.yaml              | 136 +++++++++++++++++-
 src/schema/rules/sidecars/mrs.yaml            |   8 +-
 3 files changed, 142 insertions(+), 8 deletions(-)

diff --git a/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md b/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md
index d1b3280e36..75340177b2 100644
--- a/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md
+++ b/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md
@@ -97,7 +97,7 @@ 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.                                                                                                                                                                                                                                                                                                                                                                                                  |
+| STEAM                              | steam           | A stimulated-echo sequence that uses three 90° slice-selective pulses for spatial localization.                                                                                                                                                                                                                                                                                                                                                                                                  |
 | LASER/sLASER                       | laser/slaser    | 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. In sLASER, 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° degree 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            | This spectral editing technique employs a pair of frequency-selective 180° pulses to refocus *J*-coupled spins at a narrowband frequency without affecting the spins of metabolites with resonances beyond the frequency range. Applying these pulses in alternating scans (e.g., 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. |
@@ -152,10 +152,10 @@ Metadata fields that MUST be present:
 
 {{ MACROS___make_sidecar_table("mrs.MRSRequiredFields") }}
 
-SHOULD be present
+SHOULD be present:
 
 {{ MACROS___make_sidecar_table("mrs.MRSRecommendedFields") }}
 
-MAY be present
+MAY be present:
 
 ### Example `*_svs.json`
diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index 8c482a9b99..d57191f3e5 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -70,6 +70,18 @@ AnalyticalApproach:
     - type: array
       items:
         type: string
+AnatomicalImage:
+  name: AnatomicalImage
+  display_name: Anatomical Image
+  description: |
+    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](SPEC_ROOT/02-common-principles.md#bids-uri).
+    Using forward-slash separated paths relative to the participant subdirectory is [DEPRECATED](SPEC_ROOT/02-common-principles.md#definitions).
+  anyOf:
+    - type: string
+    - type: array
+      items:
+        type: string
 AnatomicalLandmarkCoordinateSystem:
   name: AnatomicalLandmarkCoordinateSystem
   display_name: Anatomical Landmark Coordinate System
@@ -230,6 +242,12 @@ B0FieldSource:
     - type: array
       items:
         type: string
+B0ShimmingTechnique:
+  name: B0ShimmingTechnique
+  display_name: B0 Shimming Technique
+  description: |
+    The technique used to shim the *B<sub>0</sub>* field (e.g., `"FASTMAP"`).
+  type: string
 BIDSVersion:
   name: BIDSVersion
   display_name: BIDS Version
@@ -868,6 +886,42 @@ EchoTime__fmap:
   type: number
   unit: s
   exclusiveMinimum: 0
+EditCondition:
+  name: EditCondition
+  display_name: Editing Condition
+  description: |
+    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.
+  anyOf:
+    - type: string
+    - type: array
+      items:
+        type: string
+EditPulse:
+  name: EditPulse
+  display_name: Editing Pulse
+  description: |
+    If spectral editing was applied, this details the editing parameters.
+    For example:
+    `{"ON": {"PulseOffset": 1.9, "PulseDuration": 16},
+      "OFF": {"PulseOffset": 7.5, "PulseDuration": 16}}`.
+  anyOf:
+    - type: object
+      additionalProperties:
+        type: object
+EditTarget:
+  name: EditTarget
+  display_name: Editing Target
+  description: |
+    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"]`.
+  anyOf:
+    - type: string
+    - type: array
+      items:
+        type: string
 EffectiveEchoSpacing:
   name: EffectiveEchoSpacing
   display_name: Effective Echo Spacing
@@ -917,6 +971,13 @@ ElectrodeManufacturersModelName:
     If different electrode types are used,
     please use the corresponding table in the `_electrodes.tsv` file.
   type: string
+EncodingTechnique:
+  name: EncodingTechnique
+  display_name: Encoding Technique
+  description: |
+    The encoding technique used during readout.
+    For example, `"Cartesian"`, `"EPSI"`, `"Spiral"`, or `"Density-weighted concentric ring trajectory"`.
+  type: string
 EpochLength:
   name: EpochLength
   display_name: Epoch Length
@@ -1876,6 +1937,18 @@ MatrixCoilMode:
     There are typically different default modes when using un-accelerated or
     accelerated (for example, `"GRAPPA"`, `"SENSE"`) imaging.
   type: string
+MatrixSize:
+  name: MatrixSize
+  display_name: Matrix Size
+  description: |
+    An array of numbers with a length of 3 denoting the matrix size of the acquisition slab.
+    For a 2D acquisition, this should be specified as, for example, `[32, 32, 1]`.
+  type: array
+  minItems: 3
+  maxItems: 3
+  items:
+    type: number
+    exclusiveMinimum: 0
 MaxMovement:
   name: MaxMovement
   display_name: Max Movement
@@ -1933,7 +2006,8 @@ MixingTime:
   name: MixingTime
   display_name: Mixing Time
   description: |
-    In the context of a stimulated- and spin-echo 3D EPI sequence for B1+ mapping,
+    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
@@ -2087,6 +2161,19 @@ NonlinearGradientCorrection:
     Boolean stating if the image saved has been corrected for gradient
     nonlinearities by the scanner sequence.
   type: boolean
+NumberOfSpectralPoints:
+  name: NumberOfSpectralPoints
+  display_name: Number Of Spectral Points
+  description: |
+    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.
+  type: number
+NumberOfTransients:
+  name: NumberOfTransients
+  display_name: Number Of Transients
+  description: |
+    The number of single applications of the pulse sequence recorded during an MRS acquisiton.
+  type: number
 NumberOfVolumesDiscardedByScanner:
   name: NumberOfVolumesDiscardedByScanner
   display_name: Number Of Volumes Discarded By Scanner
@@ -2162,6 +2249,12 @@ OtherAcquisitionParameters:
   description: |
     Description of other relevant image acquisition parameters.
   type: string
+OuterVolumeSuppression:
+  name: OuterVolumeSuppression
+  display_name: Other-Volume Suppression
+  description: |
+    Boolean indicating whether outer-volume suppression was used prior to acquisition.
+  type: boolean
 PASLType:
   name: PASLType
   display_name: PASL Type
@@ -2532,6 +2625,18 @@ ReferencesAndLinks:
   items:
     type: string
   type: array
+ReferenceSignal:
+  name: ReferenceSignal
+  display_name: Reference Signal
+  description: |
+    The path(s) to the reference MRS file(s), if present, to which the associated MRS data file corresponds.
+    Contains one or more [BIDS URIs](SPEC_ROOT/02-common-principles.md#bids-uri).
+    Using forward-slash separated paths relative to the participant subdirectory is [DEPRECATED](SPEC_ROOT/02-common-principles.md#definitions).
+  anyOf:
+    - type: string
+    - type: array
+      items:
+        type: string
 RepetitionTime:
   name: RepetitionTime
   display_name: Repetition Time
@@ -3343,6 +3448,22 @@ VascularCrushingVENC:
       items:
         type: number
         unit: cm/s
+VolumeAffineMatrix:
+  name: VolumeAffineMatrix
+  display_name: Volume Affine Matrix
+  description: |
+    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]]`.
+  type: array
+  items:
+    type: number
 VolumeTiming:
   name: VolumeTiming
   display_name: Volume Timing
@@ -3360,6 +3481,19 @@ VolumeTiming:
   items:
     type: number
     unit: s
+WaterSuppressed:
+  name: WaterSuppressed
+  display_name: Water-Suppressed
+  description: |
+    Boolean indicating whether or not water suppression was used prior to acquisition.
+  type: boolean
+WaterSuppressionTechnique:
+  name: WaterSuppressionTechnique
+  display_name: Water Suppression Technique
+  description: |
+    The name of the pulse sequence used for water suppression (for example, `"CHESS"`, `"VAPOR"`).
+    If no water suppression was used (for example, when collecting water-unsuppressed spectra), set as `null`.
+  type: string
 WholeBloodAvail:
   name: WholeBloodAvail
   display_name: Whole Blood Avail
diff --git a/src/schema/rules/sidecars/mrs.yaml b/src/schema/rules/sidecars/mrs.yaml
index 1ed4b3fbad..68d6a6ca70 100644
--- a/src/schema/rules/sidecars/mrs.yaml
+++ b/src/schema/rules/sidecars/mrs.yaml
@@ -66,17 +66,17 @@ MRSRecommendedFields:
     InversionTime: recommended for inversion recovery data
     FlipAngle: recommended
     AcquisitionVoxelSize: recommended
-    MatrixSize: recommended
+    MatrixSize: recommended for MRSI
     VolumeAffineMatrix: recommended for MRSI
     BodyPart: recommended
     BodyPartDetails: recommended
     EditTarget: recommended for edited data
-    EditCondition: recommended for edited data
     EditPulse: recommended for edited data
+    EditCondition: recommended for edited data
     WaterSuppressed: recommended
     WaterSuppressionTechnique: recommended
     EncodingTechnique: recommended for MRSI
     B0ShimmingTechnique: recommended
     OuterVolumeSuppression: recommended
-    ReferenceSignal: recommended
-    AnatomicalImage: recommended in anatomical imaging data are present
+    ReferenceSignal: recommended if MRS reference data are present
+    AnatomicalImage: recommended if anatomical MRI data are present

From eed04ce8ac82864a6d9ef7a9ffd7a8b631d5323d Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Thu, 8 Dec 2022 16:43:41 -0500
Subject: [PATCH 06/70] Finalizing additions for bep022

---
 .../12-magnetic-resonance-spectroscopy.md     | 181 ++++++++++--------
 .../cross-modality-correspondence.md          |   4 +-
 src/schema/objects/metadata.yaml              | 181 ++++++++++++++----
 src/schema/rules/files/raw/mrs.yaml           |   2 +-
 src/schema/rules/sidecars/mri.yaml            |  25 ++-
 src/schema/rules/sidecars/mrs.yaml            |  57 +++---
 6 files changed, 304 insertions(+), 146 deletions(-)

diff --git a/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md b/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md
index 75340177b2..904d9a2a74 100644
--- a/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md
+++ b/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md
@@ -26,109 +26,113 @@ and a guide for using macros can be found at
 }}
 
 Each manufacturer has its own file format (sometimes multiple formats) for exporting MRS data from
-the scanner console for offline processing. GE exports a P-file 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 average stored separately or all averages 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` and 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 and unprocessed MRS data from each individual coil element. 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. Contrarily, Bruker stores two binary files: one file stores each average separately, while
-the other file stores the sum of the average. Bruker stores the sequence name, voxel position, voxel
-orientation, and other metadata in a separate plaintext file. These files are considered source data
-and, if present, MUST be stored in the
+the scanner console for offline processing.
+GE exports a P-file 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 transient 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` and 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.
+Contrarily, Bruker stores two binary files: one file stores each transient separately,
+while the other stores the sum of the transients.
+Bruker stores the sequence name, voxel position, voxel orientation, and other metadata in a separate plaintext file.
+These files are considered source data and, if present, MUST be stored in the
 [`/sourcedata`](../02-common-principles.md#source-vs-raw-vs-derived-data) directory.
 
-Due to the diversity in manufacturers' MRS data formats, raw data MUST be converted into the
-[NIfTI-MRS format](https://onlinelibrary.wiley.com/doi/10.1002/mrm.29418) (`*.nii[.gz]`). 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 (e.g., spectrometer frequency, echo time,
-repetition time, etc.) are stored in an JSON header extension. Conversion of proprietary MRS file
-formats to NIfTI-MRS and extractiaon of some (but not all) BIDS-compliant metadata can be performed
-using [spec2nii](https://github.com/wtclarke/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.
+Due to the diversity in manufacturers' MRS data file formats, source data MUST be converted into the
+[NIfTI-MRS format](https://onlinelibrary.wiley.com/doi/10.1002/mrm.29418) (`*.nii[.gz]`).
+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](https://github.com/wtclarke/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, 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.
+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.
 
 ### 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.                                                              |
+| Concentration or calibration reference   | ref          | A separate MRS acquisition acquired to detect a signal to serve as a concentration reference for absolute quantification or for preprocessing (for example, eddy-current correction). |
+| Unlocalized spectroscopy                 | unloc        | MRS acquisitions run without localization. This includes signals detected using coil sensitivity only.                                                                                |
+
 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 subvolumes (MRS imaging, MRSI). To avoid
-confusion, the suffixes `svs` amd `mrsi` MUST be used to distinguish the two techniques. For cases
-where localization is not used, the suffix `unloc` MUST be used.
+1, 2, or 3 spatial dimensions resulting in multiple sub-volumes (MRS imaging, MRSI).
+To avoid confusion, the suffixes `svs` amd `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 levels (e.g., to obtain concentrations) and/or aid preprocessing steps such as
-eddy-current correction, RF coil combination, phasing, and frequency calibration. This could be
-either an external reference (e.g., a phantom or a synthetic signal) or, more typically, an internal
-tissue water reference. For such datasets, the suffix `ref` 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_ref.nii.gz` and `sub-01_acq-ecc_ref.nii.gz` could be used to name two
-references to be used for concentration scaling and eddy-current correction, respectively.
-
-| **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.                                                       |
-| Concentration or calibration reference   | ref          | A separate MRS acquisition acquired to detect a signal to serve as a concentration reference for absolute quantification or for preprocessing (e.g., eddy-current correction). |
-| Unlocalized spectroscopy                 | unloc        | MRS acquisitions run without localization. This includes signals detected using coil sensitivity only.                                                                         |
+scaling metabolite levels (for example, to obtain concentrations) and/or aid 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 `ref` 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_ref.nii.gz` and `sub-01_acq-ecc_ref.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 is helpful or indeed necessary to distinguish between datasets in a given
-study. Thus, it is beneficial to provide sufficient detail in each sidecar JSON file.
+acquisition parameters is helpful or necessary to distinguish datasets in a given study.
 
 The following labels for the most commonly used in vivo MRS sequences/techniques are OPTIONAL to use
-when using the `acq-<label>` entity in the filename. 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/sLASER                       | laser/slaser    | 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. In sLASER, 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° degree 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            | This spectral editing technique employs a pair of frequency-selective 180° pulses to refocus *J*-coupled spins at a narrowband frequency without affecting the spins of metabolites with resonances beyond the frequency range. Applying these pulses in alternating scans (e.g., 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/HERCULES                    | hermes/hercules | 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 is a different flavor of HERMES that targets more metabolites using the same four-step experiment.                                                                                |
-| Multiple-quantum coherence editing | mqc             | Multiple-quantum coherence (MQC) editing targets *J*-coupled resonances by selecting desired coherence pathways using MQ gradients and frequency-selective RF pulses.                                                                                                                                                                                                                                                                                                                            |
-| L-COSY                             | lcosy           | Localized correlation spectroscopy (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, 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 the *J*-coupling constant.                                                                                                                                                                                                     |
-| Diffusion-weighted spectroscopy    | dw              | The diffusion of intracellular metabolites can be characterized using diffusion-weighted MRS. 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. When combined with slice- or slab-selection, , this approach is most often used in MRSI (i.e., FID-MRSI).                                                                                                                                                                                                                                                                |
-| Spin-echo spectroscopy             | spinecho        | An MRS experiment whereby the MR signal is detected using a spin-echo acquisition: e.g., 90°–180°–acq.                                                                                                                                                                                                                                                                                                                                                                                           |
+when using the `acq-<label>` entity in the filename.
+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/sLASER                       | laser/slaser    | 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. In sLASER, 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            | This spectral editing technique employs a pair of frequency-selective 180° pulses to refocus *J*-coupled spins at a narrowband 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/HERCULES                    | hermes/hercules | 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 is a different flavor of HERMES that targets more metabolites using the same four-step experiment.                                                                                       |
+| Multiple-quantum coherence editing | mqc             | Multiple-quantum coherence (MQC) editing targets *J*-coupled resonances by selecting desired coherence pathways using MQ gradients and frequency-selective RF pulses.                                                                                                                                                                                                                                                                                                                                   |
+| L-COSY                             | lcosy           | Localized correlation spectroscopy (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 spectroscopy    | dw              | The diffusion of intracellular metabolites can be characterized using diffusion-weighted MRS. 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.                                                                                                                                                                                                                                                                       |
+| Spin-echo spectroscopy             | spinecho        | An MRS experiment whereby the MR signal is detected using a spin-echo acquisition: for example, 90°–180°–acq.                                                                                                                                                                                                                                                                                                                                                                                           |
 
 Each `<label>` in the table MAY be combined with another to better describe the acquisition used.
 For example, `megaspecial`, `jpress`, `dwslaser`, and so on.
 
-The OPTIONAL `nuc-<label>` key/value pair 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. The key `"ResonantNucleus"` MUST also be included in the JSON file, with the same label.
+The OPTIONAL `nuc-<label>` key/value pair 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.
+The key `"ResonantNucleus"` MUST also be included in the sidecar JSON file, with the same label.
 
 Similarly, the OPTIONAL `voi-<label>` key/value pair can be used to distinguish between repeated
-acquisitions localized to different regions (i.e., acquisitions with different VOI). The label
-SHOULD be the name of the body region or part scanned. If used, the entities `"BodyPart"` and
-`"BodyPartDetails"` MUST also be included in the JSON file.
+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 entities `"BodyPart"` and `"BodyPartDetails"` MUST also be included in the sidecar JSON file.
 
-## MRS metadata
+## Sidecar JSON
 
-MRS data MUST be described by metadata fields, stored in sidecar JSON files (`*.json`).
+MRS data files MUST be described by metadata fields, stored in sidecar JSON files (`*.json`).
 
 ### Common metadata fields
 
-Metadata described in the following sections are shared with other MR modalities
-and SHOULD be present in sidecar JSON files.
+Metadata described in the following sections are shared with other MR modalities and SHOULD be
+present in the sidecar JSON files.
 
 #### Scanner hardware
 
@@ -158,4 +162,29 @@ SHOULD be present:
 
 MAY be present:
 
+{{ MACROS___make_sidecar_table("mrs.MRSOptionalFields") }}
+
 ### Example `*_svs.json`
+
+```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_ref.nii.gz",
+   "AnatomicalImage": "bids::sub-01/anat/sub-01_T1w.nii.gz"
+}
+```
diff --git a/src/appendices/cross-modality-correspondence.md b/src/appendices/cross-modality-correspondence.md
index 3d789fea40..73e4384907 100644
--- a/src/appendices/cross-modality-correspondence.md
+++ b/src/appendices/cross-modality-correspondence.md
@@ -15,7 +15,7 @@ Norgaard et al. 2019, [doi:10.1016/j.neuroimage.2019.05.055](https://doi.org/10.
 
 ## MRS-MRI correspondence
 
-It is typical to acquire a high-resolution 3D anatomical MR image alongside MRS data for
+It is typical to acquire high-resolution 3D anatomical MR images alongside MRS data for
 voxel/slab placement, co-registration, and partial volume tissue correction of metabolite concentrations.
 To avoid incorrectly matching an MRS dataset with a corresponding anatomical MR image,
-it is RECOMMENDED that the field `AnatomicalImage` be included in the MRS sidecar JSON file.
+it is RECOMMENDED that the field `AnatomicalImage` be included in the MRS sidecar JSON files.
diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index d57191f3e5..0dcbed9158 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -74,9 +74,11 @@ AnatomicalImage:
   name: AnatomicalImage
   display_name: Anatomical Image
   description: |
-    The path(s) to the anatomical MR image file(s), if present, to which the associated MRS data file corresponds.
+    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](SPEC_ROOT/02-common-principles.md#bids-uri).
-    Using forward-slash separated paths relative to the participant subdirectory is [DEPRECATED](SPEC_ROOT/02-common-principles.md#definitions).
+    Using forward-slash separated paths relative to the participant subdirectory is
+    [DEPRECATED](SPEC_ROOT/02-common-principles.md#definitions).
   anyOf:
     - type: string
     - type: array
@@ -246,7 +248,13 @@ B0ShimmingTechnique:
   name: B0ShimmingTechnique
   display_name: B0 Shimming Technique
   description: |
-    The technique used to shim the *B<sub>0</sub>* field (e.g., `"FASTMAP"`).
+    The technique used to shim the *B<sub>0</sub>* field (for example, `"FASTMAP"`).
+  type: string
+B1ShimmingTechnique:
+  name: B1ShimmingTechnique
+  display_name: B1 Shimming Technique
+  description: |
+    The technique used to shim the *B<sub>1</sub>* field (for example, `"Simple phase align"`).
   type: string
 BIDSVersion:
   name: BIDSVersion
@@ -404,6 +412,20 @@ CellType:
     Values SHOULD come from the
     [cell ontology](http://obofoundry.org/ontology/cl.html).
   type: string
+ChemicalShiftOffset:
+  name: ChemicalShiftOffset
+  display_name: Chemical Shift Offset
+  description: |
+    The chemical shift at the center of `"SpectralWidth"` corresponding to 0 Hz,
+    specified in ppm (for example, `4.65`).
+  type: number
+ChemicalShiftReference:
+  name: ChemicalShiftReference
+  display_name: Chemical Shift Reference
+  description: |
+    The chemical shift at the transmitter frequency, specified in ppm (for example, `2.68`).
+    Corresponds to DICOM Tag 0018, 9053 `Chemical Shift Reference`.
+  type: number
 ChunkTransformationMatrix:
   name: ChunkTransformationMatrix
   display_name: Chunk Transformation Matrix
@@ -834,6 +856,13 @@ EOGChannelCount:
     Number of EOG channels.
   type: integer
   minimum: 0
+EchoAcquisition:
+  name: EchoAcquisition
+  display_name: Echo Acquisition
+  description: |
+    How the detected echo was acquired when the analog-to-digital converter was turned on.
+    For example, `"Half echo"`, `"Full echo"`.
+  type: string
 EchoTime:
   name: EchoTime
   display_name: Echo Time
@@ -846,12 +875,6 @@ EchoTime:
     [file collection](SPEC_ROOT/appendices/file-collections.md)
     where the value of this field is iterated using the
     [`echo` entity](SPEC_ROOT/appendices/entities.md#echo).
-    The data type array provides a value for each volume in a 4D dataset and
-    should only be used when the volume timing is critical for interpretation
-    of the data, such as in
-    [ASL](SPEC_ROOT/04-modality-specific-files/01-magnetic-resonance-imaging-data.md#\
-    arterial-spin-labeling-perfusion-data)
-    or variable echo time fMRI sequences.
   anyOf:
     - type: number
       unit: s
@@ -891,7 +914,8 @@ EditCondition:
   display_name: Editing Condition
   description: |
     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.
+    For example, `["ON", "OFF"]` for a MEGA-edited experiment or
+    `["A", "B", "C", "D"]` for a HERMES-edited experiment.
   anyOf:
     - type: string
     - type: array
@@ -903,8 +927,8 @@ EditPulse:
   description: |
     If spectral editing was applied, this details the editing parameters.
     For example:
-    `{"ON": {"PulseOffset": 1.9, "PulseDuration": 16},
-      "OFF": {"PulseOffset": 7.5, "PulseDuration": 16}}`.
+    `{"ON": {"FrequencyOffset": 1.9, "PulseDuration": 16},
+    "OFF": {"FrequencyOffset": 7.5, "PulseDuration": 16}}`.
   anyOf:
     - type: object
       additionalProperties:
@@ -976,7 +1000,8 @@ EncodingTechnique:
   display_name: Encoding Technique
   description: |
     The encoding technique used during readout.
-    For example, `"Cartesian"`, `"EPSI"`, `"Spiral"`, or `"Density-weighted concentric ring trajectory"`.
+    For example, `"Cartesian"`, `"EPSI"`, `"Spiral"`,
+    or `"Density-weighted concentric ring trajectory"`.
   type: string
 EpochLength:
   name: EpochLength
@@ -1082,12 +1107,6 @@ FlipAngle:
     [file collection](SPEC_ROOT/appendices/file-collections.md)
     where the value of this field is iterated using the
     [`flip` entity](SPEC_ROOT/appendices/entities.md#flip).
-    The data type array provides a value for each volume in a 4D dataset and
-    should only be used when the volume timing is critical for interpretation of
-    the data, such as in
-    [ASL](SPEC_ROOT/04-modality-specific-files/01-magnetic-resonance-imaging-data.md#\
-    arterial-spin-labeling-perfusion-data)
-    or variable flip angle fMRI sequences.
   anyOf:
     - type: number
       unit: degree
@@ -1834,6 +1853,16 @@ MRAcquisitionType:
   enum:
     - 2D
     - 3D
+MRAcquisitionType__mrs:
+  name: MRAcquisitionType
+  display_name: MR Acquisition Type
+  description: |
+    Type of sequence readout.
+  type: string
+  enum:
+    - 1D
+    - 2D
+    - 3D
 MRTransmitCoilSequence:
   name: MRTransmitCoilSequence
   display_name: MR Transmit Coil Sequence
@@ -1941,14 +1970,15 @@ MatrixSize:
   name: MatrixSize
   display_name: Matrix Size
   description: |
-    An array of numbers with a length of 3 denoting the matrix size of the acquisition slab.
-    For a 2D acquisition, this should be specified as, for example, `[32, 32, 1]`.
+    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.
   type: array
   minItems: 3
   maxItems: 3
   items:
-    type: number
-    exclusiveMinimum: 0
+    type: integer
+    exclusiveMinimum: 1
 MaxMovement:
   name: MaxMovement
   display_name: Max Movement
@@ -2167,13 +2197,13 @@ NumberOfSpectralPoints:
   description: |
     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.
-  type: number
+  type: integer
 NumberOfTransients:
   name: NumberOfTransients
   display_name: Number Of Transients
   description: |
     The number of single applications of the pulse sequence recorded during an MRS acquisiton.
-  type: number
+  type: integer
 NumberOfVolumesDiscardedByScanner:
   name: NumberOfVolumesDiscardedByScanner
   display_name: Number Of Volumes Discarded By Scanner
@@ -2228,6 +2258,12 @@ NumberShots:
     - type: array
       items:
         type: number
+NumberTransmitCoilActiveElements:
+  name: NumberTransmitCoilActiveElements
+  display_name: Number of Transmit Coil Active Elements
+  description: |
+    The number of active RF elements used by the transmit coil.
+  type: integer
 NumericalAperture:
   name: NumericalAperture
   display_name: Numerical Aperture
@@ -2484,6 +2520,29 @@ PulseSequenceDetails:
     `"Siemens WIP ### version #.##,"` or
     `"Sequence written by X using a version compiled on MM/DD/YYYY"`).
   type: string
+PulseSequencePulses:
+  name: PulseSequencePulses
+  display_name: Pulse Sequence Pulses
+  description: |
+    The list of pulses used in the pulse sequence.
+    If this parameter is specified, the array MUST correspond to the array of timings in
+    `"PulseSequenceTiming"`.
+    That is, the length of both arrays MUST be equal.
+    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"]`.
+  type: array
+  items:
+    type: string
+PulseSequenceTiming:
+  name: PulseSequenceTiming
+  display_name: Pulse Sequence Timing
+  description: |
+    The time when each RF pulse of the pulse sequence was played out relative to
+    the beginning of the pulse sequence, specified in seconds.
+  type: array
+  items:
+    type: number
 PulseSequenceType:
   name: PulseSequenceType
   display_name: Pulse Sequence Type
@@ -2537,6 +2596,16 @@ ReceiveCoilName:
     in which case this field can be derived from an appropriate
     private DICOM field.
   type: string
+ReceiveGain:
+  name: ReceiveGain
+  display_name: Receive Gain
+  description: |
+    The gain of the receive coil.
+  anyOf:
+    - type: number
+    - type: array
+      items:
+        type: number
 ReconFilterSize:
   name: ReconFilterSize
   display_name: Recon Filter Size
@@ -2629,9 +2698,11 @@ ReferenceSignal:
   name: ReferenceSignal
   display_name: Reference Signal
   description: |
-    The path(s) to the reference MRS file(s), if present, to which the associated MRS data file corresponds.
+    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](SPEC_ROOT/02-common-principles.md#bids-uri).
-    Using forward-slash separated paths relative to the participant subdirectory is [DEPRECATED](SPEC_ROOT/02-common-principles.md#definitions).
+    Using forward-slash separated paths relative to the participant subdirectory is
+    [DEPRECATED](SPEC_ROOT/02-common-principles.md#definitions).
   anyOf:
     - type: string
     - type: array
@@ -2660,6 +2731,22 @@ RepetitionTime:
   type: number
   exclusiveMinimum: 0
   unit: s
+RepetitionTime__mrs:
+  name: RepetitionTime
+  display_name: Repetition Time
+  description: |
+    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.
+  anyOf:
+    - type: number
+      minimum: 0
+      unit: s
+    - type: array
+      items:
+        type: number
+        minimum: 0
+        unit: s
 RepetitionTimeExcitation:
   name: RepetitionTimeExcitation
   display_name: Repetition Time Excitation
@@ -2901,6 +2988,16 @@ ScanningSequence:
     - type: array
       items:
         type: string
+ScanningSequence__mrs:
+  name: ScanningSequence
+  display_name: Scanning Sequence
+  description: |
+    Description of the type of data acquired.
+  type: string
+  enum:
+    - SVS
+    - MRSI
+    - Unlocalized MRS
 ScatterFraction:
   name: ScatterFraction
   display_name: Scatter Fraction
@@ -3163,14 +3260,14 @@ SpectralWidth:
   name: SpectralWidth
   display_name: Spectral Width
   description: |
-    The spectral bandwidth of the MR signal (in Hz) that is sampled (for example, `2000`).
+    The spectral bandwidth of the MR signal that is sampled, specified in Hz.
     Corresponds to DICOM Tag 0018, 9052 `Spectral Width`.
   type: number
 SpectrometerFrequency:
   name: SpectrometerFrequency
   display_name: Spectrometer Frequency
   description: |
-    The frequency of the spectrometer (in MHz).
+    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 <sup>1</sup>H.
     For multi-nuclei experiments such as <sup>1</sup>H-[<sup>13</sup>C] MR at 3T,
@@ -3452,16 +3549,17 @@ VolumeAffineMatrix:
   name: VolumeAffineMatrix
   display_name: Volume Affine Matrix
   description: |
-    A 4-by-4 matrix using identical conventions and coordinate system to the *{qs}form* NIfTI affine matrix to define the orientation,
+    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*).
+    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]]`.
+    For example: `[[30, 0, 0, -30], [0, 30, -2.27, -72.67], [0, 2.27, 29.91, 5.47],
+    [0, 0, 0, 1]]`.
   type: array
+  minItems: 16
+  maxItems: 16
   items:
     type: number
 VolumeTiming:
@@ -3481,18 +3579,19 @@ VolumeTiming:
   items:
     type: number
     unit: s
-WaterSuppressed:
-  name: WaterSuppressed
-  display_name: Water-Suppressed
+WaterSuppression:
+  name: WaterSuppression
+  display_name: Water Suppression
   description: |
-    Boolean indicating whether or not water suppression was used prior to acquisition.
+    Boolean indicating whether water suppression was used prior to acquisition.
   type: boolean
 WaterSuppressionTechnique:
   name: WaterSuppressionTechnique
   display_name: Water Suppression Technique
   description: |
     The name of the pulse sequence used for water suppression (for example, `"CHESS"`, `"VAPOR"`).
-    If no water suppression was used (for example, when collecting water-unsuppressed spectra), set as `null`.
+    If no water suppression was used (for example, when collecting a water-unsuppressed reference),
+    set as `null`.
   type: string
 WholeBloodAvail:
   name: WholeBloodAvail
diff --git a/src/schema/rules/files/raw/mrs.yaml b/src/schema/rules/files/raw/mrs.yaml
index 0b55a0206e..8f9ed918c8 100644
--- a/src/schema/rules/files/raw/mrs.yaml
+++ b/src/schema/rules/files/raw/mrs.yaml
@@ -41,7 +41,7 @@ mrsi:
     nucleus: optional
     volume: optional
 
-references:
+reference:
   suffixes:
     - ref
   extensions:
diff --git a/src/schema/rules/sidecars/mri.yaml b/src/schema/rules/sidecars/mri.yaml
index 887b5b13b2..792efdbe34 100644
--- a/src/schema/rules/sidecars/mri.yaml
+++ b/src/schema/rules/sidecars/mri.yaml
@@ -50,7 +50,9 @@ MRISequenceSpecifics:
     PulseSequenceType:
       level: recommended
       description_addendum: For example, `"MPRAGE"`, `"Gradient Echo EPI"`, `"Spin Echo EPI"`, `"Multiband gradient echo EPI"`.
-    ScanningSequence: recommended
+    ScanningSequence:
+      level: recommended
+      description_addendum: Corresponds to DICOM Tag 0018, 0020 `Scanning Sequence`.
     SequenceVariant: recommended
     ScanOptions: recommended
     SequenceName: recommended
@@ -174,6 +176,13 @@ MRITimingParameters:
       level_addendum: |
         required if corresponding fieldmap data is present,
         or the data comes from a multi-echo sequence or Arterial Spin Labeling.
+      description_addendum: |
+        The data type array provides a value for each volume in a 4D dataset and
+        should only be used when the volume timing is critical for interpretation
+        of the data, such as in
+        [ASL](SPEC_ROOT/04-modality-specific-files/01-magnetic-resonance-imaging-data.md#\
+        arterial-spin-labeling-perfusion-data)
+        or variable echo time fMRI sequences.
       issue:
         name: ECHO_TIME_NOT_DEFINED
         message: |
@@ -243,6 +252,13 @@ MRIFlipAngleLookLockerFalse:
     FlipAngle:
       level: recommended
       level_addendum: required if LookLocker is set to `true`
+      description_addendum: |
+        The data type array provides a value for each volume in a 4D dataset and
+        should only be used when the volume timing is critical for interpretation of
+        the data, such as in
+        [ASL](SPEC_ROOT/04-modality-specific-files/01-magnetic-resonance-imaging-data.md#\
+        arterial-spin-labeling-perfusion-data)
+        or variable flip angle fMRI sequences.
 
 MRIFlipAngleLookLockerTrue:
   selectors:
@@ -251,6 +267,13 @@ MRIFlipAngleLookLockerTrue:
   fields:
     FlipAngle:
       level: required
+      description_addendum: |
+        The data type array provides a value for each volume in a 4D dataset and
+        should only be used when the volume timing is critical for interpretation of
+        the data, such as in
+        [ASL](SPEC_ROOT/04-modality-specific-files/01-magnetic-resonance-imaging-data.md#\
+        arterial-spin-labeling-perfusion-data)
+        or variable flip angle fMRI sequences.
       issue:
         name: LOOK_LOCKER_FLIP_ANGLE_MISSING
         message: |
diff --git a/src/schema/rules/sidecars/mrs.yaml b/src/schema/rules/sidecars/mrs.yaml
index 68d6a6ca70..c9955d538a 100644
--- a/src/schema/rules/sidecars/mrs.yaml
+++ b/src/schema/rules/sidecars/mrs.yaml
@@ -10,24 +10,16 @@ MRSScannerHardware:
   selectors:
     - modality == "mrs"
   fields:
-    Manufacturer:
-      level: recommended
-      description_addendum: Corresponds to DICOM Tag 0008, 0070 `Manufacturer`.
-    ManufacturersModelName:
-      level: recommended
-      description_addendum: Corresponds to DICOM Tag 0008, 1090 `Manufacturers Model Name`.
-    DeviceSerialNumber:
-      level: recommended
-      description_addendum: Corresponds to DICOM Tag 0018, 1000 `DeviceSerialNumber`.
-    StationName:
-      level: recommended
-      description_addendum: Corresponds to DICOM Tag 0008, 1010 `Station Name`.
-    SoftwareVersions:
-      level: recommended
-      description_addendum: Corresponds to DICOM Tag 0018, 1020 `Software Versions`.
+    InstitutionName: recommended
+    InstitutionAddress: recommended
+    InstitutionalDepartmentName: recommended
+    Manufacturer: recommended
+    ManufacturersModelName: recommended
+    DeviceSerialNumber: recommended
+    StationName: recommended
+    SoftwareVersions: recommended
     HardcopyDeviceSoftwareVersion: DEPRECATED
-    MagneticFieldStrength:
-      level: recommended
+    MagneticFieldStrength: recommended
     ReceiveCoilName: recommended
     ReceiveCoilActiveElements: recommended
     NumberReceiveCoilActiveElements: recommended
@@ -38,13 +30,12 @@ MRSSequenceSpecifics:
   fields:
     PulseSequenceType:
       level: recommended
-      description_addendum: For example, `"sLASER"`, `"MEGA-PRESS"`, `"EPSI"`, `"Metabolite-cycled MRSI"`.
-    ScanningSequence: recommended
-    SequenceVariant: recommended
-    ScanOptions: recommended
+      description_addendum: |
+        For example, `"sLASER"`, `"MEGA-PRESS"`, `"EPSI"`, `"Metabolite-cycled MRSI"`.
+    ScanningSequence__mrs: recommended
     SequenceName: recommended
     PulseSequenceDetails: recommended
-    MRAcquisitionType: recommended for MRSI
+    MRAcquisitionType__mrs: recommended for MRSI
 
 MRSRequiredFields:
   selectors:
@@ -61,7 +52,7 @@ MRSRecommendedFields:
   fields:
     NumberOfSpectralPoints: recommended
     NumberOfTransients: recommended for SVS
-    RepetitionTime: recommended
+    RepetitionTime__mrs: recommended
     MixingTime: recommended
     InversionTime: recommended for inversion recovery data
     FlipAngle: recommended
@@ -73,10 +64,26 @@ MRSRecommendedFields:
     EditTarget: recommended for edited data
     EditPulse: recommended for edited data
     EditCondition: recommended for edited data
-    WaterSuppressed: recommended
+    WaterSuppression: recommended
     WaterSuppressionTechnique: recommended
+    OuterVolumeSuppression: recommended
     EncodingTechnique: recommended for MRSI
     B0ShimmingTechnique: recommended
-    OuterVolumeSuppression: recommended
     ReferenceSignal: recommended if MRS reference data are present
     AnatomicalImage: recommended if anatomical MRI data are present
+
+MRSOptionalFields:
+  selectors:
+    - modality == "mrs"
+  fields:
+    ChemicalShiftOffset: optional
+    ChemicalShiftReference: optional
+    EchoAcquisition: optional
+    ParallelReductionFactorInPlane: optional
+    ParallelAcquisitionTechnique: optional
+    MultibandAccelerationFactor: optional
+    NumberTransmitCoilActiveElements: optional
+    B1ShimmingTechnique: optional
+    PulseSequenceTiming: optional
+    PulseSequencePulses: optional
+    ReceiveGain: optional

From 505a75fa1dfe9eabf206b887cfe9bd3d0442b7d1 Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Fri, 9 Dec 2022 12:21:01 -0500
Subject: [PATCH 07/70] Minor update

---
 src/schema/objects/entities.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/schema/objects/entities.yaml b/src/schema/objects/entities.yaml
index d709b394b9..8063b14093 100644
--- a/src/schema/objects/entities.yaml
+++ b/src/schema/objects/entities.yaml
@@ -420,7 +420,7 @@ volume:
   name: voi
   display_name: Volume of Interest
   description: |
-    The `voi-<label>` entity can be used to distinguish sequences localized to different regions.
+    The `voi-<label>` entity can be used to distinguish acquisitions localized to different regions.
     The label SHOULD be the name of the body region or part scanned.
     If used, the entities `"BodyPart"` and `"BodyPartDetails"` MUST also be defined in the JSON file.
   type: string

From dc65a360354e0630fe053fa54acd94d77ea2f028 Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Fri, 9 Dec 2022 12:28:34 -0500
Subject: [PATCH 08/70] Spelling correction

---
 src/schema/objects/entities.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/schema/objects/entities.yaml b/src/schema/objects/entities.yaml
index 8063b14093..4cd9620cf6 100644
--- a/src/schema/objects/entities.yaml
+++ b/src/schema/objects/entities.yaml
@@ -367,7 +367,7 @@ stain:
     although the label may be different.
 
     Descriptions of antibodies SHOULD also be indicated in the `"SamplePrimaryAntibodies"`
-    and/or `"SampleSecondaryAntobodies"` metadata fields, as appropriate.
+    and/or `"SampleSecondaryAntibodies"` metadata fields, as appropriate.
   type: string
   format: label
 subject:

From 197953204ae1c4512da4b006b164eec57a365f91 Mon Sep 17 00:00:00 2001
From: markmikkelsen <mark.mikkelsen@gmail.com>
Date: Thu, 5 Jan 2023 18:09:34 -0500
Subject: [PATCH 09/70] Update contributors.md

---
 src/appendices/contributors.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/appendices/contributors.md b/src/appendices/contributors.md
index 6bae5c812b..0460b51e12 100644
--- a/src/appendices/contributors.md
+++ b/src/appendices/contributors.md
@@ -191,7 +191,7 @@ If you contributed to the BIDS ecosystem and your name is not listed, please add
 -   Giacomo Mazzamuto 📖🔣
 -   David McAlpine 📖
 -   Manuel Mercier 📖🤔
--   Mark Mikkelsen 📖
+-   Mark Mikkelsen 📖💻
 -   Kai J. Miller 📖
 -   Markus Morawski 📖
 -   Clara Moreau 📖

From 81b057bbcac8a1606c20c820a1384b2e49bce9e2 Mon Sep 17 00:00:00 2001
From: markmikkelsen <mark.mikkelsen@gmail.com>
Date: Fri, 6 Jan 2023 16:23:30 -0500
Subject: [PATCH 10/70] Some minor edits

---
 .../12-magnetic-resonance-spectroscopy.md            | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md b/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md
index 904d9a2a74..7a9cab6358 100644
--- a/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md
+++ b/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md
@@ -27,7 +27,7 @@ and a guide for using macros can be found at
 
 Each manufacturer has its own file format (sometimes multiple formats) for exporting MRS data from
 the scanner console for offline processing.
-GE exports a P-file that stores unprocessed, un-coil-combined data with metadata embedded
+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
@@ -74,11 +74,11 @@ Note that NIfTI-MRS is not designed to store data that has not been spatially re
 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` amd `mrsi` MUST be used to distinguish the two techniques.
+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 levels (for example, to obtain concentrations) and/or aid preprocessing steps such as
+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.
@@ -90,7 +90,7 @@ two references to be used for concentration scaling and eddy-current correction,
 ### MRS sequences
 
 Given the large variety of MRS sequences, there will be times when providing sufficient detail of
-acquisition parameters is helpful or necessary to distinguish datasets in a given study.
+acquisition parameters in filenames is helpful or necessary to distinguish datasets in a given study.
 
 The following labels for the most commonly used in vivo MRS sequences/techniques are OPTIONAL to use
 when using the `acq-<label>` entity in the filename.
@@ -118,12 +118,12 @@ For example, `megaspecial`, `jpress`, `dwslaser`, and so on.
 
 The OPTIONAL `nuc-<label>` key/value pair 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.
-The key `"ResonantNucleus"` MUST also be included in the sidecar JSON file, with the same label.
+The key `ResonantNucleus` MUST also be included in the sidecar JSON file, with the same label.
 
 Similarly, the OPTIONAL `voi-<label>` key/value pair can be used to distinguish between repeated
 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 entities `"BodyPart"` and `"BodyPartDetails"` MUST also be included in the sidecar JSON file.
+If used, the entities `BodyPart` and `BodyPartDetails` MUST also be included in the sidecar JSON file.
 
 ## Sidecar JSON
 

From 199477d578beaa6ee3ac960aeba67916deba7b17 Mon Sep 17 00:00:00 2001
From: markmikkelsen <mark.mikkelsen@gmail.com>
Date: Tue, 10 Jan 2023 18:03:01 -0500
Subject: [PATCH 11/70] Some minor changes and fixes to automatic checks.

---
 .../12-magnetic-resonance-spectroscopy.md                  | 7 +++++--
 src/schema/objects/suffixes.yaml                           | 2 +-
 src/schema/rules/sidecars/mri.yaml                         | 4 +++-
 3 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md b/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md
index 7a9cab6358..bb9ca19632 100644
--- a/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md
+++ b/src/04-modality-specific-files/12-magnetic-resonance-spectroscopy.md
@@ -102,10 +102,12 @@ If used, the chosen label SHOULD also be described in the `PulseSequenceType` fi
 | ---------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | 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/sLASER                       | laser/slaser    | 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. In sLASER, 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.                                                                                                                         |
+| 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          | A modification of LASER, in sLASER, 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            | This spectral editing technique employs a pair of frequency-selective 180° pulses to refocus *J*-coupled spins at a narrowband 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/HERCULES                    | hermes/hercules | 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 is a different flavor of HERMES that targets more metabolites using the same four-step experiment.                                                                                       |
+| 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 editing | mqc             | Multiple-quantum coherence (MQC) editing targets *J*-coupled resonances by selecting desired coherence pathways using MQ gradients and frequency-selective RF pulses.                                                                                                                                                                                                                                                                                                                                   |
 | L-COSY                             | lcosy           | Localized correlation spectroscopy (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.                                                                                                                                                                                                                   |
@@ -118,6 +120,7 @@ For example, `megaspecial`, `jpress`, `dwslaser`, and so on.
 
 The OPTIONAL `nuc-<label>` key/value pair 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`.
 The key `ResonantNucleus` MUST also be included in the sidecar JSON file, with the same label.
 
 Similarly, the OPTIONAL `voi-<label>` key/value pair can be used to distinguish between repeated
diff --git a/src/schema/objects/suffixes.yaml b/src/schema/objects/suffixes.yaml
index 25a64e00bf..de9b25d0ea 100644
--- a/src/schema/objects/suffixes.yaml
+++ b/src/schema/objects/suffixes.yaml
@@ -749,7 +749,7 @@ ref:
   description: |
     An MRS acquisition acquired to detect a signal to serve
     as a concentration reference for absolute quantification
-    or for preprocessing (e.g., eddy-current correction).
+    or for preprocessing (for example, eddy-current correction).
 sbref:
   value: sbref
   display_name: Single-band reference image
diff --git a/src/schema/rules/sidecars/mri.yaml b/src/schema/rules/sidecars/mri.yaml
index 792efdbe34..3d5cdc3796 100644
--- a/src/schema/rules/sidecars/mri.yaml
+++ b/src/schema/rules/sidecars/mri.yaml
@@ -49,7 +49,9 @@ MRISequenceSpecifics:
   fields:
     PulseSequenceType:
       level: recommended
-      description_addendum: For example, `"MPRAGE"`, `"Gradient Echo EPI"`, `"Spin Echo EPI"`, `"Multiband gradient echo EPI"`.
+      description_addendum: |
+        For example, `"MPRAGE"`, `"Gradient Echo EPI"`, `"Spin Echo EPI"`, `"Multiband gradient
+        echo EPI"`.
     ScanningSequence:
       level: recommended
       description_addendum: Corresponds to DICOM Tag 0018, 0020 `Scanning Sequence`.

From 44bb58f314bf9dc6fe45753a7a8938aa5178cb45 Mon Sep 17 00:00:00 2001
From: markmikkelsen <mark.mikkelsen@gmail.com>
Date: Tue, 10 Jan 2023 18:29:58 -0500
Subject: [PATCH 12/70] Table style correction

---
 ....md => magnetic-resonance-spectroscopy.md} | 52 ++++++++++---------
 1 file changed, 27 insertions(+), 25 deletions(-)
 rename src/modality-specific-files/{12-magnetic-resonance-spectroscopy.md => magnetic-resonance-spectroscopy.md} (70%)

diff --git a/src/modality-specific-files/12-magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
similarity index 70%
rename from src/modality-specific-files/12-magnetic-resonance-spectroscopy.md
rename to src/modality-specific-files/magnetic-resonance-spectroscopy.md
index bb9ca19632..88e08857e8 100644
--- a/src/modality-specific-files/12-magnetic-resonance-spectroscopy.md
+++ b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -19,10 +19,11 @@ The inputs for this macro can be found in the directory
 and a guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
-{{ MACROS___make_filename_template(
-   "raw",
-   datatypes=["mrs"],
-   suffixes=["svs", "mrsi", "ref", "unloc"])
+
+{{ MACROS\_\__make_filename_template(
+"raw",
+datatypes=\["mrs"],
+suffixes=\["svs", "mrsi", "ref", "unloc"])
 }}
 
 Each manufacturer has its own file format (sometimes multiple formats) for exporting MRS data from
@@ -98,22 +99,22 @@ Users are free to choose any label they wish as long as they are consistent acro
 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          | A modification of LASER, in sLASER, 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            | This spectral editing technique employs a pair of frequency-selective 180° pulses to refocus *J*-coupled spins at a narrowband 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 editing | mqc             | Multiple-quantum coherence (MQC) editing targets *J*-coupled resonances by selecting desired coherence pathways using MQ gradients and frequency-selective RF pulses.                                                                                                                                                                                                                                                                                                                                   |
-| L-COSY                             | lcosy           | Localized correlation spectroscopy (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 spectroscopy    | dw              | The diffusion of intracellular metabolites can be characterized using diffusion-weighted MRS. 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.                                                                                                                                                                                                                                                                       |
-| Spin-echo spectroscopy             | spinecho        | An MRS experiment whereby the MR signal is detected using a spin-echo acquisition: for example, 90°–180°–acq.                                                                                                                                                                                                                                                                                                                                                                                           |
+| **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      | A modification of LASER, in sLASER, 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        | This spectral editing technique employs a pair of frequency-selective 180° pulses to refocus *J*-coupled spins at a narrowband 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 editing | mqc         | Multiple-quantum coherence (MQC) editing targets *J*-coupled resonances by selecting desired coherence pathways using MQ gradients and frequency-selective RF pulses.                                                                                                                                                                                                                                                                                                                                   |
+| L-COSY                             | lcosy       | Localized correlation spectroscopy (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 spectroscopy    | dw          | The diffusion of intracellular metabolites can be characterized using diffusion-weighted MRS. 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.                                                                                                                                                                                                                                                                       |
+| Spin-echo spectroscopy             | spinecho    | An MRS experiment whereby the MR signal is detected using a spin-echo acquisition: for example, 90°–180°–acq.                                                                                                                                                                                                                                                                                                                                                                                           |
 
 Each `<label>` in the table MAY be combined with another to better describe the acquisition used.
 For example, `megaspecial`, `jpress`, `dwslaser`, and so on.
@@ -147,25 +148,26 @@ The definitions of the fields specified in these tables may be found in
 A guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
-{{ MACROS___make_sidecar_table("mrs.MRSScannerHardware") }}
+
+{{ MACROS\_\__make_sidecar_table("mrs.MRSScannerHardware") }}
 
 #### Sequence specifics
 
-{{ MACROS___make_sidecar_table("mrs.MRSSequenceSpecifics") }}
+{{ MACROS\_\__make_sidecar_table("mrs.MRSSequenceSpecifics") }}
 
 ### MRS-specific fields
 
 Metadata fields that MUST be present:
 
-{{ MACROS___make_sidecar_table("mrs.MRSRequiredFields") }}
+{{ MACROS\_\__make_sidecar_table("mrs.MRSRequiredFields") }}
 
 SHOULD be present:
 
-{{ MACROS___make_sidecar_table("mrs.MRSRecommendedFields") }}
+{{ MACROS\_\__make_sidecar_table("mrs.MRSRecommendedFields") }}
 
 MAY be present:
 
-{{ MACROS___make_sidecar_table("mrs.MRSOptionalFields") }}
+{{ MACROS\_\__make_sidecar_table("mrs.MRSOptionalFields") }}
 
 ### Example `*_svs.json`
 

From b9ac19e2da2fbb9eded593ae5a5e075f5704a37b Mon Sep 17 00:00:00 2001
From: markmikkelsen <mark.mikkelsen@gmail.com>
Date: Wed, 11 Jan 2023 17:52:39 -0500
Subject: [PATCH 13/70] Further corrections to fix check failures

---
 mkdocs.yml                                                  | 3 ++-
 .../magnetic-resonance-spectroscopy.md                      | 6 +++---
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/mkdocs.yml b/mkdocs.yml
index 9ecaf4bcab..7a03bb44ae 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -17,7 +17,7 @@ nav:
         - Positron Emission Tomography: modality-specific-files/positron-emission-tomography.md
         - Microscopy: modality-specific-files/microscopy.md
         - Near-Infrared Spectroscopy: modality-specific-files/near-infrared-spectroscopy.md
-        - Magnetic Resonance Spectroscopy: 04-modality-specific-files/12-magnetic-resonance-spectroscopy.md
+        - Magnetic Resonance Spectroscopy: modality-specific-files/magnetic-resonance-spectroscopy.md
       - Derivatives:
         - BIDS Derivatives: derivatives/introduction.md
         - Common data types and metadata: derivatives/common-data-types.md
@@ -91,6 +91,7 @@ plugins:
             '04-modality-specific-files/09-positron-emission-tomography.md': 'modality-specific-files/positron-emission-tomography.md'
             '04-modality-specific-files/10-microscopy.md': 'modality-specific-files/microscopy.md'
             '04-modality-specific-files/11-near-infrared-spectroscopy.md': 'modality-specific-files/near-infrared-spectroscopy.md'
+            '04-modality-specific-files/12-magnetic-resonance-spectroscopy.md': 'modality-specific-files/magnetic-resonance-spectroscopy.md'
             '05-derivatives/01-introduction.md': 'derivatives/introduction.md'
             '05-derivatives/02-common-data-types.md': 'derivatives/common-data-types.md'
             '05-derivatives/03-imaging.md': 'derivatives/imaging.md'
diff --git a/src/modality-specific-files/magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
index 88e08857e8..d6efa7aed4 100644
--- a/src/modality-specific-files/magnetic-resonance-spectroscopy.md
+++ b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -21,9 +21,9 @@ and a guide for using macros can be found at
 -->
 
 {{ MACROS\_\__make_filename_template(
-"raw",
-datatypes=\["mrs"],
-suffixes=\["svs", "mrsi", "ref", "unloc"])
+    "raw",
+    datatypes=\["mrs"],
+    suffixes=\["svs", "mrsi", "ref", "unloc"])
 }}
 
 Each manufacturer has its own file format (sometimes multiple formats) for exporting MRS data from

From 64c4ec6b20c5fa760a5a243c015ca765b0b04ebb Mon Sep 17 00:00:00 2001
From: markmikkelsen <mark.mikkelsen@gmail.com>
Date: Wed, 11 Jan 2023 19:02:37 -0500
Subject: [PATCH 14/70] Further corrections to fix check failures (2)

---
 .../magnetic-resonance-spectroscopy.md                        | 2 +-
 src/schema/objects/metadata.yaml                              | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/modality-specific-files/magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
index d6efa7aed4..66e90439ed 100644
--- a/src/modality-specific-files/magnetic-resonance-spectroscopy.md
+++ b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -47,7 +47,7 @@ Contrarily, Bruker stores two binary files: one file stores each transient separ
 while the other stores the sum of the transients.
 Bruker stores the sequence name, voxel position, voxel orientation, and other metadata in a separate plaintext file.
 These files are considered source data and, if present, MUST be stored in the
-[`/sourcedata`](../02-common-principles.md#source-vs-raw-vs-derived-data) directory.
+[`/sourcedata`](../common-principles.md#source-vs-raw-vs-derived-data) directory.
 
 Due to the diversity in manufacturers' MRS data file formats, source data MUST be converted into the
 [NIfTI-MRS format](https://onlinelibrary.wiley.com/doi/10.1002/mrm.29418) (`*.nii[.gz]`).
diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index 2890277b02..e569258728 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -76,9 +76,9 @@ AnatomicalImage:
   description: |
     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](SPEC_ROOT/02-common-principles.md#bids-uri).
+    Contains one or more [BIDS URIs](SPEC_ROOT/common-principles.md#bids-uri).
     Using forward-slash separated paths relative to the participant subdirectory is
-    [DEPRECATED](SPEC_ROOT/02-common-principles.md#definitions).
+    [DEPRECATED](SPEC_ROOT/common-principles.md#definitions).
   anyOf:
     - type: string
     - type: array

From 359053586c641dc51561f05ea88406e0480bf063 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Thu, 12 Jan 2023 11:12:29 -0500
Subject: [PATCH 15/70] DOC: Remove 02- from common principles URL, drop
 DEPRECATED option.

---
 src/schema/objects/metadata.yaml | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index e569258728..523b4b354e 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -2736,9 +2736,7 @@ ReferenceSignal:
   description: |
     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](SPEC_ROOT/02-common-principles.md#bids-uri).
-    Using forward-slash separated paths relative to the participant subdirectory is
-    [DEPRECATED](SPEC_ROOT/02-common-principles.md#definitions).
+    Contains one or more [BIDS URIs](SPEC_ROOT/common-principles.md#bids-uri).
   anyOf:
     - type: string
     - type: array

From c4b066bbeb868ada8d9b23291c841d4011a5d6e4 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Thu, 12 Jan 2023 11:14:54 -0500
Subject: [PATCH 16/70] FIX: Remove 04- and 01- from MRI links

---
 src/schema/rules/sidecars/mri.yaml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/schema/rules/sidecars/mri.yaml b/src/schema/rules/sidecars/mri.yaml
index bc575cb13e..de251eeda0 100644
--- a/src/schema/rules/sidecars/mri.yaml
+++ b/src/schema/rules/sidecars/mri.yaml
@@ -183,7 +183,7 @@ MRITimingParameters:
         The data type array provides a value for each volume in a 4D dataset and
         should only be used when the volume timing is critical for interpretation
         of the data, such as in
-        [ASL](SPEC_ROOT/04-modality-specific-files/01-magnetic-resonance-imaging-data.md#\
+        [ASL](SPEC_ROOT/modality-specific-files/magnetic-resonance-imaging-data.md#\
         arterial-spin-labeling-perfusion-data)
         or variable echo time fMRI sequences.
       issue:
@@ -259,7 +259,7 @@ MRIFlipAngleLookLockerFalse:
         The data type array provides a value for each volume in a 4D dataset and
         should only be used when the volume timing is critical for interpretation of
         the data, such as in
-        [ASL](SPEC_ROOT/04-modality-specific-files/01-magnetic-resonance-imaging-data.md#\
+        [ASL](SPEC_ROOT/modality-specific-files/magnetic-resonance-imaging-data.md#\
         arterial-spin-labeling-perfusion-data)
         or variable flip angle fMRI sequences.
 
@@ -274,7 +274,7 @@ MRIFlipAngleLookLockerTrue:
         The data type array provides a value for each volume in a 4D dataset and
         should only be used when the volume timing is critical for interpretation of
         the data, such as in
-        [ASL](SPEC_ROOT/04-modality-specific-files/01-magnetic-resonance-imaging-data.md#\
+        [ASL](SPEC_ROOT/modality-specific-files/magnetic-resonance-imaging-data.md#\
         arterial-spin-labeling-perfusion-data)
         or variable flip angle fMRI sequences.
       issue:

From ba832d279981a3e0e94359dfacaea4d5d01163d1 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Thu, 12 Jan 2023 11:19:51 -0500
Subject: [PATCH 17/70] FIX: Macro formatting

---
 .../magnetic-resonance-spectroscopy.md           | 16 ++++++----------
 1 file changed, 6 insertions(+), 10 deletions(-)

diff --git a/src/modality-specific-files/magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
index 66e90439ed..af1de8623d 100644
--- a/src/modality-specific-files/magnetic-resonance-spectroscopy.md
+++ b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -20,11 +20,7 @@ and a guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
 
-{{ MACROS\_\__make_filename_template(
-    "raw",
-    datatypes=\["mrs"],
-    suffixes=\["svs", "mrsi", "ref", "unloc"])
-}}
+{{ MACROS___make_filename_template("raw", datatypes=["mrs"], suffixes=["svs", "mrsi", "ref", "unloc"]) }}
 
 Each manufacturer has its own file format (sometimes multiple formats) for exporting MRS data from
 the scanner console for offline processing.
@@ -149,25 +145,25 @@ A guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
 
-{{ MACROS\_\__make_sidecar_table("mrs.MRSScannerHardware") }}
+{{ MACROS___make_sidecar_table("mrs.MRSScannerHardware") }}
 
 #### Sequence specifics
 
-{{ MACROS\_\__make_sidecar_table("mrs.MRSSequenceSpecifics") }}
+{{ MACROS___make_sidecar_table("mrs.MRSSequenceSpecifics") }}
 
 ### MRS-specific fields
 
 Metadata fields that MUST be present:
 
-{{ MACROS\_\__make_sidecar_table("mrs.MRSRequiredFields") }}
+{{ MACROS___make_sidecar_table("mrs.MRSRequiredFields") }}
 
 SHOULD be present:
 
-{{ MACROS\_\__make_sidecar_table("mrs.MRSRecommendedFields") }}
+{{ MACROS___make_sidecar_table("mrs.MRSRecommendedFields") }}
 
 MAY be present:
 
-{{ MACROS\_\__make_sidecar_table("mrs.MRSOptionalFields") }}
+{{ MACROS___make_sidecar_table("mrs.MRSOptionalFields") }}
 
 ### Example `*_svs.json`
 

From 1fa4ab0ec25afed36557251e3cefc455b86fc58a Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Thu, 12 Jan 2023 11:25:02 -0500
Subject: [PATCH 18/70] FIX: More numeric prefixes

---
 .../magnetic-resonance-spectroscopy.md                        | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/modality-specific-files/magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
index af1de8623d..7b0fdd2a56 100644
--- a/src/modality-specific-files/magnetic-resonance-spectroscopy.md
+++ b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -1,8 +1,8 @@
 # Magnetic Resonance Spectroscopy
 
 Support for Magnetic Resonance Spectroscopy (MRS) was developed as a
-[BIDS Extension Proposal](../07-extensions.md#bids-extension-proposals).
-Please see [Citing BIDS](../01-introduction.md#citing-bids)
+[BIDS Extension Proposal](../extensions.md#bids-extension-proposals).
+Please see [Citing BIDS](../introduction.md#citing-bids)
 on how to appropriately credit this extension when referring to it in the
 context of the academic literature.
 

From ea2535b95da786d512d10c3a2e7317ca308efd3a Mon Sep 17 00:00:00 2001
From: markmikkelsen <mark.mikkelsen@gmail.com>
Date: Fri, 27 Jan 2023 13:25:45 -0500
Subject: [PATCH 19/70] Remove DEPRECATED functionalities

---
 src/schema/objects/metadata.yaml   | 2 --
 src/schema/rules/sidecars/mrs.yaml | 1 -
 2 files changed, 3 deletions(-)

diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index 0e03f5ac37..07ec80b312 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -77,8 +77,6 @@ AnatomicalImage:
     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](SPEC_ROOT/common-principles.md#bids-uri).
-    Using forward-slash separated paths relative to the participant subdirectory is
-    [DEPRECATED](SPEC_ROOT/common-principles.md#definitions).
   anyOf:
     - type: string
     - type: array
diff --git a/src/schema/rules/sidecars/mrs.yaml b/src/schema/rules/sidecars/mrs.yaml
index c9955d538a..561d38f56d 100644
--- a/src/schema/rules/sidecars/mrs.yaml
+++ b/src/schema/rules/sidecars/mrs.yaml
@@ -18,7 +18,6 @@ MRSScannerHardware:
     DeviceSerialNumber: recommended
     StationName: recommended
     SoftwareVersions: recommended
-    HardcopyDeviceSoftwareVersion: DEPRECATED
     MagneticFieldStrength: recommended
     ReceiveCoilName: recommended
     ReceiveCoilActiveElements: recommended

From b1f2ca2b734ef4331a635410df531b4fa3c517a2 Mon Sep 17 00:00:00 2001
From: markmikkelsen <mark.mikkelsen@gmail.com>
Date: Fri, 27 Jan 2023 13:43:07 -0500
Subject: [PATCH 20/70] Change URL to NIfTI-MRS paper

---
 src/modality-specific-files/magnetic-resonance-spectroscopy.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/modality-specific-files/magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
index 7b0fdd2a56..dd809d59a9 100644
--- a/src/modality-specific-files/magnetic-resonance-spectroscopy.md
+++ b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -46,7 +46,7 @@ These files are considered source data and, if present, MUST be stored in the
 [`/sourcedata`](../common-principles.md#source-vs-raw-vs-derived-data) directory.
 
 Due to the diversity in manufacturers' MRS data file formats, source data MUST be converted into the
-[NIfTI-MRS format](https://onlinelibrary.wiley.com/doi/10.1002/mrm.29418) (`*.nii[.gz]`).
+[NIfTI-MRS format](https://doi.org/10.1002/mrm.29418) (`*.nii[.gz]`).
 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.

From 28b746ebf5fef222563bf14b35459d601d4685dc Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Fri, 27 Jan 2023 16:06:06 -0500
Subject: [PATCH 21/70] Update src/schema/rules/sidecars/mrs.yaml

Change `NumberOfTransients` to be recommended for SVS and unloc data only; optional otherwise.

Co-authored-by: Chris Markiewicz <markiewicz@stanford.edu>
---
 src/schema/rules/sidecars/mrs.yaml | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/schema/rules/sidecars/mrs.yaml b/src/schema/rules/sidecars/mrs.yaml
index 561d38f56d..9bfa4e9f22 100644
--- a/src/schema/rules/sidecars/mrs.yaml
+++ b/src/schema/rules/sidecars/mrs.yaml
@@ -50,7 +50,9 @@ MRSRecommendedFields:
     - modality == "mrs"
   fields:
     NumberOfSpectralPoints: recommended
-    NumberOfTransients: recommended for SVS
+    NumberOfTransients:
+      level: optional
+      level_addendum: recommended for SVS and unloc
     RepetitionTime__mrs: recommended
     MixingTime: recommended
     InversionTime: recommended for inversion recovery data

From c25573e536ad86df86fe125ba45480a6bb89c5ee Mon Sep 17 00:00:00 2001
From: markmikkelsen <mark.mikkelsen@gmail.com>
Date: Fri, 27 Jan 2023 16:20:47 -0500
Subject: [PATCH 22/70] Update mrs.yaml

---
 src/schema/rules/sidecars/mrs.yaml | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/schema/rules/sidecars/mrs.yaml b/src/schema/rules/sidecars/mrs.yaml
index 9bfa4e9f22..2928752e67 100644
--- a/src/schema/rules/sidecars/mrs.yaml
+++ b/src/schema/rules/sidecars/mrs.yaml
@@ -73,6 +73,13 @@ MRSRecommendedFields:
     ReferenceSignal: recommended if MRS reference data are present
     AnatomicalImage: recommended if anatomical MRI data are present
 
+NumberOfTransientsRecommended:
+  selectors:
+    - datatype == "mrs"
+    - intersects([suffix], ["svs", "unloc"])
+  fields:
+    NumberOfTransients: recommended
+
 MRSOptionalFields:
   selectors:
     - modality == "mrs"

From 57b21d79af0558ec1ad4a8b1e44a48eec6787aa7 Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Tue, 7 Feb 2023 17:40:00 -0500
Subject: [PATCH 23/70] Update README.md; minor cosmetic change

---
 README.md                        | 1 +
 src/schema/objects/metadata.yaml | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 796a057f65..5c87c2c0a3 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,7 @@ BIDS currently supports the following data modalities with more to come in the f
 - PET
 - microscopy
 - NIRS
+- MRS
 
 # Formatting your data with BIDS
 
diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index 07ec80b312..95fa8fa36c 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -414,7 +414,7 @@ ChemicalShiftOffset:
   name: ChemicalShiftOffset
   display_name: Chemical Shift Offset
   description: |
-    The chemical shift at the center of `"SpectralWidth"` corresponding to 0 Hz,
+    The chemical shift at the center of `SpectralWidth` corresponding to 0 Hz,
     specified in ppm (for example, `4.65`).
   type: number
 ChemicalShiftReference:

From 96da97d7424a0d94232803d127d2b5f6f3a582c2 Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Thu, 24 Aug 2023 21:48:33 +0200
Subject: [PATCH 24/70] Update src/schema/objects/metadata.yaml

---
 src/schema/objects/metadata.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index a0c25a0ee9..c38dcdd48e 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -2281,7 +2281,7 @@ NumberOfTransients:
   name: NumberOfTransients
   display_name: Number Of Transients
   description: |
-    The number of single applications of the pulse sequence recorded during an MRS acquisiton.
+    The number of single applications of the pulse sequence recorded during an MRS acquisition.
   type: integer
 NumberOfVolumesDiscardedByScanner:
   name: NumberOfVolumesDiscardedByScanner

From cea50ab50846a8d4676e2e430b5986a749ff712a Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Mon, 27 Nov 2023 10:12:19 -0500
Subject: [PATCH 25/70] STY: Cleanup apparent merge artifacts

---
 README.md                      | 3 +--
 src/appendices/contributors.md | 1 -
 src/introduction.md            | 6 +++---
 3 files changed, 4 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 4a7c0bf7f3..9776c2b524 100644
--- a/README.md
+++ b/README.md
@@ -30,9 +30,8 @@ BIDS currently supports the following data modalities with more to come in the f
 - PET
 - microscopy
 - NIRS
-- MRS
 - motion
-
+- MRS
 
 # Formatting your data with BIDS
 
diff --git a/src/appendices/contributors.md b/src/appendices/contributors.md
index e22ee58872..2ffab4740f 100644
--- a/src/appendices/contributors.md
+++ b/src/appendices/contributors.md
@@ -365,4 +365,3 @@ If you contributed to the BIDS ecosystem and your name is not listed, please add
 | josator2                                             | 💻                                     |
 | monkeyman192                                         | 💻                                     |
 | Étienne Bergeron                                     | 🔣💻                                   |
-
diff --git a/src/introduction.md b/src/introduction.md
index 25c7f735c3..7ed3b70e65 100644
--- a/src/introduction.md
+++ b/src/introduction.md
@@ -168,11 +168,11 @@ For example:
 
 -   (publication forthcoming)
 
-
-#### MRS
-
 #### Motion
 
+-   (publication forthcoming)
+
+#### MRS
 
 -   (publication forthcoming)
 

From 50b53e60bd0a03ff52db3b5bd170d798910f4c0c Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Tue, 19 Dec 2023 16:36:14 -0500
Subject: [PATCH 26/70] Update
 src/modality-specific-files/magnetic-resonance-spectroscopy.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Julia Guiomar Niso Galán <guiomar.niso@ctb.upm.es>
---
 src/modality-specific-files/magnetic-resonance-spectroscopy.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/modality-specific-files/magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
index dd809d59a9..b84e72666d 100644
--- a/src/modality-specific-files/magnetic-resonance-spectroscopy.md
+++ b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -21,7 +21,7 @@ and a guide for using macros can be found at
 -->
 
 {{ MACROS___make_filename_template("raw", datatypes=["mrs"], suffixes=["svs", "mrsi", "ref", "unloc"]) }}
-
+MRS is a noninvasive technique to detect biochemical changes in the brain. It is conducted using conventional MRI systems.
 Each manufacturer has its own file format (sometimes multiple formats) for exporting MRS data from
 the scanner console for offline processing.
 GE exports a P-file (`*.7`) that stores unprocessed, un-coil-combined data with metadata embedded

From 983b7c225783f38c0947ac41e6e66c0bec83804d Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Tue, 19 Dec 2023 16:36:47 -0500
Subject: [PATCH 27/70] Update
 src/modality-specific-files/magnetic-resonance-spectroscopy.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Julia Guiomar Niso Galán <guiomar.niso@ctb.upm.es>
---
 src/modality-specific-files/magnetic-resonance-spectroscopy.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/modality-specific-files/magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
index b84e72666d..46741c18ae 100644
--- a/src/modality-specific-files/magnetic-resonance-spectroscopy.md
+++ b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -23,7 +23,7 @@ and a guide for using macros can be found at
 {{ MACROS___make_filename_template("raw", datatypes=["mrs"], suffixes=["svs", "mrsi", "ref", "unloc"]) }}
 MRS is a noninvasive technique to detect biochemical changes in the brain. It is conducted using conventional MRI systems.
 Each manufacturer has its own file format (sometimes multiple formats) for exporting MRS data from
-the scanner console for offline processing.
+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.

From 5f619bcb8953f674249247c7fe974a79be27eaa0 Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Tue, 19 Dec 2023 16:37:45 -0500
Subject: [PATCH 28/70] Update
 src/modality-specific-files/magnetic-resonance-spectroscopy.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Julia Guiomar Niso Galán <guiomar.niso@ctb.upm.es>
---
 .../magnetic-resonance-spectroscopy.md                      | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/modality-specific-files/magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
index 46741c18ae..ab5dbdb89d 100644
--- a/src/modality-specific-files/magnetic-resonance-spectroscopy.md
+++ b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -65,8 +65,10 @@ Note that NIfTI-MRS is not designed to store data that has not been spatially re
 | ---------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | 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.                                                              |
-| Concentration or calibration reference   | ref          | A separate MRS acquisition acquired to detect a signal to serve as a concentration reference for absolute quantification or for preprocessing (for example, eddy-current correction). |
-| Unlocalized spectroscopy                 | unloc        | MRS acquisitions run without localization. This includes signals detected using coil sensitivity only.                                                                                |
+| Unlocalized spectroscopy                 | unloc        | MRS acquisitions run without localization. This includes signals detected using coil sensitivity only.
+|
+| Concentration or calibration reference   | ref          | A separate MRS acquisition acquired to detect a signal to serve as a concentration reference for absolute quantification or 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

From d8a125608ab115b8b707ae086f05b4c977db379c Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Wed, 20 Dec 2023 17:55:15 -0500
Subject: [PATCH 29/70] Update
 src/modality-specific-files/magnetic-resonance-spectroscopy.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Julia Guiomar Niso Galán <guiomar.niso@ctb.upm.es>
---
 .../magnetic-resonance-spectroscopy.md                        | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/modality-specific-files/magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
index ab5dbdb89d..8d10ce2e0e 100644
--- a/src/modality-specific-files/magnetic-resonance-spectroscopy.md
+++ b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -77,8 +77,8 @@ To avoid confusion, the suffixes `svs` and `mrsi` MUST be used to distinguish th
 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.
+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 `ref` MUST be used.

From 36346bc98bce5ee0a6f863f162ed1d180bd1e45d Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Wed, 20 Dec 2023 17:56:47 -0500
Subject: [PATCH 30/70] Update
 src/modality-specific-files/magnetic-resonance-spectroscopy.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Julia Guiomar Niso Galán <guiomar.niso@ctb.upm.es>
---
 src/modality-specific-files/magnetic-resonance-spectroscopy.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/modality-specific-files/magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
index 8d10ce2e0e..2cf9838a7b 100644
--- a/src/modality-specific-files/magnetic-resonance-spectroscopy.md
+++ b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -91,8 +91,7 @@ two references to be used for concentration scaling and eddy-current correction,
 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.
 
-The following labels for the most commonly used in vivo MRS sequences/techniques are OPTIONAL to use
-when using the `acq-<label>` entity in the filename.
+Here we present a set of `<labels>` 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.

From 90ff2383fdd2a4ce2b84e63a7fa374577d500d07 Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Wed, 20 Dec 2023 18:13:26 -0500
Subject: [PATCH 31/70] Update
 src/modality-specific-files/magnetic-resonance-spectroscopy.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Julia Guiomar Niso Galán <guiomar.niso@ctb.upm.es>
---
 src/modality-specific-files/magnetic-resonance-spectroscopy.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/modality-specific-files/magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
index 2cf9838a7b..49da776dd2 100644
--- a/src/modality-specific-files/magnetic-resonance-spectroscopy.md
+++ b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -189,4 +189,3 @@ MAY be present:
    "ReferenceSignal": "bids::sub-01/mrs/sub-01_acq-press_ref.nii.gz",
    "AnatomicalImage": "bids::sub-01/anat/sub-01_T1w.nii.gz"
 }
-```

From aa90b54be5ba45d5a4c3069391d74bfa90566e82 Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Thu, 29 Feb 2024 18:38:48 -0500
Subject: [PATCH 32/70] Update mrs.yaml

---
 src/schema/rules/sidecars/mrs.yaml | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/src/schema/rules/sidecars/mrs.yaml b/src/schema/rules/sidecars/mrs.yaml
index 2928752e67..f0ebb22183 100644
--- a/src/schema/rules/sidecars/mrs.yaml
+++ b/src/schema/rules/sidecars/mrs.yaml
@@ -23,6 +23,16 @@ MRSScannerHardware:
     ReceiveCoilActiveElements: recommended
     NumberReceiveCoilActiveElements: recommended
 
+MRSSample:
+  selectors:
+    - modality == "mrs"
+  fields:
+    BodyPart:
+      level: recommended
+      description_addendum: Corresponds to DICOM Tag 0018, 0015 `Body Part Examined`.
+    BodyPartDetails: recommended
+    BodyPartDetailsOntology: optional
+
 MRSSequenceSpecifics:
   selectors:
     - modality == "mrs"
@@ -60,8 +70,6 @@ MRSRecommendedFields:
     AcquisitionVoxelSize: recommended
     MatrixSize: recommended for MRSI
     VolumeAffineMatrix: recommended for MRSI
-    BodyPart: recommended
-    BodyPartDetails: recommended
     EditTarget: recommended for edited data
     EditPulse: recommended for edited data
     EditCondition: recommended for edited data

From 13243f4559a2ce64b3c245f3e6bf968265d0df7c Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Thu, 29 Feb 2024 18:38:59 -0500
Subject: [PATCH 33/70] Update entities.yaml

---
 src/schema/objects/entities.yaml | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/schema/objects/entities.yaml b/src/schema/objects/entities.yaml
index efd5aba030..ee5ab67534 100644
--- a/src/schema/objects/entities.yaml
+++ b/src/schema/objects/entities.yaml
@@ -425,12 +425,13 @@ volume:
   description: |
     The `voi-<label>` entity can be used to distinguish acquisitions localized to different regions.
     The label SHOULD be the name of the body region or part scanned.
-    If used, the entities `"BodyPart"` and `"BodyPartDetails"` MUST also be defined in the JSON file.
+    If used, the fields `"BodyPart"` and `"BodyPartDetails"` MUST be defined in the JSON file.
+    `BodyPartDetailsOntology` is OPTIONAL to also include.
   type: string
   format: label
 tracksys:
   name: tracksys
-  display_name: Tracking system
+  display_name: Tracking System
   description: |
     The `tracksys-<label>` entity can be used as a key-value pair
     to label *_motion.tsv and *_motion.json files.

From 51a583fd18c7b95530c4927d0ae077fcfeef7889 Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Thu, 29 Feb 2024 18:43:16 -0500
Subject: [PATCH 34/70] Further updates

---
 .../magnetic-resonance-spectroscopy.md        | 99 +++++++++++--------
 src/schema/rules/files/raw/mrs.yaml           |  8 +-
 2 files changed, 62 insertions(+), 45 deletions(-)

diff --git a/src/modality-specific-files/magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
index 49da776dd2..779f1bca5a 100644
--- a/src/modality-specific-files/magnetic-resonance-spectroscopy.md
+++ b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -6,7 +6,7 @@ Please see [Citing BIDS](../introduction.md#citing-bids)
 on how to appropriately credit this extension when referring to it in the
 context of the academic literature.
 
-Several [example MRS datasets](https://github.com/bids-standard/bids-examples#mrs-datasets) have
+Several [example MRS datasets](https://github.com/bids-standard/bids-examples#mrs) have
 been formatted using this specification and can be used for practical guidance when curating a new
 dataset.
 
@@ -21,8 +21,26 @@ and a guide for using macros can be found at
 -->
 
 {{ MACROS___make_filename_template("raw", datatypes=["mrs"], suffixes=["svs", "mrsi", "ref", "unloc"]) }}
-MRS is a noninvasive technique to detect biochemical changes in the brain. It is conducted using conventional MRI systems.
-Each manufacturer has its own file format (sometimes multiple formats) for exporting MRS data from
+
+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](https://doi.org/10.1002/mrm.29418) (`*.nii[.gz]`).
+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](https://github.com/wtclarke/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.
@@ -43,21 +61,7 @@ Contrarily, Bruker stores two binary files: one file stores each transient separ
 while the other stores the sum of the transients.
 Bruker stores the sequence name, voxel position, voxel orientation, and other metadata in a separate plaintext file.
 These files are considered source data and, if present, MUST be stored in the
-[`/sourcedata`](../common-principles.md#source-vs-raw-vs-derived-data) directory.
-
-Due to the diversity in manufacturers' MRS data file formats, source data MUST be converted into the
-[NIfTI-MRS format](https://doi.org/10.1002/mrm.29418) (`*.nii[.gz]`).
-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](https://github.com/wtclarke/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.
+[`sourcedata`](../common-principles.md#source-vs-raw-vs-derived-data) directory.
 
 ### Single-voxel spectroscopy and MRS imaging
 
@@ -65,10 +69,8 @@ Note that NIfTI-MRS is not designed to store data that has not been spatially re
 | ---------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | 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   | ref          | A separate MRS acquisition acquired to detect a signal to serve as a concentration reference for absolute quantification or for preprocessing (for example, eddy-current correction). 
-|
+| Unlocalized spectroscopy                 | unloc        | MRS acquisitions run without localization. This includes signals detected using coil sensitivity only.                                                                                |
+| Concentration or calibration reference   | ref          | A separate MRS acquisition acquired to detect a signal to serve as a concentration reference for absolute quantification or 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
@@ -91,27 +93,28 @@ two references to be used for concentration scaling and eddy-current correction,
 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>` 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.
+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      | A modification of LASER, in sLASER, 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        | This spectral editing technique employs a pair of frequency-selective 180° pulses to refocus *J*-coupled spins at a narrowband 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 editing | mqc         | Multiple-quantum coherence (MQC) editing targets *J*-coupled resonances by selecting desired coherence pathways using MQ gradients and frequency-selective RF pulses.                                                                                                                                                                                                                                                                                                                                   |
-| L-COSY                             | lcosy       | Localized correlation spectroscopy (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 spectroscopy    | dw          | The diffusion of intracellular metabolites can be characterized using diffusion-weighted MRS. 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.                                                                                                                                                                                                                                                                       |
-| Spin-echo spectroscopy             | spinecho    | An MRS experiment whereby the MR signal is detected using a spin-echo acquisition: for example, 90°–180°–acq.                                                                                                                                                                                                                                                                                                                                                                                           |
+| **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 spectroscopy             | dw          | The diffusion of intracellular metabolites can be characterized using diffusion-weighted MRS. 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.                                                                                                                                                                                                                                                                                |
+| Spin-echo spectroscopy                      | spinecho    | An MRS experiment whereby the MR signal is detected using a spin-echo acquisition: for example, 90°–180°–acq.                                                                                                                                                                                                                                                                                                                                                                                                    |
 
 Each `<label>` in the table MAY be combined with another to better describe the acquisition used.
 For example, `megaspecial`, `jpress`, `dwslaser`, and so on.
@@ -124,7 +127,8 @@ The key `ResonantNucleus` MUST also be included in the sidecar JSON file, with t
 Similarly, the OPTIONAL `voi-<label>` key/value pair can be used to distinguish between repeated
 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 entities `BodyPart` and `BodyPartDetails` MUST also be included in the sidecar JSON file.
+If used, the fields `BodyPart` and `BodyPartDetails` MUST also be included in the corresponding sidecar JSON file.
+`BodyPartDetailsOntology` is OPTIONAL to also include.
 
 ## Sidecar JSON
 
@@ -152,6 +156,18 @@ A guide for using macros can be found at
 
 {{ MACROS___make_sidecar_table("mrs.MRSSequenceSpecifics") }}
 
+#### Tissue description
+
+<!-- This block generates a metadata table.
+These tables are defined in
+  src/schema/rules/sidecars
+The definitions of the fields specified in these tables may be found in
+  src/schema/objects/metadata.yaml
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_sidecar_table("mrs.MRSSample") }}
+
 ### MRS-specific fields
 
 Metadata fields that MUST be present:
@@ -184,8 +200,9 @@ MAY be present:
    "NumberOfTransients": 64,
    "RepetitionTime": 2,
    "AcquisitionVoxelSize": [40, 20, 30],
-   "BodyPart": "Brain",
+   "BodyPart": "BRAIN",
    "BodyPartDetails": "Anterior cingulate cortex",
    "ReferenceSignal": "bids::sub-01/mrs/sub-01_acq-press_ref.nii.gz",
    "AnatomicalImage": "bids::sub-01/anat/sub-01_T1w.nii.gz"
 }
+```
diff --git a/src/schema/rules/files/raw/mrs.yaml b/src/schema/rules/files/raw/mrs.yaml
index 8f9ed918c8..4dd3323e34 100644
--- a/src/schema/rules/files/raw/mrs.yaml
+++ b/src/schema/rules/files/raw/mrs.yaml
@@ -41,9 +41,9 @@ mrsi:
     nucleus: optional
     volume: optional
 
-reference:
+unlocalized:
   suffixes:
-    - ref
+    - unloc
   extensions:
     - .nii.gz
     - .nii
@@ -62,9 +62,9 @@ reference:
     nucleus: optional
     volume: optional
 
-unlocalized:
+reference:
   suffixes:
-    - unloc
+    - ref
   extensions:
     - .nii.gz
     - .nii

From ff370d7c8df59b2e8a3691b8341069eafc229077 Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Thu, 29 Feb 2024 20:47:18 -0500
Subject: [PATCH 35/70] Update the `MRAcquisitionType` schema

---
 src/schema/objects/enums.yaml      |  5 +++++
 src/schema/objects/metadata.yaml   | 11 +----------
 src/schema/rules/sidecars/mrs.yaml |  2 +-
 3 files changed, 7 insertions(+), 11 deletions(-)

diff --git a/src/schema/objects/enums.yaml b/src/schema/objects/enums.yaml
index f01d16cdc6..a02ba12c51 100644
--- a/src/schema/objects/enums.yaml
+++ b/src/schema/objects/enums.yaml
@@ -119,6 +119,11 @@ Absent:
   display_name: Absent
   description: |
     No specific M0 information is present.
+OneD:
+  value: 1D
+  display_name: One-dimensional
+  description: |
+    One-dimensional MR acquisition.
 TwoD:
   value: 2D
   display_name: Two-dimensional
diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index 099d03952e..1cc46553fe 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -1939,16 +1939,7 @@ MRAcquisitionType:
     Corresponds to DICOM Tag 0018, 0023 `MR Acquisition Type`.
   type: string
   enum:
-    - $ref: objects.enums.TwoD.value
-    - $ref: objects.enums.ThreeD.value
-MRAcquisitionType__mrs:
-  name: MRAcquisitionType
-  display_name: MR Acquisition Type
-  description: |
-    Type of sequence readout.
-  type: string
-  enum:
-    - 1D
+    - $ref: objects.enums.OneD.value
     - $ref: objects.enums.TwoD.value
     - $ref: objects.enums.ThreeD.value
 MRTransmitCoilSequence:
diff --git a/src/schema/rules/sidecars/mrs.yaml b/src/schema/rules/sidecars/mrs.yaml
index f0ebb22183..533eb9f10c 100644
--- a/src/schema/rules/sidecars/mrs.yaml
+++ b/src/schema/rules/sidecars/mrs.yaml
@@ -44,7 +44,7 @@ MRSSequenceSpecifics:
     ScanningSequence__mrs: recommended
     SequenceName: recommended
     PulseSequenceDetails: recommended
-    MRAcquisitionType__mrs: recommended for MRSI
+    MRAcquisitionType: recommended for MRSI
 
 MRSRequiredFields:
   selectors:

From f9b1eef05c04297c2960345c42d64da7c171eec2 Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Thu, 29 Feb 2024 20:56:03 -0500
Subject: [PATCH 36/70] Update contributors.md

---
 src/appendices/contributors.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/appendices/contributors.md b/src/appendices/contributors.md
index 2ffab4740f..5e979c5f18 100644
--- a/src/appendices/contributors.md
+++ b/src/appendices/contributors.md
@@ -246,7 +246,7 @@ If you contributed to the BIDS ecosystem and your name is not listed, please add
 | Marco Castellaro                                     | 💬🐛💻📖💡⚠️📢🚇                       |
 | Maria de la Iglesia                                  | 📖                                     |
 | Marie-Hélène Bourget                                 | 📖🔣💻🤔                               |
-| Mark Mikkelsen                                       | 📖                                     |
+| Mark Mikkelsen                                       | 📖💻                                     |
 | Markus Morawski                                      | 📖                                     |
 | Marta Bortoletto                                     | 📖                                     |
 | Martin Craig                                         | 🔣                                     |

From 43ed25331657fc97532917a7f670a04a72c082ed Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Fri, 1 Mar 2024 10:13:28 -0500
Subject: [PATCH 37/70] Revert "Update contributors.md"

This reverts commit f9b1eef05c04297c2960345c42d64da7c171eec2.
---
 src/appendices/contributors.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/appendices/contributors.md b/src/appendices/contributors.md
index 5e979c5f18..2ffab4740f 100644
--- a/src/appendices/contributors.md
+++ b/src/appendices/contributors.md
@@ -246,7 +246,7 @@ If you contributed to the BIDS ecosystem and your name is not listed, please add
 | Marco Castellaro                                     | 💬🐛💻📖💡⚠️📢🚇                       |
 | Maria de la Iglesia                                  | 📖                                     |
 | Marie-Hélène Bourget                                 | 📖🔣💻🤔                               |
-| Mark Mikkelsen                                       | 📖💻                                     |
+| Mark Mikkelsen                                       | 📖                                     |
 | Markus Morawski                                      | 📖                                     |
 | Marta Bortoletto                                     | 📖                                     |
 | Martin Craig                                         | 🔣                                     |

From 04c0c0d3a85746f5bea5924872e642700f398de0 Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Fri, 1 Mar 2024 10:38:51 -0500
Subject: [PATCH 38/70] Revert "Update contributors.md"

This reverts commit f9b1eef05c04297c2960345c42d64da7c171eec2.
---
 src/appendices/contributors.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/appendices/contributors.md b/src/appendices/contributors.md
index 5e979c5f18..2ffab4740f 100644
--- a/src/appendices/contributors.md
+++ b/src/appendices/contributors.md
@@ -246,7 +246,7 @@ If you contributed to the BIDS ecosystem and your name is not listed, please add
 | Marco Castellaro                                     | 💬🐛💻📖💡⚠️📢🚇                       |
 | Maria de la Iglesia                                  | 📖                                     |
 | Marie-Hélène Bourget                                 | 📖🔣💻🤔                               |
-| Mark Mikkelsen                                       | 📖💻                                     |
+| Mark Mikkelsen                                       | 📖                                     |
 | Markus Morawski                                      | 📖                                     |
 | Marta Bortoletto                                     | 📖                                     |
 | Martin Craig                                         | 🔣                                     |

From 873fd79846278d2218d56ee6e668312f8262b2aa Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Fri, 1 Mar 2024 14:58:20 -0500
Subject: [PATCH 39/70] Add a section about MRS-MRI correspondence

---
 .../magnetic-resonance-spectroscopy.md                        | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/src/modality-specific-files/magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
index 779f1bca5a..a2eb9b344c 100644
--- a/src/modality-specific-files/magnetic-resonance-spectroscopy.md
+++ b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -206,3 +206,7 @@ MAY be present:
    "AnatomicalImage": "bids::sub-01/anat/sub-01_T1w.nii.gz"
 }
 ```
+
+## Combining MRS with anatomical MRI
+
+For combining MRS with anatomical MRI data, see the MRS-MRI correspondence in the [Cross modality correspondence](../appendices/cross-modality-correspondence.html) section of the Appendix.

From 22c7dd9bb803c6ab89ea208bf4a60c83f91633f1 Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Thu, 21 Mar 2024 13:51:40 -0400
Subject: [PATCH 40/70] Update magnetic-resonance-spectroscopy.md

Add Mkdocs admonition to example datasets paragraph
---
 .../magnetic-resonance-spectroscopy.md                    | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/src/modality-specific-files/magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
index a2eb9b344c..9ac88a6b1d 100644
--- a/src/modality-specific-files/magnetic-resonance-spectroscopy.md
+++ b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -6,9 +6,11 @@ Please see [Citing BIDS](../introduction.md#citing-bids)
 on how to appropriately credit this extension when referring to it in the
 context of the academic literature.
 
-Several [example MRS datasets](https://github.com/bids-standard/bids-examples#mrs) have
-been formatted using this specification and can be used for practical guidance when curating a new
-dataset.
+!!! example "Example datasets"
+
+    Several [example MRS datasets](https://github.com/bids-standard/bids-examples#mrs) have
+    been formatted using this specification and can be used for practical guidance when curating a new
+    dataset.
 
 ## MRS data
 

From e75c74e0d89dbdc3fc043d9bb59a4c563467184b Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Wed, 27 Mar 2024 23:51:22 -0400
Subject: [PATCH 41/70] Change tissue description requirement levels in MRS to
 optional

---
 src/schema/rules/sidecars/mrs.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/schema/rules/sidecars/mrs.yaml b/src/schema/rules/sidecars/mrs.yaml
index 533eb9f10c..a565af0a48 100644
--- a/src/schema/rules/sidecars/mrs.yaml
+++ b/src/schema/rules/sidecars/mrs.yaml
@@ -28,9 +28,9 @@ MRSSample:
     - modality == "mrs"
   fields:
     BodyPart:
-      level: recommended
+      level: optional
       description_addendum: Corresponds to DICOM Tag 0018, 0015 `Body Part Examined`.
-    BodyPartDetails: recommended
+    BodyPartDetails: optional
     BodyPartDetailsOntology: optional
 
 MRSSequenceSpecifics:

From 4772d83dcda718f4d55e59c93377ab2962b5a6b5 Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Thu, 28 Mar 2024 00:03:36 -0400
Subject: [PATCH 42/70] Update MRS-MRI correspondence

---
 src/appendices/cross-modality-correspondence.md                | 2 +-
 src/modality-specific-files/magnetic-resonance-spectroscopy.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/appendices/cross-modality-correspondence.md b/src/appendices/cross-modality-correspondence.md
index 90440af2ca..6dba22b325 100644
--- a/src/appendices/cross-modality-correspondence.md
+++ b/src/appendices/cross-modality-correspondence.md
@@ -16,6 +16,6 @@ Norgaard et al. 2019, [doi:10.1016/j.neuroimage.2019.05.055](https://doi.org/10.
 ## MRS-MRI correspondence
 
 It is typical to acquire high-resolution 3D anatomical MR images alongside MRS data for
-voxel/slab placement, co-registration, and partial volume tissue correction of metabolite concentrations.
+voxel/slab placement, co-registration, and partial-volume tissue correction of metabolite concentrations.
 To avoid incorrectly matching an MRS dataset with a corresponding anatomical MR image,
 it is RECOMMENDED that the field `AnatomicalImage` be included in the MRS sidecar JSON files.
diff --git a/src/modality-specific-files/magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
index 9ac88a6b1d..531cbd4406 100644
--- a/src/modality-specific-files/magnetic-resonance-spectroscopy.md
+++ b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -211,4 +211,4 @@ MAY be present:
 
 ## Combining MRS with anatomical MRI
 
-For combining MRS with anatomical MRI data, see the MRS-MRI correspondence in the [Cross modality correspondence](../appendices/cross-modality-correspondence.html) section of the Appendix.
+For combining MRS data with anatomical MRI data, see [MRS-MRI correspondence](../appendices/cross-modality-correspondence.md#mrs-mri-correspondence) in the Appendix.

From 248de47ec238325a784df3ecfda2a3d053f3b8a1 Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Thu, 28 Mar 2024 00:24:09 -0400
Subject: [PATCH 43/70] Change suffix `ref` to `mrsref`

---
 .../magnetic-resonance-spectroscopy.md        | 44 +++++++++----------
 src/schema/objects/suffixes.yaml              | 21 +++++----
 src/schema/rules/files/raw/mrs.yaml           |  2 +-
 3 files changed, 33 insertions(+), 34 deletions(-)

diff --git a/src/modality-specific-files/magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
index 531cbd4406..7b6e4f53e4 100644
--- a/src/modality-specific-files/magnetic-resonance-spectroscopy.md
+++ b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -22,7 +22,7 @@ and a guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
 
-{{ MACROS___make_filename_template("raw", datatypes=["mrs"], suffixes=["svs", "mrsi", "ref", "unloc"]) }}
+{{ MACROS___make_filename_template("raw", datatypes=["mrs"], suffixes=["svs", "mrsi", "unloc", "mrsref"]) }}
 
 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.
@@ -72,7 +72,7 @@ These files are considered source data and, if present, MUST be stored in the
 | 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   | ref          | A separate MRS acquisition acquired to detect a signal to serve as a concentration reference for absolute quantification or for preprocessing (for example, eddy-current correction). |
+| 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
@@ -85,9 +85,9 @@ scaling metabolite signal levels (for example, to obtain concentrations) and/or
 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 `ref` MUST be used.
+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_ref.nii.gz` and `sub-01_acq-ecc_ref.nii.gz` could be used to name
+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
@@ -188,24 +188,24 @@ MAY be present:
 
 ```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_ref.nii.gz",
-   "AnatomicalImage": "bids::sub-01/anat/sub-01_T1w.nii.gz"
+  "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"
 }
 ```
 
diff --git a/src/schema/objects/suffixes.yaml b/src/schema/objects/suffixes.yaml
index 52e0e23bb5..29b7d36b59 100644
--- a/src/schema/objects/suffixes.yaml
+++ b/src/schema/objects/suffixes.yaml
@@ -666,17 +666,23 @@ meg:
   description: |
     Unprocessed MEG data stored in the native file format of the MEG instrument
     with which the data was collected.
+motion:
+  value: motion
+  display_name: Motion
+  description: |
+    Data recorded from a tracking system store.
 mrsi:
   value: mrsi
   display_name: Magnetic resonance spectroscopy imaging
   description: |
     MRS acquisitions where additional imaging gradients are used
     to detect the MR signal from 1, 2, or 3 spatial dimensions.
-motion:
-  value: motion
-  display_name: Motion
+mrsref:
+  value: mrsref
+  display_name: MRS reference acquisition
   description: |
-    Data recorded from a tracking system store.
+    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).
 nirs:
   value: nirs
   display_name: Near Infrared Spectroscopy
@@ -745,13 +751,6 @@ probseg:
     A probabilistic segmentation.
 
     This suffix may only be used in derivative datasets.
-ref:
-  value: ref
-  display_name: MRS
-  description: |
-    An MRS acquisition acquired to detect a signal to serve
-    as a concentration reference for absolute quantification
-    or for preprocessing (for example, eddy-current correction).
 sbref:
   value: sbref
   display_name: Single-band reference image
diff --git a/src/schema/rules/files/raw/mrs.yaml b/src/schema/rules/files/raw/mrs.yaml
index 4dd3323e34..835c31e008 100644
--- a/src/schema/rules/files/raw/mrs.yaml
+++ b/src/schema/rules/files/raw/mrs.yaml
@@ -64,7 +64,7 @@ unlocalized:
 
 reference:
   suffixes:
-    - ref
+    - mrsref
   extensions:
     - .nii.gz
     - .nii

From b52b725f1d3dfdcbdd245070c6b4fa1b5b842e84 Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Thu, 28 Mar 2024 01:45:46 -0400
Subject: [PATCH 44/70] Update magnetic-resonance-spectroscopy.md

Adding metabolite-cycled spectroscopy to MRS sequences
---
 .../magnetic-resonance-spectroscopy.md                       | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/modality-specific-files/magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
index 7b6e4f53e4..2802834236 100644
--- a/src/modality-specific-files/magnetic-resonance-spectroscopy.md
+++ b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -114,12 +114,13 @@ If used, the chosen label SHOULD also be described in the `PulseSequenceType` fi
 | 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 spectroscopy             | dw          | The diffusion of intracellular metabolites can be characterized using diffusion-weighted MRS. In such acquisitions, the strength of gradients in a conventional MRS sequence is modulated to sensitize the metabolite signals to diffusion.                                                                                                                                                                                                                                                                      |
+| 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: for example, 90°–180°–acq.                                                                                                                                                                                                                                                                                                                                                                                                    |
 
 Each `<label>` in the table MAY be combined with another to better describe the acquisition used.
-For example, `megaspecial`, `jpress`, `dwslaser`, and so on.
+For example, `megaspecial`, `jpress`, `dwslaser`, `mcdwsteam`, and so on.
 
 The OPTIONAL `nuc-<label>` key/value pair 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.

From 37620c9b38c3575bc77c4703142ae4cc233c0d89 Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Thu, 28 Mar 2024 02:50:09 -0400
Subject: [PATCH 45/70] Update mrs.yaml

---
 src/schema/rules/sidecars/mrs.yaml | 7 -------
 1 file changed, 7 deletions(-)

diff --git a/src/schema/rules/sidecars/mrs.yaml b/src/schema/rules/sidecars/mrs.yaml
index a565af0a48..46f73e43b3 100644
--- a/src/schema/rules/sidecars/mrs.yaml
+++ b/src/schema/rules/sidecars/mrs.yaml
@@ -81,13 +81,6 @@ MRSRecommendedFields:
     ReferenceSignal: recommended if MRS reference data are present
     AnatomicalImage: recommended if anatomical MRI data are present
 
-NumberOfTransientsRecommended:
-  selectors:
-    - datatype == "mrs"
-    - intersects([suffix], ["svs", "unloc"])
-  fields:
-    NumberOfTransients: recommended
-
 MRSOptionalFields:
   selectors:
     - modality == "mrs"

From 704844cb2ea55edb91f294cc690c2c7f061c529c Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Mon, 8 Apr 2024 23:46:44 -0400
Subject: [PATCH 46/70] Update magnetic-resonance-spectroscopy.md

- Cosmetic edits
---
 .../magnetic-resonance-spectroscopy.md        | 36 +++++++++++++++++--
 1 file changed, 33 insertions(+), 3 deletions(-)

diff --git a/src/modality-specific-files/magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
index 2802834236..19e4868a48 100644
--- a/src/modality-specific-files/magnetic-resonance-spectroscopy.md
+++ b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -17,11 +17,10 @@ context of the academic literature.
 <!--
 This block generates filename templates.
 The inputs for this macro can be found in the directory
-  src/schema/rules/files
+  src/schema/rules/files/raw
 and a guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
-
 {{ MACROS___make_filename_template("raw", datatypes=["mrs"], suffixes=["svs", "mrsi", "unloc", "mrsref"]) }}
 
 MRS is a spectroscopic technique based on the phenomenon of nuclear magnetic resonance
@@ -152,11 +151,18 @@ The definitions of the fields specified in these tables may be found in
 A guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
-
 {{ MACROS___make_sidecar_table("mrs.MRSScannerHardware") }}
 
 #### Sequence specifics
 
+<!-- This block generates a metadata table.
+These tables are defined in
+  src/schema/rules/sidecars
+The definitions of the fields specified in these tables may be found in
+  src/schema/objects/metadata.yaml
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_sidecar_table("mrs.MRSSequenceSpecifics") }}
 
 #### Tissue description
@@ -175,14 +181,38 @@ A guide for using macros can be found at
 
 Metadata fields that MUST be present:
 
+<!-- This block generates a metadata table.
+These tables are defined in
+  src/schema/rules/sidecars
+The definitions of the fields specified in these tables may be found in
+  src/schema/objects/metadata.yaml
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_sidecar_table("mrs.MRSRequiredFields") }}
 
 SHOULD be present:
 
+<!-- This block generates a metadata table.
+These tables are defined in
+  src/schema/rules/sidecars
+The definitions of the fields specified in these tables may be found in
+  src/schema/objects/metadata.yaml
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_sidecar_table("mrs.MRSRecommendedFields") }}
 
 MAY be present:
 
+<!-- This block generates a metadata table.
+These tables are defined in
+  src/schema/rules/sidecars
+The definitions of the fields specified in these tables may be found in
+  src/schema/objects/metadata.yaml
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_sidecar_table("mrs.MRSOptionalFields") }}
 
 ### Example `*_svs.json`

From 836d01b4b64866ce5000dd58917ccee4430a3b45 Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Fri, 12 Apr 2024 22:25:23 -0400
Subject: [PATCH 47/70] Cleaning up language

---
 .../magnetic-resonance-spectroscopy.md        | 58 +++++++++----------
 src/schema/objects/metadata.yaml              |  9 ++-
 2 files changed, 33 insertions(+), 34 deletions(-)

diff --git a/src/modality-specific-files/magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
index 19e4868a48..bc3c94be4c 100644
--- a/src/modality-specific-files/magnetic-resonance-spectroscopy.md
+++ b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -47,9 +47,9 @@ GE exports a P-file (`*.7`) that stores unprocessed, un-coil-combined data with
 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 transient summed into a signal average.
+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` and DICOM files.
+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;
@@ -58,10 +58,10 @@ 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.
-Contrarily, Bruker stores two binary files: one file stores each transient separately,
+Bruker data are are exported as two binary files: one file stores each transient separately,
 while the other stores the sum of the transients.
-Bruker stores the sequence name, voxel position, voxel orientation, and other metadata in a separate plaintext file.
-These files are considered source data and, if present, MUST be stored in the
+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`](../common-principles.md#source-vs-raw-vs-derived-data) directory.
 
 ### Single-voxel spectroscopy and MRS imaging
@@ -100,33 +100,33 @@ Users are free to choose any label they wish as long as they are consistent acro
 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: for example, 90°–180°–acq.                                                                                                                                                                                                                                                                                                                                                                                                    |
-
-Each `<label>` in the table MAY be combined with another to better describe the acquisition used.
+| **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>` key/value pair can be used to distinguish acquisitions tuned to detect different nuclei.
+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`.
-The key `ResonantNucleus` MUST also be included in the sidecar JSON file, with the same label.
+If used, the field `ResonantNucleus` MUST also be included in the corresponding sidecar JSON file, using the same label.
 
-Similarly, the OPTIONAL `voi-<label>` key/value pair can be used to distinguish between repeated
+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.
@@ -138,8 +138,8 @@ MRS data files MUST be described by metadata fields, stored in sidecar JSON file
 
 ### Common metadata fields
 
-Metadata described in the following sections are shared with other MR modalities and SHOULD be
-present in the sidecar JSON files.
+Metadata described in the following sections are shared with other MR modalities that SHOULD
+or MAY be present in the sidecar JSON files.
 
 #### Scanner hardware
 
diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index 20f98ba386..fcf7c97081 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -37,7 +37,7 @@ AcquisitionVoxelSize:
   display_name: Acquisition Voxel Size
   description: |
     An array of numbers with a length of 3, in millimeters.
-    This parameter denotes the original acquisition voxel size,
+    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,
@@ -2641,9 +2641,7 @@ PulseSequencePulses:
   display_name: Pulse Sequence Pulses
   description: |
     The list of pulses used in the pulse sequence.
-    If this parameter is specified, the array MUST correspond to the array of timings in
-    `"PulseSequenceTiming"`.
-    That is, the length of both arrays MUST be equal.
+    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"]`.
@@ -2655,7 +2653,8 @@ PulseSequenceTiming:
   display_name: Pulse Sequence Timing
   description: |
     The time when each RF pulse of the pulse sequence was played out relative to
-    the beginning of the pulse sequence, specified in seconds.
+    the beginning of the pulse sequence (that is, the top of the excitation RF pulse),
+    specified in seconds.
   type: array
   items:
     type: number

From 326a870ca8f3fac4495407be1c023a96c2cc7226 Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Fri, 12 Apr 2024 22:34:40 -0400
Subject: [PATCH 48/70] Update mrs.yaml

- Reorder MRS fields to coincide with (now) shared MRI fields
---
 src/schema/rules/sidecars/mrs.yaml | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/src/schema/rules/sidecars/mrs.yaml b/src/schema/rules/sidecars/mrs.yaml
index 46f73e43b3..e36b76e9e2 100644
--- a/src/schema/rules/sidecars/mrs.yaml
+++ b/src/schema/rules/sidecars/mrs.yaml
@@ -21,7 +21,8 @@ MRSScannerHardware:
     MagneticFieldStrength: recommended
     ReceiveCoilName: recommended
     ReceiveCoilActiveElements: recommended
-    NumberReceiveCoilActiveElements: recommended
+    NumberReceiveCoilActiveElements: optional
+    NumberTransmitCoilActiveElements: optional
 
 MRSSample:
   selectors:
@@ -45,6 +46,11 @@ MRSSequenceSpecifics:
     SequenceName: recommended
     PulseSequenceDetails: recommended
     MRAcquisitionType: recommended for MRSI
+    WaterSuppression: recommended
+    WaterSuppressionTechnique: optional
+    OuterVolumeSuppression: recommended
+    B0ShimmingTechnique: optional
+    B1ShimmingTechnique: optional
 
 MRSRequiredFields:
   selectors:
@@ -73,11 +79,7 @@ MRSRecommendedFields:
     EditTarget: recommended for edited data
     EditPulse: recommended for edited data
     EditCondition: recommended for edited data
-    WaterSuppression: recommended
-    WaterSuppressionTechnique: recommended
-    OuterVolumeSuppression: recommended
     EncodingTechnique: recommended for MRSI
-    B0ShimmingTechnique: recommended
     ReferenceSignal: recommended if MRS reference data are present
     AnatomicalImage: recommended if anatomical MRI data are present
 
@@ -91,8 +93,6 @@ MRSOptionalFields:
     ParallelReductionFactorInPlane: optional
     ParallelAcquisitionTechnique: optional
     MultibandAccelerationFactor: optional
-    NumberTransmitCoilActiveElements: optional
-    B1ShimmingTechnique: optional
     PulseSequenceTiming: optional
     PulseSequencePulses: optional
     ReceiveGain: optional

From c00f3602186847e02f8fe4ebece1fdbe340900c7 Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Sat, 20 Apr 2024 17:44:51 -0400
Subject: [PATCH 49/70] Apply suggestions from code review

Co-authored-by: Chris Markiewicz <markiewicz@stanford.edu>
---
 .../magnetic-resonance-spectroscopy.md        |  4 +-
 src/schema/objects/metadata.yaml              | 28 +++++++--
 src/schema/rules/files/raw/mrs.yaml           | 62 +------------------
 src/schema/rules/sidecars/mrs.yaml            |  4 +-
 4 files changed, 27 insertions(+), 71 deletions(-)

diff --git a/src/modality-specific-files/magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
index bc3c94be4c..276cd64323 100644
--- a/src/modality-specific-files/magnetic-resonance-spectroscopy.md
+++ b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -8,7 +8,7 @@ context of the academic literature.
 
 !!! example "Example datasets"
 
-    Several [example MRS datasets](https://github.com/bids-standard/bids-examples#mrs) have
+    Several [example MRS datasets](https://github.com/bids-standard/bids-examples/pull/425) have
     been formatted using this specification and can be used for practical guidance when curating a new
     dataset.
 
@@ -28,7 +28,7 @@ that allows for the noninvasive detection and quantification of molecules in bio
 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](https://doi.org/10.1002/mrm.29418) (`*.nii[.gz]`).
+[NIfTI-MRS format](https://wtclarke.github.io/mrs_nifti_standard/) (`*.nii[.gz]`).
 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.
diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index fcf7c97081..2a6ddfdfb4 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -79,9 +79,11 @@ AnatomicalImage:
     Contains one or more [BIDS URIs](SPEC_ROOT/common-principles.md#bids-uri).
   anyOf:
     - type: string
+      format: bids_uri
     - type: array
       items:
         type: string
+        format: bids_uri
 AnatomicalLandmarkCoordinateSystem:
   name: AnatomicalLandmarkCoordinateSystem
   display_name: Anatomical Landmark Coordinate System
@@ -421,6 +423,7 @@ ChemicalShiftOffset:
     The chemical shift at the center of `SpectralWidth` corresponding to 0 Hz,
     specified in ppm (for example, `4.65`).
   type: number
+  unit: ppm
 ChemicalShiftReference:
   name: ChemicalShiftReference
   display_name: Chemical Shift Reference
@@ -428,6 +431,7 @@ ChemicalShiftReference:
     The chemical shift at the transmitter frequency, specified in ppm (for example, `2.68`).
     Corresponds to DICOM Tag 0018, 9053 `Chemical Shift Reference`.
   type: number
+  unit: ppm
 ChunkTransformationMatrix:
   name: ChunkTransformationMatrix
   display_name: Chunk Transformation Matrix
@@ -2059,7 +2063,7 @@ MatrixSize:
   maxItems: 3
   items:
     type: integer
-    exclusiveMinimum: 1
+    minimum: 1
 MaxMovement:
   name: MaxMovement
   display_name: Max Movement
@@ -2658,6 +2662,7 @@ PulseSequenceTiming:
   type: array
   items:
     type: number
+    unit: s
 PulseSequenceType:
   name: PulseSequenceType
   display_name: Pulse Sequence Type
@@ -2718,9 +2723,11 @@ ReceiveGain:
     The gain of the receive coil.
   anyOf:
     - type: number
+      unit: dB
     - type: array
       items:
         type: number
+        unit: dB
 ReconFilterSize:
   name: ReconFilterSize
   display_name: Recon Filter Size
@@ -2818,9 +2825,11 @@ ReferenceSignal:
     Contains one or more [BIDS URIs](SPEC_ROOT/common-principles.md#bids-uri).
   anyOf:
     - type: string
+      format: bids_uri
     - type: array
       items:
         type: string
+        format: bids_uri
 RepetitionTime:
   name: RepetitionTime
   display_name: Repetition Time
@@ -2853,12 +2862,12 @@ RepetitionTime__mrs:
     may differ over the scan, an array of numbers can be used.
   anyOf:
     - type: number
-      minimum: 0
+      exclusiveMinimum: 0
       unit: s
     - type: array
       items:
         type: number
-        minimum: 0
+        exclusiveMinimum: 0
         unit: s
 RepetitionTimeExcitation:
   name: RepetitionTimeExcitation
@@ -3475,6 +3484,7 @@ SpectralWidth:
     The spectral bandwidth of the MR signal that is sampled, specified in Hz.
     Corresponds to DICOM Tag 0018, 9052 `Spectral Width`.
   type: number
+  unit: Hz
 SpectrometerFrequency:
   name: SpectrometerFrequency
   display_name: Spectrometer Frequency
@@ -3486,9 +3496,11 @@ SpectrometerFrequency:
     an array can be used: `[127.731, 32.125]`.
   anyOf:
     - type: number
+      unit: MHz
     - type: array
       items:
         type: number
+        unit: MHz
 SpoilingGradientDuration:
   name: SpoilingGradientDuration
   display_name: Spoiling Gradient Duration
@@ -3804,10 +3816,14 @@ VolumeAffineMatrix:
     For example: `[[30, 0, 0, -30], [0, 30, -2.27, -72.67], [0, 2.27, 29.91, 5.47],
     [0, 0, 0, 1]]`.
   type: array
-  minItems: 16
-  maxItems: 16
+  minItems: 4
+  maxItems: 4
   items:
-    type: number
+    type: array
+    minItems: 4
+    maxItems: 4
+    items:
+      type: number
 VELChannelCount:
   name: VELChannelCount
   display_name: Velocity Channel Count
diff --git a/src/schema/rules/files/raw/mrs.yaml b/src/schema/rules/files/raw/mrs.yaml
index 835c31e008..fe95f08f3a 100644
--- a/src/schema/rules/files/raw/mrs.yaml
+++ b/src/schema/rules/files/raw/mrs.yaml
@@ -1,69 +1,9 @@
 ---
-svs:
+mrs:
   suffixes:
     - svs
-  extensions:
-    - .nii.gz
-    - .nii
-    - .json
-  datatypes:
-    - mrs
-  entities:
-    subject: required
-    session: optional
-    task: optional
-    acquisition: optional
-    reconstruction: optional
-    run: optional
-    echo: optional
-    inversion: optional
-    nucleus: optional
-    volume: optional
-
-mrsi:
-  suffixes:
     - mrsi
-  extensions:
-    - .nii.gz
-    - .nii
-    - .json
-  datatypes:
-    - mrs
-  entities:
-    subject: required
-    session: optional
-    task: optional
-    acquisition: optional
-    reconstruction: optional
-    run: optional
-    echo: optional
-    inversion: optional
-    nucleus: optional
-    volume: optional
-
-unlocalized:
-  suffixes:
     - unloc
-  extensions:
-    - .nii.gz
-    - .nii
-    - .json
-  datatypes:
-    - mrs
-  entities:
-    subject: required
-    session: optional
-    task: optional
-    acquisition: optional
-    reconstruction: optional
-    run: optional
-    echo: optional
-    inversion: optional
-    nucleus: optional
-    volume: optional
-
-reference:
-  suffixes:
     - mrsref
   extensions:
     - .nii.gz
diff --git a/src/schema/rules/sidecars/mrs.yaml b/src/schema/rules/sidecars/mrs.yaml
index e36b76e9e2..684125ba7f 100644
--- a/src/schema/rules/sidecars/mrs.yaml
+++ b/src/schema/rules/sidecars/mrs.yaml
@@ -45,7 +45,7 @@ MRSSequenceSpecifics:
     ScanningSequence__mrs: recommended
     SequenceName: recommended
     PulseSequenceDetails: recommended
-    MRAcquisitionType: recommended for MRSI
+    MRAcquisitionType: optional, but recommended for MRSI
     WaterSuppression: recommended
     WaterSuppressionTechnique: optional
     OuterVolumeSuppression: recommended
@@ -81,7 +81,7 @@ MRSRecommendedFields:
     EditCondition: recommended for edited data
     EncodingTechnique: recommended for MRSI
     ReferenceSignal: recommended if MRS reference data are present
-    AnatomicalImage: recommended if anatomical MRI data are present
+    AnatomicalImage: optional, but recommended if anatomical MRI data are present
 
 MRSOptionalFields:
   selectors:

From 7b00ba33a1fba941efc7912f248b860d943e3749 Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Mon, 22 Apr 2024 17:11:15 -0400
Subject: [PATCH 50/70] Update magnetic-resonance-spectroscopy.md

- Add NIfTI paper DOI
---
 src/modality-specific-files/magnetic-resonance-spectroscopy.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/modality-specific-files/magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
index 276cd64323..81ae6c68a4 100644
--- a/src/modality-specific-files/magnetic-resonance-spectroscopy.md
+++ b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -28,7 +28,7 @@ that allows for the noninvasive detection and quantification of molecules in bio
 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](https://wtclarke.github.io/mrs_nifti_standard/) (`*.nii[.gz]`).
+[NIfTI-MRS format](https://wtclarke.github.io/mrs_nifti_standard/) (`*.nii[.gz]`) ([doi:10.1002/mrm.29418](https://doi.org/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.

From e1c1d189f0d5e623e13a28747e1e227f055178d6 Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Mon, 22 Apr 2024 18:06:08 -0400
Subject: [PATCH 51/70] Update magnetic-resonance-spectroscopy.md

- Fix table at lines 69-74
---
 .../magnetic-resonance-spectroscopy.md                 | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/modality-specific-files/magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
index 81ae6c68a4..963d45b145 100644
--- a/src/modality-specific-files/magnetic-resonance-spectroscopy.md
+++ b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -66,11 +66,11 @@ All of these files are considered source data and, if present, MUST be stored in
 
 ### 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.                                                                                |
+| **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

From 5eb0b5b1927aca27dab5adab8e9179596e7d38b2 Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Wed, 1 May 2024 19:30:13 -0400
Subject: [PATCH 52/70] Update `mrs.yaml`

- Change 'EditTarget', 'EditPulse', and 'EditCondition' to 'optional'
---
 src/schema/rules/sidecars/mrs.yaml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/schema/rules/sidecars/mrs.yaml b/src/schema/rules/sidecars/mrs.yaml
index 684125ba7f..bedbec51c5 100644
--- a/src/schema/rules/sidecars/mrs.yaml
+++ b/src/schema/rules/sidecars/mrs.yaml
@@ -76,9 +76,6 @@ MRSRecommendedFields:
     AcquisitionVoxelSize: recommended
     MatrixSize: recommended for MRSI
     VolumeAffineMatrix: recommended for MRSI
-    EditTarget: recommended for edited data
-    EditPulse: recommended for edited data
-    EditCondition: recommended for edited data
     EncodingTechnique: recommended for MRSI
     ReferenceSignal: recommended if MRS reference data are present
     AnatomicalImage: optional, but recommended if anatomical MRI data are present
@@ -89,6 +86,9 @@ MRSOptionalFields:
   fields:
     ChemicalShiftOffset: optional
     ChemicalShiftReference: optional
+    EditTarget: optional
+    EditPulse: optional
+    EditCondition: optional
     EchoAcquisition: optional
     ParallelReductionFactorInPlane: optional
     ParallelAcquisitionTechnique: optional

From f024d8e3af3762e339a8964c4164f02f39867793 Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Wed, 1 May 2024 23:17:33 -0400
Subject: [PATCH 53/70] Update src/schema/objects/metadata.yaml

Co-authored-by: Chris Markiewicz <markiewicz@stanford.edu>
---
 src/schema/objects/metadata.yaml | 20 ++++++++++++++++----
 1 file changed, 16 insertions(+), 4 deletions(-)

diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index 8881d02b4c..f00f96cfbf 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -947,10 +947,22 @@ EditPulse:
     For example:
     `{"ON": {"FrequencyOffset": 1.9, "PulseDuration": 16},
     "OFF": {"FrequencyOffset": 7.5, "PulseDuration": 16}}`.
-  anyOf:
-    - type: object
-      additionalProperties:
-        type: object
+  type: object
+  additionalProperties:
+    type: object
+    recommended_fields: [FrequencyOffset, PulseDuration]
+    properties:
+      FrequencyOffset:
+        anyOf:
+          - type: number
+            unit: ppm
+          - type: array
+            items:
+              type: number
+              unit: ppm
+      PulseDuration:
+        type: number
+        unit: ms
 EditTarget:
   name: EditTarget
   display_name: Editing Target

From defe06bcc48c7a2c5aeeaa2446a6eeeaf38467d6 Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Wed, 1 May 2024 23:43:36 -0400
Subject: [PATCH 54/70] Update magnetic-resonance-spectroscopy.md

- Change "MRS-specific" to "MRS-relevant"
---
 src/modality-specific-files/magnetic-resonance-spectroscopy.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/modality-specific-files/magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
index 963d45b145..1c5c15b1a9 100644
--- a/src/modality-specific-files/magnetic-resonance-spectroscopy.md
+++ b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -177,7 +177,7 @@ A guide for using macros can be found at
 -->
 {{ MACROS___make_sidecar_table("mrs.MRSSample") }}
 
-### MRS-specific fields
+### MRS-relevant fields
 
 Metadata fields that MUST be present:
 

From f8a45345289f6e4c80e53f99a0e06ca35c4da1f5 Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Wed, 1 May 2024 23:50:03 -0400
Subject: [PATCH 55/70] Set `OuterVolumeSuppression` as `optional`

---
 src/schema/rules/sidecars/mrs.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/schema/rules/sidecars/mrs.yaml b/src/schema/rules/sidecars/mrs.yaml
index bedbec51c5..aa164f98ea 100644
--- a/src/schema/rules/sidecars/mrs.yaml
+++ b/src/schema/rules/sidecars/mrs.yaml
@@ -48,7 +48,7 @@ MRSSequenceSpecifics:
     MRAcquisitionType: optional, but recommended for MRSI
     WaterSuppression: recommended
     WaterSuppressionTechnique: optional
-    OuterVolumeSuppression: recommended
+    OuterVolumeSuppression: optional
     B0ShimmingTechnique: optional
     B1ShimmingTechnique: optional
 

From 44f5e63e34fee7e43539cbcb4450ad10ffb4ff21 Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Thu, 2 May 2024 00:30:55 -0400
Subject: [PATCH 56/70] Update fields for MRS

---
 .../magnetic-resonance-spectroscopy.md        |  8 +++++-
 src/schema/rules/sidecars/mrs.yaml            | 25 ++++++++++++++++---
 2 files changed, 28 insertions(+), 5 deletions(-)

diff --git a/src/modality-specific-files/magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
index 1c5c15b1a9..0c6e547b62 100644
--- a/src/modality-specific-files/magnetic-resonance-spectroscopy.md
+++ b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -201,7 +201,13 @@ The definitions of the fields specified in these tables may be found in
 A guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
-{{ MACROS___make_sidecar_table("mrs.MRSRecommendedFields") }}
+{{ MACROS___make_sidecar_table([
+  "mrs.MRSRecommendedFields",
+  "mrs.MRSRecommendedFieldsNumTransients",
+  "mrs.MRSRecommendedFieldsAnatomicalImage",
+  "mrs.MRSIRecommendedFields"
+  ])
+}}
 
 MAY be present:
 
diff --git a/src/schema/rules/sidecars/mrs.yaml b/src/schema/rules/sidecars/mrs.yaml
index aa164f98ea..7ac11a6697 100644
--- a/src/schema/rules/sidecars/mrs.yaml
+++ b/src/schema/rules/sidecars/mrs.yaml
@@ -66,9 +66,6 @@ MRSRecommendedFields:
     - modality == "mrs"
   fields:
     NumberOfSpectralPoints: recommended
-    NumberOfTransients:
-      level: optional
-      level_addendum: recommended for SVS and unloc
     RepetitionTime__mrs: recommended
     MixingTime: recommended
     InversionTime: recommended for inversion recovery data
@@ -78,7 +75,27 @@ MRSRecommendedFields:
     VolumeAffineMatrix: recommended for MRSI
     EncodingTechnique: recommended for MRSI
     ReferenceSignal: recommended if MRS reference data are present
-    AnatomicalImage: optional, but recommended if anatomical MRI data are present
+
+MRSRecommendedFieldsAnatomicalImage:
+  selectors:
+    - modality == "mrs"
+    - '"anat" in dataset.datatypes'
+  fields:
+    AnatomicalImage: recommended
+
+MRSRecommendedFieldsNumTransients:
+  selectors:
+    - modality == "mrs"
+    - intersects([suffix], ["svs", "unloc"])
+  fields:
+    NumberOfTransients: recommended
+
+MRSIRecommendedFields:
+  selectors:
+    - modality == "mrs"
+    - suffix == "mrsi"
+  fields:
+    MRAcquisitionType: recommended
 
 MRSOptionalFields:
   selectors:

From 533194e7d043add2053cffc3d46fd1dc65307daf Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Thu, 2 May 2024 14:43:01 -0400
Subject: [PATCH 57/70] Update metadata.yaml

- Minor grammar change
---
 src/schema/objects/metadata.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index f00f96cfbf..cfe99285fc 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -250,14 +250,14 @@ B0ShimmingTechnique:
   name: B0ShimmingTechnique
   display_name: B0 Shimming Technique
   description: |
-    The technique used to shim the *B<sub>0</sub>* field (for example, `"Dynamic shim updating"`
+    The technique used to shim the *B*<sub>0</sub> field (for example, `"Dynamic shim updating"`
     or `"FASTMAP"`).
   type: string
 B1ShimmingTechnique:
   name: B1ShimmingTechnique
   display_name: B1 Shimming Technique
   description: |
-    The technique used to shim the *B<sub>1</sub>* field (for example, `"Simple phase align"`
+    The technique used to shim the *B*<sub>1</sub> field (for example, `"Simple phase align"`
     or `"Pre-saturated TurboFLASH"`).
   type: string
 BIDSVersion:

From 30aab9a962a8d2906e2ecf6402d5823246ded8bb Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Tue, 7 May 2024 21:33:07 -0400
Subject: [PATCH 58/70] Some further changes

- Reordered recommended MRS-relevant fields
- Some rearranging of src/schema/rules/sidecars/mrs.yaml
---
 .../magnetic-resonance-spectroscopy.md        |  7 ++++---
 src/schema/rules/sidecars/mrs.yaml            | 21 ++++++++++++++-----
 2 files changed, 20 insertions(+), 8 deletions(-)

diff --git a/src/modality-specific-files/magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
index 0c6e547b62..55088a5f85 100644
--- a/src/modality-specific-files/magnetic-resonance-spectroscopy.md
+++ b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -202,10 +202,11 @@ A guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
 {{ MACROS___make_sidecar_table([
-  "mrs.MRSRecommendedFields",
   "mrs.MRSRecommendedFieldsNumTransients",
-  "mrs.MRSRecommendedFieldsAnatomicalImage",
-  "mrs.MRSIRecommendedFields"
+  "mrs.MRSRecommendedFields",
+  "mrs.MRSIRecommendedFields",
+  "mrs.MRSRecommendedFieldsRefSignal",
+  "mrs.MRSRecommendedFieldsAnatomicalImage"
   ])
 }}
 
diff --git a/src/schema/rules/sidecars/mrs.yaml b/src/schema/rules/sidecars/mrs.yaml
index 7ac11a6697..7524053ec7 100644
--- a/src/schema/rules/sidecars/mrs.yaml
+++ b/src/schema/rules/sidecars/mrs.yaml
@@ -45,7 +45,6 @@ MRSSequenceSpecifics:
     ScanningSequence__mrs: recommended
     SequenceName: recommended
     PulseSequenceDetails: recommended
-    MRAcquisitionType: optional, but recommended for MRSI
     WaterSuppression: recommended
     WaterSuppressionTechnique: optional
     OuterVolumeSuppression: optional
@@ -74,14 +73,15 @@ MRSRecommendedFields:
     MatrixSize: recommended for MRSI
     VolumeAffineMatrix: recommended for MRSI
     EncodingTechnique: recommended for MRSI
-    ReferenceSignal: recommended if MRS reference data are present
 
 MRSRecommendedFieldsAnatomicalImage:
   selectors:
     - modality == "mrs"
-    - '"anat" in dataset.datatypes'
+    - intersects(dataset.datatypes, ["anat"])
   fields:
-    AnatomicalImage: recommended
+    AnatomicalImage:
+      level: recommended
+      level_addendum: if anatomical MRI data are present
 
 MRSRecommendedFieldsNumTransients:
   selectors:
@@ -90,12 +90,23 @@ MRSRecommendedFieldsNumTransients:
   fields:
     NumberOfTransients: recommended
 
+MRSRecommendedFieldsRefSignal:
+  selectors:
+    - modality == "mrs"
+    - intersects([suffix], ["mrsref"])
+  fields:
+    ReferenceSignal:
+      level: recommended
+      level_addendum: if MRS reference data are present
+
 MRSIRecommendedFields:
   selectors:
     - modality == "mrs"
     - suffix == "mrsi"
   fields:
-    MRAcquisitionType: recommended
+    MRAcquisitionType:
+      level: recommended
+      level_addendum: for MRSI
 
 MRSOptionalFields:
   selectors:

From 2c969bb35e448f475d856f8dbf9fff505d67172e Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Wed, 29 May 2024 14:02:23 -0400
Subject: [PATCH 59/70] Update metadata.yaml

- Spelling correction
---
 src/schema/objects/metadata.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index cfe99285fc..0cf6b12cce 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -2399,7 +2399,7 @@ OtherAcquisitionParameters:
   type: string
 OuterVolumeSuppression:
   name: OuterVolumeSuppression
-  display_name: Other-Volume Suppression
+  display_name: Outer-Volume Suppression
   description: |
     Boolean indicating whether outer-volume suppression was used prior to acquisition.
   type: boolean

From 8fc41eae2a44ae5acc5c5164fcd21fca953f8ef4 Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Wed, 29 May 2024 14:18:18 -0400
Subject: [PATCH 60/70] Update src/schema/objects/metadata.yaml

Co-authored-by: Chris Markiewicz <markiewicz@stanford.edu>
---
 src/schema/objects/metadata.yaml | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index cfe99285fc..d8471ad99e 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -2944,11 +2944,9 @@ ResonantNucleus:
     For multi-nuclei experiments such as <sup>1</sup>H-[<sup>13</sup>C] MR,
     an array can be used: `["1H", "13C"]`.
     Corresponds to DICOM Tag 0018, 9100 `Resonant Nucleus`.
-  anyOf:
-    - type: string
-    - type: array
-      items:
-        type: string
+  type: array
+  items:
+    type: string
 RotationOrder:
   name: RotationOrder
   display_name: RotationOrder

From 9116defcd1f14da0d8d9e6d45dc41ea8c3c622bd Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Wed, 29 May 2024 14:19:03 -0400
Subject: [PATCH 61/70] Update src/schema/objects/metadata.yaml

Co-authored-by: Chris Markiewicz <markiewicz@stanford.edu>
---
 src/schema/objects/metadata.yaml | 11 ++++-------
 1 file changed, 4 insertions(+), 7 deletions(-)

diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index d8471ad99e..fbff99b0c5 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -3504,13 +3504,10 @@ SpectrometerFrequency:
     to the resonant frequency of <sup>1</sup>H.
     For multi-nuclei experiments such as <sup>1</sup>H-[<sup>13</sup>C] MR at 3T,
     an array can be used: `[127.731, 32.125]`.
-  anyOf:
-    - type: number
-      unit: MHz
-    - type: array
-      items:
-        type: number
-        unit: MHz
+  type: array
+  items:
+    type: number
+    unit: MHz
 SpoilingGradientDuration:
   name: SpoilingGradientDuration
   display_name: Spoiling Gradient Duration

From f6e3f721bfdde953d26d713e1513a81ee9907bca Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Tue, 21 May 2024 17:04:00 -0400
Subject: [PATCH 62/70] SCHEMA: Add nifti_header.mrs to context

---
 src/schema/meta/context.yaml | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/src/schema/meta/context.yaml b/src/schema/meta/context.yaml
index 7f9ca1259c..1c82dc13c0 100644
--- a/src/schema/meta/context.yaml
+++ b/src/schema/meta/context.yaml
@@ -329,6 +329,10 @@ context:
           name: 'sform code'
           description: 'Use of the affine fields.'
           type: integer
+        mrs:
+          name: 'NIfTI-MRS extension'
+          description: 'NIfTI-MRS JSON fields'
+          type: object
     ome:
       name: 'Open Microscopy Environment fields'
       description: 'Parsed contents of OME-XML header, which may be found in OME-TIFF or OME-ZARR files'

From 899e6ec5f5f80a7d5f6eeb71d7dafcac5486d806 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Tue, 21 May 2024 17:51:20 -0400
Subject: [PATCH 63/70] SCHEMA: Add check for consistency between MRS header
 and sidecar

---
 src/schema/rules/checks/mrs.yaml | 14 ++++++++++++++
 1 file changed, 14 insertions(+)
 create mode 100644 src/schema/rules/checks/mrs.yaml

diff --git a/src/schema/rules/checks/mrs.yaml b/src/schema/rules/checks/mrs.yaml
new file mode 100644
index 0000000000..a38a3007c6
--- /dev/null
+++ b/src/schema/rules/checks/mrs.yaml
@@ -0,0 +1,14 @@
+---
+MRSNiftiConsistency:
+  issue:
+    code: MRS_NIFTI_CONSISTENCY
+    message: |
+      ResonantNucleus and/or SpectrometerFrequency fields are inconsistent
+      between the NIfTI-MRS header extension and the BIDS sidecar.
+    level: error
+  selectors:
+    - datatype == "mrs"
+    - nifti_header.mrs
+  checks:
+    - sidecar.ResonantNucleus == nifti_header.mrs.ResonantNucleus
+    - sidecar.SpectrometerFrequency == nifti_header.mrs.SpectrometerFrequency

From 9dabf8e2e4ffe78e4971e38015cc2649ee48726d Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Wed, 29 May 2024 11:30:46 -0400
Subject: [PATCH 64/70] Split conditional matrices in schema, combine in doc

This implements the following agreed upon suggestions:

* Set InversionTime to recommended if `inv` entity is present.
  (`entities.inversion`)
* Move to RepetitionTime and VolumeTiming, rather than RepetitionTime
  as an array in the variable-timing case.
* ReferenceSignal should be uniformly recommended.
---
 .../magnetic-resonance-spectroscopy.md        | 37 +++--------
 src/schema/objects/metadata.yaml              | 24 +------
 src/schema/rules/sidecars/func.yaml           |  4 ++
 src/schema/rules/sidecars/mrs.yaml            | 64 ++++++++++++-------
 4 files changed, 57 insertions(+), 72 deletions(-)

diff --git a/src/modality-specific-files/magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
index 55088a5f85..910d4b70a3 100644
--- a/src/modality-specific-files/magnetic-resonance-spectroscopy.md
+++ b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -179,19 +179,7 @@ A guide for using macros can be found at
 
 ### MRS-relevant fields
 
-Metadata fields that MUST be present:
-
-<!-- This block generates a metadata table.
-These tables are defined in
-  src/schema/rules/sidecars
-The definitions of the fields specified in these tables may be found in
-  src/schema/objects/metadata.yaml
-A guide for using macros can be found at
- https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
--->
-{{ MACROS___make_sidecar_table("mrs.MRSRequiredFields") }}
-
-SHOULD be present:
+Metadata fields that MUST, SHOULD or MAY be present:
 
 <!-- This block generates a metadata table.
 These tables are defined in
@@ -202,26 +190,17 @@ A guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
 {{ MACROS___make_sidecar_table([
-  "mrs.MRSRecommendedFieldsNumTransients",
-  "mrs.MRSRecommendedFields",
+  "mrs.MRSRelevantFields",
+  "mrs.MRSRepetitionTime",
+  "mrs.MRSVolumeTiming",
+  "mrs.MRSConditionalNumTransients",
   "mrs.MRSIRecommendedFields",
-  "mrs.MRSRecommendedFieldsRefSignal",
-  "mrs.MRSRecommendedFieldsAnatomicalImage"
+  "mrs.MRSConditionalInversionTime",
+  "mrs.MRSConditionalAnatomicalImage",
+  "mrs.MRSOptionalFields",
   ])
 }}
 
-MAY be present:
-
-<!-- This block generates a metadata table.
-These tables are defined in
-  src/schema/rules/sidecars
-The definitions of the fields specified in these tables may be found in
-  src/schema/objects/metadata.yaml
-A guide for using macros can be found at
- https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
--->
-{{ MACROS___make_sidecar_table("mrs.MRSOptionalFields") }}
-
 ### Example `*_svs.json`
 
 ```JSON
diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index c4b5350e86..7f7e69b338 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -2865,22 +2865,6 @@ RepetitionTime:
   type: number
   exclusiveMinimum: 0
   unit: s
-RepetitionTime__mrs:
-  name: RepetitionTime
-  display_name: Repetition Time
-  description: |
-    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.
-  anyOf:
-    - type: number
-      exclusiveMinimum: 0
-      unit: s
-    - type: array
-      items:
-        type: number
-        exclusiveMinimum: 0
-        unit: s
 RepetitionTimeExcitation:
   name: RepetitionTimeExcitation
   display_name: Repetition Time Excitation
@@ -3851,12 +3835,10 @@ VolumeTiming:
   description: |
     The time at which each volume was acquired during the acquisition.
     It is described using a list of times referring to the onset of each volume
-    in the BOLD series.
-    The list must have the same length as the BOLD series,
+    in the series.
+    The list must have the same length as the 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.
+    This field is mutually exclusive with `"RepetitionTime"`.
   type: array
   minItems: 1
   items:
diff --git a/src/schema/rules/sidecars/func.yaml b/src/schema/rules/sidecars/func.yaml
index f3b7e70b69..475bc23207 100644
--- a/src/schema/rules/sidecars/func.yaml
+++ b/src/schema/rules/sidecars/func.yaml
@@ -41,6 +41,10 @@ MRIFuncVolumeTiming:
     VolumeTiming:
       level: required
       level_addendum: mutually exclusive with `RepetitionTime`
+      description_addendum: |
+        This field is mutually exclusive with `"DelayTime"`.
+        If defined, this requires acquisition time (TA) be defined via either
+        `"SliceTiming"` or `"AcquisitionDuration"` be defined.
 
 # Timing Parameters
 MRIFuncTimingParameters:
diff --git a/src/schema/rules/sidecars/mrs.yaml b/src/schema/rules/sidecars/mrs.yaml
index 7524053ec7..d4be8d58d0 100644
--- a/src/schema/rules/sidecars/mrs.yaml
+++ b/src/schema/rules/sidecars/mrs.yaml
@@ -51,7 +51,7 @@ MRSSequenceSpecifics:
     B0ShimmingTechnique: optional
     B1ShimmingTechnique: optional
 
-MRSRequiredFields:
+MRSRelevantFields:
   selectors:
     - modality == "mrs"
   fields:
@@ -59,45 +59,56 @@ MRSRequiredFields:
     SpectrometerFrequency: required
     SpectralWidth: required
     EchoTime: required
-
-MRSRecommendedFields:
-  selectors:
-    - modality == "mrs"
-  fields:
     NumberOfSpectralPoints: recommended
-    RepetitionTime__mrs: recommended
     MixingTime: recommended
-    InversionTime: recommended for inversion recovery data
     FlipAngle: recommended
     AcquisitionVoxelSize: recommended
-    MatrixSize: recommended for MRSI
-    VolumeAffineMatrix: recommended for MRSI
-    EncodingTechnique: recommended for MRSI
+    ReferenceSignal: recommended
 
-MRSRecommendedFieldsAnatomicalImage:
+MRSRepetitionTime:
   selectors:
     - modality == "mrs"
-    - intersects(dataset.datatypes, ["anat"])
+    - '!("VolumeTiming" in sidecar)'
   fields:
-    AnatomicalImage:
+    RepetitionTime:
       level: recommended
-      level_addendum: if anatomical MRI data are present
+      level_addendum: mutually exclusive with `VolumeTiming`
 
-MRSRecommendedFieldsNumTransients:
+MRSVolumeTiming:
   selectors:
     - modality == "mrs"
-    - intersects([suffix], ["svs", "unloc"])
+    - '!("RepetitionTime" in sidecar)'
   fields:
-    NumberOfTransients: recommended
+    VolumeTiming:
+      level: recommended
+      level_addendum: mutually exclusive with `RepetitionTime`
 
-MRSRecommendedFieldsRefSignal:
+MRSConditionalInversionTime:
   selectors:
     - modality == "mrs"
-    - intersects([suffix], ["mrsref"])
+    - entities.inversion
   fields:
-    ReferenceSignal:
+    InversionTime:
       level: recommended
-      level_addendum: if MRS reference data are present
+      level_addendum: if `inv` entity is present
+
+MRSConditionalAnatomicalImage:
+  selectors:
+    - modality == "mrs"
+    - intersects(dataset.datatypes, ["anat"])
+  fields:
+    AnatomicalImage:
+      level: recommended
+      level_addendum: if anatomical MRI data are present
+
+MRSConditionalNumTransients:
+  selectors:
+    - modality == "mrs"
+    - intersects([suffix], ["svs", "unloc"])
+  fields:
+    NumberOfTransients:
+      level: recommended
+      level_addendum: for SVS and unlocalized acquisitions
 
 MRSIRecommendedFields:
   selectors:
@@ -107,6 +118,15 @@ MRSIRecommendedFields:
     MRAcquisitionType:
       level: recommended
       level_addendum: for MRSI
+    MatrixSize:
+      level: recommended
+      level_addendum: for MRSI
+    VolumeAffineMatrix:
+      level: recommended
+      level_addendum: for MRSI
+    EncodingTechnique:
+      level: recommended
+      level_addendum: for MRSI
 
 MRSOptionalFields:
   selectors:

From 07d2ec8ebd45aec15f04f322fbc52d2c0d55ed13 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Wed, 29 May 2024 11:32:53 -0400
Subject: [PATCH 65/70] Make BodyPart(Details) required if voi entity is
 present

---
 src/schema/rules/sidecars/mrs.yaml | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/src/schema/rules/sidecars/mrs.yaml b/src/schema/rules/sidecars/mrs.yaml
index d4be8d58d0..1149a1ae79 100644
--- a/src/schema/rules/sidecars/mrs.yaml
+++ b/src/schema/rules/sidecars/mrs.yaml
@@ -30,10 +30,21 @@ MRSSample:
   fields:
     BodyPart:
       level: optional
+      level_addendum: required if `voi` entity is present
       description_addendum: Corresponds to DICOM Tag 0018, 0015 `Body Part Examined`.
-    BodyPartDetails: optional
+    BodyPartDetails:
+      level: optional
+      level_addendum: required if `voi` entity is present
     BodyPartDetailsOntology: optional
 
+MRSSampleVOI:
+  selectors:
+    - modality == "mrs"
+    - '"volume" in entities'
+  fields:
+    BodyPart: required
+    BodyPartDetails: required
+
 MRSSequenceSpecifics:
   selectors:
     - modality == "mrs"

From 0181150f68c08cd7afa942ae67c35c22cd7bdc74 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Wed, 29 May 2024 11:36:55 -0400
Subject: [PATCH 66/70] feat(checks): Add check to ensure MatrixSize and
 nifti_header.dim are consistent

---
 src/schema/rules/checks/mrs.yaml | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/src/schema/rules/checks/mrs.yaml b/src/schema/rules/checks/mrs.yaml
index a38a3007c6..41417feb93 100644
--- a/src/schema/rules/checks/mrs.yaml
+++ b/src/schema/rules/checks/mrs.yaml
@@ -12,3 +12,18 @@ MRSNiftiConsistency:
   checks:
     - sidecar.ResonantNucleus == nifti_header.mrs.ResonantNucleus
     - sidecar.SpectrometerFrequency == nifti_header.mrs.SpectrometerFrequency
+
+MRSMatrixSize:
+  issue:
+    code: MRS_MATRIX_SIZE
+    message: |
+      MatrixSize metadata must match NIfTI header field `dim[1:4]`.
+    level: error
+  selectors:
+    - datatype == "mrs"
+    - nifti_header
+    - type(sidecar.MatrixSize) != "null"
+  checks:
+    - sidecar.MatrixSize[0] == nifti_header.dim[1]
+    - sidecar.MatrixSize[1] == nifti_header.dim[2]
+    - sidecar.MatrixSize[2] == nifti_header.dim[3]

From 83c6f3ea10a0a87a4baf7c98a5e4e953135e35f5 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Thu, 30 May 2024 14:29:17 -0400
Subject: [PATCH 67/70] fix(checks): Use non-trivial expressions for selectors

---
 src/schema/rules/checks/mrs.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/schema/rules/checks/mrs.yaml b/src/schema/rules/checks/mrs.yaml
index 41417feb93..598a59c94f 100644
--- a/src/schema/rules/checks/mrs.yaml
+++ b/src/schema/rules/checks/mrs.yaml
@@ -8,7 +8,7 @@ MRSNiftiConsistency:
     level: error
   selectors:
     - datatype == "mrs"
-    - nifti_header.mrs
+    - type(nifti_header.mrs) != "null"
   checks:
     - sidecar.ResonantNucleus == nifti_header.mrs.ResonantNucleus
     - sidecar.SpectrometerFrequency == nifti_header.mrs.SpectrometerFrequency
@@ -21,7 +21,7 @@ MRSMatrixSize:
     level: error
   selectors:
     - datatype == "mrs"
-    - nifti_header
+    - type(nifti_header) != "null"
     - type(sidecar.MatrixSize) != "null"
   checks:
     - sidecar.MatrixSize[0] == nifti_header.dim[1]

From 1d5e089e75c011bcd9e55486df673c563ef923d6 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <effigies@gmail.com>
Date: Fri, 31 May 2024 20:37:39 -0400
Subject: [PATCH 68/70] Uncombine required/recommended/optional fields

---
 .../magnetic-resonance-spectroscopy.md        | 33 +++++++++++++++++--
 src/schema/rules/sidecars/mrs.yaml            |  7 +++-
 2 files changed, 37 insertions(+), 3 deletions(-)

diff --git a/src/modality-specific-files/magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
index 910d4b70a3..d5a0d992ac 100644
--- a/src/modality-specific-files/magnetic-resonance-spectroscopy.md
+++ b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -179,7 +179,7 @@ A guide for using macros can be found at
 
 ### MRS-relevant fields
 
-Metadata fields that MUST, SHOULD or MAY be present:
+Metadata fields that MUST be present:
 
 <!-- This block generates a metadata table.
 These tables are defined in
@@ -190,13 +190,42 @@ A guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
 {{ MACROS___make_sidecar_table([
-  "mrs.MRSRelevantFields",
+  "mrs.MRSRequiredFields",
+  ])
+}}
+
+Metadata fields that SHOULD be present:
+
+<!-- This block generates a metadata table.
+These tables are defined in
+  src/schema/rules/sidecars
+The definitions of the fields specified in these tables may be found in
+  src/schema/objects/metadata.yaml
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_sidecar_table([
+  "mrs.MRSRecommendedFields",
   "mrs.MRSRepetitionTime",
   "mrs.MRSVolumeTiming",
   "mrs.MRSConditionalNumTransients",
   "mrs.MRSIRecommendedFields",
   "mrs.MRSConditionalInversionTime",
   "mrs.MRSConditionalAnatomicalImage",
+  ])
+}}
+
+Metadata fields that MAY be present:
+
+<!-- This block generates a metadata table.
+These tables are defined in
+  src/schema/rules/sidecars
+The definitions of the fields specified in these tables may be found in
+  src/schema/objects/metadata.yaml
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_sidecar_table([
   "mrs.MRSOptionalFields",
   ])
 }}
diff --git a/src/schema/rules/sidecars/mrs.yaml b/src/schema/rules/sidecars/mrs.yaml
index 1149a1ae79..75fe94bd2b 100644
--- a/src/schema/rules/sidecars/mrs.yaml
+++ b/src/schema/rules/sidecars/mrs.yaml
@@ -62,7 +62,7 @@ MRSSequenceSpecifics:
     B0ShimmingTechnique: optional
     B1ShimmingTechnique: optional
 
-MRSRelevantFields:
+MRSRequiredFields:
   selectors:
     - modality == "mrs"
   fields:
@@ -70,6 +70,11 @@ MRSRelevantFields:
     SpectrometerFrequency: required
     SpectralWidth: required
     EchoTime: required
+
+MRSRecommendedFields:
+  selectors:
+    - modality == "mrs"
+  fields:
     NumberOfSpectralPoints: recommended
     MixingTime: recommended
     FlipAngle: recommended

From b0bea61b26efe2982ecba2c89a3631f57cb0c1f7 Mon Sep 17 00:00:00 2001
From: Mark Mikkelsen <mark.mikkelsen@gmail.com>
Date: Thu, 25 Jul 2024 16:53:20 -0400
Subject: [PATCH 69/70] Update src/schema/rules/sidecars/func.yaml

Co-authored-by: Taylor Salo <salot@pennmedicine.upenn.edu>
---
 src/schema/rules/sidecars/func.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/schema/rules/sidecars/func.yaml b/src/schema/rules/sidecars/func.yaml
index ff2d54be9a..3e23056396 100644
--- a/src/schema/rules/sidecars/func.yaml
+++ b/src/schema/rules/sidecars/func.yaml
@@ -44,7 +44,7 @@ MRIFuncVolumeTiming:
       description_addendum: |
         This field is mutually exclusive with `"DelayTime"`.
         If defined, this requires acquisition time (TA) be defined via either
-        `"SliceTiming"` or `"AcquisitionDuration"` be defined.
+        `"SliceTiming"` or `"AcquisitionDuration"`.
 
 # Timing Parameters
 MRIFuncTimingParameters:

From 1ef102b9fa579d0237183c9cdf1d78ab02cbd511 Mon Sep 17 00:00:00 2001
From: Chris Markiewicz <markiewicz@stanford.edu>
Date: Thu, 25 Jul 2024 19:23:10 -0400
Subject: [PATCH 70/70] FIX: Add MRS events files, restrict sidecar metadata
 checks to data files (#1875)

* FIX: Add MRS events files, restrict sidecar metadata checks to data files

* FIX: Do not limit suffixes for filename template
---
 .../magnetic-resonance-spectroscopy.md              |  2 +-
 src/schema/rules/files/raw/task.yaml                | 10 ++++++++++
 src/schema/rules/sidecars/mrs.yaml                  | 13 +++++++++++++
 3 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/src/modality-specific-files/magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
index d5a0d992ac..22ec6540e0 100644
--- a/src/modality-specific-files/magnetic-resonance-spectroscopy.md
+++ b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -21,7 +21,7 @@ The inputs for this macro can be found in the directory
 and a guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
-{{ MACROS___make_filename_template("raw", datatypes=["mrs"], suffixes=["svs", "mrsi", "unloc", "mrsref"]) }}
+{{ MACROS___make_filename_template("raw", datatypes=["mrs"]) }}
 
 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.
diff --git a/src/schema/rules/files/raw/task.yaml b/src/schema/rules/files/raw/task.yaml
index b7171e568f..812765a063 100644
--- a/src/schema/rules/files/raw/task.yaml
+++ b/src/schema/rules/files/raw/task.yaml
@@ -91,6 +91,16 @@ events__pet:
     reconstruction: optional
     run: optional
 
+events__mrs:
+  $ref: rules.files.raw.task.events
+  datatypes:
+    - mrs
+  entities:
+    $ref: rules.files.raw.task.events.entities
+    reconstruction: optional
+    nucleus: optional
+    volume: optional
+
 timeseries__func:
   $ref: rules.files.raw.task.timeseries
   datatypes:
diff --git a/src/schema/rules/sidecars/mrs.yaml b/src/schema/rules/sidecars/mrs.yaml
index 75fe94bd2b..28796eb5e4 100644
--- a/src/schema/rules/sidecars/mrs.yaml
+++ b/src/schema/rules/sidecars/mrs.yaml
@@ -9,6 +9,7 @@
 MRSScannerHardware:
   selectors:
     - modality == "mrs"
+    - match(extension, "^\.nii(\.gz)?$")
   fields:
     InstitutionName: recommended
     InstitutionAddress: recommended
@@ -27,6 +28,7 @@ MRSScannerHardware:
 MRSSample:
   selectors:
     - modality == "mrs"
+    - match(extension, "^\.nii(\.gz)?$")
   fields:
     BodyPart:
       level: optional
@@ -40,6 +42,7 @@ MRSSample:
 MRSSampleVOI:
   selectors:
     - modality == "mrs"
+    - match(extension, "^\.nii(\.gz)?$")
     - '"volume" in entities'
   fields:
     BodyPart: required
@@ -48,6 +51,7 @@ MRSSampleVOI:
 MRSSequenceSpecifics:
   selectors:
     - modality == "mrs"
+    - match(extension, "^\.nii(\.gz)?$")
   fields:
     PulseSequenceType:
       level: recommended
@@ -65,6 +69,7 @@ MRSSequenceSpecifics:
 MRSRequiredFields:
   selectors:
     - modality == "mrs"
+    - match(extension, "^\.nii(\.gz)?$")
   fields:
     ResonantNucleus: required
     SpectrometerFrequency: required
@@ -74,6 +79,7 @@ MRSRequiredFields:
 MRSRecommendedFields:
   selectors:
     - modality == "mrs"
+    - match(extension, "^\.nii(\.gz)?$")
   fields:
     NumberOfSpectralPoints: recommended
     MixingTime: recommended
@@ -84,6 +90,7 @@ MRSRecommendedFields:
 MRSRepetitionTime:
   selectors:
     - modality == "mrs"
+    - match(extension, "^\.nii(\.gz)?$")
     - '!("VolumeTiming" in sidecar)'
   fields:
     RepetitionTime:
@@ -93,6 +100,7 @@ MRSRepetitionTime:
 MRSVolumeTiming:
   selectors:
     - modality == "mrs"
+    - match(extension, "^\.nii(\.gz)?$")
     - '!("RepetitionTime" in sidecar)'
   fields:
     VolumeTiming:
@@ -102,6 +110,7 @@ MRSVolumeTiming:
 MRSConditionalInversionTime:
   selectors:
     - modality == "mrs"
+    - match(extension, "^\.nii(\.gz)?$")
     - entities.inversion
   fields:
     InversionTime:
@@ -111,6 +120,7 @@ MRSConditionalInversionTime:
 MRSConditionalAnatomicalImage:
   selectors:
     - modality == "mrs"
+    - match(extension, "^\.nii(\.gz)?$")
     - intersects(dataset.datatypes, ["anat"])
   fields:
     AnatomicalImage:
@@ -120,6 +130,7 @@ MRSConditionalAnatomicalImage:
 MRSConditionalNumTransients:
   selectors:
     - modality == "mrs"
+    - match(extension, "^\.nii(\.gz)?$")
     - intersects([suffix], ["svs", "unloc"])
   fields:
     NumberOfTransients:
@@ -129,6 +140,7 @@ MRSConditionalNumTransients:
 MRSIRecommendedFields:
   selectors:
     - modality == "mrs"
+    - match(extension, "^\.nii(\.gz)?$")
     - suffix == "mrsi"
   fields:
     MRAcquisitionType:
@@ -147,6 +159,7 @@ MRSIRecommendedFields:
 MRSOptionalFields:
   selectors:
     - modality == "mrs"
+    - match(extension, "^\.nii(\.gz)?$")
   fields:
     ChemicalShiftOffset: optional
     ChemicalShiftReference: optional