Skip to content

Commit

Permalink
Merge pull request #651 from oesteban/rf/mri-fieldmaps
Browse files Browse the repository at this point in the history 
[FIX] Rewrite the MRI/fieldmaps subsection for consistency with the rest of specs
  • Loading branch information
@effigies
effigies authored Nov 6, 2020
2 parents 7d3f73a + 353d346 commit 4be793f
Show file tree
Hide file tree
Showing 4 changed files with 143 additions and 85 deletions.
20 changes: 14 additions & 6 deletions src/02-common-principles.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -149,6 +149,14 @@ data from subject `01`.
The suffix `eeg` and the extension `.edf` depend on the imaging modality and
the data format and indicate further details of the file's contents.

In cases where entities duplicate metadata,
the presence of an entity should not be used as a replacement for
the corresponding metadata field.
For instance, in echo-planar imaging MRI,
the [`dir-<label>`](./99-appendices/09-entities.md#dir) entity MAY be used
to distinguish files with different phase-encoding directions,
but the file's `PhaseEncodingDirection` can only be specified as metadata.

A summary of all entities in BIDS and the order in which they MUST be
specified is available in the [entity table](./99-appendices/04-entity-table.md)
in the appendix.
Expand Down Expand Up @@ -558,16 +566,16 @@ it refers to. For example `sub-01` refers to the `sub` entity (a
subject) with the label `01`. The `sub-` prefix is not part of the subject
label, but must be included in file names (similarly to other key names).

## Uniform Resource Indicator
## Uniform Resource Indicator

A Uniform Resource Indicator (URI) is a string referring to a resource and SHOULD
have the form `<scheme>:[//<authority>]<path>[?<query>][#<fragment>]`, as specified
in [RFC 3986](https://tools.ietf.org/html/rfc3986).
This applies to URLs and other common URIs, including Digital Object Identifiers (DOIs),
which may be fully specified as `doi:<path>`,
have the form `<scheme>:[//<authority>]<path>[?<query>][#<fragment>]`, as specified
in [RFC 3986](https://tools.ietf.org/html/rfc3986).
This applies to URLs and other common URIs, including Digital Object Identifiers (DOIs),
which may be fully specified as `doi:<path>`,
for example, [doi:10.5281/zenodo.3686061](https://doi.org/10.5281/zenodo.3686061).
A given resource may have multiple URIs.
When selecting URIs to add to dataset metadata, it is important to consider
When selecting URIs to add to dataset metadata, it is important to consider
specificity and persistence.

Several fields are designated for DOIs, for example, `DatasetDOI` in `dataset_description.json`.
Expand Down
199 changes: 124 additions & 75 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 @@ -567,39 +567,37 @@ JSON example:

## Fieldmap data

Data acquired to correct for B0 inhomogeneities can come in different forms. The
current version of this standard considers four different scenarios. Please note
that in all cases fieldmap data can be linked to a specific scan(s) it was
acquired for by filling the IntendedFor field in the corresponding JSON file.
For example:
Data acquired to correct for *B<sub>0</sub>* inhomogeneities can come in different forms.
The current version of this standard considers four different scenarios:

```JSON
{
"IntendedFor": "func/sub-01_task-motor_bold.nii.gz"
}
```
1. [Phase-difference map](#case-1-phase-difference-map-and-at-least-one-magnitude-image)
1. [Two phase maps](#case-2-two-phase-maps-and-two-magnitude-images)
1. [Direct *field mapping*](#case-3-direct-field-mapping)
1. ["*PEpolar*" fieldmaps](#case-4-multiple-phase-encoded-directions-pepolar)

The IntendedFor field may contain one or more filenames with paths relative to
the subject subfolder. The path needs to use forward slashes instead of backward
slashes. Here's an example with multiple target scans:
These four different types of field mapping strategies can be encoded
using the following image types:

```JSON
{
"IntendedFor": ["ses-pre/func/sub-01_ses-pre_task-motor_run-1_bold.nii.gz",
"ses-post/func/sub-01_ses-post_task-motor_run-1_bold.nii.gz"]
}
```
| **Name** | `suffix` | **Description** |
| ---------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Magnitude | magnitude\[1,2\] | Field-mapping MR schemes such as gradient-recalled echo (GRE) generate a Magnitude image to be used for anatomical reference. Requires the existence of Phase, Phase-difference or Fieldmap maps. |
| Phase | phase{1,2} | Phase map generated by GRE or similar schemes, each associated with the first (`phase1`) or second (`phase2`) echoes in the sequence. |
| Phase-difference | phasediff | Some scanners subtract the `phase1` from the `phase2` map and generate a unique `phasediff` file. For instance, this is a common output for the built-in fieldmap sequence of Siemens scanners. |
| Fieldmap | fieldmap | Some MR schemes such as spiral-echo (SE) sequences are able to directly provide maps of the *B<sub>0</sub>* field inhomogeneity. |
| EPI | epi | The phase-encoding polarity (PEpolar) technique combines two or more Spin Echo EPI scans with different phase encoding directions to estimate the underlying inhomogeneity/deformation map. |

Two OPTIONAL entities, following more general rules of the specification,
are allowed across all the four scenarios:

- The OPTIONAL [`run-<index>`](../99-appendices/09-entities.md#run) key/value pair corresponds to a one-based index
to distinguish multiple fieldmaps with the same parameters.

The IntendedFor field is OPTIONAL and in case the fieldmaps do not correspond to
any particular scans it does not have to be filled.
- The OPTIONAL [`acq-<label>`](../99-appendices/09-entities.md#acq) key/value pair corresponds to a custom label
the user may use to distinguish different set of parameters.

Multiple fieldmaps can be stored.
In such case the [`run-<index>`](../99-appendices/09-entities.md#run) key/value pair should be
used. The OPTIONAL [`acq-<label>`](../99-appendices/09-entities.md#acq)
key/value pair corresponds to a custom label
the user may use to distinguish different set of parameters.
### Types of fieldmaps

### Case 1: Phase difference image and at least one magnitude image
#### Case 1: Phase-difference map and at least one magnitude image

Template:

Expand All @@ -609,32 +607,38 @@ sub-<label>/[ses-<label>/]
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phasediff.nii[.gz]
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phasediff.json
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_magnitude1.nii[.gz]
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_magnitude2.nii[.gz] # OPTIONAL
```

OPTIONAL
where
the REQUIRED `_phasediff` image corresponds to the phase-drift map between echo times,
the REQUIRED `_magnitude1` image corresponds to the shorter echo time, and
the OPTIONAL `_magnitude2` image to the longer echo time.

```Text
sub-<label>/[ses-<label>/]
fmap/
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_magnitude2.nii[.gz]
```
Required fields:

This is a common output for build in fieldmap sequence on Siemens scanners. In
this particular case the sidecar JSON file has to define the Echo Times of the
two phase images used to create the difference image. `EchoTime1` corresponds to
the shorter echo time and `EchoTime2` to the longer echo time. Similarly
`_magnitude1` image corresponds to the shorter echo time and the OPTIONAL
`_magnitude2` image to the longer echo time. For example:
| **Key name** | **Requirement level** | **Data type** | **Description** |
| -------------- | --------------------- | ------------------------ | ----------------------------------------------------------- |
| EchoTime1 | REQUIRED | [number][] | The time (in seconds) when the first (shorter) echo occurs. |
| EchoTime2 | REQUIRED | [number][] | The time (in seconds) when the second (longer) echo occurs. |

In this particular case, the sidecar JSON file
`sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phasediff.json`
MUST define the time of two echos used to map the phase and finally calculate
the phase-difference map.
For example:

```JSON
{
"EchoTime1": 0.00600,
"EchoTime2": 0.00746,
"IntendedFor": "func/sub-01_task-motor_bold.nii.gz"
"EchoTime2": 0.00746
}
```

### Case 2: Two phase images and two magnitude images
#### Case 2: Two phase maps and two magnitude images
Similar to case 1, but instead of a precomputed phase-difference map, two
separate phase images and two magnitude images corresponding to first and
second echos are available.

Template:

Expand All @@ -649,18 +653,24 @@ sub-<label>/[ses-<label>/]
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_magnitude2.nii[.gz]
```

Similar to the case above, but instead of a precomputed phase difference map two
separate phase images are presented. The two sidecar JSON files need to specify
corresponding `EchoTime` values. For example:
Required fields:

| **Key name** | **Requirement level** | **Data type** | **Description** |
| -------------- | --------------------- | ------------------------ | --------------------------------------------------------------------------------- |
| EchoTime | REQUIRED | [number][] | The time (in seconds) when the echo corresponding to this phase map was acquired. |

Each phase map has a corresponding sidecar JSON file to specify its corresponding `EchoTime`.
For example, `sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phase2.json` may read:

```JSON
{
"EchoTime": 0.00746,
"IntendedFor": "func/sub-01_task-motor_bold.nii.gz"
"EchoTime": 0.00746
}
```

### Case 3: A real fieldmap image
#### Case 3: Direct *field mapping*
In some cases (for example GE), the scanner software will directly reconstruct a
*B<sub>0</sub>* field map along with a magnitude image used for anatomical reference.

Template:

Expand All @@ -672,12 +682,12 @@ sub-<label>/[ses-<label>/]
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_fieldmap.json
```

In some cases (for example GE) the scanner software will output a precomputed
fieldmap denoting the B0 inhomogeneities along with a magnitude image used for
coregistration.
In this case the sidecar JSON file needs to include the units of the fieldmap.
The possible options are: Hertz (`Hz`), Radians per second (`rad/s`), or Tesla
(`T`).
Required fields:

| **Key name** | **Requirement level** | **Data type** | **Description** |
| -------------- | --------------------- | ------------------------ | ---------------------------------------------------------------------------------- |
| Units | REQUIRED | [string][] | Units of the fieldmap: Hertz (`Hz`), Radians per second (`rad/s`), or Tesla (`T`). |

For example:

```JSON
Expand All @@ -687,7 +697,17 @@ For example:
}
```

### Case 4: Multiple phase encoded directions ("pepolar")
See [Using `IntendedFor` metadata](#using-intendedfor-metadata)
for details on the `IntendedFor` field.

#### Case 4: Multiple phase encoded directions ("pepolar")
The phase-encoding polarity (PEpolar) technique combines two or more Spin Echo
EPI scans with different phase encoding directions to estimate the distortion
map corresponding to the nonuniformities of the *B<sub>0</sub>* field.
These `_epi.nii[.gz]` files can be 3D or 4D --
in the latter case, all timepoints share the same scanning parameters.
Examples of software tools using these kinds of images are FSL TOPUP,
AFNI `3dqwarp`, and SPM.

Template:

Expand All @@ -698,17 +718,20 @@ sub-<label>/[ses-<label>/]
sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>]_dir-<label>[_run-<index>]_epi.json
```

The phase-encoding polarity (PEpolar) technique combines two or more Spin Echo
EPI scans with different phase encoding directions to estimate the underlying
inhomogeneity/deformation map. Examples of tools using this kind of images are
FSL TOPUP, AFNI 3dqwarp and SPM. In such a case, the phase encoding direction is
specified in the corresponding JSON file as one of: `i`, `j`, `k`, `i-`, `j-`,
`k-`. For these differentially phase encoded sequences, one also needs to
specify the Total Readout Time defined as the time (in seconds) from the center
of the first echo to the center of the last echo (aka "FSL definition" - see
[here](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/topup/Faq#How_do_I_know_what_phase-encode_vectors_to_put_into_my_--datain_text_file.3F) and
[here](https://lcni.uoregon.edu/kb-articles/kb-0003) how to calculate it). For
example
The [`dir-<label>`](../99-appendices/09-entities.md#dir) entity is REQUIRED
for these files.
This key-value pair MUST be used in addition to
the REQUIRED `PhaseEncodingDirection` metadata field
(see [File name structure](../02-common-principles.md#file-name-structure)).

Required fields:

| **Key name** | **Requirement level** | **Data type** | **Description** |
| ---------------------- | --------------------- | ------------- | ---------------------------------------------------------------------------------- |
| PhaseEncodingDirection | REQUIRED | [string][] | See [in-plane spatial encoding](#in-plane-spatial-encoding) table of fields. |
| TotalReadoutTime | REQUIRED | [number][] | See [in-plane spatial encoding](#in-plane-spatial-encoding) table of fields. |

For example:

```JSON
{
Expand All @@ -718,15 +741,41 @@ example
}
```

The `label` value of the [`dir-<label>`](../99-appendices/09-entities.md#dir) key/value pair
can be set to arbitrary alphanumeric label (`[a-zA-Z0-9]+` for
example `LR` or `AP`) that can help users to distinguish between different
files, but should not be used to infer any scanning parameters (such as phase
encoding directions) of the corresponding sequence. Please rely only on the JSON
file to obtain scanning parameters. \_epi files can be a 3D or 4D - in the
latter case all timepoints share the same scanning parameters. To indicate which
run is intended to be used with which functional or diffusion scan the
IntendedFor field in the JSON file should be used.
See [Using `IntendedFor` metadata](#using-intendedfor-metadata)
for details on the `IntendedFor` field.

As for other EPI sequences, these field mapping sequences may have any of the
[in-plane spatial encoding](#in-plane-spatial-encoding) metadata keys.
However, please note that `PhaseEncodingDirection` and `TotalReadoutTime` keys
are REQUIRED for these field mapping sequences.

### Expressing the MR protocol intent for fieldmaps

Fieldmaps are typically acquired with the purpose of correcting one or more EPI
scans under `func/` or `dwi/` for distortions derived from *B<sub>0</sub>*
nonuniformity.
This linking between fieldmaps and their targetted data MAY be encoded with the
`IntendedFor` metadata.

#### Using `IntendedFor` metadata

Fieldmap data MAY be linked to the specific scan(s) it was acquired for by
filling the `IntendedFor` field in the corresponding JSON file.

| **Key name** | **Requirement level** | **Data type** | **Description** |
| ------------ | --------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| IntendedFor | RECOMMENDED | [string][] or [array][] of [string][] | Contains one or more filenames with paths relative to the participant subfolder. The path needs to use forward slashes instead of backward slashes. This field is OPTIONAL, and in case the fieldmaps do not correspond to any particular scans, it does not have to be filled. |

For example:

```JSON
{
"IntendedFor": [
"ses-pre/func/sub-01_ses-pre_task-motor_run-1_bold.nii.gz",
"ses-pre/func/sub-01_ses-pre_task-motor_run-2_bold.nii.gz"
]
}
```

<!-- Link Definitions -->

Expand Down
4 changes: 2 additions & 2 deletions src/99-appendices/09-entities.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -103,8 +103,8 @@ Full name: Phase-Encoding Direction

Format: `dir-<label>`

Definition: The `dir-<label>` key/value can be used to distinguish
different phase-encoding directions.
Definition: The `dir-<label>` key/value can be set to an arbitrary alphanumeric label
(for example, `dir-LR` or `dir-AP`) to distinguish different phase-encoding directions.

## run

Expand Down
5 changes: 3 additions & 2 deletions src/schema/entities.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -77,8 +77,9 @@ direction:
name: Phase-Encoding Direction
entity: dir
description: |
The `dir-<label>` key/value can be used to distinguish
different phase-encoding directions.
The `dir-<label>` key/value can be set to an arbitrary alphanumeric label
(for example, `dir-LR` or `dir-AP`) to distinguish different phase-encoding
directions.
format: label
run:
name: Run
Expand Down

0 comments on commit 4be793f

Please sign in to comment.