Skip to content

Commit ab6aa3b

Browse files
bclenetbclenet
committed
Add examples description
1 parent bf9c6b6 commit ab6aa3b

File tree

1 file changed

+131
-92
lines changed

1 file changed

+131
-92
lines changed

‎bep028spec.md‎

Lines changed: 131 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
**Extension moderators/leads:** Satra Ghosh <[[email protected]](mailto:[email protected])> and Camille Maumet <[[email protected]](mailto:[email protected])>
66

7-
**Contributors:** Stefan Appelhoff, Chris Markiewicz, Yaroslav O. Halchenko, Cyril R. Pernet, Jean-Baptiste Poline, Rémi Adon, Michael Dayan, Sarah Saneei, Eric Earl, Tibor Auer, Ghislain Vaillant, Matthieu Joulot, Omar El Rifai, Ryan J. Cali, Thomas Betton, Cyril Regan, Hermann Courteille, Arnaud Delorme, Boris Clénet.*
7+
**Contributors:** Stefan Appelhoff, Chris Markiewicz, Yaroslav O. Halchenko, Cyril R. Pernet, Jean-Baptiste Poline, Rémi Adon, Michael Dayan, Sarah Saneei, Eric Earl, Tibor Auer, Ghislain Vaillant, Matthieu Joulot, Omar El Rifai, Ryan J. Cali, Thomas Betton, Cyril Regan, Hermann Courteille, Arnaud Delorme, Boris Clénet.
88

99
We meet every two weeks by videoconference on Mondays at 7-8am PDT / 10am-11am EDT / 3-4pm BST. The group is always open to new contributors interested in neuroimaging data sharing. To join the call or to ask any question, please email us at [[email protected]](mailto:[email protected]).
1010

@@ -55,9 +55,82 @@ BIDS-Prov metadata is written in JSON or JSON-LD.
5555

5656
[JSON-LD](https://www.w3.org/TR/json-ld11/) is a specific type of JSON that allows encoding graph-like structures with the Resource Description Framework[^1].
5757

58-
TODO: written in a single file (JSON-LD) or several JSON files that can be aggregated into one JSON-LD
58+
A skeleton for a BIDS-Prov JSON-LD file looks like this:
59+
```
60+
{
61+
"@context": "https://purl.org/nidash/bidsprov/context.json",
62+
"BIDSProvVersion": "0.0.1",
63+
"records": {
64+
"Agent": [
65+
{
66+
<...Agent 1...>
67+
},
68+
{
69+
<...Agent 2...>
70+
}
71+
],
72+
"Activity": [
73+
{
74+
<...Activity 1...>
75+
},
76+
{
77+
<...Activity 2...>
78+
}
79+
],
80+
"Entity": [
81+
{
82+
<...Entity 1...>
83+
},
84+
{
85+
<...Entity 2...>
86+
}
87+
],
88+
"Environment": [
89+
{
90+
<...Environment 1...>
91+
},
92+
{
93+
<...Environment 2...>
94+
}
95+
]
96+
}
97+
}
98+
```
99+
100+
<table>
101+
<tr>
102+
<td><strong>Key name</strong>
103+
</td>
104+
<td><strong>Description</strong>
105+
</td>
106+
</tr>
107+
<tr>
108+
<td><code>@context</code>
109+
</td>
110+
<td>REQUIRED. A URL to the BIDS-Prov json context. Value must be <code>"https://purl.org/nidash/bidsprov/context.json"</code>
111+
</td>
112+
</tr>
113+
<tr>
114+
<td><code>BIDSProvVersion</code>
115+
</td>
116+
<td>REQUIRED. A string identifying the version of the specification adhered to.
117+
</td>
118+
</tr>
119+
<tr>
120+
<td><code>records</code>
121+
</td>
122+
<td>REQUIRED. A list of provenance records (Activity, Entity, Agent, Environement), describing the provenance (see "Provenance records" sections below).
123+
</td>
124+
</tr>
125+
</table>
126+
127+
BIDS-Prov allows this skeleton to be splitted into several *JSON* files. This is described in sections [3.1.3 Suffixes](#3-1-3-suffixes)
128+
and [3.2 Provenance description levels](#3-2-provenance-description-levels).
129+
Using tools provided by BIDS-Prov ([5 Tools](#5-tools)), these JSON contents can be merged back to a JSON-LD graph as described above.
59130

60-
TODO: BIDS-Prov tools
131+
Note: since the JSON-LD documents are graph objects, they can be aggregated using RDF tools without the need to apply the inheritance principle.
132+
133+
A complete schema for the model file to facilitate specification and validation is available from [https://github.com/bids-standard/BEP028_BIDSprov](https://github.com/bids-standard/BEP028_BIDSprov). In the event of disagreements between the schema and the specification, the specification is authoritative.
61134

62135
## 2. Provenance records {#2-provenance-records}
63136

@@ -342,47 +415,47 @@ In the following example, two separated processings (`conversion` and `smoothing
342415
└─ ...
343416
```
344417

345-
#### 3.1.3 Suffixes {#3-1-3-Suffixes}
418+
#### 3.1.3 Suffixes {#3-1-3-suffixes}
346419

347420
The following BIDS suffixes (cf. [Definitions](https://bids-specification.readthedocs.io/en/stable/common-principles.html#definitions)) specify the contents of a provenance file.
348421

349422
<table>
350423
<tr>
351424
<td><strong>Suffix</strong>
352425
</td>
353-
<td><strong>Description</strong>
426+
<td><strong>File contents</strong>
354427
</td>
355428
<td><strong>File extension</strong>
356429
</td>
357430
</tr>
358431
<tr>
359432
<td><code>act</code>
360433
</td>
361-
<td>Activities for the group of provenance records.
434+
<td>Activity records for the group of provenance
362435
</td>
363436
<td><code>.json</code>
364437
</td>
365438
</tr>
366439
<tr>
367440
<td><code>ent</code>
368441
</td>
369-
<td>Agents for the group of provenance records.
442+
<td>Agent records for the group of provenance
370443
</td>
371444
<td><code>.json</code>
372445
</td>
373446
</tr>
374447
<tr>
375448
<td><code>env</code>
376449
</td>
377-
<td>Entities for the group of provenance records.
450+
<td>Entity records for the group of provenance
378451
</td>
379452
<td><code>.json</code>
380453
</td>
381454
</tr>
382455
<tr>
383456
<td><code>base</code>
384457
</td>
385-
<td>Common parameters for the group of provenance records (version and context for BIDS-Prov).
458+
<td>Common parameters for the group of provenance (<code>BIDSProvVersion</code> and <code>@context</code>).
386459
<td><code>.json</code>
387460
</td>
388461
</td>
@@ -461,6 +534,8 @@ If the `SidecarGenearatedBy` field is not defined, BIDS-Prov assumes that the si
461534

462535
No other field is allowed to describe provenance inside sidecar JSONs.
463536

537+
TODO: where are the @context and BIDSProvVersion ?
538+
464539
#### 3.2.2 Subdirectories level provenance {#3-2-2-subdirectories-level-provenance}
465540

466541
BIDS-Prov files can be stored in a `prov/` directory in any subdirectory of the dataset (or BIDS-Derivatives directories).
@@ -495,6 +570,8 @@ Here is an example dataset tree:
495570
└─ dataset_description.json
496571
```
497572

573+
TODO: where are the @context and BIDSProvVersion ?
574+
498575
#### 3.2.3 Dataset level provenance - `prov/` directory {#3-2-3-dataset-level-provenance-prov-directory}
499576

500577
BIDS-Prov files can be stored in a `prov/` directory immediately below the BIDS dataset (or BIDS-Derivatives dataset) root. At the dataset level, provenance can be about any BIDS file in the dataset.
@@ -561,75 +638,9 @@ Here is an example of a `GeneratedByProv` field containing the IRI of an `Entity
561638
}
562639
```
563640

564-
### 3.3 Top-level structure {#3-3-top-level-structure}
565-
566-
#### File-level provenance
641+
TODO: where are the @context and BIDSProvVersion ?
567642

568-
A skeleton for a file-level BIDS-Prov JSON-LD file looks like this:
569-
570-
```
571-
{
572-
"@context": "https://purl.org/nidash/bidsprov/context.json",
573-
"BIDSProvVersion": "1.0.0",
574-
<...Entity 1...>
575-
"wasGeneratedBy": {
576-
<...Activity...>
577-
"wasAssociatedWith": {
578-
<...Agent...>
579-
},
580-
"used": {
581-
<...Entity 2…>
582-
}
583-
}
584-
}
585-
```
586-
587-
<table>
588-
<tr>
589-
<td>
590-
591-
<strong>Key name</strong>
592-
</td>
593-
<td><strong>Description</strong>
594-
</td>
595-
</tr>
596-
<tr>
597-
<td><code>@context</code>
598-
</td>
599-
<td>REQUIRED. A URL to the BIDS-Prov json context. Value must be “<code>https://purl.org/nidash/bidsprov/context.json"</code>
600-
</td>
601-
</tr>
602-
<tr>
603-
<td><code>BIDSProvVersion</code>
604-
</td>
605-
<td>REQUIRED. A string identifying the version of the specification adhered to.
606-
</td>
607-
</tr>
608-
<tr>
609-
<td><code>[no-key : root-level attributes]</code>
610-
</td>
611-
<td>REQUIRED. An Entity record describing the provenance (see “Entity” section below).
612-
</td>
613-
</tr>
614-
<tr>
615-
<td><code>wasGeneratedBy</code>
616-
</td>
617-
<td>REQUIRED. An Activity describing the provenance (see “Activity”, section below).
618-
</td>
619-
</tr>
620-
<tr>
621-
<td><code>wasAssociatedWith</code>
622-
</td>
623-
<td>OPTIONAL. An Agent describing the provenance (see “Activity”, section below).
624-
</td>
625-
</tr>
626-
<tr>
627-
<td><code>used</code>
628-
</td>
629-
<td>OPTIONAL. An Entity describing the provenance (see “Entity”, section below).
630-
</td>
631-
</tr>
632-
</table>
643+
### 3.3 Contents of a BIDS-Prov file {#3-3-contents-of-a-bids-prov-file}
633644

634645
#### Dataset-level provenance
635646

@@ -674,45 +685,73 @@ A skeleton for a dataset level BIDS-Prov JSON-LD file looks like this:
674685
}
675686
```
676687

688+
## 4 Examples
689+
690+
A list of examples for BIDS-Prov are available in https://github.com/bids-standard/BEP028_BIDSprov/tree/master/examples
691+
692+
TODO: some examples are not merged yet.
693+
677694
<table>
678695
<tr>
679-
<td>
680-
681-
<strong>Key name</strong>
696+
<td><strong>Location</strong>
682697
</td>
683698
<td><strong>Description</strong>
684699
</td>
685700
</tr>
701+
686702
<tr>
687-
<td><code>@context</code>
703+
<td><a href="https://github.com/bids-standard/BEP028_BIDSprov/tree/master/examples/simple_example/">examples/simple_example/</a>
688704
</td>
689-
<td>REQUIRED. A URL to the BIDS-Prov json context. Value must be “<code>https://purl.org/nidash/bidsprov/context.json"</code>
705+
<td>A simple example describing the downsampling of EEG data using EEGLAB.
690706
</td>
691707
</tr>
708+
692709
<tr>
693-
<td><code>BIDSProvVersion</code>
710+
<td><a href="https://github.com/bids-standard/BEP028_BIDSprov/tree/master/examples/from_parsers/afni/">examples/from_parsers/afni/</a>
694711
</td>
695-
<td>REQUIRED. A string identifying the version of the specification adhered to.
712+
<td>A set of examples for fMRI processing using AFNI. These where generated generated from ...
696713
</td>
697714
</tr>
715+
698716
<tr>
699-
<td><code>records</code>
717+
<td><a href="https://github.com/bids-standard/BEP028_BIDSprov/tree/master/examples/from_parsers/fsl/">examples/from_parsers/fsl/</a>
700718
</td>
701-
<td>REQUIRED. A list of Activity, Entity and Agent records describing the provenance (see “Activity”, “Entity” and “Agent” sections below).
719+
<td>A set of examples for fMRI processing using FSL. These where generated generated from ...
702720
</td>
703721
</tr>
704-
</table>
705722

706-
A complete schema for the model file to facilitate specification and validation is available from [https://github.com/bids-standard/BEP028_BIDSprov](https://github.com/bids-standard/BEP028_BIDSprov). In the event of disagreements between the schema and the specification, the specification is authoritative.
723+
<tr>
724+
<td><a href="https://github.com/bids-standard/BEP028_BIDSprov/tree/master/examples/from_parsers/spm/">examples/from_parsers/spm/</a>
725+
</td>
726+
<td>A set of examples for fMRI processing using SPM. These where generated generated from ...
727+
</td>
728+
</tr>
729+
730+
<tr>
731+
<td><a href="https://github.com/bids-standard/BEP028_BIDSprov/tree/master/examples/dcm2niix/">examples/dcm2niix/</a>
732+
</td>
733+
<td>A set of examples describing dicom to nifti conversion using dcm2niix. These aim at showing different ways to organise the exact same provenance records inside a dataset.
734+
</td>
735+
</tr>
707736

737+
<tr>
738+
<td><a href="https://github.com/bids-standard/BEP028_BIDSprov/tree/master/examples/heudiconv/">examples/heudiconv/</a>
739+
</td>
740+
<td>An example describing dicom to nifti conversion using heudiconv.
741+
</td>
742+
</tr>
708743

744+
<tr>
745+
<td><a href="https://github.com/bids-standard/BEP028_BIDSprov/tree/master/examples/nipype/">examples/nipype/</a>
746+
</td>
747+
<td>An example describing simple processings on anatomical MRI using FSL through Nipype.
748+
</td>
749+
</tr>
709750

710-
## 4 Graph model {#4-graph-model}
751+
</table>
711752

712-
Note: since these jsonld documents are graph objects, they can be aggregated using RDF tools without the need to apply the inheritance principle.
713753

714-
## 4 Examples
715-
A list of fMRI examples for BIDS-Prov are available for SPM, FSL and AFNI in: https://github.com/bids-standard/BEP028_BIDSprov/tree/master/examples
754+
## 5 Tools
716755

717756
## 5 Future perspectives
718757

0 commit comments

Comments
 (0)