Skip to content

Commit 7a76b94

Browse files
yarikopticyarikoptic
committed
Small tune ups to formatting of JSONs and use .jsonld not .prov
1 parent f3aa34d commit 7a76b94

File tree

1 file changed

+113
-90
lines changed

1 file changed

+113
-90
lines changed

‎src/03-modality-agnostic-files.md‎

Lines changed: 113 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -404,10 +404,8 @@ suffer if an external repository would not be available anymore).
404404

405405
Template:
406406

407-
```Text
408-
- [Dataset level] prov.jsonld
409-
- [File level] sub-<label>/[ses-<label>/]sub-<label>[_ses-<label>]_<suffix>.prov
410-
```
407+
- **Dataset level**: `prov.jsonld`
408+
- **File level**: `sub-<label>/[ses-<label>/]sub-<label>[_ses-<label>]_<suffix>.jsonld`
411409

412410
Optional: Yes
413411

@@ -447,75 +445,93 @@ a collection of files or a specific file at any level_of the bids hierarchy.
447445

448446
v. Provenance information SHOULD be anonymized/de-identified as necessary.
449447

450-
### Examples of provenance in BIDS.
448+
### Examples
451449

452-
1. The raw conversion from DICOM images or other instrument native formats
450+
The conversion from DICOM images or other instrument native formats
453451
to BIDS structure, details of stimulus presentation and cognitive paradigms,
454452
and clinical and neuropsychiatric assessments, each come with their
455453
own details of provenance.
456-
```
457-
{ "identifier": "sub-01/anat/..._T1.nii.gz",
458-
"type": "NIfTIGZ",
459-
"checksum": {"type": "sha512",
460-
"value": "21231221ab4534..."
461-
},
462-
"derivedFrom": ["sourcedata/12345-1.dcm", "sourcedata/12345-2.dcm"],
463-
"generatedBy": {"started": 2019-01-10T10:00:00"
464-
"associatedWith": {"type": "softwareAgent",
465-
"name": "dcm2niix",
466-
"version": "2.0.0"},
467-
"commandLine": "dcm2niix ..."
468-
}
469-
}
454+
```JSON
455+
{
456+
"identifier": "sub-01/anat/..._T1.nii.gz",
457+
"type": "NIfTIGZ",
458+
"checksum": {
459+
"type": "sha512",
460+
"value": "21231221ab4534..."
461+
},
462+
"derivedFrom": [
463+
"sourcedata/12345-1.dcm",
464+
"sourcedata/12345-2.dcm"
465+
],
466+
"generatedBy": {
467+
"started": "2019-01-10T10:00:00",
468+
"associatedWith": {
469+
"type": "softwareAgent",
470+
"name": "dcm2niix",
471+
"version": "2.0.0"
472+
},
473+
"commandLine": "dcm2niix ..."
474+
}
475+
}
476+
```
470477
which inputs from the BIDS dataset were used together with what software was
471478
run in what environment and with what parameters.
472-
```
473-
{ "identifier": "derivatives/freesurfer/sub-01/mri/orig/001.mgz",
474-
"type": "MGZ",
475-
"checksum": {"type": "sha512",
476-
"value": "121231221ab4534..."
477-
},
478-
"derivedFrom": "sub-01/anat/..._T1.nii.gz",
479-
"generatedBy": {"started": 2019-01-10T10:00:00"
480-
"associatedWith": {"type": "softwareAgent",
481-
"name": "FreeSurfer",
482-
"uri": "RRID:SCR_001847",
483-
"version": "6.0.0"},
484-
"commandLine": "mri_convert ..."
485-
}
486-
}
479+
```JSON
480+
{
481+
"identifier": "derivatives/freesurfer/sub-01/mri/orig/001.mgz",
482+
"type": "MGZ",
483+
"checksum": {
484+
"type": "sha512",
485+
"value": "121231221ab4534..."
486+
},
487+
"derivedFrom": "sub-01/anat/..._T1.nii.gz",
488+
"generatedBy": {
489+
"started": "2019-01-10T10:00:00",
490+
"associatedWith": {
491+
"type": "softwareAgent",
492+
"name": "FreeSurfer",
493+
"uri": "RRID:SCR_001847",
494+
"version": "6.0.0"
495+
},
496+
"commandLine": "mri_convert ..."
497+
}
498+
}
499+
```
487500
involved in a study.
488-
```
489-
{
490-
"@context": "https://some/url/to/bids_context.jsonld",
491-
"identifier": "http://example.org/ds00000X",
492-
"generatedBy": {
493-
"type": "Project",
494-
"uri": "https://banda.mit.edu/",
495-
"startedAt": "2016-09-01T10:00:00",
496-
"wasAssociatedWith": {
497-
"type": "Organization",
498-
"uri": "NIH",
499-
"role": "Funding"},
500-
},
501-
"wasAttributedTo": {
502-
"type": "Person",
503-
"name": "Prof. Smith",
504-
"uri": "ORCID:0123",
505-
"role": "PI"}
506-
}
501+
```JSON
502+
{
503+
"@context": "https://some/url/to/bids_context.jsonld",
504+
"identifier": "http://example.org/ds00000X",
505+
"generatedBy": {
506+
"type": "Project",
507+
"uri": "https://banda.mit.edu/",
508+
"startedAt": "2016-09-01T10:00:00",
509+
"wasAssociatedWith": {
510+
"type": "Organization",
511+
"uri": "NIH",
512+
"role": "Funding"
507513
}
514+
},
515+
"wasAttributedTo": {
516+
"type": "Person",
517+
"name": "Prof. Smith",
518+
"uri": "ORCID:0123",
519+
"role": "PI"
520+
}
521+
}
522+
```
508523
appropriate attribution to the original dataset generators as well as
509-
future transformers.
510-
5. For datasets and derivatives, provenance can also include details of
524+
future transformers.
525+
526+
For datasets and derivatives, provenance can also include details of
511527
why the data were collected in the first place covering hypotheses, claims,
512528
and prior publications. Provenance can encode support for which claims were
513529
supported by future analyses.
514530

515531
### Justification for Separating Provenance from file JSON
516532

517533
Provenance is information about a file, including any metadata that is relevant
518-
to the file itself. Thus any BIDS data file and its associated JSON sidecar
534+
to the file itself. Thus, any BIDS data file and its associated JSON sidecar
519535
metadata together constitute a unique entity. As such, one may want to record
520536
the provenance of the JSON file as much as the provenance of the BIDS file.
521537
In addition, separating the provenance as a separate file for now, allows
@@ -534,34 +550,40 @@ BIDS derived data. One option is to make use of
534550
In this example, with this `prov.jsonld` file we encode that the T1.mgz file
535551
was generated by version 6 of the FreeSurfer software.
536552

537-
```json
553+
```JSON
538554
{
539555
"@context": "https://some/url/to/bids_context.jsonld",
540556
"identifier": "http://example.org/ds00000X",
541557
"generatedAt": "2020-01-10T10:00:00",
542558
"generatedBy": {
543-
"type": "Project",
544-
"uri": "https://banda.mit.edu/",
545-
"startedAt": "2016-09-01T10:00:00",
546-
"wasAssociatedWith": { "type": "Organization",
547-
"uri": "NIH",
548-
"role": "Funding"
549-
}
550-
},
559+
"type": "Project",
560+
"uri": "https://banda.mit.edu/",
561+
"startedAt": "2016-09-01T10:00:00",
562+
"wasAssociatedWith": {
563+
"type": "Organization",
564+
"uri": "NIH",
565+
"role": "Funding"
566+
}
567+
},
551568
"records": [
552-
{ "identifier": "derivatives/freesurfer/sub-01/mri/orig/001.mgz",
569+
{
570+
"identifier": "derivatives/freesurfer/sub-01/mri/orig/001.mgz",
553571
"type": "MGZ",
554-
"checksum": {"type": "sha512",
555-
"value": "121231221ab4534..."
556-
},
572+
"checksum": {
573+
"type": "sha512",
574+
"value": "121231221ab4534..."
575+
},
557576
"derivedFrom": "sub-01/anat/..._T1.nii.gz",
558-
"generatedBy": {"started": 2019-01-10T10:00:00"
559-
"associatedWith": {"type": "softwareAgent",
560-
"name": "FreeSurfer",
561-
"uri": "RRID:SCR_001847",
562-
"version": "6.0.0"},
563-
"commandLine": "mri_convert ..."
564-
}
577+
"generatedBy": {
578+
"started": "2019-01-10T10:00:00",
579+
"associatedWith": {
580+
"type": "softwareAgent",
581+
"name": "FreeSurfer",
582+
"uri": "RRID:SCR_001847",
583+
"version": "6.0.0"
584+
},
585+
"commandLine": "mri_convert ..."
586+
}
565587
}
566588
]
567589
}
@@ -570,14 +592,13 @@ was generated by version 6 of the FreeSurfer software.
570592
**File level provenance.** This follows some of the same concepts at the dataset
571593
level, but is specifically about the current file under consideration.
572594

573-
```bash
595+
```Text
574596
sub-01/
575597
func/
576598
sub-01_task-xyz_acq-test1_run-1_bold.nii.gz
577599
sub-01_task-xyz_acq-test1_run-1_prov.jsonld
578-
...
579600
```
580-
```json
601+
```JSON
581602
{
582603
"@context": "https://some/url/to/bids_context.jsonld",
583604
"generatedAt": "2020-01-10T10:00:00",
@@ -588,25 +609,26 @@ sub-01/
588609
"version": "1.3.0",
589610
"RRID": "RRID:SCR_017427",
590611
"label": "SPM",
591-
"description": "If this is a custom script, treat this as a methods section",
612+
"description": "If this is a custom script, treat this as a methods section"
592613
}
593614
}
594615
```
595616

596-
The NIDM extensions (nidash.org) to the PROV model would allow one to
617+
# TODO: check for better url than https://nidash.org which just says "Use your astrocytes!"
618+
The NIDM extensions ([nidash.org](https://nidash.org)) to the PROV model would allow one to
597619
incorporate many aspects of the neuroimaging research workflow from data to
598620
results. This includes capturing who performed data collection,
599621
what software were used, what analyses were run, and what hardware and
600-
software resources (e.g., operating system and dependencies) were used.
622+
software resources (for instance, operating system and dependencies) were used.
601623

602624
### BIDS JSON-LD context
603625

604626
For most developers and users, the context will appear in the jsonld file as:
605627

606-
```json
628+
```JSON
607629
{
608630

609-
"@context": "https://some/url/to/bids_context.jsonld",`
631+
"@context": "https://some/url/to/bids_context.jsonld",
610632
...
611633
}
612634
```
@@ -615,7 +637,7 @@ Details of the context, will encode terminology that is consistent across BIDS
615637
and may itself involve separate context files.
616638
so `"https://some/url/to/bids_context.jsonld"` could look like:
617639

618-
```json
640+
```JSON
619641
{
620642

621643
"@context": ["https://some/url/to/bids_common_context.jsonld",
@@ -636,7 +658,7 @@ vocabularies whenever possible.
636658
Example context: Common
637659

638660
[https://some/url/to/bids_common_context.jsonld]()
639-
```json
661+
```JSON
640662
{
641663
"@context": {
642664
"RepetitionTime": {
@@ -652,7 +674,7 @@ Example context: Common
652674
Example context: Provenance
653675

654676
[https://some/url/to/bids_provenance_context.jsonld]()
655-
```json
677+
```JSON
656678
{
657679
"@context": {
658680
"generatedAt": {
@@ -667,8 +689,9 @@ Example context: Provenance
667689
"@id": "http://www.w3.org/ns/prov#wasDerivedFrom",
668690
"@type": "@id"
669691
},
670-
"RRID": {"@id": "https://schema.org/identifier", "@type": "@id"}
671-
"sha512": {"@id": "http://id.loc.gov/vocabulary/preservation/cryptographicHashFunctions/sha512", "@type": "@id"}
692+
"RRID": {"@id": "https://schema.org/identifier", "@type": "@id"},
693+
"sha512": {"@id": "http://id.loc.gov/vocabulary/preservation/cryptographicHashFunctions/sha512",
694+
"@type": "@id"}
672695
},
673696
...
674697
}

0 commit comments

Comments
 (0)