Skip to content

Commit

Permalink
enh: rewrite the fieldmaps subsection for consistency with rest of specs
Browse files Browse the repository at this point in the history 
this commit rewrites the fieldmaps subsection to better allocate the
proposed changes, while making its structure more consistent with the
previous contents of the section.
  • Loading branch information
@oesteban
oesteban committed Oct 23, 2020
1 parent d576ad0 commit 15c1a58
Showing 1 changed file with 128 additions and 79 deletions.
207 changes: 128 additions & 79 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,31 @@ 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 B0 inhomogeneities can come in different forms.
The current version of this standard considers four different scenarios.
These four different types of field mapping strategies can be encoded
using the following image types:

```JSON
{
"IntendedFor": "func/sub-01_task-motor_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 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. |
| 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. |

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:
Two OPTIONAL key/value pairs following more general rules of the specification
are allowed across all the four scenarios:

```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"]
}
```
- The OPTIONAL [`run-<index>`](../99-appendices/09-entities.md#run) key/value pair correspond to a one-base 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 +601,32 @@ 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
where `_magnitude1` image corresponds to the shorter echo time and the OPTIONAL
`_magnitude2` (represented within brackets) 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:

| **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. |

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:
In this particular case the sidecar JSON file has to define the Echo Times of the
two phase images used to create 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 are available.

Template:

Expand All @@ -649,18 +641,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
B0 field mapping along with a magnitude image used for anatomical reference.

Template:

Expand All @@ -672,22 +670,28 @@ 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
{
"Units": "rad/s",
"IntendedFor": "func/sub-01_task-motor_bold.nii.gz"
"Units": "rad/s"
}
```

### Case 4: Multiple phase encoded directions ("pepolar")
#### 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.
These `_epi.nii[.gz]` files can be a 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,35 +702,80 @@ 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 REQUIRED [`dir-<label>`](../99-appendices/09-entities.md#dir) key/value pair
can be set to arbitrary alphanumeric label (`[a-zA-Z0-9]+` for
example `dir-LR` or `dir-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.
It is RECOMMENDED to only rely on the JSON sidecar metadata described in the following
to obtain the scanning parameters.

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
{
"PhaseEncodingDirection": "j-",
"TotalReadoutTime": 0.095,
"IntendedFor": "func/sub-01_task-motor_bold.nii.gz"
"TotalReadoutTime": 0.095
}
```

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

#### Using `IntendedFor` metadata

Fieldmap data can be linked to a 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. |

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:

```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"]
}
```

The `IntendedFor` field is OPTIONAL and in case the fieldmaps do not correspond to
any particular scans it does not have to be filled.

For example, extending from the previous example of `sub-<label>_fieldmap.json` file:

```JSON
{
"Units": "rad/s",
"IntendedFor": "func/sub-01_task-motor_bold.nii.gz"
}
```

or:

```JSON
{
"Units": "rad/s",
"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"
]
}
```

<!-- Link Definitions -->

Expand Down

0 comments on commit 15c1a58

Please sign in to comment.