Skip to content

Commit 690b104

Browse files
bclenetbclenet
committed
Doc for utils entry points
1 parent b515347 commit 690b104

File tree

1 file changed

+100
-14
lines changed

1 file changed

+100
-14
lines changed

‎bids_prov/README.md‎

Lines changed: 100 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -15,21 +15,18 @@ python launch_parser_on_nidm.py --input_dir input_examples --output_dir output_r
1515
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.
1616

1717

18-
### Notes
19-
All scripts provide a `--help` flag, to get an overview of possible parameters and default values
20-
Here is an example
21-
```bash
22-
>> python -m bids_prov.visualize --help
23-
Usage: visualize.py [OPTIONS] [FILENAMES]...
18+
### Parser entry points
2419

25-
Options:
26-
-o, --output_file TEXT
27-
--omit-details omit the following low level details : {'Activity':
28-
('startedAtTime', 'endedAtTime'), 'Entity':
29-
('atLocation', 'generatedAt')}
20+
The following parser python modules provide entry points for direct use in a terminal:
3021

31-
--help Show this message and exit.
32-
```
22+
* `bids_prov.afni_parser`
23+
* `bids_prov.fsl_parser`
24+
* `bids_prov.spm_parser`
25+
26+
> [!NOTE]
27+
> All scripts provide a `--help` flag, to get an overview of possible parameters and default values.
28+
29+
Here are examples:
3330

3431
```bash
3532
>> python -m bids_prov.spm_parser --help
@@ -39,4 +36,93 @@ Options:
3936
-o, --output-file TEXT [required]
4037
-c, --context-url TEXT
4138
--help Show this message and exit.
42-
```
39+
```
40+
41+
### Visualize provenance as a graph
42+
43+
The `bids_prov.visualize` module allows to generate an image showing provenance contained in a JSON-LD file as a graph.
44+
45+
```bash
46+
>> python -m bids_prov.visualize --help
47+
usage: visualize.py [-h] --input_file INPUT_FILE [--output_file OUTPUT_FILE]
48+
49+
options:
50+
-h, --help show this help message and exit
51+
--input_file INPUT_FILE
52+
input BIDSprov data as a .jsonld file
53+
--output_file OUTPUT_FILE
54+
output .png file showing BIDSprov graph
55+
```
56+
57+
This is a generated graph, form the spm_default_batch example.
58+
59+
![provenance graph for the spm_default_batch](examples/from_parsers/spm/spm_default_batch.png)
60+
61+
### Merge provenance provenance records
62+
63+
The `bids_prov.merge` module allows to merge provenance records contained in a BIDS dataset into a single JSON-LD file.
64+
65+
```bash
66+
>> python -m bids_prov.merge --help
67+
usage: merge.py [-h] [--dataset DATASET] --output_file OUTPUT_FILE [--group GROUP]
68+
69+
options:
70+
-h, --help show this help message and exit
71+
--dataset DATASET, -d DATASET
72+
The path to the input BIDS dataset.
73+
--output_file OUTPUT_FILE, -o OUTPUT_FILE
74+
Output JSON-LD file containing the provenance graph for the input dataset.
75+
--group GROUP, -g GROUP
76+
Provenance group for which to extract the metadata.
77+
```
78+
79+
In the example of the following BIDS dataset:
80+
81+
```
82+
.
83+
├── dataset_description.json
84+
├── prov/
85+
│ ├── prov-fmriprep_act.json
86+
│ ├── prov-fmriprep_ent.json
87+
│ ├── prov-fmriprep_env.json
88+
│ └── prov-fmriprep_soft.json
89+
├── README.md
90+
└── sub-001/
91+
├── anat
92+
│ ├── sub-001_T1w_brainmask.nii.gz
93+
│ ├── sub-001_T1w_dtissue.nii.gz
94+
│ ├── sub-001_T1w_label-aparcaseg_roi.nii.gz
95+
│ ├── sub-001_T1w_label-aseg_roi.nii.gz
96+
│ ├── sub-001_T1w_preproc.nii.gz
97+
│ ├── sub-001_T1w_space-MNI152NLin2009cAsym_brainmask.nii.gz
98+
│ ├── sub-001_T1w_space-MNI152NLin2009cAsym_dtissue.nii.gz
99+
│ └── sub-001_T1w_space-MNI152NLin2009cAsym_preproc.nii.gz
100+
└── func
101+
├── sub-001_task-MGT_run-01_bold_confounds.tsv
102+
├── sub-001_task-MGT_run-01_bold_space-MNI152NLin2009cAsym_brainmask.nii.gz
103+
├── sub-001_task-MGT_run-01_bold_space-MNI152NLin2009cAsym_preproc.nii.gz
104+
├── sub-001_task-MGT_run-01_bold_space-T1w_label-aparcaseg_roi.nii.gz
105+
├── sub-001_task-MGT_run-01_bold_space-T1w_label-aseg_roi.nii.gz
106+
├── sub-001_task-MGT_run-02_bold_confounds.tsv
107+
├── sub-001_task-MGT_run-02_bold_space-MNI152NLin2009cAsym_brainmask.nii.gz
108+
├── sub-001_task-MGT_run-02_bold_space-MNI152NLin2009cAsym_preproc.nii.gz
109+
├── sub-001_task-MGT_run-02_bold_space-T1w_label-aparcaseg_roi.nii.gz
110+
├── sub-001_task-MGT_run-02_bold_space-T1w_label-aseg_roi.nii.gz
111+
├── sub-001_task-MGT_run-03_bold_confounds.tsv
112+
├── sub-001_task-MGT_run-03_bold_space-MNI152NLin2009cAsym_brainmask.nii.gz
113+
├── sub-001_task-MGT_run-03_bold_space-MNI152NLin2009cAsym_preproc.nii.gz
114+
├── sub-001_task-MGT_run-03_bold_space-T1w_label-aparcaseg_roi.nii.gz
115+
├── sub-001_task-MGT_run-03_bold_space-T1w_label-aseg_roi.nii.gz
116+
├── sub-001_task-MGT_run-04_bold_confounds.tsv
117+
├── sub-001_task-MGT_run-04_bold_space-MNI152NLin2009cAsym_brainmask.nii.gz
118+
├── sub-001_task-MGT_run-04_bold_space-MNI152NLin2009cAsym_preproc.nii.gz
119+
├── sub-001_task-MGT_run-04_bold_space-T1w_label-aparcaseg_roi.nii.gz
120+
└── sub-001_task-MGT_run-04_bold_space-T1w_label-aseg_roi.nii.gz
121+
```
122+
123+
Launching this command from the root dir of the dataset:
124+
```shell
125+
python -m bids_prov.merge -d . -o prov/prov-fmriprep_all.jsonld
126+
```
127+
128+
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.

0 commit comments

Comments
 (0)