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

Show file tree
Hide file tree
Changes from all 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
20 changes: 14 additions & 6 deletions src/02-common-principles.md
View file
Open in desktop
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 @@ -552,16 +560,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
Open in desktop
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. |
oesteban marked this conversation as resolved.
Show resolved Hide resolved
| 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
Comment on lines 609 to +610
Copy link
Member

Choose a reason for hiding this comment

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

One thing that confuses me about this template (even before this PR)- wouldn't we still have jsons for the magnitude maps?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

The magnitude maps are part of the acquisition (as the phase maps are), so all the metadata is probably best stored only on the phase information files. I'm not sure what metadata could possibly exist that only applies to the magnitude (and doesn't to the phase).

Copy link
Member

Choose a reason for hiding this comment

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

That's true, but I don't think that kind of relationship is supported in the specification. I guess we would call it something like horizontal inheritance?

I could be wrong though.

Copy link
Member

Choose a reason for hiding this comment

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

For tools like pybids, I think you need sidecar files for the magnitude images in order to extract their metadata. @effigies is that still the case or can pybids infer metadata from linked files?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I haven't encountered any case where PyBIDS could not correctly query the metadata of fieldmaps.

Copy link
Collaborator

Choose a reason for hiding this comment

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

I had phase1/phase2/magnitude1/magnitude2 images, and I believe I had to duplicate the metadata across both phase and magnitude images.

Copy link
Collaborator

Choose a reason for hiding this comment

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

sbref files are also optional, but not labeled so in the template.

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

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I think it is important to mark optional elements on the template. Following that argument all fieldmaps are essentially optional because a BIDS-valid dataset may or may not have them.

There's been some discussion about this annotation with @tsalo. Could you read through that and then let us know if you still think this change should be made (i.e., remove the OPTIONAL annotation in the template)?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Also, I'm growing a feeling that _sbref should not exist altogether.

Copy link
Collaborator

Choose a reason for hiding this comment

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

Agreed that all files are optional, so it seems strange to mark one out as super-extra optional in either form. (I did find and mark unresolved that comment thread, btw.)

Immediately below the template is:

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.

I don't understand why we need to add novel markup to the template when the text is right there.

Just as a final point, I would say that I'm not opposed to the concept of indicating in the template that one file in a group is optional, but I am opposed to introducing it in a one-off manner. I would rather we made a principled decision that takes into account all such groupings and applies it to the entire spec in one PR.

That said, I won't block this PR over this quibble.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I don't understand why we need to add novel markup to the template when the text is right there.

Most people will not read that paragraph, especially if they feel they know the specification and are making a quick confirmatory look-up.

Just as a final point, I would say that I'm not opposed to the concept of indicating in the template that one file in a group is optional, but I am opposed to introducing it in a one-off manner. I would rather we made a principled decision that takes into account all such groupings and applies it to the entire spec in one PR.

I agree with this. For this PR I see three alternatives:

  1. Leave it as is now and come back to the issue later (or within [SCHEMA] Render schema elements in text #610)
  2. Roll it back to [] since that nomenclature, even though not formalized, is apparently present elsewhere in BIDS (and finally address it within [SCHEMA] Render schema elements in text #610).
  3. Remove any annotations (and bring them up in a separate PR or [SCHEMA] Render schema elements in text #610).

I think 3 would be the best option, but I'm afraid that this will concept will be probably lost (I'm honestly not willing to go through the whole spec to propose something in a separate PR or in #610). So, after the discussion with @tsalo I think I prefer option 1.

```

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:
}
```

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

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

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
Open in desktop
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
Open in desktop
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