From 57f338efcdff347199b538257f9fcac25ad8f370 Mon Sep 17 00:00:00 2001 From: Oscar Esteban Date: Fri, 23 Oct 2020 21:55:53 +0200 Subject: [PATCH] enh: allow encoding the fieldmapping intent of the protocol This PR addresses the problem @mattcieslak spotted at in #239. This enhancement (WIP) basically allows for researchers to encode the protocol's intent regarding fieldmaps. As @satra introduced in #239 (comment), BIDS "*could encode intent and automation. Whether it should is a community decision." This PR proposes a solution to encoding the intent. It doesn't modify anything to allow also encoding automation. The PR attempts to be backwards compatible, and is based off of #651, where the text about fieldmaps is being revised. I'm submitting this draft PR to open discussions and looking forward to feedback. Resolves: #239. Depends: #651. References: #263, nipreps/dmriprep#43, bids-standard/bids-2-devel#39 --- .../01-magnetic-resonance-imaging-data.md | 35 ++++++++++++++++--- 1 file changed, 31 insertions(+), 4 deletions(-) diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md index c80bdd6e33..0f4eee8e6d 100644 --- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md +++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md @@ -107,6 +107,24 @@ Useful for multimodal co-registration with MEG, (S)EEG, TMS, and so on. | ----------------------------- | --------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | AnatomicalLandmarkCoordinates | RECOMMENDED | [object][] of [arrays][] | Key:value pairs of any number of additional anatomical landmarks and their coordinates in voxel units (where first voxel has index 0,0,0) relative to the associated anatomical MRI (for example, `{"AC": [127,119,149], "PC": [128,93,141], "IH": [131,114,206]}`, or `{"NAS": [127,213,139], "LPA": [52,113,96], "RPA": [202,113,91]}`). Each array MUST contain three numeric values corresponding to x, y, and z axis of the coordinate system in that exact order. | +### Echo-Planar Imaging and *B0* mapping + +Echo-Planar Imaging (EPI) schemes typically used in the acquisition of +diffusion and functional MRI may also be *intended for* estimating the +*B0* field nonuniformity inside the scanner (in other words, +*mapping the field*,) without the acquisition of additional MRI schemes +such as gradient-recalled echo (GRE) sequences that are stored under the +`fmap/` folder of the BIDS structure. + +The modality labels `dwi` (under `dwi/`), `bold`, and `sbref` (under `func/`) +and any modality under `fmap/` are allowed to encode the MR protocol intent for +fieldmap estimation using the following metadata: + +| **Key name** | **Requirement level** | **Data type** | **Description** | +| --------------------------- | --------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| B0FieldIdentifier | OPTIONAL | [string][] | The presence of this key states that this particular 3D or 4D image MAY be used for fieldmap estimation purposes. The `B0FieldIdentifier` MUST be a unique string within one participant's tree, shared only by the images meant to be used as inputs for the estimation of a particular instance of the *B0 field* estimation. | +| B0FieldSource | OPTIONAL | [string][] or [array][] of [string][] | At least one existing `B0FieldIdentifier` defined by other images in the participant's tree. This field states the *B0 field* estimation designated by the `B0FieldIdentifier` that may be used to correct the dataset for distortions caused by B0 inhomogeneities. `B0FieldSource` and `B0FieldIdentifier` are mutually exclusive. When a list of identifiers is given, the estimated fieldmap may be averaged across the different sources. | + ### Institution information | **Key name** | **Requirement level** | **Data type** | **Description** | @@ -362,7 +380,8 @@ sub-control01/ "PhaseEncodingDirection": "j", "InstitutionName": "Stanford University", "InstitutionAddress": "450 Serra Mall, Stanford, CA 94305-2004, USA", - "DeviceSerialNumber": "11035" + "DeviceSerialNumber": "11035", + "B0FieldSource": ["phasediff_fmap0", "pepolar_fmap0"] } ``` @@ -561,7 +580,8 @@ JSON example: ```JSON { "PhaseEncodingDirection": "j-", - "TotalReadoutTime": 0.095 + "TotalReadoutTime": 0.095, + "B0FieldSource": ["phasediff_fmap0", "pepolar_fmap0"] } ``` @@ -746,8 +766,15 @@ are REQUIRED for these field mapping sequences. Fieldmaps are typically acquired with the purpose of correcting one or more EPI scans under `func/` or `dwi/` for distortions derived from *B0* nonuniformity. -This linking between fieldmaps and their targetted data MAY be encoded with the -`IntendedFor` metadata. + +#### Using `B0FieldIdentifier` metadata + +The general purpose `B0FieldIdentifier` MRI metadata is RECOMMENDED for the +prescription of the B0 field estimation intent of the original acquisition +protocol. +This encoding fully overrides the `IntendedFor` approach (see below). +However, the `IntendedFor` encoding is permitted and RECOMMENDED in combination +with the `B0FieldIdentifier` to maintain compatibility with outdated software. #### Using `IntendedFor` metadata