Module to merge provenance

bids_prov/README.md

@@ -15,21 +15,18 @@ python launch_parser_on_nidm.py --input_dir input_examples --output_dir output_r
 Your `output_results` directory tree will be generated by itself. A folder is created for each parser and each example contains the input file, the jsonld and the associated png. 
 
 
-### Notes
-All scripts provide a `--help` flag, to get an overview of possible parameters and default values
-Here is an example
-```bash
->> python -m bids_prov.visualize --help
-Usage: visualize.py [OPTIONS] [FILENAMES]...
+### Parser entry points
 
-Options:
-  -o, --output_file TEXT
-  --omit-details          omit the following low level details : {'Activity':
-                          ('startedAtTime', 'endedAtTime'), 'Entity':
-                          ('atLocation', 'generatedAt')}
+The following parser python modules provide entry points for direct use in a terminal:
 
-  --help                  Show this message and exit.
-```
+* `bids_prov.afni_parser`
+* `bids_prov.fsl_parser`
+* `bids_prov.spm_parser`
+
+> [!NOTE]
+> All scripts provide a `--help` flag, to get an overview of possible parameters and default values.
+
+Here are examples:
 
 ```bash
 >> python -m bids_prov.spm_parser --help
@@ -39,4 +36,99 @@ Options:
   -o, --output-file TEXT  [required]
   -c, --context-url TEXT
   --help                  Show this message and exit.
-```
+```
+
+### Visualize provenance as a graph
+
+The `bids_prov.visualize` module allows to generate an image showing provenance contained in a JSON-LD file as a graph.
+
+```bash
+>> python -m bids_prov.visualize --help
+usage: visualize.py [-h] --input_file INPUT_FILE [--output_file OUTPUT_FILE]
+
+options:
+  -h, --help            show this help message and exit
+  --input_file INPUT_FILE
+                        input BIDSprov data as a .jsonld file
+  --output_file OUTPUT_FILE
+                        output .png file showing BIDSprov graph
+```
+
+This is a generated graph, form the spm_default_batch example.
+
+![](examples/from_parsers/spm/spm_default_batch.png)
+
+### Merge provenance provenance records
+
+The `bids_prov.merge` module allows to merge provenance records contained in a BIDS dataset into a single JSON-LD file.
+
+```bash
+>> python -m bids_prov.merge --help
+usage: merge.py [-h] [--dataset DATASET] [--derivative] --output_file
+                OUTPUT_FILE [--group GROUP]
+
+options:
+  -h, --help            show this help message and exit
+  --dataset DATASET, -d DATASET
+                        The path to the input BIDS dataset.
+  --derivative          Set this option to specify the dataset is a BIDS
+                        derivative dataset.
+  --output_file OUTPUT_FILE, -o OUTPUT_FILE
+                        Output JSON-LD file containing the provenance graph
+                        for the input dataset.
+  --group GROUP, -g GROUP
+                        Provenance group for which to extract the metadata.
+```
+
+In the example of the following BIDS dataset:
+
+```
+.
+├── dataset_description.json
+├── prov/
+│   ├── prov-fmriprep_act.json
+│   ├── prov-fmriprep_ent.json
+│   ├── prov-fmriprep_env.json
+│   └── prov-fmriprep_soft.json
+├── README.md
+└── sub-001/
+    ├── anat
+    │   ├── sub-001_T1w_brainmask.nii.gz
+    │   ├── sub-001_T1w_dtissue.nii.gz
+    │   ├── sub-001_T1w_label-aparcaseg_roi.nii.gz
+    │   ├── sub-001_T1w_label-aseg_roi.nii.gz
+    │   ├── sub-001_T1w_preproc.nii.gz
+    │   ├── sub-001_T1w_space-MNI152NLin2009cAsym_brainmask.nii.gz
+    │   ├── sub-001_T1w_space-MNI152NLin2009cAsym_dtissue.nii.gz
+    │   └── sub-001_T1w_space-MNI152NLin2009cAsym_preproc.nii.gz
+    └── func
+        ├── sub-001_task-MGT_run-01_bold_confounds.tsv
+        ├── sub-001_task-MGT_run-01_bold_space-MNI152NLin2009cAsym_brainmask.nii.gz
+        ├── sub-001_task-MGT_run-01_bold_space-MNI152NLin2009cAsym_preproc.nii.gz
+        ├── sub-001_task-MGT_run-01_bold_space-T1w_label-aparcaseg_roi.nii.gz
+        ├── sub-001_task-MGT_run-01_bold_space-T1w_label-aseg_roi.nii.gz
+        ├── sub-001_task-MGT_run-02_bold_confounds.tsv
+        ├── sub-001_task-MGT_run-02_bold_space-MNI152NLin2009cAsym_brainmask.nii.gz
+        ├── sub-001_task-MGT_run-02_bold_space-MNI152NLin2009cAsym_preproc.nii.gz
+        ├── sub-001_task-MGT_run-02_bold_space-T1w_label-aparcaseg_roi.nii.gz
+        ├── sub-001_task-MGT_run-02_bold_space-T1w_label-aseg_roi.nii.gz
+        ├── sub-001_task-MGT_run-03_bold_confounds.tsv
+        ├── sub-001_task-MGT_run-03_bold_space-MNI152NLin2009cAsym_brainmask.nii.gz
+        ├── sub-001_task-MGT_run-03_bold_space-MNI152NLin2009cAsym_preproc.nii.gz
+        ├── sub-001_task-MGT_run-03_bold_space-T1w_label-aparcaseg_roi.nii.gz
+        ├── sub-001_task-MGT_run-03_bold_space-T1w_label-aseg_roi.nii.gz
+        ├── sub-001_task-MGT_run-04_bold_confounds.tsv
+        ├── sub-001_task-MGT_run-04_bold_space-MNI152NLin2009cAsym_brainmask.nii.gz
+        ├── sub-001_task-MGT_run-04_bold_space-MNI152NLin2009cAsym_preproc.nii.gz
+        ├── sub-001_task-MGT_run-04_bold_space-T1w_label-aparcaseg_roi.nii.gz
+        └── sub-001_task-MGT_run-04_bold_space-T1w_label-aseg_roi.nii.gz
+```
+
+Launching this command from the root dir of the dataset:
+```shell
+python -m bids_prov.merge -d . -o prov/prov-fmriprep_all.jsonld
+```
+
+will look through all the sidecar JSON files, the `dataset_description.json`, and the `prov/*` files to extract provenance metadata, and merge it into the `prov/prov-fmriprep_all.jsonld` file as a JSON-LD RDF graph.
+
+Note that it is possible to extract provenance metadata for all provenance groups or for one provenance group only. Also note that it is important to set the `--derivative` option to parse BIDS derivative datasets.