|
| 1 | +# BIDS Prov example #1 for `dcm2niix` |
| 2 | + |
| 3 | +This example aims at showing provenance traces from a DICOM to Nifti conversion, performed by `dcm2niix` on a Linux-based (Fedora) operating system. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +We use the single file `prov/dcm2niix.prov.jsonld` to store all provenance traces relative to the conversion steps. |
| 8 | + |
| 9 | +After conversion, and adding provenance traces, the resulting directory tree looks like this: |
| 10 | + |
| 11 | +``` |
| 12 | +prov/ |
| 13 | +└── dcm2niix.prov.jsonld |
| 14 | +sourcedata/ |
| 15 | +sub-02/ |
| 16 | +└── anat |
| 17 | + ├── sub-02_T1w.json |
| 18 | + └── sub-02_T1w.nii |
| 19 | +``` |
| 20 | + |
| 21 | +Note that the `sourcedata/` directory contains the source dataset described in the [section hereafter](#source-dataset). |
| 22 | + |
| 23 | +## Provenance visualization |
| 24 | + |
| 25 | +We are able to visualize these provenance files using the following commands (current directory is `examples/dcm2niix_1/`): |
| 26 | + |
| 27 | +```shell |
| 28 | +pip install bids-prov==0.1.0 |
| 29 | +bids_prov_visualizer --input_file prov/dcm2niix.prov.jsonld --output_file prov/dcm2niix.prov.png |
| 30 | +``` |
| 31 | + |
| 32 | + |
| 33 | + |
| 34 | +## Source dataset |
| 35 | + |
| 36 | +We get raw data from https://github.com/psychoinformatics-de/hirni-demo.git, a demo datalad dataset containing dicoms. |
| 37 | + |
| 38 | +```shell |
| 39 | +# Get example dicom(s) in a sourcedata/ directory |
| 40 | +mkdir sourcedata |
| 41 | +cd sourcedata |
| 42 | +datalad install --recursive https://github.com/psychoinformatics-de/hirni-demo.git |
| 43 | +cd acq1 |
| 44 | +datalad get ./* |
| 45 | +cd .. |
| 46 | +ls -1 |
| 47 | + acq1 |
| 48 | + acq2 |
| 49 | + code |
| 50 | + dataset_description.json |
| 51 | + README |
| 52 | + studyspec.json |
| 53 | +cd .. |
| 54 | +``` |
| 55 | + |
| 56 | +Note that we will only convert the anatomical data available in this dataset (`acq1/` directory). |
| 57 | + |
| 58 | +## Perform the conversions |
| 59 | + |
| 60 | +Install `dcm2niix`. |
| 61 | + |
| 62 | +```shell |
| 63 | +sudo yum install dcm2niix |
| 64 | +``` |
| 65 | + |
| 66 | +With this setup we are ready to convert dicoms to nifti files using `dcm2niix`. |
| 67 | + |
| 68 | +```shell |
| 69 | +dcm2niix -o . -f sub-%i/anat/sub-%i_T1w sourcedata/acq1/dicoms/example-dicom-structural-master/dicoms/ |
| 70 | +``` |
| 71 | + |
| 72 | +## Limitations |
| 73 | + |
| 74 | +### `Used` key for activities |
| 75 | + |
| 76 | +Although the BIDS-Prov spec mentions: |
| 77 | + |
| 78 | +> Used : OPTIONAL. UUID. Identifier of an entity used by this activity (the corresponding Entity must be defined with its own Entity record). |
| 79 | +
|
| 80 | +We represented used entities in a list to link all the dicom files of a directory to the corresponding conversion activity. |
| 81 | + |
| 82 | +### `Environments` not defined in the context |
| 83 | + |
| 84 | +We cannot use an `Environments` list because the current context (commit ce0eb77) does not define the `Environments` term. Therefore, we defined the `urn:fedora-b7hmkmqd` environments as an `Entity`. |
| 85 | + |
| 86 | +### High number of dicom files |
| 87 | + |
| 88 | +Listing all the DICOM files used by the dcm2niix conversion steps would lower readability of the JSON-LD provenance files. Therefore we only listed the following directories as `Entities`: |
| 89 | + |
| 90 | +``` |
| 91 | +bids::sourcedata/hirni-demo/acq1/dicoms/example-dicom-structural-master/dicoms |
| 92 | +``` |
| 93 | + |
| 94 | +although it is not allowed by the current version of the BIDS Prov specification to have directories as `Entities`. |
0 commit comments