[ENH] Add "study" DatasetType to organize a collection of source and derivative datasets

src/common-principles.md

@@ -275,49 +275,6 @@ However, in the case that these data are to be included:
     We RECOMMEND including the PDF print-out with the actual sequence
     parameters generated by the scanner in the `sourcedata`  directory.
 
-Alternatively one can organize their data in the following way
-
-<!-- This block generates a file tree.
-A guide for using macros can be found at
- https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
--->
-{{ MACROS___make_filetree_example(
-    {
-    "my_project-1": {
-        "sourcedata": {
-            "dicoms": {},
-            "raw": {
-                "sub-01": {},
-                "sub-02": {},
-                "...": "",
-                "dataset_description.json": "",
-				"...": "",
-            },
-            "..." : "",
-        },
-        "derivatives": {
-            "pipeline_1": {},
-            "pipeline_2": {},
-            "...": "",
-        }
-    }
-   }
-) }}
-
-In this example, `sourcedata/dicoms` is not nested inside
-`sourcedata/raw`, **and only the `sourcedata/raw` subdirectory** is a BIDS-compliant dataset among `sourcedata/` subfolders.
-The subdirectories of `derivatives` MAY be BIDS-compliant derivatives datasets
-(see [Non-compliant derivatives](#non-compliant-derivatives) for further discussion).
-The above example is just a convention useful for organizing source, raw BIDS, and derived BIDS data while maintaining BIDS compliance of the raw data directory.
-When using this convention it is RECOMMENDED to set the `SourceDatasets`
-field in `dataset_description.json` of each subdirectory of `derivatives` to:
-
-```JSON
-{
-  "SourceDatasets": [ {"URL": "../../sourcedata/raw/"} ]
-}
-```
-
 !!! danger "Caution"
 
     Sharing source data may help amend errors and missing data discovered
@@ -443,6 +400,53 @@ In particular, if a BIDS dataset contains a `derivatives/` subdirectory,
 the contents of that directory may be a heterogeneous mix of BIDS Derivatives
 datasets and non-compliant derivatives.
 
+## Study dataset
+
+BIDS allows one to organize the data for the entire study (original source data, raw BIDS, derivatives) as a valid BIDS dataset in the following way
+
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filetree_example(
+    {
+    "study-1": {
+        "sourcedata": {
+            "dicoms": {},
+            "raw": {
+                "sub-01": {},
+                "sub-02": {},
+                "...": "",
+                "dataset_description.json": "",
+				"...": "",
+            },
+            "..." : "",
+        },
+        "derivatives": {
+            "pipeline_1": {},
+            "pipeline_2": {},
+            "...": "",
+        },
+        "dataset_description.json": "",
+        "...": "",
+    }
+   }
+) }}
+
+In this example, `sourcedata/dicoms` is not nested inside
+`sourcedata/raw`, **and only the `sourcedata/raw` subdirectory** is a BIDS-compliant dataset among `sourcedata/` subfolders.
+The subdirectories of `derivatives` MAY be BIDS-compliant derivatives datasets
+(see [Non-compliant derivatives](#non-compliant-derivatives) for further discussion).
+The above example is a fully compliant BIDS dataset, providing a convention useful for organizing source, raw BIDS, and derived BIDS data while maintaining overall BIDS compliance.
+When using this convention, `dataset_description.json` MUST have `DatasetType` to be set to `"study"`.  It is also RECOMMENDED to set the `SourceDatasets`
+field in `dataset_description.json` of each subdirectory of `derivatives` to:
+
+```JSON
+{
+  "SourceDatasets": [ {"URL": "../../sourcedata/raw/"} ]
+}
+```
+
 ## File format specification
 
 ### Imaging files

src/schema/objects/enums.yaml

@@ -360,14 +360,19 @@ individual:
     In context of surfaces this space has been referred to as `fsnative`.
 
     In order for this space to be interpretable, `SpatialReference` metadata MUST be provided.
-study:
+study__space:
   value: study
   display_name: study
   description: |
     Custom space defined using a group/study-specific template.
     This coordinate system requires specifying an additional file to be fully defined.
 
     In order for this space to be interpretable, `SpatialReference` metadata MUST be provided.
+study__datasettype:
+  value: study
+  display_name: study
+  description: |
+    A study BIDS dataset.
 scanner:
   value: scanner
   display_name: scanner

src/schema/objects/metadata.yaml

@@ -583,6 +583,7 @@ DatasetType:
   enum:
     - $ref: objects.enums.raw.value
     - $ref: objects.enums.derivative.value
+    - $ref: objects.enums.study__datasettype.value
 DecayCorrectionFactor:
   name: DecayCorrectionFactor
   display_name: Decay Correction Factor

src/schema/rules/checks/dataset.yaml

@@ -6,13 +6,26 @@ SubjectFolders:
   issue:
     code: SUBJECT_FOLDERS
     message: |
-      There are no subject directories (labeled "sub-*") in the root of this dataset.
+      There are no subject directories (labeled "sub-*") in the root of this BIDS dataset.
     level: warning
   selectors:
     - path == '/dataset_description.json'
+    - dataset.dataset_description.DatasetType != "study"
   checks:
     - length(dataset.subjects.sub_dirs) > 0
 
+NoSubjectFolders:
+  issue:
+    code: NOSUBJECT_FOLDERS
+    message: |
+      There should be no subject directories (labeled "sub-*") in the root of this study BIDS dataset.
+    level: warning
+  selectors:
+    - path == '/dataset_description.json'
+    - dataset.dataset_description.DatasetType == "study"
+  checks:
+    - length(dataset.subjects.sub_dirs) == 0
+
 # 49
 ParticipantIDMismatch:
   issue: