Skip to content

Commit

Permalink
[ENH] BEP001 - Entity-linked file collections (#688)
Browse files Browse the repository at this point in the history 
* Squashed commit of the following:

commit 8e1ac5f
Author: Stefan Appelhoff <[email protected]>
Date:   Fri Nov 27 11:09:24 2020 +0100

    fix links and latin

commit 27c9b41
Author: Stefan Appelhoff <[email protected]>
Date:   Fri Nov 27 10:03:51 2020 +0100

    remove latin

    Co-authored-by: Chris Markiewicz <[email protected]>

commit 7d87070
Author: Agah <[email protected]>
Date:   Mon Nov 23 08:46:47 2020 -0500

    Update src/99-appendices/10-file-collections.md

    Co-authored-by: Chris Markiewicz <[email protected]>

commit b137a9e
Author: Agah <[email protected]>
Date:   Mon Nov 23 08:45:19 2020 -0500

    Update src/02-common-principles.md

    Co-authored-by: Chris Markiewicz <[email protected]>

commit d7897b8
Author: Agah <[email protected]>
Date:   Mon Nov 23 08:44:40 2020 -0500

    Update src/02-common-principles.md

    Co-authored-by: Chris Markiewicz <[email protected]>

commit 09e9d32
Author: Agah <[email protected]>
Date:   Mon Nov 23 08:44:15 2020 -0500

    Commit suggestion

    Co-authored-by: Chris Markiewicz <[email protected]>

commit 009a9ab
Author: Agah Karakuzu <[email protected]>
Date:   Mon Nov 23 08:43:00 2020 -0500

    Add file-collecitons appendix to the TOC

commit 8f6c4df
Author: Agah Karakuzu <[email protected]>
Date:   Mon Nov 23 08:41:13 2020 -0500

    Address suggestion by @tsalo

commit 45210a9
Author: Agah Karakuzu <[email protected]>
Date:   Wed Nov 11 14:32:20 2020 -0500

    Wording

commit 66ba5a5
Author: Agah Karakuzu <[email protected]>
Date:   Wed Nov 11 14:31:40 2020 -0500

    RECOMMENDED --> MUST for adding an application def to the appdx

commit 5611fac
Author: Agah Karakuzu <[email protected]>
Date:   Wed Nov 11 14:29:21 2020 -0500

    Improve the appendix

commit 6d3bbea
Author: Agah Karakuzu <[email protected]>
Date:   Mon Nov 2 16:12:04 2020 -0500

    Address suggestions by @tsalo

commit bcb0223
Author: Agah Karakuzu <[email protected]>
Date:   Tue Oct 27 21:37:26 2020 -0400

    [ADD] Link to the appendix

commit 44e760f
Author: Agah Karakuzu <[email protected]>
Date:   Tue Oct 27 21:28:38 2020 -0400

    [ADD] Appendix - File collections

    - For parametrically linked file collections

commit 523b1c1
Author: Agah Karakuzu <[email protected]>
Date:   Tue Oct 27 21:27:52 2020 -0400

    [ADD] Parametrically linked file collections

    - Description

* ENH: Link to all BEP-001 entities

* STY: Escape asterisk, adjust table widths

* Add suggestions by @sappelhoff

* Update src/02-common-principles.md

Co-authored-by: Chris Markiewicz <[email protected]>

* Update src/02-common-principles.md

Co-authored-by: Chris Markiewicz <[email protected]>

* Update src/02-common-principles.md

Co-authored-by: Chris Markiewicz <[email protected]>

* Update src/99-appendices/10-file-collections.md

Co-authored-by: Chris Markiewicz <[email protected]>

* Update src/02-common-principles.md

Thank you @effigies!

Co-authored-by: Chris Markiewicz <[email protected]>

* Update src/02-common-principles.md

Co-authored-by: Chris Markiewicz <[email protected]>

Co-authored-by: Agah Karakuzu <[email protected]>
  • Loading branch information
@effigies @agahkarakuzu
effigies and agahkarakuzu authored Dec 1, 2020
1 parent 547c11b commit 614b811
Show file tree
Hide file tree
Showing 3 changed files with 70 additions and 0 deletions.
1 change: 1 addition & 0 deletions mkdocs.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ nav:
- MEG systems: 99-appendices/07-meg-systems.md
- Coordinate systems: 99-appendices/08-coordinate-systems.md
- Entities: 99-appendices/09-entities.md
- File collections: 99-appendices/10-file-collections.md
- Changelog: CHANGES.md
- The BIDS Starter Kit:
- GitHub repository: https://github.com/bids-standard/bids-starter-kit
Expand Down
22 changes: 22 additions & 0 deletions src/02-common-principles.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -161,6 +161,28 @@ 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.

### Entity-linked file collections

An entity-linked file collection is a set of files that are related to each other
based on a repetitive acquisition of sequential data
by changing acquisition parameters one (or multiple) at a time
or by being inherent components of the same data.
Entity-linked collections are identified by a common suffix,
indicating the group of files that should be considered a logical unit.
Within each collection, files MUST be distinguished from each other by at least one
entity (for example, `echo`) that corresponds to an altered acquisition parameter
(`EchoTime`) or that defines a component relationship (for example, `part`).
Note that these entities MUST be described by the specification and
the parameter changes they declare MUST NOT invalidate the definition of the accompanying suffix.
For example, the use of the `echo` entity along with the `T1w` suffix casts doubt on
the validity of the identified contrast weighting.
Provided the conditions above are satisfied,
any suffix (such as `bold`) can identify an entity-linked file collection,
although certain suffixes are exclusive for this purpose (for example, `MP2RAGE`).
Use cases concerning this convention are compiled in the
[file collections](./99-appendices/10-file-collections.md) appendix.
This convention is mainly intended for but not limited to MRI modalities.

## Source vs. raw vs. derived data

BIDS was originally designed to describe and apply consistent naming conventions
Expand Down
47 changes: 47 additions & 0 deletions src/99-appendices/10-file-collections.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# Appendix X: File collections

To give context to the use of [entity-linked file collections](../02-common-principles.md#file-name-structure),
applications concerned with this common principle are listed by descriptive tables
under their respective modalities.

Note that the tables in this appendix catalog applications where the use of
a file collection is REQUIRED.

Certain entitites interlink the files in a file collection through a metadata field.
Unlike other common entities (for example `run`), they require an iteration over different
values of the metadata fields they represent.
Please keep the following list of linking entities up-to-date with the file collections
included in this appendix:

* Magnetic Resonance Imaging
* [`echo`](./09-entities.md#echo)
* [`flip`](./09-entities.md#flip)
* [`inv`](./09-entities.md#inv)
* [`mt`](./09-entities.md#mt)
* [`part`](./09-entities.md#part)

## Magnetic Resonance Imaging

### Anatomy imaging data

| Suffix | Linking entities | Application | Description |
|---------|-----------------------|--------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| VFA | flip | Variable flip angle | The VFA method involves at least two spoiled gradient echo (SPGR) of steady-state free precession (SSFP) images acquired at different flip angles. Depending on the provided metadata fields and the sequence type, data may be eligible for DESPOT1, DESPOT2 and their variants ([Deoni et al. 2005](https://onlinelibrary.wiley.com/doi/full/10.1002/mrm.20314)). |
| IRT1 | inv, part | Inversion recovery T1 mapping | The IRT1 method involves multiple inversion recovery spin-echo images acquired at different inversion times ([Barral et al. 2010](https://onlinelibrary.wiley.com/doi/full/10.1002/mrm.22497)). |
| MP2RAGE | flip, inv, echo, part | Magnetization prepared two gradient echoes | The MP2RAGE method is a special protocol that collects several images at different flip angles and inversion times to create a parametric T1map by combining the magnitude and phase images ([Marques et al. 2010](https://www.sciencedirect.com/science/article/pii/S1053811909010738?casa_token=u_CYBx4hi7IAAAAA:3w0cMTyU5jA1BdFs0s5oVcQeqF2tZho0iJ9d4N1kExfaX27v9-JnWacF6mbEp_lMKZ64CvoTl8k) |
| MESE | echo | Multi-echo spin-echo | The MESE method involves multiple spin echo images acquired at different echo times and is primarily used for T2 mapping. Please note that this suffix is not intended for the logical grouping of images acquired using an Echo Planar Imaging (EPI) readout. |
| MEGRE | echo | Multi-echo gradient-echo | Anatomical gradient echo images acquired at different echo times. Please note that this suffix is not intended for the logical grouping of images acquired using an Echo Planar Imaging (EPI) readout. |
| MTR | mt | Magnetization transfer ratio | This method is to calculate a semi-quantitative magnetization transfer ratio map. |
| MTS | flip, mt | Magnetization transfer saturation | This method is to calculate a semi-quantitative magnetization transfer saturation index map. The MTS method involves three sets of anatomical images that differ in terms of application of a magnetization transfer RF pulse (MTon or MToff) and flip angle ([Helms et al. 2008](https://onlinelibrary.wiley.com/doi/full/10.1002/mrm.21732)). |
| MPM | flip, mt, echo, part | Multi-parametric mapping | The MPM approaches (a.k.a hMRI) involves the acquisition of highly-similar anatomical images that differ in terms of application of a magnetization transfer RF pulse (MTon or MToff), flip angle and (optionally) echo time and magnitue/phase parts ([Weiskopf et al. 2013](https://www.frontiersin.org/articles/10.3389/fnins.2013.00095/full)). See [here](https://owncloud.gwdg.de/index.php/s/iv2TOQwGy4FGDDZ) for suggested MPM acquisition protocols. |

### Fieldmap data

| Suffix | Meta-data relevant entity | Application | Description |
|--------|--------------------------------|------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| TB1DAM | flip | Double-angle B1+ mapping | The double-angle B1<sup>+</sup> method ([Insko and Bolinger 1993](https://www.sciencedirect.com/science/article/abs/pii/S1064185883711332)) is based on the calculation of the actual angles from signal ratios, collected by two acquisitions at different nominal excitation flip angles. Common sequence types for this application include spin echo and echo planar imaging. |
| TB1EPI | flip, echo | B1<sup>+</sup> mapping with 3D EPI | This B1<sup>+</sup> mapping method ([Jiru and Klose 2006](https://dx.doi.org/10.1002/mrm.21083)) is based on two EPI readouts to acquire spin echo (SE) and stimulated echo (STE) images at multiple flip angles in one sequence, used in the calculation of deviations from the nominal flip angle. |
| TB1AFI | flip, inv | Actual Flip Angle Imaging (AFI) | This method ([Yarnykh 2007](https://dx.doi.org/10.1002/mrm.21120)) calculates a B1<sup>+</sup> map from two images acquired at interleaved (two) TRs with identical RF pulses using a steady-state sequence |
| TB1TFL | Please see the qMRI appendix | Siemens `tfl_b1_map` | B1<sup>+</sup> data acquired using `tfl_b1_map` product sequence by Siemens based on the method by [Chung et al. (2010)](https://onlinelibrary.wiley.com/doi/full/10.1002/mrm.22423). The sequence generates one ~anatomical image and one scaled flip angle map. |
| TB1RMF | Please see the qMRI appendix | Siemens `rf_map` | B1<sup>+</sup> data acquired using `rf_map` product sequence by Siemens |
| RB1COR | Please see the qMRI appendix | B1<sup>-</sup> field correction | Low resolution images acquired by the body coil (in the gantry of the scanner) and the head coil using identical acquisition parameters to generate a combined sensitivity map as described in [Papp et al. (2016)](https://onlinelibrary.wiley.com/doi/full/10.1002/mrm.26058) |

0 comments on commit 614b811

Please sign in to comment.