# BIDS-Prov: Recording neuroimaging provenance

Camille Maumet

► To cite this version:

Camille Maumet. BIDS-Prov: Recording neuroimaging provenance. Brain Imaging Data Structure (BIDS) derivatives meeting, Jun 2023, Copenhagen, Denmark. hal-04137329

HAL Id: hal-04137329

https://inria.hal.science/hal-04137329

Submitted on 22 Jun 2023

HAL is a multi-disciplinary open access
archive for the deposit and dissemination of sci-
entific research documents, whether they are pub-
lished or not. The documents may come from
teaching and research institutions in France or
abroad, or from public or private research centers.

L'archive ouverte pluridisciplinaire HAL, est
destinée au dépôt et à la diffusion de documents
scientifiques de niveau recherche, publiés ou non,
émanant des établissements d'enseignement et de
recherche français ou étrangers, des laboratoires
publics ou privés.

<figure><img src="image_1.png" /></figure>

Distributed under a Creative Commons Attribution 4.0 International License
<figure><img src="image_2.png" /></figure>

# BIDS-Prov
Recording neuroimaging provenance

Camille Maumet

Inria, Univ Rennes, Inserm, CNRS, IRISA
# The BIDS-Prov Team

## BIDS Extension Proposal 28

**Moderators:** Satra Ghosh and Camille Maumet

**Contributors:** Rémi Adon, Tibor Auer, Stefan Appelhoff, Thomas Betton, Hermann Courteille, Michael Dayan, Eric Earl, Dorota Jarecka, Yaroslav Halchenko, Matthieu Joulot, Chris Markiewicz, Cyril R. Pernet, Jean-Baptiste Poline, Cyril Regan, Omar El Rifai, Sarah Saneei, Ghislain Vaillant.

Thank you!

<figure><img src="image_3.png" /></figure>

BIDS
BRAIN IMAGING DATA STRUCTURE

<figure><img src="image_4.png" /></figure>

enabling open and
FAIR neuroscience

**BIDS steering committee:** Guiomar Niso, Melanie Ganz, Robert Oostenveld, Russell Poldrack, Ariel Rokem.

**BIDS maintainers:** Stefan Appelhoff, Chris Markiewicz, Franklin Feingold, Taylor Salo, Rémi Gau, Ross Blair, Anthony Galassi, Eric Earl, Christine Rogers.
# What is BIDS-Prov?

<figure><img src="image_5.png" /></figure>
# What is BIDS-Prov?

<figure><img src="image_6.png" /></figure>

my_dataset/

<figure><img src="image_7.png" /></figure>

participants tsv

<figure><img src="image_8.png" /></figure>

sub-01/

<figure><img src="image_9.png" /></figure>

anat/

<figure><img src="image_10.png" /></figure>

sub-01_T1w.nii.gz

<figure><img src="image_11.png" /></figure>

func/

BIDS
"raw"

<figure><img src="image_12.png" /></figure>

<figure><img src="image_13.png" /></figure>

<figure><img src="image_14.png" /></figure>

my_dataset/

<figure><img src="image_15.png" /></figure>

participants tsv

<figure><img src="image_16.png" /></figure>

sub-01/

<figure><img src="image_17.png" /></figure>

BIDS-derivatives
(NIDM-Results)

<figure><img src="image_18.png" /></figure>
# What is BIDS-Prov?

<figure><img src="image_19.png" /></figure>

my_dataset/

<figure><img src="image_20.png" /></figure>

participants tsv

<figure><img src="image_21.png" /></figure>

sub-01/

<figure><img src="image_22.png" /></figure>

anat/

<figure><img src="image_23.png" /></figure>

sub-01_T1w.nii.gz

<figure><img src="image_24.png" /></figure>

func/

BIDS
"raw"

<figure><img src="image_25.png" /></figure>

<figure><img src="image_26.png" /></figure>

BIDS-Prov

<figure><img src="image_27.png" /></figure>

BIDS-derivatives
(NIDM-Results)

<figure><img src="image_28.png" /></figure>

my_dataset/

<figure><img src="image_29.png" /></figure>

participants tsv

<figure><img src="image_30.png" /></figure>

sub-01/

<figure><img src="image_31.png" /></figure>
# Goal of BIDS-Prov

* Describing **the provenance** of a BIDS dataset.

* Description is **retrospective**, i.e. set of steps that were executed in order to obtain the dataset.
# Why BIDS-Prov?

* BIDS focus on metadata that will maximize the **(re)usability** of datasets

* E.g. onsets for task-fMRI

* Relies on expert knowledge to identify metadata that “matter”

* But for derived datasets this can get complicated...
# What is a reusable derived dataset?

* Can depend on the software package (different stopping points) → Paul

* We sometimes lack expert knowledge to identify metadata that "matter" in neuroimaging pipelines
**Understanding** analytical variability...

?

<figure><img src="image_32.png" /></figure>
**Understanding** analytical variability...

?

<figure><img src="image_33.png" /></figure>

Numerical
uncertainty
(e.g. ≠ OS)

[Glatard 2015,
Kiar 2021]

Different
implen.

Unwanted
variability

[Gronenschild 2012,
Bowring 2019]
**Understanding** analytical variability...

?

<figure><img src="image_34.png" /></figure>

Numerical
uncertainty
(e.g. ≠ OS)

Assumption
violations

Unwanted
variability

Different
implen.

Unreliable
results

Data
induced
variability
# Understanding analytical variability...

?

Better fit to the data

Variability of interest

Assumption violations

<figure><img src="image_35.png" /></figure>

Numerical uncertainty (e.g. ≠ OS)

Unreliable results

Data induced variability

Different implem.

Unwanted variability
# What is a reusable derived dataset?

* Can depend on the software package (different stopping points) → Paul

* We sometimes lack expert knowledge to identify metadata that "matter" in neuroimaging pipelines

* Expert knowledge can evolve and in that case it is really useful to be able and go back to previous studies.
# What is a reusable derived dataset?

* Can depend on the software package (different stopping points) → Paul

* We sometimes lack expert knowledge to identify metadata that "matter" in neuroimaging pipelines

* Expert knowledge can evolve and in that case it is really useful to be able and go back to previous studies.

We need detailed description of "what happened" to a dataset (i.e. provenance)
# Provenance in neuroimaging software

* **AFNI history** is stored in the BRIK files

* **MINC** also has a mechanism to store provenance

* SPM stores some provenance in the **SPM.mat**, saving the **matlabbatch** as a batch script is also provenance.

* Similarly in FSL with the **fsf** files.

BIDS-Prov = an attempt at a software agnostic representation
# BIDS-Prov extension proposal

Key idea:

A common model to represent **chaining of processing** (for now no description of the 'meaning' of those processing)

<figure><img src="image_36.png" /></figure>
# BIDS-Prov extension proposal

Key idea:

A common model to represent **chaining of processing** (for now no description of the 'meaning' of those processing)

<figure><img src="image_37.png" /></figure>

BIDS-Prov files can be stored at two-levels:

* File-level provenance `<path-to-file><file-name-with-ext>.prov.jsonld`

* Dataset-level provenance `prov/[<subfolders>/*]<label>.prov.jsonld`
# BIDS-Prov extension proposal

## RDF

BIDS-Prov uses semantic web technologies and is based on the W3C PROV

<figure><img src="image_38.png" /></figure>

## BIDS

<figure><img src="image_39.png" /></figure>

BIDS
BRAIN IMAGING DATA STRUCTURE

<figure><img src="image_40.png" /></figure>

## JSON-LD
Example

{ "@context": "https://raw.github.com/bids-standard/BEP028_BIDSprov/master/context.json",
"BIDSProvVersion": "dev",
"records": {
  "prov:Agent": [
    {"@id": "urn:030f431e-c8bd-4ad2-a374-1f115df2930e",
      "RRID": "RRID:SCR_007037",
      "@type": "prov:SoftwareAgent",
      "label": "SPM",
      "version": "SPM12r7224"}
  ],
  "prov:Activity": [
    {"@id": "urn:d124a1ec-ede9-4c55-9f3b-5534ba2d4bf1",
      "label": "Segment",
      "used": [
        "urn:7d6b4ad3-03f6-4196-a307-35cc3bd624d6"
      ],
      "associatedWith": "urn:030f431e-c8bd-4ad2-a374-1f115df2930e",
      "command": "matlabbatch{7}.spm.spatial.preproc(channel.vols(1) = [...] }
    ],
  "prov:Entity": [
    {"@id": "urn:7d6b4ad3-03f6-4196-a307-35cc3bd624d6",
      "label": "anat_sub-01_T1w.nii",
      "generatedBy": "urn:771015e0-2dcd-4c90-b82f-1910bff41ca0"}
  ]}
```json
{
    "@context": "https://raw.github.com/bids-standard/BEP028_BIDSprov/master/context.json",
    "BIDSProvVersion": "dev",
    "records": {
        "prov:Agent": [
            {"@id": "urn:030f431e-c8bd-4ad2-a374-1f115df2930e",
              "RRID": "RRID:SCR_007037",
              "@type": "prov:SoftwareAgent",
              "label": "SPM",
              "version": "SPM12r7224"}
        ],
        "prov:Activity": [
            {"@id": "urn:d124a1ec-ede9-4c55-9f3b-5534ba2d4bf1",
              "label": "Segment",
              "used": [
                "urn:7d6b4ad3-03f6-4196-a307-35cc3bd624d6"
              ],
              "associatedWith": "urn:030f431e-c8bd-4ad2-a374-1f115df2930e",
              "command": "matlabbatch{7}.spm.spatial.preproc/channel.vols(1) = [...]"
            ],
        "prov:Entity": [
            {"@id": "urn:7d6b4ad3-03f6-4196-a307-35cc3bd624d6",
              "label": "anat_sub-01_T1w.nii",
              "generatedBy": "urn:771015e0-2dcd-4c90-b82f-1910bff41ca0"}
        ]}
```
# Example

```json
{
    "@context": "https://raw.github.com/bids-standard/BEP028_BIDSprov/master/context.json",
    "BIDSProvVersion": "dev",
    "records": {
        "prov:Agent": [
            {"@id": "urn:030f431e-c8bd-4ad2-a374-1f115df2930e",
               "RRID": "RRID:SCR_007037",
               "@type": "prov:SoftwareAgent",
               "label": "SPM",
               "version": "SPM12r7224"}
        ],
        "prov:Activity": [
            {"@id": "urn:d124a1ec-ede9-4c55-9f3b-5534ba2d4bf1",
               "label": "Segment",
               "used": [
                   "urn:7d6b4ad3-03f6-4196-a307-35cc3bd624d6"
               ],
               "associatedWith": "urn:030f431e-c8bd-4ad2-a374-1f115df2930e",
               "command": "matlabbatch{7}.spm.spatial.preproc/channel.vols(1) = [...]"
            ],
            "prov:Entity": [
                {"@id": "urn:7d6b4ad3-03f6-4196-a307-35cc3bd624d6",
                   "label": "anat_sub-01_T1w.nii",
                   "generatedBy": "urn:771015e0-2dcd-4c90-b82f-1910bff41ca0"}
            ]
        ]
    }
```
# Example

```json
{
    "@context": "https://raw.github.com/bids-standard/BEP028_BIDSprov/master/context.json",
    "BIDSProvVersion": "dev",
    "records": {
```

```json
        "prov:Agent": [
            {"@id": "urn:030f431e-c8bd-4ad2-a374-1f115df2930e",
              "RRID": "RRID:SCR_007037",
              "@type": "prov:SoftwareAgent",
              "label": "SPM",
              "version": "SPM12r7224"}
        ],
```

Software used

```json
        "prov:Activity": [
            {"@id": "urn:d124a1ec-ede9-4c55-9f3b-5534ba2d4bf1",
              "label": "Segment",
              "used": [
                "urn:7d6b4ad3-03f6-4196-a307-35cc3bd624d6"
              ],
              "associatedWith": "urn:030f431e-c8bd-4ad2-a374-1f115df2930e",
              "command": "matlabbatch{7}.spm.spatial.preproc.channel.vols(1) = [...] }
          ],
```

```json
        "prov:Entity": [
            {"@id": "urn:7d6b4ad3-03f6-4196-a307-35cc3bd624d6",
              "label": "anat_sub-01_T1w.nii",
              "generatedBy": "urn:771015e0-2dcd-4c90-b82f-1910bff41ca0"}
        ]}
```

```json
```

SPM
## Example

```json
{
    "@context": "https://raw.github.com/bids-standard/BEP028_BIDSprov/master/context.json",
    "BIDSProvVersion": "dev",
    "records": {
        "prov:Agent": [
            {"@id": "urn:030f431e-c8bd-4ad2-a374-1f115df2930e",
              "RRID": "RRID:SCR_007037",
              "@type": "prov:SoftwareAgent",
              "label": "SPM",
              "version": "SPM12r7224"}
        ],
        "prov:Activity": [
            {"@id": "urn:d124a1ec-ede9-4c55-9f3b-5534ba2d4bf1",
              "label": "Segment",
              "used": [
                "urn:7d6b4ad3-03f6-4196-a307-35cc3bd624d6"
              ],
              "associatedWith": "urn:030f431e-c8bd-4ad2-a374-1f115df2930e",
              "command": "matlabbatch{7}.spm.spatial.preproc/channel.vols(1) = [...]"
            ]},
        "prov:Entity": [
            {"@id": "urn:7d6b4ad3-03f6-4196-a307-35cc3bd624d6",
              "label": "anat_sub-01_T1w.nii",
              "generatedBy": "urn:771015e0-2dcd-4c90-b82f-1910bff41ca0"}
        ]}
}
```
# Example

```json
{
    "@context": "https://raw.github.com/bids-standard/BEP028_BIDSprov/master/context.json",
    "BIDSProvVersion": "dev",
    "records": {
        "prov:Agent": [
            {"@id": "urn:030f431e-c8bd-4ad2-a374-1f115df2930e",
              "RRID": "RRID:SCR_007037",
              "@type": "prov:SoftwareAgent",
              "label": "SPM",
              "version": "SPM12r7224"}
        ],
        "prov:Activity": [
            {"@id": "urn:d124a1ec-ede9-4c55-9f3b-5534ba2d4bf1",
              "label": "Segment",
              "used": [
                "urn:7d6b4ad3-03f6-4196-a307-35cc3bd624d6"
              ],
              "associatedWith": "urn:030f431e-c8bd-4ad2-a374-1f115df2930e",
              "command": "matlabbatch{7}.spm.spatial.preproc/channel.vols(1) = [...]"
            ]},
        "prov:Entity": [
            {"@id": "urn:7d6b4ad3-03f6-4196-a307-35cc3bd624d6",
              "label": "anat_sub-01_T1w.nii",
              "generatedBy": "urn:771015e0-2dcd-4c90-b82f-1910bff41ca0"}
        ]}
    }
}
```

<figure><img src="image_41.png" /></figure>

Processing applied ("steps")
## Example

```json
{
    "@context": "https://raw.github.com/bids-standard/BEP028_BIDSprov/master/context.json",
    "BIDSProvVersion": "dev",
    "records": {
        "prov:Agent": [
            {"@id": "urn:030f431e-c8bd-4ad2-a374-1f115df2930e",
              "RRID": "RRID:SCR_007037",
              "@type": "prov:SoftwareAgent",
              "label": "SPM",
              "version": "SPM12r7224"}
        ],
        "prov:Activity": [
            {"@id": "urn:d124a1ec-ede9-4c55-9f3b-5534ba2d4bf1",
              "label": "Segment",
              "used": [
                "urn:7d6b4ad3-03f6-4196-a307-35cc3bd624d6"
              ],
              "associatedWith": "urn:030f431e-c8bd-4ad2-a374-1f115df2930e",
              "command": "matlabbatch{7}.spm.spatial.preproc/channel.vols(1) = [...]"
            ],
        "prov:Entity": [
            {"@id": "urn:7d6b4ad3-03f6-4196-a307-35cc3bd624d6",
              "label": "anat_sub-01_T1w.nii",
              "generatedBy": "urn:771015e0-2dcd-4c90-b82f-1910bff41ca0"}
        ]}
    }
}
```

<figure><img src="image_42.png" /></figure>

Inputs and
outputs
# Example

```json
{
    "@context": "https://raw.github.com/bids-standard/BEP028_BIDSprov/master/context.json",
    "BIDSProvVersion": "dev",
    "records": {
        "prov:Agent": [
            {"@id": "urn:030f431e-c8bd-4ad2-a374-1f115df2930e",
              "RRID": "RRID:SCR_007037",
              "@type": "prov:SoftwareAgent",
              "label": "SPM",
              "version": "SPM12r7224"}
        ],
        "prov:Activity": [
            {"@id": "urn:d124a1ec-ede9-4c55-9f3b-5534ba2d4bf1",
              "label": "Segment",
              "used": [
                "urn:7d6b4ad3-03f6-4196-a307-35cc3bd624d6"
              ],
              "associatedWith": "urn:030f431e-c8bd-4ad2-a374-1f115df2930e",
              "command": "matlabbatch{7}.spm.spatial.preproc/channel.vols(1) = [...]"
            ],
        "prov:Entity": [
            {"@id": "urn:7d6b4ad3-03f6-4196-a307-35cc3bd624d6",
              "label": "anat_sub-01_T1w.nii",
              "generatedBy": "urn:771015e0-2dcd-4c90-b82f-1910bff41ca0"}
        ]}
    }
}
```

anat_sub-01_T1w.nii

Segment

SPM

Inputs and
outputs
# Real world examples

https://github.com/bids-standard/BEP028_BIDSprov/tree/master/examples/from_parsers

50+ examples in

* AFNI

* FSL

* SPM

<figure><img src="image_43.png" /></figure>
# Different "levels" of provenance

<figure><img src="image_44.png" /></figure>
Timeline and next steps

Tentative

Now

**Finalize Google doc for community review**

Combine latest changes into Google doc

Add more examples

Mid April

**Community review**

Initiate BIDS community discussion

Continue adding examples

End of May

**Open PR to BIDS specification**

OHBM

**Engage with software developers**

Make any final adjustments as necessary

End of June

**Merge**

Presented to
BIDS steering in
March 2022
# BIDS-Prov extension proposal

BIDS-Prov adds provenance information to the BIDS structure in the form of sidecar JSON-LD files, which constitute a graph of provenance information.

Open questions / thoughts:

* Some provenance is already in BIDS

* Different levels of provenance will enable different use cases

* Ability to keep track of provenance might depend on the application and the context (which metadata is available)

* Satra: Possibility to implement via message passing
BIDS-Prov

Recording neuroimaging provenance

Camille Maumet

<figure><img src="image_45.png" /></figure>

Thank you!

<figure><img src="image_46.png" /></figure>

<figure><img src="image_47.png" /></figure>