Readme explaining the creation of dcm2niix example

Author: bclenet

examples/dcm2niix/README.md

@@ -0,0 +1,61 @@
+# A `dcm2niix` example for BIDS-Prov
+
+This example aim at showing provenance traces from a DICOM to Nifti conversion, performed by `dcm2niix` on a Linux-based (Fedora) operating system.
+
+## `dcm2niix` installation
+
+```shell
+sudo yum install dcm2niix
+```
+
+## Source dataset
+
+We get raw data from https://github.com/psychoinformatics-de/hirni-demo.git, a demo datalad dataset containing dicoms.
+
+```shell
+# Get example dicom(s) in a sourcedata/ directory
+mkdir sourcedata
+cd sourcedata
+datalad install --recursive https://github.com/psychoinformatics-de/hirni-demo.git
+cd acq1
+datalad get ./*
+cd ../acq2
+datalad get ./*
+ls -1
+    acq1
+    acq2
+    code
+    dataset_description.json
+    README
+    studyspec.json
+cd ..
+```
+
+## Conversions
+
+With this setup we are ready to convert dicoms to nifti files using `dcm2niix`.
+
+```shell
+dcm2niix -o . -f sub-%i/ses-%t/anat/sub-%i_ses-%t_T1w sourcedata/acq1/dicoms/example-dicom-structural-master/dicoms/
+dcm2niix -o . -f sub-%i/ses-%t/func/sub-%i_ses-%t_task-oneback_run-1_bold sourcedata/acq1/dicoms/example-dicom-structural-master/dicoms/
+
+# Control results
+tree sub-02/
+    sub-02/
+    ├── ses-20130717141500
+    │   └── anat
+    │       ├── sub-02_ses-20130717141500_T1w.json
+    │       └── sub-02_ses-20130717141500_T1w.nii
+    └── ses-20140425155335
+        └── func
+            ├── sub-02_ses-20140425155335_task-oneback_run-1_bold.json
+            └── sub-02_ses-20140425155335_task-oneback_run-1_bold.nii
+```
+
+## Associated provenance
+
+See the `dcm2niix.prov.jsonld` file.
+
+Some limitations :
+* for now, the values of Activities `Used` keys only refer to the first dicom file of a series, although each activity should be linked to all the data it actually used (i.e.: all dicom files in a directory in our case).
+* as there is a high number of dicom files (384 in `acq1/` and 5460 in `acq2/`), we did not create an entity for each of these. Only the first three files of each directory were represented.

examples/dcm2niix/dcm2niix.prov.jsonld

@@ -2,9 +2,16 @@
 "@context": "https://purl.org/nidash/bidsprov/context.json",
   "BIDSProvVersion": "0.0.1",
   "Records": {
+    "Environments": [
+      {
+        "Id": "urn:fedora",
+        "Label": "Fedora release 36 (Thirty Six)",
+        "OperatingSystem": " GNU/Linux 6.2.15-100.fc36.x86_64"
+      }
+    ],
     "Software": [
       {
-        "Id": "urn:dcm2niix-4a586b50",
+        "Id": "urn:dcm2niix",
         "Label": "dcm2niix",
         "Version": "v1.0.20220720"
       }
@@ -13,14 +20,16 @@
       {
         "Id": "urn:conversion-00f3a18f",
         "Label": "Conversion",
-        "Command": "dcm2niix -o . -f sub-%i/ses-%t/anat/sub-%i_ses-%t_T1w sourcedata/acq1/dicoms/example-dicom-structural-master/dicoms/"
-        "AssociatedWith": "urn:dcm2niix-4a586b50"
+        "Command": "dcm2niix -o . -f sub-%i/ses-%t/anat/sub-%i_ses-%t_T1w sourcedata/acq1/dicoms/example-dicom-structural-master/dicoms/",
+        "AssociatedWith": "urn:dcm2niix-4a586b50",
+        "Used": "bids::sourcedata/hirni-demo/acq1/dicoms/example-dicom-structural-master/dicoms/N2D_0001.dcm"
       },
       {
         "Id": "urn:conversion-5a66f5be",
         "Label": "Conversion",
-        "Command": "dcm2niix -o . -f sub-%i/ses-%t/func/sub-%i_ses-%t_task-oneback_run-1_bold sourcedata/acq1/dicoms/example-dicom-structural-master/"
-        "AssociatedWith": "urn:dcm2niix-4a586b50"
+        "Command": "dcm2niix -o . -f sub-%i/ses-%t/func/sub-%i_ses-%t_task-oneback_run-1_bold sourcedata/acq1/dicoms/example-dicom-structural-master/dicoms/",
+        "AssociatedWith": "urn:dcm2niix-4a586b50",
+        "Used": "bids::sourcedata/hirni-demo/acq2/dicoms/example-dicom-functional-master/dicoms/MR.1.3.46.670589.11.38317.5.0.4476.2014042516042547586"
       }
     ],
     "Entities": [