[BEP028] provenance - dcm2niix conversion

.github/workflows/validate_datasets.yml

@@ -107,7 +107,7 @@ jobs:
         fi
 
     - name: Skip legacy validation for post-legacy datasets
-      run: for DS in mrs_* dwi_deriv pet006 pheno004 volume_timing; do touch $DS/.SKIP_VALIDATION; done
+      run: for DS in mrs_* dwi_deriv pet006 pheno004 volume_timing provenance_*; do touch $DS/.SKIP_VALIDATION; done
       if: matrix.bids-validator == 'legacy'
 
     - name: Skip stable validation for datasets with unreleased validator features
@@ -119,7 +119,7 @@ jobs:
     - name: Skip main validation for datasets with unreleased spec features
       # Replace ${EMPTY} with dataset patterns, when this is needed
       # Reset to "for DS in ${EMPTY}; ..." after a spec release
-      run: for DS in dwi_deriv pheno004; do touch $DS/.SKIP_VALIDATION; done
+      run: for DS in dwi_deriv pheno004 provenance_*; do touch $DS/.SKIP_VALIDATION; done
       if: matrix.bids-validator != 'dev'
 
     - name: Set BIDS_SCHEMA variable for dev version
@@ -128,7 +128,7 @@ jobs:
       # Update this URL to the schema.json from PRs to the spec, when needed.
       # If this variable is unset, dev will generally track the latest development
       # release of https://jsr.io/@bids/schema
-      run: echo BIDS_SCHEMA=https://bids-specification.readthedocs.io/en/latest/schema.json >> $GITHUB_ENV
+      run: echo BIDS_SCHEMA=https://bids-specification--2099.org.readthedocs.build/en/2099/schema.json >> $GITHUB_ENV
 
     - name: Validate all BIDS datasets using bids-validator
       run: |

README.md

@@ -372,5 +372,6 @@ TABLE BELOW IS GENERATED AUTOMATICALLY.
 DO NOT EDIT DIRECTLY.
 -->
 
-| name   | description   | datatypes   | suffixes   | link to full data   | maintained by   |
-|--------|---------------|-------------|------------|---------------------|-----------------|
+| name                                                                                                  | description                                                                                                                           | datatypes   | suffixes                 | link to full data                                                                                | maintained by                          |
+|:------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------|:------------|:-------------------------|:-------------------------------------------------------------------------------------------------|:---------------------------------------|
+| [provenance_dcm2niix](https://github.com/bids-standard/bids-examples/tree/master/provenance_dcm2niix) | Shows minimal example of provenance metadata for a DICOM to Nifti conversion with [`dcm2niix`](https://github.com/rordenlab/dcm2niix) | anat        | T1w, act, ent, env, soft | This example is based upon [hirni-demo](https://github.com/psychoinformatics-de/hirni-demo) data | [@bclenet](https://github.com/bclenet) |

dataset_listing.tsv

@@ -86,3 +86,4 @@ xeeg_hed_score	EEG and iEEG data with annotations of artifacts, seizures and mod
 dwi_deriv	exemplifies the storage of diffusion MRI derivates that may be generated on the Siemens XA platform.			dwi	dwi
 pheno004	Minimal dataset with subjects with imaging and/or phenotype data		[@ericearl](https://github.com/ericearl)	phenotype, anat	T1w
 mri_chunk	Example MRI dataset to illustrate BIDS chunk entity. A single subject, two chunks.		[@valosekj](https://github.com/valosekj)	anat	T1w
+provenance_dcm2niix	Shows minimal example of provenance metadata for a DICOM to Nifti conversion with [`dcm2niix`](https://github.com/rordenlab/dcm2niix)	This example is based upon [hirni-demo](https://github.com/psychoinformatics-de/hirni-demo) data	[@bclenet](https://github.com/bclenet)	anat	T1w, act, ent, env, soft

provenance_dcm2niix/README.md

@@ -0,0 +1,45 @@
+# Provenance of DICOM to Nifti conversion with `dcm2niix`
+
+## Goal
+
+This example aims at showing provenance metadata for a DICOM to Nifti conversion with [`dcm2niix`](https://github.com/rordenlab/dcm2niix
+). Provenance metadata was created manually ; its acts as a guideline for further machine-generated provenance by `dcm2niix`. 
+
+## Source data
+
+That the `sourcedata/` directory contains the source dataset (DICOM files) known as [hirni-demo](https://github.com/psychoinformatics-de/hirni-demo).
+
+## Directory tree
+
+After conversion, and adding provenance traces, the directory tree is as follows.
+
+Legend:
+* files with a ⭐ were generated by `dcm2niix`;
+* files marked with a ✍️ were generated manually;
+* files marked with a 🤖 were computed from the manually generated provenance metadata;
+* the ⭐✍️ marked `sub-02/anat/sub-02_T1w.json` file was generated by `dcm2niix`, then the `GeneratedBy` and `SidecarGeneratedBy` provenance-related fields were added manually.
+
+> [!NOTE]
+> Note that the `docs/` directory contains explanatory data (see [Provenance as a RDF graph](#provenance-as-a-rdf-graph)) that is not required to encode provenance.
+
+```
+✍️ docs/
+├── 🤖 prov-dcm2niix.jsonld
+└── 🤖 prov-dcm2niix.png
+✍️ prov/
+├── ✍️ prov-dcm2niix_act.json
+├── ✍️ prov-dcm2niix_ent.json
+├── ✍️ prov-dcm2niix_env.json
+└── ✍️ prov-dcm2niix_soft.json
+sourcedata/
+⭐ sub-02/
+└── ⭐ anat
+    ├── ⭐✍️ sub-02_T1w.json
+    └── ⭐ sub-02_T1w.nii
+```
+
+## Provenance as a RDF graph
+
+Provenance metadata can be aggregated as a JSON-LD RDF graph, which is available in [`docs/prov-dcm2niix.jsonld`](docs/prov-dcm2niix.jsonld). This is a rendered version of the graph, also available in [`docs/prov-dcm2niix.png`](docs/prov-dcm2niix.png).
+
+![Rendered version of the RDF graph](docs/prov-dcm2niix.png)

provenance_dcm2niix/dataset_description.json

@@ -0,0 +1,14 @@
+{
+    "Name": "Provenance records for dcm2niix",
+    "BIDSVersion": "1.10.0",
+    "DatasetType": "raw",
+    "License": "CC0",
+    "Authors": [
+        "Boris Clénet"
+    ],
+    "SourceDatasets": [
+        {
+            "URL": "https://github.com/psychoinformatics-de/hirni-demo"
+        }
+    ]
+}

provenance_dcm2niix/docs/prov_dcm2niix.jsonld

@@ -0,0 +1,52 @@
+{
+  "BIDSProvVersion": "0.0.1",
+  "@context": "https://raw.githubusercontent.com/bclenet/bids-specification/refs/heads/BEP028_spec/src/provenance-context.json",
+  "Records": {
+    "Software": [
+      {
+        "Id": "bids::prov#dcm2niix-khhkm7u1",
+        "Label": "dcm2niix",
+        "AltIdentifier": "RRID:SCR_023517",
+        "Version": "v1.0.20220720"
+      }
+    ],
+    "Activities": [
+      {
+        "Id": "bids::prov#conversion-00f3a18f",
+        "Label": "Conversion",
+        "Command": "dcm2niix -o . -f sub-%i/anat/sub-%i_T1w sourcedata/hirni-demo/acq1/dicoms/example-dicom-structural-master/dicoms",
+        "AssociatedWith": "bids::prov#dcm2niix-khhkm7u1",
+        "Used": [
+          "bids::prov#fedora-uldfv058",
+          "bids::sourcedata/hirni-demo/acq1/dicoms/example-dicom-structural-master/dicoms"
+        ]
+      }
+    ],
+    "ProvEntities": [
+      {
+        "Id": "bids::sourcedata/hirni-demo/acq1/dicoms/example-dicom-structural-master/dicoms",
+        "Type": "Entity",
+        "Label": "dicoms"
+      },
+      {
+        "Id": "bids::sub-02/anat/sub-02_T1w.nii",
+        "Label": "sub-02_T1w.nii",
+        "AtLocation": "sub-02/anat/sub-02_T1w.nii",
+        "GeneratedBy": "bids::prov#conversion-00f3a18f"
+      },
+      {
+        "Id": "bids::sub-02/anat/sub-02_T1w.json",
+        "Label": "sub-02_T1w.json",
+        "AtLocation": "sub-02/anat/sub-02_T1w.json",
+        "GeneratedBy": "bids::prov#conversion-00f3a18f"
+      }
+    ],
+    "Environments": [
+      {
+        "Id": "bids::prov#fedora-uldfv058",
+        "Label": "Fedora release 36 (Thirty Six)",
+        "OperatingSystem": "GNU/Linux 6.2.15-100.fc36.x86_64"
+      }
+    ]
+  }
+}

provenance_dcm2niix/prov/prov-dcm2niix_act.json

@@ -0,0 +1,14 @@
+{
+  "Activities": [
+    {
+      "Id": "bids::prov#conversion-00f3a18f",
+      "Label": "Conversion",
+      "Command": "dcm2niix -o . -f sub-%i/anat/sub-%i_T1w sourcedata/hirni-demo/acq1/dicoms/example-dicom-structural-master/dicoms",
+      "AssociatedWith": "bids::prov#dcm2niix-khhkm7u1",
+      "Used": [
+        "bids::prov#fedora-uldfv058",
+        "bids::sourcedata/hirni-demo/acq1/dicoms/example-dicom-structural-master/dicoms"
+      ]
+    }
+  ]
+}

provenance_dcm2niix/prov/prov-dcm2niix_ent.json

@@ -0,0 +1,9 @@
+{
+  "ProvEntities": [
+    {
+      "Id": "bids::sourcedata/hirni-demo/acq1/dicoms/example-dicom-structural-master/dicoms",
+      "Type": "Entity",
+      "Label": "dicoms"
+    }
+  ]
+}

provenance_dcm2niix/prov/prov-dcm2niix_env.json

@@ -0,0 +1,9 @@
+{
+  "Environments": [
+    {
+      "Id": "bids::prov#fedora-uldfv058",
+      "Label": "Fedora release 36 (Thirty Six)",
+      "OperatingSystem": "GNU/Linux 6.2.15-100.fc36.x86_64"
+    }
+  ]
+}

provenance_dcm2niix/prov/prov-dcm2niix_soft.json

@@ -0,0 +1,10 @@
+{
+  "Software": [
+    {
+      "Id": "bids::prov#dcm2niix-khhkm7u1",
+      "Label": "dcm2niix",
+      "AltIdentifier": "RRID:SCR_023517",
+      "Version": "v1.0.20220720"
+    }
+  ]
+}

provenance_dcm2niix/sub-02/anat/sub-02_T1w.json

@@ -0,0 +1,25 @@
+{
+    "Modality": "MR",
+    "ManufacturersModelName": "nifti2dicom",
+    "SoftwareVersions": "0.4.11",
+    "SeriesDescription": "anat-T1w",
+    "ProtocolName": "anat-T1w",
+    "ImageType": ["DERIVED", "SECONDARY"],
+    "RawImage": false,
+    "SeriesNumber": 401,
+    "AcquisitionTime": "13:25:18.000000",
+    "AcquisitionNumber": 1,
+    "SliceThickness": 0.666667,
+    "SpacingBetweenSlices": 0.666667,
+    "ImageOrientationPatientDICOM": [
+        0.999032,
+        -0.0217884,
+        0.0382096,
+        0.0265195,
+        0.991414,
+        -0.128044   ],
+    "ConversionSoftware": "dcm2niix",
+    "ConversionSoftwareVersion": "v1.0.20220720",
+    "GeneratedBy": "bids::prov#conversion-00f3a18f",
+    "SidecarGeneratedBy": "bids::prov#conversion-00f3a18f"
+}