diff --git a/docs/getting_started/folders_and_files/derivatives.md b/docs/getting_started/folders_and_files/derivatives.md index abef2874..74c7a01c 100644 --- a/docs/getting_started/folders_and_files/derivatives.md +++ b/docs/getting_started/folders_and_files/derivatives.md @@ -171,49 +171,61 @@ BIDS Derivatives datasets are intended to be interpretable and distributable with or without the datasets used to generate them. This is necessary for storage and bandwidth constraints, as well as to permit the distribution of derivatives when the source data are restricted. +Similarly, BIDS Raw datasets should be interpretable and distributable without +all possible derivatives produced from them. This independence affords flexibility in the relative organization of datasets. -The following examples show three ways to organize, relative to each other, -a raw BIDS dataset, a preprocessed derivative dataset, and an analysis that uses both as inputs. +The following examples show three ways to organize: -A collection of derivative datasets may be stored in the `derivatives/` subdirectory -of a BIDS (or BIDS Derivatives) dataset: +The following examples show three ways to organize: -```bash -my_dataset/ - derivatives/ - preprocessed/ - analysis/ - sub-01/ - ... -``` +#### 1. BIDS Raw with derivatives/ -A BIDS Derivatives dataset may contain references to its input datasets -in the `sourcedata/` subdirectory: +A collection of derivative datasets may be stored in the `derivatives/` subdirectory. Disadvantage is that such organization would complicate distribution of the raw BIDS dataset +by itself as it would require explicit exclusion of datasets within its `derivatives/` folder. + +#### 2. BIDS Derivative with sourcedata/raw + +A BIDS Derivative dataset may contain references to its input datasets +(could be BIDS Raw, non-BIDS or even other BIDS Derivatives) in the `sourcedata/` subdirectory: ```bash my_analysis/ - sourcedata/ - raw/ - preprocessed/ - sub-01/ - ... +sourcedata/ +raw/ + sub-01/ + ... + dataset_description.json +preprocessed/ +sub-01/ +... + dataset_description.json ``` Note that the `sourcedata/` and `derivatives/` subdirectories constitute dataset boundaries. -Any contents of these directories may be validated independently, -but their contents must not affect the interpretation of the nested or containing datasets. +Any subfolders of these directories may be validated independently, if they are BIDS datasets +which would be indicated by presence of `dataset_description.json` file(s) in them with a +REQUIRED `"BIDSVersion"` key. +It is important to note that their contents must not affect the interpretation of the nested +or containing datasets. + +One potential disadvantage to nesting a BIDS Derivative dataset inside a BIDS Raw dataset, or vice versa, +is that packaging them for independent sharing or publication can become more complicated. + +#### 3. BIDS Study with sourcedata/raw and derivatives/ -Unnested datasets are also possible. For example: +It is also possible to completely avoid nesting of BIDS Raw datasets into BIDS Derivative datasets (or vice versa), +by simply placing them in separate folders, namely `sourcedata/` and `derivatives/` at root level: ```bash my_study/ - raw_data/ - sub-01/ - ... - derivatives/ - preprocessed/ - analysis/ + sourcedata/ + raw/ + sub-01/ + ... +derivatives/ +preprocessed/ +analysis/ ```