[ENH] Allow encoding the fieldmapping intent of the protocol #622

oesteban · 2020-09-28T09:59:28Z

This PR addresses the problem @mattcieslak spotted at in #239.

This enhancement (WIP) basically allows for researchers to encode the protocol's intent regarding fieldmaps.

As @satra introduced in #239 (comment), BIDS "could encode intent and automation. Whether it should is a community decision."

This PR proposes a solution to encoding the intent. It doesn't modify anything to allow also encoding automation.

The PR attempts to be backward compatible.

I'm submitting this draft PR to open discussions and looking forward to feedback.

Resolves: #239.
References: #263, nipreps/dmriprep#43, bids-standard/bids-2-devel#39

The gist of this PR...

... is the creation of two new metadata pairs B0FieldIdentifier and B0FieldSource to encode how the researcher originally designed the MR protocol regarding fieldmaps.

B0FieldIdentifier is set in all images that are to be used in estimating some fieldmap. Images with the same B0FieldIdentifier are expected to be used together (e.g., two _epi datasets under fmap/ with opposed PE direction, two _epi datasets under fmap/ plus two _dwi datasets under dwi/, or maybe two _sbref datasets under func/ with opposed PEs, etc.)

B0FieldSource states identifiers intended for correcting the particular instance where it is defined.

Currently unsupported example:

func/
  sub-01_task-rest_bold.json
  sub-01_task-rest_bold.nii.gz
  sub-01_task-rest_dir-ap_sbref.json
  sub-01_task-rest_dir-ap_sbref.nii.gz
  sub-01_task-rest_dir-pa_sbref.json
  sub-01_task-rest_dir-pa_sbref.nii.gz

would have the following metadata:

sub-01_task-rest_bold.json:

{
  "B0FieldSource": "sbrefs_fmap",
  "PhaseEncodingDirection": "j",
  "RepetitionTime": 2.0,
  "TotalReadoutTime": 0.05
}

sub-01_task-rest_dir-ap_sbref.json

{
  "B0FieldIdentifier": "sbrefs_fmap",
  "PhaseEncodingDirection": "j",
  "TotalReadoutTime": 0.05
}

and sub-01_task-rest_dir-pa_sbref.json

{
  "B0FieldIdentifier": "sbrefs_fmap",
  "PhaseEncodingDirection": "j-",
  "TotalReadoutTime": 0.05
}

A currently supported example:

fmap/
  sub-01_phasediff.json
  sub-01_phasediff.nii.gz
  sub-01_magnitude1.nii.gz
func/
  sub-01_task-rest_bold.json
  sub-01_task-rest_bold.nii.gz

would have the following metadata:

sub-01_task-rest_bold.json:

{
  "B0FieldSource": "phdiff_fmap",
  "PhaseEncodingDirection": "j",
  "RepetitionTime": 2.0,
  "TotalReadoutTime": 0.05
}

sub-01_phasediff.json

{
  "B0FieldIdentifier": "phdiff_fmap",
  "EffectiveEchoSpacing": "0.00246",
  "IntendedFor": "func/sub-01_task-rest_bold.nii.gz"
}

oesteban · 2020-09-28T15:11:48Z

src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md

@@ -70,8 +70,11 @@ reflected in a single DICOM tag for all possible aforementioned scan
 manipulations). See [here](https://lcni.uoregon.edu/kb-articles/kb-0003) and
 [here](https://github.com/neurolabusc/dcm_qa/tree/master/In/TotalReadoutTime)

-<sup>3</sup>We use the "FSL definition", i.e, the time between the center of the


this was mentioned again under fieldmaps. I've moved that mention (after applying some improvements to the language) over here for completeness.

oesteban · 2020-09-28T15:12:15Z

src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md

@@ -104,6 +107,24 @@ Useful for multimodal co-registration with MEG, (S)EEG, TMS, etc.
 | ----------------------------- | --------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | AnatomicalLandmarkCoordinates | RECOMMENDED           | [object][] of [arrays][] | Key:value pairs of any number of additional anatomical landmarks and their coordinates in voxel units (where first voxel has index 0,0,0) relative to the associated anatomical MRI, (e.g. `{"AC": [127,119,149], "PC": [128,93,141], "IH": [131,114,206]}, or {"NAS": [127,213,139], "LPA": [52,113,96], "RPA": [202,113,91]}`). |

+### Echo-Planar Imaging & B0 field-mapping


this is the core of the proposal

src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md

Addresses the use case of DWI sequencies that need to be split in several runs because, e.g., the scanner would exceed temperature specifications due to fast gradient-switching. This PR also refactors the text of DWIs to better accomodate the addition and make DWIs more consistent with the rest of the file. The approach to solve this is similar to that of bids-standard#622 for fieldmaps. References: nipreps/dmriprep#43.

src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md

Addresses the use case of DWI sequencies that need to be split in several runs because, e.g., the scanner would exceed temperature specifications due to fast gradient-switching. This PR also refactors the text of DWIs to better accomodate the addition and make DWIs more consistent with the rest of the file. The approach to solve this is similar to that of bids-standard#622 for fieldmaps. References: nipreps/dmriprep#43.

oesteban · 2020-10-23T20:09:00Z

Clean diff with #651 - oesteban/bids-specification@rf/mri-fieldmaps...oesteban:enh/fieldmaps-refactor

effigies · 2021-04-12T13:35:02Z

I think the BIDS standard should be internally consistent. The draft for direct field mapping introduces the field Units, but BEP009 uses Unit for the same DICOM field. @effigies perhaps you have thoughts on this.

Good catch. It looks like Units in fieldmaps pre-dates Unit, and we haven't released PET, so we have a chance to fix without breaking backwards compatiblity.

oesteban · 2021-04-21T06:30:53Z

Are any code owners willing to leave a green tick to get this merged? We will need two more (and/or give Matt rights, how does that process work?)

@bids-standard/raw-mri-dwi @bids-standard/raw-mri

francopestilli · 2021-04-21T16:32:42Z

✅

tsalo

Everything looks good to me.

tsalo · 2021-04-21T17:03:40Z

This PR has the necessary approvals at this point, I think, but since we're in the embargo period before a release, we can't merge this until Friday, at least.

effigies · 2021-04-22T21:00:49Z

@oesteban Can you check that merge? I think I may have done it backwards.

oesteban · 2021-04-23T06:33:30Z

The merge looks good, with the latest additions to master my latest commit was outdated. I quickly checked and I don't see any difference w.r.t. before the merge.

Should I just merge?

effigies · 2021-04-27T17:51:35Z

@oesteban I think I restored something you intended to remove. I'm going to re-do the merge.

…actor

effigies · 2021-04-27T17:59:43Z

Here's the change that I accidentally dropped: https://github.com/bids-standard/bids-specification/compare/b0312f8a6d1daa2d3683bc45bbd9e9f65d232c43..8d862e79d42390094e8cfa3ca75cedba2d4df5a2

* Draft schema for suffixes. * Delete Untitled.ipynb * Clean up suffixes from Anatomical MRI's first table. * Add second table from Anatomical MRI. * Add third table from Anatomical MRI. * Add first table from Task imaging data * Add DWI and B0 field map suffixes. * Add anatomical qMRI table suffixes * Add field map qMRI table suffixes * Add ASL suffixes. * Add MEG suffixes. * Add EEG suffixes. * Add remaining suffixes. * Fix T1map. * Add make_suffix_table. * Add angio to first suffix table. * Add suffix info to README. * Add descriptions for remaining suffixes. * Update fieldmap suffix definition from #622. * Fix bad merge. * Use three underscores, not two. * Apply suggestions from code review Co-authored-by: Chris Markiewicz <effigies@gmail.com> * Further address review. * Apply suggestions from code review Co-authored-by: Chris Markiewicz <effigies@gmail.com> * Remove hardcoded tables. Co-authored-by: Chris Markiewicz <effigies@gmail.com>

oesteban requested review from effigies, francopestilli, Lestropie, mattcieslak, satra, sebastientourbier and edickie September 28, 2020 10:00

oesteban mentioned this pull request Sep 28, 2020

Concatenating different runs nipreps/dmriprep#43

Closed

oesteban commented Sep 28, 2020

View reviewed changes

oesteban marked this pull request as ready for review September 28, 2020 16:09

oesteban requested a review from chrisgorgo as a code owner September 28, 2020 16:09

oesteban requested a review from tsalo September 28, 2020 16:10

oesteban mentioned this pull request Sep 28, 2020

[ENH] Add "multipart DWI" acquisitions and refactor DWI specifications #624

Merged

tsalo reviewed Sep 28, 2020

View reviewed changes

src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md Show resolved Hide resolved

oesteban requested a review from arokem September 28, 2020 20:37

oesteban mentioned this pull request Sep 29, 2020

1.4.1 RELEASE of the BIDS specification #607

Closed

tsalo reviewed Sep 29, 2020

View reviewed changes

src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md Outdated Show resolved Hide resolved

tsalo mentioned this pull request Sep 29, 2020

Add concept of a "grouped scan collection" to common principles #529

Closed

arokem reviewed Sep 29, 2020

View reviewed changes

src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md Outdated Show resolved Hide resolved

oesteban mentioned this pull request Oct 1, 2020

[ENH] A doctested grouping algorithm nipreps/dmriprep#70

Closed

This was referenced Oct 14, 2020

SDC-pepolar: topup implementation v2 nipreps/sdcflows#106

Closed

ENH: Refactor the workflow infrastructure nipreps/sdcflows#113

Closed

oesteban force-pushed the enh/fieldmaps-refactor branch 2 times, most recently from 0fcc838 to 953ed10 Compare October 23, 2020 20:02

oesteban marked this pull request as draft October 23, 2020 20:08

oesteban mentioned this pull request Oct 24, 2020

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

Merged

effigies mentioned this pull request Apr 12, 2021

[FIX] Rename "Unit" metadata to "Units" for consistency with existing fields #773

Merged

effigies modified the milestones: 1.5.0, 1.6.1 Apr 14, 2021

mgxd mentioned this pull request Apr 15, 2021

ENH: Add estimation method description to outputs nipreps/sdcflows#191

Merged

tsalo approved these changes Apr 21, 2021

View reviewed changes

effigies force-pushed the enh/fieldmaps-refactor branch from b0312f8 to 234b5b8 Compare April 27, 2021 17:56

Merge remote-tracking branch 'upstream/master' into enh/fieldmaps-ref…

8d862e7

…actor

effigies force-pushed the enh/fieldmaps-refactor branch from 234b5b8 to 8d862e7 Compare April 27, 2021 17:57

effigies merged commit 9748a7c into bids-standard:master Apr 28, 2021

bids-maintenance added a commit that referenced this pull request Apr 28, 2021

[DOC] Auto-generate changelog entry for PR #622

31679c3

oesteban deleted the enh/fieldmaps-refactor branch April 28, 2021 15:32

tsalo added a commit to tsalo/bids-specification that referenced this pull request Apr 30, 2021

Update fieldmap suffix definition from bids-standard#622.

b5ac922

dlevitas mentioned this pull request Nov 3, 2021

Add B0FieldIdentifier and B0FieldSource brainlife/ezbids#38

Closed

sappelhoff modified the milestones: 1.6.1, 1.7.0 Nov 9, 2021

effigies mentioned this pull request Jan 7, 2022

[ENH] Update B0Field metadata to accommodate single-blip fieldmaps #968

Merged

marcelzwiers mentioned this pull request Feb 3, 2022

Handle duplicated fieldmaps in interrupted session Donders-Institute/bidscoin#123

Closed

marcelzwiers mentioned this pull request Feb 19, 2022

Sophisticated PEPOLAR schemes are unsupported error nipreps/fmriprep#2719

Open

tsalo mentioned this pull request May 17, 2022

Move and rename IntendedFor field from fieldmap to functional image bids-standard/bids-2-devel#39

Open

Lestropie mentioned this pull request Aug 8, 2022

Change handling of field mapping information bids-standard/bids-2-devel#53

Open

mateuszpawlik mentioned this pull request Mar 27, 2024

Update B0fieldIdentifier/Source when having multiple fieldmap runs Donders-Institute/bidscoin#198

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[ENH] Allow encoding the fieldmapping intent of the protocol #622

[ENH] Allow encoding the fieldmapping intent of the protocol #622

oesteban commented Sep 28, 2020 •

edited

Loading

oesteban Sep 28, 2020

oesteban Sep 28, 2020

oesteban commented Oct 23, 2020

effigies commented Apr 12, 2021

oesteban commented Apr 21, 2021

francopestilli commented Apr 21, 2021

tsalo left a comment

tsalo commented Apr 21, 2021

effigies commented Apr 22, 2021

oesteban commented Apr 23, 2021

effigies commented Apr 27, 2021

effigies commented Apr 27, 2021

[ENH] Allow encoding the fieldmapping intent of the protocol #622

[ENH] Allow encoding the fieldmapping intent of the protocol #622

Conversation

oesteban commented Sep 28, 2020 • edited Loading

The gist of this PR...

Currently unsupported example:

A currently supported example:

oesteban Sep 28, 2020

Choose a reason for hiding this comment

oesteban Sep 28, 2020

Choose a reason for hiding this comment

oesteban commented Oct 23, 2020

effigies commented Apr 12, 2021

oesteban commented Apr 21, 2021

francopestilli commented Apr 21, 2021

tsalo left a comment

Choose a reason for hiding this comment

tsalo commented Apr 21, 2021

effigies commented Apr 22, 2021

oesteban commented Apr 23, 2021

effigies commented Apr 27, 2021

effigies commented Apr 27, 2021

oesteban commented Sep 28, 2020 •

edited

Loading