Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[FIX] Rewrite the MRI/fieldmaps subsection for consistency with the rest of specs #651

Merged
merged 11 commits into from
Nov 6, 2020
Merged

[FIX] Rewrite the MRI/fieldmaps subsection for consistency with the rest of specs #651

Changes from 2 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
648471c
enh: rewrite the fieldmaps subsection for consistency with rest of specs
oesteban Sep 28, 2020
ca5dcb8
fix: replace weird example with plausible one
oesteban Oct 23, 2020
6e05ad6
enh: summarize scenarios first following @sappelhoff's suggestion
oesteban Oct 24, 2020
dd3c87f
fix: uprank the warning about ``dir-<label>`` to common principles
oesteban Oct 24, 2020
d81d291
fix: annotate magnitude2 map as OPTIONAL in case 1 template
oesteban Oct 27, 2020
7533998
Apply suggestions from code review
oesteban Oct 27, 2020
1c63137
fix: indentation in example
oesteban Oct 27, 2020
9d1c49b
fix: more proper writing of B_0 and consistency changes
oesteban Oct 28, 2020
ea830e5
fix: roll back nonstandard MAY NOT statement
oesteban Oct 28, 2020
504dd30
Apply suggestions from code review (from #622)
oesteban Oct 28, 2020
353d346
Apply suggestions from code review
oesteban Oct 30, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
188 changes: 109 additions & 79 deletions src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
View file
Open in desktop
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.
oesteban marked this conversation as resolved.
Show resolved Hide resolved
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. |
oesteban marked this conversation as resolved.
Show resolved Hide resolved
| 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
oesteban marked this conversation as resolved.
Show resolved Hide resolved
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.
oesteban marked this conversation as resolved.
Show resolved Hide resolved

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,34 @@ 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]]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Including brackets around the whole filename to indicate that it's an optional file isn't used consistently across the specification. I think it really only shows up in the MEG/EEG sections, so I'm not sure if we want to introduce it here.

Also, the schema isn't capable of storing that kind of information at the moment, so those brackets will be removed when/if #610 is merged.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure what the alternative would be. Any suggestions?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure what the alternative would be

I think it'd be fine not to communicate requirement level in the "template" section. After all, we are also not distinguishing between recommended and required files either. Users can see which files are optional from the spec text.

Copy link
Collaborator Author

@oesteban oesteban Oct 27, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not particularly attached to this indication of an optional data object, but I think there are two different discussions here.

  1. Whether the schema can store this information at the moment -- here the question is whether the schema should store this information, actually. I guess so, because the validator needs to know whether magnitude2 must be found (phase1/2 fieldmaps) or is optional (phasediff fieldmaps).
  2. Whether the template is the right place to state the indication

IMHO, 1) is harder to address, and outside the scope of this PR -- I guess that merging #610 will have to address this question, and if that means that the brackets in the template are gone because some other mechanism implements this, I'm fine by that (that's how BIDS evolves, anyways).

Then 2) - I think that the Template is basically what most of the people check when preparing their data. Therefore, I think this is the most effective way of expressing that this element is optional. It also needs to be clearly stated within the text, but considering that magnitude2 may and may not be optional (phasediff and phase1/2, respectively), there is a larger chance this is lost in some future refactor. For clarity, I think having the template annotated with requirement levels, especially when irregular, is very useful.

@tsalo: would something like:

        sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_magnitude2.nii[.gz]  # OPTIONAL

work out?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There really isn't any mechanism for stating that some suffixes or extensions are optional in combination with others in the schema at the moment, so #610 will erase any indications of that from templates and users will need to rely on the text for that kind of information. I don't think it's that big a deal to address this issue in #610 though.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What would you prefer then for this PR?

        [sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_magnitude2.nii[.gz]]

or

        sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_magnitude2.nii[.gz]  # OPTIONAL

I'm leaning towards the # OPTIONAL annotation which is more visible and obvious - WDYT?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think # OPTIONAL works well.

```

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:

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 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 +643,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 +672,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"
oesteban marked this conversation as resolved.
Show resolved Hide resolved
"Units": "rad/s"
oesteban marked this conversation as resolved.
Show resolved Hide resolved
}
```

oesteban marked this conversation as resolved.
Show resolved Hide resolved
### 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 --
oesteban marked this conversation as resolved.
Show resolved Hide resolved
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 +704,59 @@ 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
oesteban marked this conversation as resolved.
Show resolved Hide resolved
}
```

oesteban marked this conversation as resolved.
Show resolved Hide resolved
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
oesteban marked this conversation as resolved.
Show resolved Hide resolved

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

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

Expand Down