Merge branch 'lazaral-master'

ProposedChangesToSpecification.md

@@ -4,17 +4,97 @@ This document captures all of the changes that the BEP001 team are proposing to
 
 Table of contents:
 
+* [Indexable metadata](#indexable-metadata)
+* [Acquisition metadata field](#acquisition-metadata-field)
+* [Part metadata field](#part-metadata-field)
+* [Repetition time](#repetition-time)
+* [Symbolic links](#symbolic-links)
+* [Suffix](#suffix)
+* [B1plus fieldmaps](#b1plus-fieldmaps)
 * [Repetition Time](#repetition-time)
+* [B1plus fieldmaps](#b1plus-fieldmaps)
+* [S0map](#s0map)
+
+## Indexable metadata
+
+Change in `/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md`.
+
+There are a lot of different additional metadata fields that may be needed for structural brain imaging.
+In this change we added a field called `indexable_metadata` to capture those changes.
+The use is described in `/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md#indexable_metadata-index-key-value-pair`.
+
+The keys can be pulled from the "Sequence specifics" table (`/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md#sequence-specifics`).
+This table was updated to include metadata fields for MT sequences and to include metadata fields for any sequence with spoiling gradients.
+
+## Acquisition metadata field
+
+The `acq-<label>` key-value pair was added to capture a group of parametrically linked anatomical images.
+This was updated in `/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md#acq-label-key-value-pair`.
+
+## Part metadata field
+
+### Proposed change
+
+Change in `/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md#part-magphase-keyvalue-pair`.
+
+The `part-<mag/phase>` key-value pair was added to distinguish the magnitude and phase parts of an acquisition.
+
+We additionally recommend (but do not require) that phase images should be in radians and have a range of 0 (inclusive) to 2pi (not included).
 
 ## Repetition Time
 
 ### Proposed Change
 
-Adjust the definition of `RepetitionTime` in section [4.1.x Task (including resting state) imaging data](https://github.com/bids-standard/bids-specification/blob/master/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md#task-including-resting-state-imaging-data) and add two new fields to section [4.1.y Anatomy imaging data](https://github.com/bids-standard/bids-specification/blob/master/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md#anatomy-imaging-data).
+Adjust the definition of `RepetitionTime` in section [4.1.x Task (including resting state) imaging data](/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md#task-including-resting-state-imaging-data) and add two new fields to section [4.1.y Anatomy imaging data](/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md#anatomy-imaging-data).
 
 ### Justification
 
 `RepetitionTime` is currently defined very specifically as relating to functional imaging data.
 However there are structural scans that collect multiple volumes during an acquisition.
 Here we adjust the definition of `RepetitionTime` in section 4.1.x and add `RepetitionTimeExcitation` and `RepetitionTimePreparation` as two additional terms for structural acquisitions that include multiple contrasts in 4.1.y.
 
+## Symbolic links
+
+### Proposed change
+
+Files in the derived folder can be symbolically linked to the main BIDS folder.
+For example, a derived quantitative map `derivatives/sub-01/anat/sub-01_R1.nii.gz` may be linked as `sub-01/anat/sub-01_T1w.nii.gz` to be used as a standard structural image for functional MRI processing pipelines.
+
+This change was made in `/src/02-common-principles.md#symbolic-links`.
+
+### Justification
+
+Whether a file is "derived" or "raw" depends on where you're starting from.
+To give a specific example, some researchers will be working on _creating_ quantitative maps, while others will want to _use_ the map as an input file to a structural processing pipeline.
+There is a possible natural cut off by saying that files in the BIDS specification are "raw" as they come off the scanner, and "derived" if offline processing has happened.
+Unfortunately, it is not possible to harmonize datasets across different scanners when following this rule.
+For example MP2RAGE images are sometimes used to construct `_T1uni`-images and `_T1map`s on the scanner system, but on some systems, this only happens post-hoc/"offline".
+
+## Suffix
+
+The original specification uses `modality_label` at the end of each file name.
+We have updated this to `suffix` as there are multiple modalities that are not captured in the proposed options, and because the boundaries between "modalities" differ by domain specification.
+This change was made in `/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md#anatomy-imaging-data`
+
+## B1+ Fieldmaps
+
+### Proposed Change
+
+Extend the part on `Fieldmaps` in [4.1.x Task (including resting state) imaging data](/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md#task-including-resting-state-imaging-data) by also allowing
+for storing B1+ fieldmaps.
+
+### Justification
+
+For some anatomical MRI acquisitions, especially when doing quantiative MRI (qMRI), B1+ fieldmaps can be useful to get better estimates of the underlying physical parameters (e.g., T1 in T1 maps obtained with MP2RAGE-sequence, see Marques et al., 2013).
+
+## S0map
+
+### Proposed Change
+
+Add a suffix `_S0map` to store the intercept-parameter for when T2\*-decay curves are fit, for example using a multi-echo Gradien-Recalled Echo (GRE)-sequence.
+
+Change in `/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md#suffix`.
+
+### Justification
+
+Both structural and functional multi-echo sequences are becoming more and more common. By fitting an exponential T2\*-model to such data, a `S0-map` remains that contains contrast for proton density (PD) and B1+ and B1--effects. This can be useful for for example skull-stripping.

examples/BEP001_examples.md

@@ -0,0 +1,22 @@
+# BEP001 examples
+
+This branch of the BEP001 repository contains some practical examples of what a BIDS-compatible qMRI dataset will look like. 
+
+You can find more about the BEP001 addition to the BIDS standard, and the rationale for the additions/changes that it brings to the BIDS format, here: https://github.com/bids-standard/bep001.
+
+ *The datasets in this branch contain empty data files, which might be useful for building simple software tests. 
+ The current branch may eventually be merged with the bids-examples branch of the main bids-standard repo: https://github.com/bids-standard/bids-examples, in which case this disclaimer will be redundant.*
+
+
+## Example 1: MEGRE, multi-echo
+This is a sample dataset from a single MEGRE sequence, which yields multiple images, corresponding to different echo times. This dataset has been used to calculate a quantitative susceptibility map (QSM), as well as a T2* map.
+
+## Example 2: MP2RAGE, single echo
+This is a sample dataset from a standard MP2RAGE sequence, which includes two GRE images acquired after a single inversion pulse. This data have been used to create a T1-map, as well as a T1-weighted image, corrected for B0 and B1-inhomogeneities, which are both part of the example dataset.
+
+## Example 3: MP2RAGE, multi-echo 
+This is a sample dataset from an MP2RAGE sequence with two inversion times, and, for the second inversion time, 4 different echoes.
+
+## Example 4: MultiParameter Mapping (MPM) dataset
+This is a sample dataset from a MultiParameter Mapping (MPM) sequence (as per Weiskopf et al., 2013), which yields multi-echo FLASH scans that are predominantly T1-, PD-, or MT-weighted by changing repetition time and flip angle.
+Note that the raw data for these scans are not called "FLASH" (or MEGRE, following our recommended vendor-neutral notation) in their suffices, rather they are grouped together with the "MPM" suffix and the "acq" tag is used to clarify which weightings the scans are highlighting.

examples/ds-01/dataset_description.json → examples/MEGRE_multiecho/dataset_description.json

@@ -5,5 +5,5 @@
         "Kirstie Whitaker",
         "Gilles de Hollander"
     ],
-    "Description": "This virtual dataset is collected using a single FLASH sequence, which yields multiple images, corresponding to different echo times. This data has been used to calculate a quantitative susceptibility map, as well as a T2* map."
+    "Description": "This virtual dataset is collected using a single MEGRE sequence, which yields multiple images, corresponding to different echo times. This data has been used to calculate a quantitative susceptibility map, as well as a T2* map."
 }

src/02-common-principles.md

@@ -109,6 +109,17 @@ these data are to be included:
 1.  We RECOMMEND including the PDF print-out with the actual sequence parameters
     generated by the scanner in the `sourcedata` folder.
 
+### Symbolic links
+
+Quantitative images/maps should be stored in the `derivatives` folder, but can
+be symbolic linked to the corresponding raw data directory to facilitate the
+easy use of these images as input to processing workflows implemented as
+BIDS-apps.
+
+For example, the quantitative map `derivatives/sub-01/anat/sub-01_R1.nii.gz`
+may be linked as `sub-01/anat/sub-01_T1w.nii.gz` to be used as a standard
+structural image for functional MRI processing pipelines.
+
 ## The Inheritance Principle
 
 Any metadata file (`.json`, `.bvec`, `.tsv`, etc.) may be defined at any