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

* Add the notion that example layout can in fact be a valid BIDS dataset

This reverts commit a3c12f8 where I have tried
to introduce it in
#1741 but it required a
little more of further detailing.

* Move and extend description and definition of DatasetType "project"

* Add rule to ensure that "project" DatasetType has no subject folders

Idea from @effigies while discussing this PR at BIDS Maintainers meeting 2025

* Make NoSubjectFolders into a "warning" from "error" to have aligned with SubjectFolders check

Also adjusted wording to be aligned too

* Rename "project" to "study"

While discussing with @jbpoline we wondered, if may be `study` would be a better descriptor to use here in favor of `project`.  One of the rationales, is that e.g. in [BEP035](https://bids.neuroimaging.io/extensions/beps/bep_035.html) (attn @bids-standard/bep035) on Mega-analysis they introduce `study-` entity as a groupping element.  It kinda then would match natively.

we also  mention "study" in various places in BIDS which seems to align nicely here

```shell
❯ git grep study
src/CHANGES.md:-   \[FIX] update physio bids name in longitudinal study page examples [#863](#863) ([Remi-Gau](https://github.com/Remi-Gau))
src/appendices/coordinate-systems.md:The following template identifiers are RECOMMENDED for individual- and study-specific reference
src/appendices/coordinate-systems.md:In the case of multiple study templates, additional names may need to be defined.
src/appendices/coordinate-systems.md:| study                 | Custom space defined using a group/study-specific template. This coordinate system requires specifying an additional file to be fully defined.                                                                                                                         |
src/appendices/hed.md:numerical values that are similar across the recordings in the study.
src/appendices/hed.md:repository on GitHub should be used to validate the study event annotations.
src/common-principles.md:    unless when appropriate given the study goals, for example, when scanning babies.
src/introduction.md:> The data used in the study were organized using the
src/modality-specific-files/genetic-descriptor.md:     "Dataset": "https://www.ncbi.nlm.nih.gov/projects/gap/cgi-bin/study.cgi?study_id=phs001364.v1.p1",
src/modality-specific-files/intracranial-electroencephalography.md:Note that the date and time information SHOULD be stored in the study key file
src/modality-specific-files/magnetic-resonance-spectroscopy.md:acquisition parameters in filenames is helpful or necessary to distinguish datasets in a given study.
src/modality-specific-files/motion.md:Note that the onsets of the recordings SHOULD be stored in the study key file [(`scans.tsv`)](../modality-agnostic-files.md#scans-file).
src/modality-specific-files/positron-emission-tomography.md:This entity is OPTIONAL if only one tracer is used in the study,
src/modality-specific-files/task-events.md:Please mind that this does not imply that only so called "event related" study designs
src/schema/objects/common_principles.yaml:    A set of neuroimaging and behavioral data acquired for a purpose of a particular study.
src/schema/objects/common_principles.yaml:    Session can (but doesn't have to) be synonymous to a visit in a longitudinal study.
src/schema/objects/common_principles.yaml:    A person or animal participating in the study.
src/schema/objects/entities.yaml:    For example, this should be used when a study includes two T1w images -
src/schema/objects/entities.yaml:    Session can (but doesn't have to) be synonymous to a visit in a longitudinal study.
src/schema/objects/entities.yaml:    A person or animal participating in the study.
src/schema/objects/enums.yaml:study:
src/schema/objects/enums.yaml:  value: study
src/schema/objects/enums.yaml:  display_name: study
src/schema/objects/enums.yaml:    Custom space defined using a group/study-specific template.
src/schema/objects/metadata.yaml:    Reference to the study/studies on which the implementation is based.
src/schema/objects/metadata.yaml:    The version of the HED schema used to validate HED tags for study.
tools/schemacode/src/bidsschematools/tests/data/broken_dataset_description.json:"EthicsApprovals": ["The original study from which this BIDS example dataset was derived was approved by the Ethics committee of Ghent University Hospital with identifier EC 2017/1103."]

```

and "project" mentionings are not particularly  aligned.  So, I think, we should just make it a "study", hence renaming accordingly.

* Update src/schema/objects/metadata.yaml

* Remove divergence: do alert about absent subjects in any "non-study" dataset

Well, any BIDS dataset is a "study" dataset, but there the point is that ATM for both
"raw" and "derivative" types we expect to have sub- folders and that was the prior
behavior, which should not be affected by this PR.

This should address the review comment of @effigies
https://github.com/bids-standard/bids-specification/pull/1972/files#r2142639988

* Clarify description of "study BIDS dataset"

Co-authored-by: Kabilar Gunalan <[email protected]>

---------

Co-authored-by: Chris Markiewicz <[email protected]>
Co-authored-by: Kabilar Gunalan <[email protected]>
Co-authored-by: Julia-Katharina Pfarr <[email protected]>

Author: 4 people

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,20 @@ 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 to organize the data for the entire study (original source data, raw BIDS,
+    derivatives) as a valid BIDS dataset.
 scanner:
   value: scanner
   display_name: scanner

src/schema/objects/metadata.yaml

@@ -582,6 +582,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: