bids-standard · sappelhoff · Jun 10, 2020 · Dec 16, 2018 · Dec 16, 2018 · Dec 16, 2018
diff --git a/CODEOWNERS b/CODEOWNERS
@@ -13,4 +13,8 @@
 /src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md @chrisgorgo
 /src/04-modality-specific-files/03-electroencephalography.md @sappelhoff @ezemikulan
 /src/04-modality-specific-files/04-intracranial-electroencephalography.md @ezemikulan
+/src/05-derivatives/03-imaging.md @effigies
+/src/05-derivatives/04-structural-derivatives.md @edickie @ahoopes
+/src/05-derivatives/05-functional-derivatives.md @effigies
+/src/05-derivatives/06-diffusion-derivatives.md @francopestilli @oesteban
 /src/99-appendices/06-meg-file-formats.md @monkeyman192
diff --git a/Pipfile b/Pipfile
@@ -6,6 +6,7 @@ name = "pypi"
 [packages]
 mkdocs = "==1.0.4"
 mkdocs-material = "==4.1.2"
+pymdown-extensions = "==6.0.0"
 
 [dev-packages]
 

diff --git a/Pipfile.lock b/Pipfile.lock
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -9,6 +9,7 @@ extra_javascript:
 markdown_extensions:
     - toc:
         anchorlink: true
+    - pymdownx.superfences
 plugins:
     - search
 docs_dir: 'src'
@@ -26,8 +27,12 @@ nav:
         - Task events: 04-modality-specific-files/05-task-events.md
         - Physiological and other continuous recordings: 04-modality-specific-files/06-physiological-and-other-continuous-recordings.md
         - Behavioral experiments (with no MRI): 04-modality-specific-files/07-behavioral-experiments.md
-      - Longitudinal and multi-site studies: 05-longitudinal-and-multi-site-studies.md
-      - Extending the BIDS specification: 06-extensions.md
+      - Derivatives:
+        - Introduction: 05-derivatives/01-introduction.md
+        - Common data types: 05-derivatives/02-common-data-types.md
+        - Imaging data types: 05-derivatives/03-imaging.md
+      - Longitudinal and multi-site studies: 06-longitudinal-and-multi-site-studies.md
+      - Extending the BIDS specification: 07-extensions.md
       - Appendix:
         - Contributors: 99-appendices/01-contributors.md
         - Licenses: 99-appendices/02-licenses.md

diff --git a/src/01-introduction.md b/src/01-introduction.md
@@ -47,8 +47,7 @@ different backgrounds.
 The BIDS specification can be extended in a backwards compatible way and will
 evolve over time. This is accomplished through community-driven BIDS Extension
 Proposals (BEPs). For more information about the BEP process, and list of
-current BEP proposals, see
-[Extending the BIDS specification](06-extensions.md).
+current BEP proposals, see [Extending the BIDS specification](07-extensions.md).
 
 ## Citing BIDS
 

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
@@ -102,39 +102,32 @@ in the appendix.
 
 ## Source vs. raw vs. derived data
 
-BIDS in its current form is designed to harmonize and describe raw (unprocessed
+BIDS originally was designed to harmonize and describe raw (unprocessed
 or minimally processed due to file format conversion) data. During analysis such
 data will be transformed and partial as well as final results will be saved.
 Derivatives of the raw data (other than products of DICOM to NIfTI conversion)
 MUST be kept separate from the raw data. This way one can protect the raw data
 from accidental changes by file permissions. In addition it is easy to
-distinguish partial results from the raw data and share the latter. Similar
-rules apply to source data which is defined as data before harmonization and/or
-file format conversion (for example E-Prime event logs or DICOM files).
-
-This specification currently does not go into details of recommending a
-particular naming scheme for including different types of source data (raw event
-logs, parameter files, etc. before conversion to BIDS) and data derivatives
-(correlation maps, brain masks, contrasts maps, etc.). However, in the case that
-these data are to be included:
-
-1.  These data MUST be kept in separate `sourcedata` and `derivatives` folders
-    each with a similar folder structure as presented below for the BIDS-managed
-    data. For example:
-    `derivatives/fmriprep/sub-01/ses-pre/sub-01_ses-pre_mask.nii.gz` or
+distinguish partial results from the raw data and share the latter. You can read
+more about organizing derivatives [here](05-derivatives/01-introduction.md).
+
+Similar rules apply to source data which is defined as data before 
+harmonization and/or file format conversion (for example E-Prime event logs or 
+DICOM files). This specification currently does not go into details of 
+recommending a particular naming scheme for including different types of 
+source data (raw event logs, parameter files, etc. before conversion to BIDS). 
+However, in the case that these data are to be included:
+
+1.  These data MUST be kept in separate `sourcedata` folder with a similar 
+    folder structure as presented below for the BIDS-managed data. For example:
     `sourcedata/sub-01/ses-pre/func/sub-01_ses-pre_task-rest_bold.dicom.tgz` or
     `sourcedata/sub-01/ses-pre/func/MyEvent.sce`.
 
-1.  A README file SHOULD be found at the root of the `sourcedata` or the
-    `derivatives` folder (or both). This file should describe the nature of the
-    raw data or the derived data. In the case of the existence of a
-    `derivatives` folder, we RECOMMEND including details about the software
-    stack and settings used to generate the results. Inclusion of non-imaging
-    objects that improve reproducibility are encouraged (scripts, settings
-    files, etc.).
-
-1.  We RECOMMEND including the PDF print-out with the actual sequence parameters
-    generated by the scanner in the `sourcedata` folder.
+1.  A README file SHOULD be found at the root of the `sourcedata` folder or the
+    `derivatives` folder, or both.
+    This file should describe the nature of the raw data or the derived data.
+    We RECOMMEND including the PDF print-out with  the actual sequence
+    parameters generated by the scanner in the `sourcedata`  folder.
 
 Alternatively one can organize their data in the following way
 
@@ -149,15 +142,32 @@ my_dataset/
     sub-02/
     ...
   derivatives/
+    pipeline_1/
+    pipeline_2/
     ...
 ```
 
-In this example **only the `rawdata` subfolder needs to be BIDS compliant**
-dataset. This specification does not prescribe anything about the contents of
-`sourcedata` and `derivatives` 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 folder.
+In this example, where `sourcedata` and `derivatives` are not nested inside
+`rawdata`, **only the `rawdata` subfolder** needs to be a BIDS-compliant
+dataset.
+The subfolders of `derivatives` MAY be BIDS-compliant derivatives datasets
+(see [Non-compliant datasets][non-compliant-datasets] for further discussion).
+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 
+folder. When using this convention it is RECOMMENDED to set the `SourceDatasets`
+field in `dataset_description.json` of each subfolder of `derivatives` to:
+
+```JSON
+{
+  "SourceDatasets": [ {"URL": "file://../../rawdata/"} ]
+}
+```
+
+See [Derived dataset and pipeline description](05-derivatives/01-introduction.md#derived-dataset-and-pipeline-description)
+for more information.
 
 ## The Inheritance Principle
 
@@ -456,3 +466,5 @@ meaning of file names and setting requirements on their contents or metadata.
 Validation and parsing tools MAY treat the presence of non-standard files and
 directories as an error, so consult the details of these tools for mechanisms
 to suppress warnings or provide interpretations of your file names.
+
+[non-compliant-datasets]: 05-derivatives/01-introduction.md#non-compliant-datasets
diff --git a/src/04-modality-specific-files/02-magnetoencephalography.md b/src/04-modality-specific-files/02-magnetoencephalography.md
@@ -1,6 +1,6 @@
 # Magnetoencephalography (MEG)
 
-Support for MEG was developed as a [BIDS Extension Proposal](../06-extensions.md#bids-extension-proposals).
+Support for MEG was developed as a [BIDS Extension Proposal](../07-extensions.md#bids-extension-proposals).
 Please cite the following paper when referring to this part of the standard in
 context of the academic literature:
 

diff --git a/src/04-modality-specific-files/03-electroencephalography.md b/src/04-modality-specific-files/03-electroencephalography.md
@@ -1,6 +1,6 @@
 # Electroencephalography (EEG)
 
-Support for EEG was developed as a [BIDS Extension Proposal](../06-extensions.md#bids-extension-proposals).
+Support for EEG was developed as a [BIDS Extension Proposal](../07-extensions.md#bids-extension-proposals).
 Please cite the following paper when referring to this part of the standard in
 context of the academic literature:
 

diff --git a/src/04-modality-specific-files/04-intracranial-electroencephalography.md b/src/04-modality-specific-files/04-intracranial-electroencephalography.md
@@ -1,6 +1,6 @@
 # intracranial Electroencephalography (iEEG)
 
-Support for iEEG was developed as a [BIDS Extension Proposal](../06-extensions.md#bids-extension-proposals).
+Support for iEEG was developed as a [BIDS Extension Proposal](../07-extensions.md#bids-extension-proposals).
 Please cite the following paper when referring to this part of the standard in
 context of the academic literature: