Minimal example for study dataset

Author: bclenet

src/modality-agnostic-files/provenance.md

@@ -71,7 +71,7 @@ For the most part, this metadata consists of **provenance records** of 4 types:
 
 Provenance records are described as JSON objects in BIDS. They are stored inside **provenance files** (see [Provenance files](#provenance-files)).
 
-Additionally, provenance metadata of entities can be stored inside:
+Additionally, **provenance metadata** of entities can be stored as regular BIDS metadata inside:
 
 -   sidecar JSON files (see [Provenance of a BIDS file](#provenance-of-a-bids-file));
 -   `dataset_description.json` files (see [Provenance of a BIDS dataset](#provenance-of-a-bids-dataset)).
@@ -476,9 +476,11 @@ The uniqueness of this identifier MUST be used to distinguish any activity, soft
     - `bids::prov#fedora-uldfv058` - a Fedora based environment described inside the current dataset.
     - `bids:preprocessing:prov#fmriprep-r4kzzMt8` - the fMRIPrep software described inside the `preprocessing` dataset.
 
-## Minimal example
+## Minimal examples
 
-Here is a comprehensive example that considers the following dataset:
+### Provenance of a BIDS raw dataset
+
+Consider the following BIDS raw dataset:
 
 <!-- This block generates a file tree.
 A guide for using macros can be found at
@@ -504,7 +506,7 @@ A guide for using macros can be found at
     }
 ) }}
 
-The following provenance record is defined in `prov/prov-dcm2niix_soft.json`. As mentioned in the [Consistency and uniqueness of Ids](#consistency-and-uniqueness-of-ids) section, its identifier SHOULD start with `bids:<dataset>:prov#` (here, `bids::` refers to the current dataset).
+Here are the contents of the `prov/prov-dcm2niix_soft.json` file:
 
 ```JSON
 {
@@ -518,7 +520,9 @@ The following provenance record is defined in `prov/prov-dcm2niix_soft.json`. As
 }
 ```
 
-The previously described software record is referred to in the `prov/prov-dcm2niix_act.json` file:
+A software package is described using a provenance record inside the `Software` array. As mentioned in the [Consistency and uniqueness of identifiers](#consistency-and-uniqueness-of-identifiers) section, its identifier SHOULD start with `bids:<dataset>:prov#` (here, `bids::` refers to the current dataset).
+
+Here are the contents of the `prov/prov-dcm2niix_act.json` file:
 
 ```JSON
 {
@@ -533,10 +537,96 @@ The previously described software record is referred to in the `prov/prov-dcm2ni
 }
 ```
 
-The previously described activity record is referred to in the `sub-001/anat/sub-001_T1w.json` sidecar JSON file:
+An activity is described using a provenance record inside the `Activities` array. Note that the identifier of the previously described software package is used here to describe that the software package was associated with this activity.
+
+Here are the contents of the `sub-001/anat/sub-001_T1w.json` file:
 
 ```JSON
 {
     "GeneratedBy": "bids::prov#conversion-00f3a18f"
 }
 ```
+
+The provenance metadata `GeneratedBy` indicates that the `sub-001/anat/sub-001_T1w.nii.gz` file was generated by the previously described activity.
+
+### Provenance of a BIDS study dataset
+
+Consider the following BIDS study dataset:
+
+<!-- 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": {
+            "raw": {
+                "sub-01": {},
+                "sub-02": {},
+                "...": ""
+            }
+        },
+        "derivatives": {
+            "fmriprep": {}
+        },
+        "prov": {
+            "prov-fmriprep_act.json": "",
+            "prov-fmriprep_ent.json": ""
+        },
+        "dataset_description.json": "",
+        "...": ""
+    }
+   }
+) }}
+
+Here are the contents of the `dataset_description.json` file for the study dataset:
+
+```JSON
+{
+    ...
+    "DatasetLinks": {
+        "raw": "sourcedata/raw",
+        "fmriprep": "derivatives/fmriprep"
+    }
+}
+```
+
+Dataset names are defined in order to refer to two nested datasets using BIDS URIs.
+
+Here are the contents of the `prov/prov-fmriprep_ent.json` file:
+
+```JSON
+{
+    "Entities": [
+        {
+            "Id": "bids:raw",
+            "Label": "Raw data"
+        },
+        {
+            "Id": "bids:fmriprep",
+            "Label": "Preprocessed data",
+            "GeneratedBy": "bids::prov#preprocessing-00f3a18f"
+        },
+    ]
+}
+```
+
+Two entities are described inside the `Entities` array, using one provenance record per nested dataset.
+
+Here are the contents of the `prov/prov-fmriprep_act.json` file:
+
+```JSON
+{
+    "Activities": [
+        {
+            "Id": "bids::prov#preprocessing-00f3a18f",
+            "Label": "Preprocessing with fMRIprep",
+            "Command": "docker run  -v sourcedata/raw:/data:ro -v derivatives/fmriprep:/out poldracklab/fmriprep:1.1.4 /data /out",
+            "Used": "bids:raw"
+        }
+    ]
+}
+```
+
+An activity is described using a provenance record inside the `Activities` array.

src/schema/objects/metadata.yaml

@@ -62,7 +62,7 @@ Activities:
         name: Id
         description: |
           Identifier for the activity
-          (see the [Consistency and uniqueness of Ids](SPEC_ROOT/modality-agnostic-files/provenance.md#consistency-and-uniqueness-of-ids)
+          (see the [Consistency and uniqueness of Ids](SPEC_ROOT/modality-agnostic-files/provenance.md#consistency-and-uniqueness-of-identifiers)
           section).
         type: string
         format: uri
@@ -1268,7 +1268,7 @@ Entities:
         name: Id
         description: |
           Identifier for the entity
-          (see the [Consistency and uniqueness of Ids](SPEC_ROOT/modality-agnostic-files/provenance.md#consistency-and-uniqueness-of-ids)
+          (see the [Consistency and uniqueness of Ids](SPEC_ROOT/modality-agnostic-files/provenance.md#consistency-and-uniqueness-of-identifiers)
           section).
         type: string
         format: uri
@@ -1327,7 +1327,7 @@ Environments:
         name: Id
         description: |
           Identifier for the environment.
-          (see the [Consistency and uniqueness of Ids](SPEC_ROOT/modality-agnostic-files/provenance.md#consistency-and-uniqueness-of-ids)
+          (see the [Consistency and uniqueness of Ids](SPEC_ROOT/modality-agnostic-files/provenance.md#consistency-and-uniqueness-of-identifiers)
           section).
         type: string
         format: uri
@@ -3715,7 +3715,7 @@ Software:
         name: Id
         description: |
           Identifier for the software package
-          (see the [Consistency and uniqueness of Ids](SPEC_ROOT/modality-agnostic-files/provenance.md#consistency-and-uniqueness-of-ids)
+          (see the [Consistency and uniqueness of Ids](SPEC_ROOT/modality-agnostic-files/provenance.md#consistency-and-uniqueness-of-identifiers)
           section).
         type: string
         format: uri