Skip to content

Commit

Permalink
fix: more proper writing of B_0 and consistency changes
Browse files Browse the repository at this point in the history
  • Loading branch information
@oesteban
oesteban committed Oct 28, 2020
1 parent 1c63137 commit a45f13f
Showing 1 changed file with 26 additions and 19 deletions.
45 changes: 26 additions & 19 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,7 +567,7 @@ JSON example:

## Fieldmap data

Data acquired to correct for B0 inhomogeneities can come in different forms.
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:

1. [Phase-difference map](#case-1-phase-difference-map-and-at-least-one-magnitude-image)
Expand All @@ -583,7 +583,7 @@ as described [below](#types-of-fieldmaps), using the following image types:
| 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 as described below. |
| Phase | phase{1,2} | Phase map generated by GRE schemes and alike, 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 B0 field inhomogeneity. |
| 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 key/value pairs following more general rules of the specification
Expand All @@ -610,8 +610,10 @@ sub-<label>/[ses-<label>/]
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_magnitude2.nii[.gz] # OPTIONAL
```

where `_magnitude1` image corresponds to the shorter echo time and the OPTIONAL
`_magnitude2` (represented within brackets) image to the longer echo time.
where
the REQUIRED `_phasediff` image correspond 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.

Required fields:

Expand All @@ -620,8 +622,10 @@ Required fields:
| 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 MUST define the time of
two echos used to map the phase and finally calculate the phase-difference map.
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
Expand Down Expand Up @@ -665,8 +669,8 @@ For example, `sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phase2.json`
```

#### Case 3: Direct *field mapping*
In some cases (for example GE) the scanner software will directly reconstruct a
B0 field mapping along with a magnitude image used for anatomical reference.
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 Down Expand Up @@ -694,8 +698,8 @@ For example:

#### 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 underlying
inhomogeneity/deformation map.
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,
Expand All @@ -710,9 +714,9 @@ sub-<label>/[ses-<label>/]
sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>]_dir-<label>[_run-<index>]_epi.json
```

The [`dir-<label>`](../99-appendices/09-entities.md#dir) key/value pair used to
distinguish between different phase-encoding directions is REQUIRED for these
files, and SHOULD NOT be used to replace the required `PhaseEncodingDirection`
The [`dir-<label>`](../99-appendices/09-entities.md#dir) entity is REQUIRED
for these files.
This key-value pair SHOULD NOT be used to replace the required `PhaseEncodingDirection`
(nor any other acquisition parameter, as prescribed by the
[common principles](../02-common-principles.md#file-name-structure)).

Expand All @@ -739,14 +743,20 @@ 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 can be linked to the specific scan(s) it was
acquired for by filling the `IntendedFor` field in the corresponding JSON file.
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. |
| 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 MAY NOT be filled. |

For example:

Expand All @@ -759,9 +769,6 @@ For example:
}
```

The `IntendedFor` field is OPTIONAL and in case the fieldmaps do not correspond to
any particular scan(s), it does not have to be filled.

<!-- Link Definitions -->

[deprecated]: ../02-common-principles.md#definitions
Expand Down

0 comments on commit a45f13f

Please sign in to comment.