Skip to content

Commit

Permalink
enh: allow encoding the fieldmapping intent of the protocol
Browse files Browse the repository at this point in the history 
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
  • Loading branch information
@oesteban
oesteban committed Oct 23, 2020
1 parent ca5dcb8 commit 953ed10
Showing 1 changed file with 31 additions and 2 deletions.
33 changes: 31 additions & 2 deletions src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 & B0 field-mapping

Echo-Planar Imaging (EPI) schemes typically used in the acquisition of
diffusion and functional MRI may also be *intended for* estimating the
*B=0* field inside the scanner (in other words, *estimating the fieldmap*,)
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** |
Expand Down Expand Up @@ -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"]
}
```

Expand Down Expand Up @@ -561,7 +580,8 @@ JSON example:
```JSON
{
"PhaseEncodingDirection": "j-",
"TotalReadoutTime": 0.095
"TotalReadoutTime": 0.095,
"B0FieldSource": ["phasediff_fmap0", "pepolar_fmap0"]
}
```

Expand Down Expand Up @@ -735,6 +755,15 @@ are REQUIRED for these field mapping sequences.

### Expressing the MR protocol intent for fieldmaps

#### 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

Fieldmap data can be linked to the specific scan(s) it was
Expand Down

0 comments on commit 953ed10

Please sign in to comment.