From ef6f851d989e36ab8d0701a6225ac2b99b3f36a7 Mon Sep 17 00:00:00 2001 From: Stefan Appelhoff Date: Wed, 2 Dec 2020 13:02:15 +0100 Subject: [PATCH] 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 * Update src/schema/entities.yaml Co-authored-by: Stefan Appelhoff * table fix by @sappelhoff * Conditional requirement Co-authored-by: Stefan Appelhoff * [ENH] BEP001 - Entity-linked file collections (#688) * Squashed commit of the following: commit 8e1ac5fe358691f34ca1c2b57b5812d2dc602173 Author: Stefan Appelhoff Date: Fri Nov 27 11:09:24 2020 +0100 fix links and latin commit 27c9b41b1d1cedc38654db39b3fd5e573b8ce660 Author: Stefan Appelhoff Date: Fri Nov 27 10:03:51 2020 +0100 remove latin Co-authored-by: Chris Markiewicz commit 7d87070ecb6eb3636d5b15e304b8e65de2b8c93b Author: Agah Date: Mon Nov 23 08:46:47 2020 -0500 Update src/99-appendices/10-file-collections.md Co-authored-by: Chris Markiewicz commit b137a9e3cd2bce7cfe7853909684267d4689b692 Author: Agah Date: Mon Nov 23 08:45:19 2020 -0500 Update src/02-common-principles.md Co-authored-by: Chris Markiewicz commit d7897b8259213dd1cfb6e1db4ec835116491bfb1 Author: Agah Date: Mon Nov 23 08:44:40 2020 -0500 Update src/02-common-principles.md Co-authored-by: Chris Markiewicz commit 09e9d32b033a076a8eeb8408d5e62798bb3629ed Author: Agah Date: Mon Nov 23 08:44:15 2020 -0500 Commit suggestion Co-authored-by: Chris Markiewicz commit 009a9ab1563020c130553253480ef76467d894c2 Author: Agah Karakuzu Date: Mon Nov 23 08:43:00 2020 -0500 Add file-collecitons appendix to the TOC commit 8f6c4dfbe7f79232cadca72f0fd22b693a238c52 Author: Agah Karakuzu Date: Mon Nov 23 08:41:13 2020 -0500 Address suggestion by @tsalo commit 45210a9d167a7532c1ab8463c62dbbc519969c95 Author: Agah Karakuzu Date: Wed Nov 11 14:32:20 2020 -0500 Wording commit 66ba5a5313d4951c826063de13da2d60363b6edd Author: Agah Karakuzu Date: Wed Nov 11 14:31:40 2020 -0500 RECOMMENDED --> MUST for adding an application def to the appdx commit 5611fac6a365eef07acf36290cbf12f22a1d4751 Author: Agah Karakuzu Date: Wed Nov 11 14:29:21 2020 -0500 Improve the appendix commit 6d3bbeadc464ec4a93f97d96d3cffdad8f920f29 Author: Agah Karakuzu Date: Mon Nov 2 16:12:04 2020 -0500 Address suggestions by @tsalo commit bcb02232ca769f14a11eb8b056bb963591901012 Author: Agah Karakuzu Date: Tue Oct 27 21:37:26 2020 -0400 [ADD] Link to the appendix commit 44e760f69163eb11bec74be58279bd260aad963c Author: Agah Karakuzu Date: Tue Oct 27 21:28:38 2020 -0400 [ADD] Appendix - File collections - For parametrically linked file collections commit 523b1c163df4b5a1d46f25156d1b0ea0d06ac7bb Author: Agah Karakuzu 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 * Update src/02-common-principles.md Co-authored-by: Chris Markiewicz * Update src/02-common-principles.md Co-authored-by: Chris Markiewicz * Update src/99-appendices/10-file-collections.md Co-authored-by: Chris Markiewicz * Update src/02-common-principles.md Thank you @effigies! Co-authored-by: Chris Markiewicz * Update src/02-common-principles.md Co-authored-by: Chris Markiewicz Co-authored-by: Agah Karakuzu * [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 * 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 * Update src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md Co-authored-by: Chris Markiewicz Co-authored-by: Chris Markiewicz Co-authored-by: Chris Markiewicz * Update config.yml * Update readthedocs.yml Co-authored-by: bids-maintenance Co-authored-by: Agah Co-authored-by: Chris Markiewicz Co-authored-by: Chris Markiewicz --- .circleci/config.yml | 2 +- mkdocs.yml | 1 + readthedocs.yml | 2 +- src/02-common-principles.md | 22 +++++++++ .../01-magnetic-resonance-imaging-data.md | 25 ++++++---- src/99-appendices/09-entities.md | 26 ++++++++++ src/99-appendices/10-file-collections.md | 47 +++++++++++++++++++ src/CHANGES.md | 7 +++ src/schema/entities.yaml | 22 +++++++++ 9 files changed, 144 insertions(+), 10 deletions(-) create mode 100644 src/99-appendices/10-file-collections.md diff --git a/.circleci/config.yml b/.circleci/config.yml index d8dd1461db..fd98fb122b 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -11,7 +11,7 @@ jobs: pip install -r requirements.txt - run: name: generate docs - command: mkdocs build --clean --verbose + command: mkdocs build --clean --strict --verbose - persist_to_workspace: root: . paths: site diff --git a/mkdocs.yml b/mkdocs.yml index 65466633d6..4fce5fb957 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -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 diff --git a/readthedocs.yml b/readthedocs.yml index e8e8f765c7..f8ded24aa3 100644 --- a/readthedocs.yml +++ b/readthedocs.yml @@ -12,4 +12,4 @@ python: mkdocs: configuration: mkdocs.yml - fail_on_warning: false + fail_on_warning: true diff --git a/src/02-common-principles.md b/src/02-common-principles.md index f090efd094..1eadbe98e1 100644 --- a/src/02-common-principles.md +++ b/src/02-common-principles.md @@ -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 diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md index 8dfabe3c81..1932ca90ef 100644 --- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md +++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md @@ -53,6 +53,13 @@ that a given scan was collected with the intended coil elements selected | PulseSequenceDetails | RECOMMENDED | [string][] | Information beyond pulse sequence type that identifies the specific pulse sequence used (for example, "Standard Siemens Sequence distributed with the VB17 software," "Siemens WIP ### version #.##," or "Sequence written by X using a version compiled on MM/DD/YYYY"). | | NonlinearGradientCorrection | RECOMMENDED | [boolean][] | Boolean stating if the image saved has been corrected for gradient nonlinearities by the scanner sequence. | | MRAcquisitionType | RECOMMENDED, but REQUIRED for Arterial Spin Labeling | [string][] | Possible values: `2D` or `3D`. Type of sequence readout. Corresponds to DICOM Tag 0018,0023 `MR Acquisition Type`. | +| MTState | RECOMMENDED | [boolean][] | Boolean stating whether the magnetization transfer pulse is applied. Corresponds to DICOM tag (0018, 9020) `Magnetization Transfer`. | +| MTOffsetFrequency | RECOMMENDED if the MTstate is `True`. | [number][] | The frequency offset of the magnetization transfer pulse with respect to the central H1 Larmor frequency in Hertz (Hz). | +| MTPulseBandwidth | RECOMMENDED if the MTstate is `True`. | [number][] | The excitation bandwidth of the magnetization transfer pulse in Hertz (Hz). | +| MTNumberOfPulses | RECOMMENDED if the MTstate is `True`. | [number][] | The number of magnetization transfer RF pulses applied before the readout. | +| MTPulseShape | RECOMMENDED if the MTstate is `True`. | [string][] | Shape of the magnetization transfer RF pulse waveform. Accepted values: `HARD`, `GAUSSIAN`, `GAUSSHANN` (gaussian pulse with Hanning window), `SINC`, `SINCHANN` (sinc pulse with Hanning window), `SINCGAUSS` (sinc pulse with Gaussian window), `FERMI`. | +| MTPulseDuration | RECOMMENDED if the MTstate is `True`. | [number][] | Duration of the magnetization transfer RF pulse in seconds. | + ### In-Plane Spatial Encoding | **Key name** | **Requirement level** | **Data type** | **Description** | @@ -192,9 +199,11 @@ JSON file. See [Common metadata fields](#common-metadata-fields) for a list of terms and their definitions. There are also some OPTIONAL JSON fields specific to anatomical scans: -| **Key name** | **Requirement level** | **Data type** | **Description** | -| ----------------------- | --------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -| ContrastBolusIngredient | OPTIONAL | [string][] | Active ingredient of agent. Values MUST be one of: IODINE, GADOLINIUM, CARBON DIOXIDE, BARIUM, XENON Corresponds to DICOM Tag 0018,1048. | +| **Key name** | **Requirement level** | **Data type** | **Description** | +| ----------------------- | --------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| ContrastBolusIngredient | OPTIONAL | [string][] | Active ingredient of agent. Values MUST be one of: IODINE, GADOLINIUM, CARBON DIOXIDE, BARIUM, XENON Corresponds to DICOM Tag 0018,1048. | +| RepetitionTimeExcitation | OPTIONAL | [number][] | The interval, in seconds, between two successive excitations. The DICOM tag that best refers to this parameter is [(0018, 0080)](http://dicomlookup.com/lookup.asp?sw=Tnumber&q=(0018,0080)). This field may be used together with the `RepetitionTimePreparation` for certain use cases, such as [MP2RAGE](https://doi.org/10.1016/j.neuroimage.2009.10.002). Use `RepetitionTimeExcitation` (in combination with `RepetitionTimePreparation` if needed) for anatomy imaging data rather than `RepetitionTime` as it is already defined as the amount of time that it takes to acquire a single volume in the [task imaging data](#task-including-resting-state-imaging-data) section. | +| RepetitionTimePreparation | OPTIONAL | [number][] or [array][] of [numbers][] | The interval, in seconds, that it takes a preparation pulse block to re-appear at the beginning of the succeeding (essentially identical) pulse sequence block. The data type number may apply to files from any MRI modality concerned with a single value for this field. The data type array provides a value for each volume in a 4D dataset and should only be used when the volume timing is critical for interpretation of the data, such as in [ASL](#arterial-spin-labeling-perfusion-data). | The [`part-