Skip to content

Commit ef6f851

Browse files
sappelhoffbids-maintenanceagahkarakuzueffigies
authored
update bep005 with latest master + resolve conflict (#689)
* [DOC] Auto-generate changelog entry for PR #677 * [ENH] BEP001 - New entities: inv & mt (#681) * add entity inv * add mt: * add MT specific metadata * Generate entity.md * Update src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md Co-authored-by: Stefan Appelhoff <[email protected]> * Update src/schema/entities.yaml Co-authored-by: Stefan Appelhoff <[email protected]> * table fix by @sappelhoff * Conditional requirement Co-authored-by: Stefan Appelhoff <[email protected]> * [ENH] BEP001 - Entity-linked file collections (#688) * 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]> * [ENH] BEP001 - RepetitionTimeExcitation and RepetitionTimePreparation (#671) * [ENH] Improve TR definitions - Include RepetitionTimePreparation - Include RepetitionTimeExcitation - Add explanation on the former RepetitionTime field. * Typo * Update src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md Co-authored-by: Chris Markiewicz <[email protected]> * ENH: Allow for variable RTE/P * STY: Update table widths * Update src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md * Update src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md * Change ref to DOI @Remi-Gau * Update src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md Co-authored-by: Chris Markiewicz <[email protected]> * Update src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md Co-authored-by: Chris Markiewicz <[email protected]> Co-authored-by: Chris Markiewicz <[email protected]> Co-authored-by: Chris Markiewicz <[email protected]> * Update config.yml * Update readthedocs.yml Co-authored-by: bids-maintenance <[email protected]> Co-authored-by: Agah <[email protected]> Co-authored-by: Chris Markiewicz <[email protected]> Co-authored-by: Chris Markiewicz <[email protected]>
1 parent 1f7a43f commit ef6f851

File tree

9 files changed

+144
-10
lines changed

9 files changed

+144
-10
lines changed

.circleci/config.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ jobs:
1111
pip install -r requirements.txt
1212
- run:
1313
name: generate docs
14-
command: mkdocs build --clean --verbose
14+
command: mkdocs build --clean --strict --verbose
1515
- persist_to_workspace:
1616
root: .
1717
paths: site

mkdocs.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ nav:
4949
- MEG systems: 99-appendices/07-meg-systems.md
5050
- Coordinate systems: 99-appendices/08-coordinate-systems.md
5151
- Entities: 99-appendices/09-entities.md
52+
- File collections: 99-appendices/10-file-collections.md
5253
- Changelog: CHANGES.md
5354
- The BIDS Starter Kit:
5455
- GitHub repository: https://github.com/bids-standard/bids-starter-kit

readthedocs.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,4 +12,4 @@ python:
1212

1313
mkdocs:
1414
configuration: mkdocs.yml
15-
fail_on_warning: false
15+
fail_on_warning: true

src/02-common-principles.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -161,6 +161,28 @@ A summary of all entities in BIDS and the order in which they MUST be
161161
specified is available in the [entity table](./99-appendices/04-entity-table.md)
162162
in the appendix.
163163

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

166188
BIDS was originally designed to describe and apply consistent naming conventions

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

Lines changed: 17 additions & 8 deletions
Large diffs are not rendered by default.

src/99-appendices/09-entities.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -157,6 +157,32 @@ This entity represents the `FlipAngle` metadata field. Please note that the `<in
157157
denotes the number/index (in the form of a nonnegative integer), not the `FlipAngle`
158158
value which needs to be stored in the field `FlipAngle` of the separate JSON file.
159159

160+
## inv
161+
162+
Full name: Inversion Time
163+
164+
Format: `inv-<index>`
165+
166+
Definition: If files belonging to an entity-linked file collection are acquired at different
167+
inversion times, the `_inv-<index>` key/value pair MUST be used to distinguish
168+
individual files.
169+
This entity represents the `InversionTime` metadata field. Please note that the `<index>`
170+
denotes the number/index (in the form of a nonnegative integer), not the `InversionTime`
171+
value which needs to be stored in the field `InversionTime` of the separate JSON file.
172+
173+
## mt
174+
175+
Full name: Magnetization Transfer
176+
177+
Format: `mt-<label>`
178+
179+
Definition: If files belonging to an entity-linked file collection are acquired at different
180+
magnetization transfer (MT) states, the `_mt-<label>` key/value pair MUST be used to
181+
distinguish individual files.
182+
This entity represents the `MTState` metadata field. Allowed label values for this
183+
entity are `on` and `off`, for images acquired in presence and absence of an MT pulse,
184+
respectively.
185+
160186
## recording
161187

162188
Full name: Recording
Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Appendix X: File collections
2+
3+
To give context to the use of [entity-linked file collections](../02-common-principles.md#file-name-structure),
4+
applications concerned with this common principle are listed by descriptive tables
5+
under their respective modalities.
6+
7+
Note that the tables in this appendix catalog applications where the use of
8+
a file collection is REQUIRED.
9+
10+
Certain entitites interlink the files in a file collection through a metadata field.
11+
Unlike other common entities (for example `run`), they require an iteration over different
12+
values of the metadata fields they represent.
13+
Please keep the following list of linking entities up-to-date with the file collections
14+
included in this appendix:
15+
16+
* Magnetic Resonance Imaging
17+
* [`echo`](./09-entities.md#echo)
18+
* [`flip`](./09-entities.md#flip)
19+
* [`inv`](./09-entities.md#inv)
20+
* [`mt`](./09-entities.md#mt)
21+
* [`part`](./09-entities.md#part)
22+
23+
## Magnetic Resonance Imaging
24+
25+
### Anatomy imaging data
26+
27+
| Suffix | Linking entities | Application | Description |
28+
|---------|-----------------------|--------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
29+
| 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)). |
30+
| 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)). |
31+
| 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) |
32+
| 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. |
33+
| 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. |
34+
| MTR | mt | Magnetization transfer ratio | This method is to calculate a semi-quantitative magnetization transfer ratio map. |
35+
| 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)). |
36+
| 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. |
37+
38+
### Fieldmap data
39+
40+
| Suffix | Meta-data relevant entity | Application | Description |
41+
|--------|--------------------------------|------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
42+
| 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. |
43+
| 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. |
44+
| 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 |
45+
| 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. |
46+
| TB1RMF | Please see the qMRI appendix | Siemens `rf_map` | B1<sup>+</sup> data acquired using `rf_map` product sequence by Siemens |
47+
| 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) |

src/CHANGES.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,22 @@
22

33
## [Unreleased](https://github.com/bids-standard/bids-specification/tree/HEAD)
44

5+
- \[MISC] use RFC 2119 language in legend of the "volume timing" table [#678](https://github.com/bids-standard/bids-specification/pull/678) ([Remi-Gau](https://github.com/Remi-Gau))
6+
- \[FIX] Add OPTIONAL acq entity to channels.tsv, events.tsv to match electrophysiological acquisitions [#677](https://github.com/bids-standard/bids-specification/pull/677) ([sappelhoff](https://github.com/sappelhoff))
7+
- \[MISC] Update all links to use HTTPS whenever possible. [#676](https://github.com/bids-standard/bids-specification/pull/676) ([gllmflndn](https://github.com/gllmflndn))
8+
- \[INFRA] Relax line length limit for linting YAML files [#673](https://github.com/bids-standard/bids-specification/pull/673) ([effigies](https://github.com/effigies))
9+
- \[ENH] BEP001 - New entity: flip [#672](https://github.com/bids-standard/bids-specification/pull/672) ([agahkarakuzu](https://github.com/agahkarakuzu))
510
- \[FIX] Added white space after table [#660](https://github.com/bids-standard/bids-specification/pull/660) ([robertoostenveld](https://github.com/robertoostenveld))
611
- \[MISC] add remi as maintainer [#657](https://github.com/bids-standard/bids-specification/pull/657) ([Remi-Gau](https://github.com/Remi-Gau))
712
- update Contributing with info on how to respond to reviews [#655](https://github.com/bids-standard/bids-specification/pull/655) ([Remi-Gau](https://github.com/Remi-Gau))
813
- \[FIX] add paragraph on MEG specific "markers" suffix in MEG spec [#653](https://github.com/bids-standard/bids-specification/pull/653) ([sappelhoff](https://github.com/sappelhoff))
914
- \[FIX] Rewrite the MRI/fieldmaps subsection for consistency with the rest of specs [#651](https://github.com/bids-standard/bids-specification/pull/651) ([oesteban](https://github.com/oesteban))
1015
- \[FIX] Fixing template string on electrodes for eeg and ieeg. [#650](https://github.com/bids-standard/bids-specification/pull/650) ([adam2392](https://github.com/adam2392))
1116
- ENH: Update genetics-BIDS citation [#646](https://github.com/bids-standard/bids-specification/pull/646) ([effigies](https://github.com/effigies))
17+
- \[SCHEMA] Add derivatives entities to the schema [#645](https://github.com/bids-standard/bids-specification/pull/645) ([tsalo](https://github.com/tsalo))
1218
- \[MISC] add brief note that TSV example in the spec may currently use either tab or space characters [#643](https://github.com/bids-standard/bids-specification/pull/643) ([yarikoptic](https://github.com/yarikoptic))
1319
- \[ENH] Add "multipart DWI" acquisitions and refactor DWI specifications [#624](https://github.com/bids-standard/bids-specification/pull/624) ([oesteban](https://github.com/oesteban))
20+
- \[ENH] Add part entity for complex-valued data [#424](https://github.com/bids-standard/bids-specification/pull/424) ([tsalo](https://github.com/tsalo))
1421

1522
## [v1.4.1](https://github.com/bids-standard/bids-specification/tree/v1.4.1) (2020-10-13)
1623

src/schema/entities.yaml

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,28 @@ flip:
121121
denotes the number/index (in the form of a nonnegative integer), not the `FlipAngle`
122122
value which needs to be stored in the field `FlipAngle` of the separate JSON file.
123123
format: index
124+
inv:
125+
name: Inversion Time
126+
entity: inv
127+
description: |
128+
If files belonging to an entity-linked file collection are acquired at different
129+
inversion times, the `_inv-<index>` key/value pair MUST be used to distinguish
130+
individual files.
131+
This entity represents the `InversionTime` metadata field. Please note that the `<index>`
132+
denotes the number/index (in the form of a nonnegative integer), not the `InversionTime`
133+
value which needs to be stored in the field `InversionTime` of the separate JSON file.
134+
format: index
135+
mt:
136+
name: Magnetization Transfer
137+
entity: mt
138+
description: |
139+
If files belonging to an entity-linked file collection are acquired at different
140+
magnetization transfer (MT) states, the `_mt-<label>` key/value pair MUST be used to
141+
distinguish individual files.
142+
This entity represents the `MTState` metadata field. Allowed label values for this
143+
entity are `on` and `off`, for images acquired in presence and absence of an MT pulse,
144+
respectively.
145+
format: label
124146
recording:
125147
name: Recording
126148
entity: recording

0 commit comments

Comments
 (0)