prov BIDS entity description

Author: bclenet

src/modality-agnostic-files/provenance.md

@@ -22,8 +22,6 @@ context of the academic literature.
 
 ## Overview
 
-### Goals
-
 This part of the BIDS specification is aimed at describing the provenance of a BIDS dataset.
 
 This description is retrospective, it describes a set of steps that were executed in order to obtain the dataset (this is different from prospective descriptions of workflows that could for instance list all sets of steps that can be run on this dataset).
@@ -36,7 +34,7 @@ Provenance information SHOULD be included in a BIDS dataset when possible.
 
 If provenance information is included, it MUST be described using the conventions detailed by this specification.
 
-Provenance information reflect the provenance of a full dataset and/or of specific files at any level of the BIDS hierarchy.
+Provenance information reflects the provenance of a full dataset and/or of specific files at any level of the BIDS hierarchy.
 
 Provenance information SHOULD not include human subject identifying data.
 
@@ -90,7 +88,7 @@ prov/
 ```
 
 !!! note
-    The `prov` BIDS entity allow to group related provenance files, using an arbitrary value for `<label>`. A subdirectory MAY be used to organise provenance files, using an arbitrary value for `<subdir>`.
+    The `prov` BIDS entity allows to group related provenance files, using an arbitrary value for `<label>`. A subdirectory MAY be used to organise provenance files, using an arbitrary value for `<subdir>`.
 
 The following suffixes specify the contents of provenance files.
 
@@ -545,6 +543,77 @@ Here are the contents of the `sub-001/anat/sub-001_T1w.json` file:
 
 The metadata field `GeneratedBy` indicates that the `sub-001/anat/sub-001_T1w.nii.gz` file was generated by the previously described activity.
 
+### Provenance of a BIDS derivative dataset
+
+Consider the following BIDS derivative 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(
+    {
+        "sourcedata": {
+            "dicoms": {
+                "...": "",
+            },
+        },
+        "sub-001": {
+            "anat": {
+                "sub-001_T1w.nii.gz": "",
+                "sub-001_T1w.json": ""
+            },
+        },
+        "prov": {
+            "prov-dcm2niix_act.json": "",
+            "prov-dcm2niix_soft.json": ""
+        }
+    }
+) }}
+
+Here are the contents of the `prov/prov-dcm2niix_soft.json` file:
+
+```JSON
+{
+    "Software": [
+        {
+            "Id": "bids::prov#dcm2niix-70ug8pl5",
+            "Label": "dcm2niix",
+            "Version": "v1.1.3"
+        }
+    ]
+}
+```
+
+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
+{
+    "Activities": [
+        {
+            "Id": "bids::prov#conversion-00f3a18f",
+            "Label": "Conversion",
+            "Command": "dcm2niix -o . -f sub-%i/anat/sub-%i_T1w sourcedata/dicoms",
+            "AssociatedWith": "bids::prov#dcm2niix-70ug8pl5"
+        }
+    ]
+}
+```
+
+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 metadata field `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:

src/schema/objects/entities.yaml

@@ -249,8 +249,7 @@ prov:
   name: prov
   display_name: Provenance group
   description: |
-    A grouping of provenance records.
-    Defining multiple provenance records groups is appropriate when several processings have been performed on data.
+    The `prov-<label>` entity allows to group related provenance files, using an arbitrary value for `<label>`.
   type: string
   format: label
 reconstruction: