diff --git a/.circleci/config.yml b/.circleci/config.yml index c4bfc197ae..81be0c967a 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -37,7 +37,7 @@ jobs: name: check links command: | git status - if (! git log -1 --pretty=%b | grep REL:) ; then + if (! git log -1 --pretty=oneline | grep REL:) ; then chmod a+rX -R ~ linkchecker -t 1 ~/project/site/ # check external separately by pointing to all *html so no diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 711bb91c43..3e347881d3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,7 +25,7 @@ Jump to the following sections: - [Example pull request](#example-pull-request) - [Commenting on a pull request](#commenting-on-a-pull-request) - [Accepting suggestion from a review](#accepting-suggestion-from-a-review) -- [Updating the specification schema](#updating-the-schema) +- [Making a change to the BIDS-schema](#making-a-change-to-the-BIDS-schema) - [Recognizing contributions](#recognizing-contributions) ## Joining the community @@ -575,47 +575,20 @@ reviewer as a co-author. ![BIDS_pr_reviewer_credit](commenting_images/BIDS_pr_reviewer_credit.png "BIDS_pr_reviewer_credit") -## Updating the schema - -Portions of the BIDS specification are defined using YAML files, in order to -make the specification machine-readable. -Currently, the only portion of the specification that relies on this schema is -the Entity Table, but any changes to the specification should be mirrored in the schema. - -### The format of the schema - -The schema reflects the files and objects in the specification, as well as -associations between these objects. -Here is a list of the files and subfolders of the schema, roughly in order of importance: - -- `datatypes/*.yaml`: - Data types supported by the specification. - Each datatype may support many suffixes. - These suffixes are divided into groups based on what extensions and entities are allowed for each. - Data types correspond to subfolders (for example, `anat`, `func`) in the BIDS structure. -- `entities.yaml`: - A list of entities (key/value pairs in folder and filenames) with associated descriptions and formatting rules. - The order of the entities in the file determines the order in which entities must appear in filenames. -- `top_level_files.yaml`: - Modality-agnostic files stored at the top level of a BIDS dataset. - The schema specifies whether these files are required or optional, as well as acceptable extensions for each. -- `modalities.yaml`: - Modalities supported by the specification, along with a list of associated data types. - Modalities are not reflected directly in the BIDS structure, but data types are modality-specific. -- `associated_data.yaml`: - Folders that are commonly contained within the same folder as a BIDS dataset, but which do not follow the BIDS structure internally, such as `code` or `sourcedata`. - The schema specifies which folders are accepted and whether they are required or optional. - -### Making a change to the schema - -#### 1. Ensure that changes to the specification are matched in the schema +## Making a change to the BIDS-schema + +Several aspects of the specification are defined in a set of YAML files in the +`src/schema` folder. The content of those files is described in a dedicated +[README file](./src/schema/README.md). + +### 1. Ensure that changes to the specification are matched in the schema The schema formalizes the rules described in the specification text, so you must ensure that any changes which impact the rules of the specification (including, but not limited to, adding new entities, suffixes, datatypes, modalities) are reflected in the schema as well. -#### 2. Ensure that changes to the schema are matched in auto-generated sections of the specification +### 2. Ensure that changes to the schema are matched in auto-generated sections of the specification The schema is used to generate a number of elements in the specification text, including: - Filename format templates @@ -625,7 +598,7 @@ The schema is used to generate a number of elements in the specification text, i As such, you need to ensure that the functions used throughout the specification to render these elements are appropriately referencing the schema. In essence, please make sure, if your changes do impact how functions should be called, that you also update how the function are called. -#### 3. Render the specification with `mkdocs` to check your changes +### 3. Render the specification with `mkdocs` to check your changes Run `mkdocs serve` and open `localhost:8000` to browse the rendered specification. Make sure that all filename format templates, entity tables, and entity definitions are correct @@ -635,7 +608,7 @@ While the continuous integration run on pull requests by the repository will ren it is crucial to manually review the rendered changes to ensure that the code not only successfully runs, but also that the rendered changes appear as expected. -#### 4. Push your changes +### 4. Push your changes For more information on making general changes with a pull request, please review diff --git a/mkdocs.yml b/mkdocs.yml index 140e23c9a3..1646dee90e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,4 +1,4 @@ -site_name: Brain Imaging Data Structure v1.6.0-dev +site_name: Brain Imaging Data Structure v1.6.1-dev theme: name: material custom_dir: theme_customizations/ @@ -35,6 +35,7 @@ nav: - Physiological and other continuous recordings: 04-modality-specific-files/06-physiological-and-other-continuous-recordings.md - Behavioral experiments (with no neural recordings): 04-modality-specific-files/07-behavioral-experiments.md - Genetic Descriptor: 04-modality-specific-files/08-genetic-descriptor.md + - Positron Emission Tomography: 04-modality-specific-files/09-positron-emission-tomography.md - Derivatives: - BIDS Derivatives: 05-derivatives/01-introduction.md - Common data types and metadata: 05-derivatives/02-common-data-types.md @@ -54,6 +55,7 @@ nav: - File collections: 99-appendices/10-file-collections.md - Quantitative MRI: 99-appendices/11-qmri.md - Arterial Spin Labeling: 99-appendices/12-arterial-spin-labeling.md + - Cross modality correspondence: 99-appendices/13-cross-modality-correspondence.md - Changelog: CHANGES.md - The BIDS Starter Kit: - GitHub repository: https://github.com/bids-standard/bids-starter-kit diff --git a/src/01-introduction.md b/src/01-introduction.md index 5b7e387578..79ce0831d2 100644 --- a/src/01-introduction.md +++ b/src/01-introduction.md @@ -111,6 +111,18 @@ For example: Scientific Data, 5 (180110). [doi:10.1038/sdata.2018.110](https://doi.org/10.1038/sdata.2018.110) +#### PET + +- Knudsen GM, Ganz M, Appelhoff S, Boellaard R, Bormans G, Carson RE, Catana C, + Doudet D, Gee AD, Greve DN, Gunn RN, Halldin C, Herscovitch P, Huang H, Keller SH, + Lammertsma AA, Lanzenberger R, Liow JS, Lohith TG, Lubberink M, Lyoo CH, Mann JJ, + Matheson GJ, Nichols TE, Nørgaard M, Ogden T, Parsey R, Pike VW, Price J, Rizzo G, + Rosa-Neto P, Schain M, Scott PJH, Searle G, Slifstein M, Suhara T, Talbot PS, + Thomas A, Veronese M, Wong DF, Yaqub M, Zanderigo F, Zoghbi S, Innis RB. (2020). + **Guidelines for Content and Format of PET Brain Data in Publications and in Archives: A Consensus Paper**. + Journal of Cerebral Blood Flow and Metabolism, 2020 Aug; 40(8): 1576-1585. + [doi:10.1177/0271678X20905433](https://doi.org/10.1177/0271678X20905433) + #### Genetics - Clara Moreau, Martineau Jean-Louis, Ross Blair, Christopher Markiewicz, Jessica Turner, diff --git a/src/02-common-principles.md b/src/02-common-principles.md index 36452e7818..27b60a2604 100644 --- a/src/02-common-principles.md +++ b/src/02-common-principles.md @@ -28,6 +28,9 @@ misunderstanding we clarify them here. sessions is appropriate when several identical or similar data acquisitions are planned and performed on all -or most- subjects, often in the case of some intervention between sessions (for example, training). + In the [PET](04-modality-specific-files/09-positron-emission-tomography.md) + context, a session may also indicate a group of related scans, + taken in one or more visits. 1. **Data acquisition** - a continuous uninterrupted block of time during which a brain scanning instrument was acquiring data according to particular @@ -73,6 +76,13 @@ misunderstanding we clarify them here. acquisition parameters and task (however events can change from run to run due to different subject response or randomized nature of the stimuli). Run is a synonym of a data acquisition. + Note that "uninterrupted" may look different by modality due to the nature of the + recording. + For example, in [MRI](04-modality-specific-files/01-magnetic-resonance-imaging-data.md) + or [MEG] (04-modality-specific-files/02-magnetoencephalography.md), + if a subject leaves the scanner, the acquisition must be restarted. + For some types of [PET](04-modality-specific-files/09-positron-emission-tomography.md) acquisitions, + a subject may leave and re-enter the scanner without interrupting the scan. 1. **Modality** - the category of brain data recorded by a file. For MRI data, different pulse sequences are considered distinct modalities, @@ -244,7 +254,7 @@ This specification does not prescribe anything about the contents of `sourcedata folders in the above example - nor does it prescribe the `sourcedata`, `derivatives`, or `rawdata` folder names. The above example is just a convention that can be useful for organizing raw, -source, and derived data while maintaining BIDS compliancy of the raw data +source, and derived data while maintaining BIDS compliance of the raw data folder. When using this convention it is RECOMMENDED to set the `SourceDatasets` field in `dataset_description.json` of each subfolder of `derivatives` to: 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 6aef32fb32..ea1d5f08d3 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 @@ -43,27 +43,27 @@ that a given scan was collected with the intended coil elements selected ### Sequence Specifics -| **Key name** | **Requirement level** | **Data type** | **Description** | -| --------------------------- | ---------------------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| PulseSequenceType | RECOMMENDED | [string][] | A general description of the pulse sequence used for the scan (for example, `"MPRAGE"`, `"Gradient Echo EPI"`, `"Spin Echo EPI"`, `"Multiband gradient echo EPI"`). | -| ScanningSequence | RECOMMENDED | [string][] or [array][] of [strings][] | Description of the type of data acquired. Corresponds to DICOM Tag 0018, 0020 `Scanning Sequence`. | -| SequenceVariant | RECOMMENDED | [string][] or [array][] of [strings][] | Variant of the ScanningSequence. Corresponds to DICOM Tag 0018, 0021 `Sequence Variant`. | -| ScanOptions | RECOMMENDED | [string][] or [array][] of [strings][] | Parameters of ScanningSequence. Corresponds to DICOM Tag 0018, 0022 `Scan Options`. | -| SequenceName | RECOMMENDED | [string][] | Manufacturer's designation of the sequence name. Corresponds to DICOM Tag 0018, 0024 `Sequence Name`. | -| 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. | -| SpoilingState | RECOMMENDED | [boolean][] | Boolean stating whether the pulse sequence uses any type of spoiling strategy to suppress residual transverse magnetization. | -| SpoilingType | RECOMMENDED if the SpoilingState is `True`. | [string][] | Specifies which spoiling method(s) are used by a spoiled sequence. Accepted values: `"RF"`, `"GRADIENT"` or `"COMBINED"`. | -| SpoilingRFPhaseIncrement | RECOMMENDED if the SpoilingType is `"RF"` or `"COMBINED"`. | [number][] | The amount of incrementation described in degrees, which is applied to the phase of the excitation pulse at each TR period for achieving RF spoiling. | -| SpoilingGradientMoment | RECOMMENDED if the SpoilingType is `"GRADIENT"` or `"COMBINED"`. | [number][] | Zeroth moment of the spoiler gradient lobe in millitesla times second per meter (mT.s/m). | -| SpoilingGradientDuration | RECOMMENDED if the SpoilingType is `"GRADIENT"` or `"COMBINED"`. | [number][] | The duration of the spoiler gradient lobe in seconds. The duration of a trapezoidal lobe is defined as the summation of ramp-up and plateau times. | +| **Key name** | **Requirement level** | **Data type** | **Description** | +| --------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| PulseSequenceType | RECOMMENDED | [string][] | A general description of the pulse sequence used for the scan (for example, `"MPRAGE"`, `"Gradient Echo EPI"`, `"Spin Echo EPI"`, `"Multiband gradient echo EPI"`). | +| ScanningSequence | RECOMMENDED | [string][] or [array][] of [strings][] | Description of the type of data acquired. Corresponds to DICOM Tag 0018, 0020 `Scanning Sequence`. | +| SequenceVariant | RECOMMENDED | [string][] or [array][] of [strings][] | Variant of the ScanningSequence. Corresponds to DICOM Tag 0018, 0021 `Sequence Variant`. | +| ScanOptions | RECOMMENDED | [string][] or [array][] of [strings][] | Parameters of ScanningSequence. Corresponds to DICOM Tag 0018, 0022 `Scan Options`. | +| SequenceName | RECOMMENDED | [string][] | Manufacturer's designation of the sequence name. Corresponds to DICOM Tag 0018, 0024 `Sequence Name`. | +| 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, but REQUIRED if [PET](./09-positron-emission-tomography.md) data are present | [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. | +| SpoilingState | RECOMMENDED | [boolean][] | Boolean stating whether the pulse sequence uses any type of spoiling strategy to suppress residual transverse magnetization. | +| SpoilingType | RECOMMENDED if the SpoilingState is `True`. | [string][] | Specifies which spoiling method(s) are used by a spoiled sequence. Accepted values: `"RF"`, `"GRADIENT"` or `"COMBINED"`. | +| SpoilingRFPhaseIncrement | RECOMMENDED if the SpoilingType is `"RF"` or `"COMBINED"`. | [number][] | The amount of incrementation described in degrees, which is applied to the phase of the excitation pulse at each TR period for achieving RF spoiling. | +| SpoilingGradientMoment | RECOMMENDED if the SpoilingType is `"GRADIENT"` or `"COMBINED"`. | [number][] | Zeroth moment of the spoiler gradient lobe in millitesla times second per meter (mT.s/m). | +| SpoilingGradientDuration | RECOMMENDED if the SpoilingType is `"GRADIENT"` or `"COMBINED"`. | [number][] | The duration of the spoiler gradient lobe in seconds. The duration of a trapezoidal lobe is defined as the summation of ramp-up and plateau times. | ### In-Plane Spatial Encoding @@ -170,7 +170,7 @@ non-parametric structural MR images include: | Inplane T1 | inplaneT1 | In arbitrary units (arbitrary). T1 weighted structural image matched to a functional (task) image. | | Inplane T2 | inplaneT2 | In arbitrary units (arbitrary). T2 weighted structural image matched to a functional (task) image. | | PD and T2 weighted images | PDT2 | In arbitrary units (arbitrary). PDw and T2w images acquired using a dual echo FSE sequence through view sharing process ([Johnson et al. 1994](https://pubmed.ncbi.nlm.nih.gov/8010268/)). | -| Homogeneous (flat) T1-weighted MP2RAGE image | UNIT1 | In arbitrary units (arbitrary). UNIT1 images are REQUIRED to use this suffix regardless of the method used to generate them. Note that although this image is T1-weighted, regions without MR signal will contain white salt-and-pepper noise that most segmentation algorithms will fail on. Therefore, it is important to dissociate it from from `T1w`. Plase see [`MP2RAGE` specific notes](../99-appendices/11-qmri.md#unit1-images) in the qMRI appendix for further information. | +| Homogeneous (flat) T1-weighted MP2RAGE image | UNIT1 | In arbitrary units (arbitrary). UNIT1 images are REQUIRED to use this suffix regardless of the method used to generate them. Note that although this image is T1-weighted, regions without MR signal will contain white salt-and-pepper noise that most segmentation algorithms will fail on. Therefore, it is important to dissociate it from from `T1w`. Please see [`MP2RAGE` specific notes](../99-appendices/11-qmri.md#unit1-images) in the qMRI appendix for further information. | If the structural images included in the dataset were defaced (to protect identity of participants) one MAY provide the binary mask that was used to @@ -873,7 +873,7 @@ filling the `IntendedFor` field in the corresponding JSON file. | **Key name** | **Requirement level** | **Data type** | **Description** | | ------------ | --------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| IntendedFor | OPTIONAL | [string][] or [array][] of [string][] | Contains one or more filenames with paths relative to the participant subfolder. The path needs to use forward slashes instead of backward slashes. This field is OPTIONAL, and in case the fieldmaps do not correspond to any particular scans, it does not have to be filled. | +| IntendedFor | RECOMMENDED | [string][] or [array][] of [string][] | Contains one or more filenames with paths relative to the participant subfolder. The path needs to use forward slashes instead of backward slashes. This field is OPTIONAL, and in case the fieldmaps do not correspond to any particular scans, it does not have to be filled. | For example: diff --git a/src/04-modality-specific-files/02-magnetoencephalography.md b/src/04-modality-specific-files/02-magnetoencephalography.md index 6c6fe6ea8c..70fb693c67 100644 --- a/src/04-modality-specific-files/02-magnetoencephalography.md +++ b/src/04-modality-specific-files/02-magnetoencephalography.md @@ -47,7 +47,7 @@ remember to list all files separately in `scans.tsv` and that the entries for th `acq_time` column in `scans.tsv` MUST all be identical, as described in [Scans file](../03-modality-agnostic-files.md#scans-file). -Another manufacturer-specific detail pertains to the KIT/Yokogawa/Ricoh sytem, +Another manufacturer-specific detail pertains to the KIT/Yokogawa/Ricoh system, which saves the MEG sensor coil positions in a separate file with two possible filename extensions (`.sqd`, `.mrk`). For these files, the `markers` suffix MUST be used. For example: `sub-01_task-nback_markers.sqd` diff --git a/src/04-modality-specific-files/03-electroencephalography.md b/src/04-modality-specific-files/03-electroencephalography.md index 72f07794fc..4f57ba9eb4 100644 --- a/src/04-modality-specific-files/03-electroencephalography.md +++ b/src/04-modality-specific-files/03-electroencephalography.md @@ -198,7 +198,7 @@ about the channels. Note that electrode positions SHOULD NOT be added to this file, but to [`*_electrodes.tsv`](./03-electroencephalography.md#electrodes-description-_electrodestsv). Furthermore, the entries in `*_electrodes.tsv` and `*_channels.tsv` do not have to match exactly, as for example in the case of recording a single `EOG` channel from a bipolar referencing scheme -of two electrodes, or a data channel originating from an auxilliary, non-electrode device. +of two electrodes, or a data channel originating from an auxiliary, non-electrode device. That is, in most cases `*_electrodes.tsv` will have more entries than `*_channels.tsv`. See the examples for `*_channels.tsv` below, and for `*_electrodes.tsv` in ["Electrodes description"](./03-electroencephalography.md#electrodes-description-_electrodestsv). diff --git a/src/04-modality-specific-files/05-task-events.md b/src/04-modality-specific-files/05-task-events.md index 0e3369b97f..960e8c166d 100644 --- a/src/04-modality-specific-files/05-task-events.md +++ b/src/04-modality-specific-files/05-task-events.md @@ -1,16 +1,28 @@ # Task events +The purpose of this file is to describe timing and other properties of events +recorded during a run. +Events MAY be either stimuli presented to the participant or participant responses. +A single event file MAY include any combination of stimuli and response events. +Events MAY overlap in time. +Please mind that this does not imply that only so called "event related" study designs +are supported (in contrast to "block" designs) - each "block of events" can be +represented by an individual row in the `_events.tsv` file (with a long +duration). + Template: ```Text sub-