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-