Use-case(s): BIDS-inspired/like standards

[yarikoptic]

Quite often projects do not adopt BIDS due to complexity or not perfect fit, and then establish new a file layout and/or metadata convention/standard while saying they are "BIDS-like". The likeness varies greatly. Quite often it is simply the aspect of having folders and file names with some metadata in them. Those are not worth mentioning here. But there is a good number of BIDS-like standards (in my words - formalized descriptions adopted by a considerable number of people) which are worth reviewing and analyzing for what could minimize divergence between them and current BIDS through possibly introducing missing but reasonable and desired features into BIDS 2.0.

This issue would be used to collect pointers and possibly summarize rationale and major features behind them.

DANDI layout

Established by me and @satra for https://dandiarchive.org, primarily due to complete lack of usable standard/layout at that earlier point in time .

• There is no specification, and layout is largely "enforced" via dandi organize command on a set of .nwb files.
• dandiset.yaml schema is defined within pydantic model in https://github.com/dandi/dandi-schema/blob/master/dandischema/models.py#L1405
• see Convergence between DANDI Layout and BIDS dandi/dandi-cli#1498

Notable divergences:

• no dataset_description.json - metadata is in "in-house" dandiset.yaml
• no ses-*/ level subfolder but there is ses- entity in the target filenames (convergence possible through Make it possible to specify folders layout to be other than sub-{label}/[ses-{label}/] #54)
• no datatype (AKA modality) subfolder (related: Change modality directories to entity format #55, convergence possible through Make it possible to specify folders layout to be other than sub-{label}/[ses-{label}/] #54)
• main file format is .nwb (convergence through https://bids.neuroimaging.io/bep032 for animal ephys data, discussed/not (yet) accepted in BIDS 1.0 for micr/: Allow for .nwb standard/file format to be used for "micr" bids-specification#1632)
• entity labels/values could contain - and +. (TODO: ref BIDS PR)
• Suffix can contain + (no PR yet I think)
• Suffix contains (often multiple) data modalities contained within the single .nwb file, concatenated with +

PsychDS

https://psych-ds.github.io/ https://github.com/psych-ds/psych-DS (attn @mekline and @bleonar5 - would appreciate details/feedback alike for DANDI here or in a dedicated issue/doc)

• Overall motivation: Re-use BIDS schema formalization to derive a customized subset of the BIDS standard to simplify domain specific use and adoption.

NeuroBlueprint

https://neuroblueprint.neuroinformatics.dev/latest/specification.html .
Request for summarization of rationale/divergences: neuroinformatics-unit/NeuroBlueprint#51

SPARC Data Structure (SDS)

The SPARC platform has a preprint online that describes a BIDS inspired data structure: https://www.biorxiv.org/content/10.1101/2021.02.10.430563v2. Rough details are also on their wiki.

• Example dataset online: https://sparc.science/datasets/382?datasetDetailsTab=files and in https://metacell.github.io/sds-viewer/?doi=10.26275%2Fcheq-otb2
• Document on "population, specimen, subject, sample"

TemplateFlow

https://www.templateflow.org/usage/archive/#acceptable-data-types

• A related discussion "has happened" in BEP Proposal: Atlas specification bids-specification#1281

Brain-Development.org Atlas

https://brain-development.org/brain-atlases/atlases-from-the-dhcp-project/cortical-surface-template/ describes itself as "using BIDS conventions", and proceeds to define custom entities and metadata.

NiPoppy

Study-level description which includes bids dataset and uses some conventions (like derivatives/ subfolder with clearer defined naming convention).

• Add DatasetType="project" and rework existing "layout" example into a proper BIDS dataset bids-specification#1861 attempts to converge NiPoppy and BIDS

CAPS

ClinicA Processed Structure:

When the development of Clinica started in 2015, the BIDS specifications did not provide specific rules for the processed data. As a result, the goal of CAPS (designed by the Aramis Lab) was to define a hierarchy for the data processed using Clinica. The idea is to include in a single folder all the results of the different pipelines and organize the data following the main patterns of the BIDS specification.

Several differences exist between the BIDS and CAPS specifications.

• Instead of the BIDS derivatives/ folder, the processed data are stored in the CAPS folder.
• CAPS assumes that the session is always present in a BIDS dataset even though there is a single session. In other words, all datasets are considered longitudinal, even when they have only one session.
• NIfTI files generated by a Clinica pipeline are always compressed. Compression is recommended by the BIDS specification but not mandatory.

b2ai-voice

@satra pointed to https://docs.b2ai-voice.org/ where BIDS-inspired organization was also used and looked like

└── sub-<participant_id>
    ├── ses-<another_session_id>
    │   ├── beh
    │   │   ├── sub-<participant_id>_ses-<session_id>_task-<task_name>_run-<index>_metadata.json
    │   │   └── sub-<participant_id>_ses-<session_id>_task-<task_name>_run-<index>_response.json
    │   └── voice
    │       ├── sub-<participant_id>_ses-<session_id>_task-<task_name>_run-<index>_audio.wav
    │       ├── sub-<participant_id>_ses-<session_id>_task-<task_name>_run-<index>_features.pt
    │       ├── sub-<participant_id>_ses-<session_id>_task-<task_name>_run-<index>_metadata.json
    │       └── sub-<participant_id>_ses-<session_id>_task-<task_name>_run-<index>_transcript.txt

much relevant to that particular use-case is the

• BEP for audio/video capture of behaving subjects bids-specification#1771

EBRAINS: Clinical Connectome

No publicly shared (yet) spec. Shared at BIDS meeting: EBRAINS_WP2_New_proposed_Data-Management-Plan_BIDS-like.docx .

TODOs:

• represent/quantify divergences from BIDS in form of a table. Dimensions/features
  • need for extra entities
  • need for alternative folders hierarchy
    • need for new modalities
  • need for other file formats (there MINC BIDS?)

Mermaid diagram for above

---
config:
  layout: dagre
---
flowchart LR
  OpenfMRI --Inspired--> BIDS-project
  %% & BIDS-stats-models
 
  subgraph BIDS-project

    BIDS 
    BEP028["<a href=https://bids.neuroimaging.io/bep028>BEP028:Prov</a>"] -.->BIDS
    BEP032["<a href=https://bids.neuroimaging.io/bep032>BEP032:Microphys</a>"] -.->BIDS
    PR1972["<a href=https://github.com/bids-standard/bids-specification/pull/1972>#1972: DatasetType=project</a>"] -.->BIDS
    BIDS-stats-models
    BIDS2["<a href=https://github.com/orgs/bids-standard/projects/10>BIDS 2.0</a>"]
    BIDS2 -.make more modular,consistent,flexible.-> BIDS
  end

  BIDS --allowed for--> supplements
  BIDS --inspired--> bids-like
  BIDS --basis for--> bids-schema-based
  %% bids-canna-be -.could converge.-> BIDS

  subgraph bids-like["BIDS-like
  more at <a href=https://github.com/bids-standard/bids-2-devel/issues/62>bids-2-devel/issues/62</a>"]

    DANDI("<a href=https://github.com/dandi/dandi-cli/issues/1498>DANDI</a>")
    DANDI -.->BEP032
    DANDI -.->BIDS2
    NeuroBlueprint("<a href=https://neuroblueprint.neuroinformatics.dev/specification.html>NeuroBlueprint</a>")
    
    SDS("<a href=https://neuroblueprint.neuroinformatics.dev/specification.html>SDS(SPARC)</a>")
    TemplateFlow
    Brain-Development.org-Atlas
    CAPS("<a href=https://aramislab.paris.inria.fr/clinica/docs/public/latest/CAPS/Introduction/>CAPS</a>")
    b2ai-voice("<a href=https://docs.b2ai-voice.org>b2ai-voice</a>")
  end

  subgraph bids-schema-based[Reuse BIDS schema machinery]
    PsychDS[<a href=http://psychds-docs.readthedocs.io/>PsychDS</a>]
  end

  subgraph bids-canna-be
    Nipoppy -.could converge on.->PR1972
  end


  %% TODO: revert arrow back, place 
  %% bids-canna-be --> BIDS
  subgraph supplements["Supplements (BIDS-'valid')
    rely on adding extra metadata"
    ]
    
    subgraph ldbids["Linked BIDS"]
        Neurobagel("<a href=https://neurobagel.org>Neurobagel</a>")
        NIDM-Terms
    end
    converters["dcm2niix,heudiconv"] -.->BEP028
  end

  style OpenfMRI stroke:#000000,fill:#F2F7D2 
  %% C3EFE0

  style BIDS stroke:#000000,fill:#BEF6AC
  style BIDS-stats-models stroke:#000000,fill:#BEF6AC

  style supplements stroke:#000000,fill:#F6ACD8
  style bids-schema-based stroke:#000000,fill:#F6ACD8
  style bids-canna-be stroke:#000000,fill:#F6ACD8
  style bids-like stroke:#000000,fill:#F6ACD8

Loading

[satra]

ping @tgbugs for SPARC info on bids-like

[dorahermes]

SPARC Data Structure (SDS)

The SPARC platform has a preprint online that describes a BIDS inspired data structure: https://www.biorxiv.org/content/10.1101/2021.02.10.430563v2. Rough details are also on their wiki.

edit by @yarikoptic : thanks -- added

[satra]

also pinging @saskiad and @dyf for bids inspired data container for the allen institute for neural dynamics

[yarikoptic]

also pinging @saskiad and @dyf for bids inspired data container for the allen institute for neural dynamics

after review with @dyf we agreed that it was a little too distant from BIDS, at most indeed just "inspired" ;), so we have it as

• a separate issue: Use-case: AIND schema #60

[satra]

that's good. although, i'm not quite sure that use-case is too distant. practically speaking, we run into that issue with ukbiobank and any of the large datasets where we need to process a few subjects with bids-apps. we have had to create sub-bids to satisfy bids and hence tools like fmriprep. one could say that bids should not care about that. however, a self-contained single subject/session subset would be a relevant use-case in bids i believe.

ps. the challenge has been that bids has the different levels of consolidation of information: grouped (participants, sessions, etc) inheritance (via jsons), and single (the files). this necessitates a connected structure that relies on those pieces of information. the advantage of bids is efficiency (for the grouped files; although longitudinal data is inefficient) and deduplication (for the inheritance), and readability (single path+filename).

these different use cases may be good to consider in bids 2.

[effigies]

Will also add Templateflow: https://www.templateflow.org/usage/archive/#acceptable-data-types

• https://brain-development.org/brain-atlases/atlases-from-the-dhcp-project/cortical-surface-template/ describes itself as "using BIDS conventions", and proceeds to define custom entities and metadata.

[niksirbi]

Our NeuroBlueprint specification is definitely in the BIDS-inspired category. Together with @JoeZiminski we are working on putting together a list of divergences from BIDS and the rationale behind them.

[yarikoptic]

however, a self-contained single subject/session subset would be a relevant use-case in bids i believe.
...
these different use cases may be good to consider in bids 2.

@satra see

• Allow composition of a BIDS dataset (dataset level) from smaller (subj or subj/ses) level #59 which was born out of the Use-case: AIND schema #60 I have mentioned, and
• Make it possible to specify folders layout to be other than sub-{label}/[ses-{label}/] #54

May be we should add/promote upvoting via 👍 on the issues, so "go wild" ;)

[bleonar5]

I can share some context on Psych-DS if it's helpful, but I'm unsure how to comment on DANDI. Our data standard is pretty explicitly modeled on BIDS and our validator tool is a essentially a very pared-down fork of BIDS' recent deno implementation.

Definitely our reasoning for diverging instead of using BIDS directly or creating some sort of module within it has to do with complexity. A big part of the ethos of our project is simplicity, since we're trying to bring researchers with a lack of experience with explicit data standards into the fold of producing FAIR datasets. We designed our standard to be the minimal set of conventions for producing consistently-structured, machine-readable datasets with linked metadata, and we avoided the impulse to include additional advanced/options conventions or conventions governing the internal content of datafiles, because we figured that even the presence of this additional material in our documentation could scare off our target audience.

On a technical level, I noticed that the BIDS deno-based validator only applied rules to files that actually appeared within datasets, with no functionality to produce errors/issues in cases where certain elements were absent, and since this notion of presence/absence was important in our schema, that was one initial additional impetus for diverging with our own tool. Additionally, with Psych-DS 1.0 at least, we only wanted to validate simple tabular CSV data, and a lot of the structure of the BIDS validator had to do with applying different rules and conventions depending on datatype.

We followed BIDS' lead when it came to our usage of linkML for creating a structured model of our schema, and I definitely used BIDS' examples explicitly when developing our stack of tools, which was extremely helpful.

These are just a few random thoughts and pieces of context. Feel free to ask me anything specific and I can answer in detail. Also, I should mention that @mekline is on maternity leave until sometime this June/July and @ianchandlercampbell is our interim director for the project.

[yarikoptic]

That is very valuable insights @bleonar5 , thank for sharing!
Given that you seems to use BIDS schema, my short overarching summary would be to: Re-use BIDS schema formalization to derive a customized subset of the BIDS standard to simplify domain specific use and adoption. If I am totally off -- please correct me ;)

I noticed that the BIDS deno-based validator only applied rules to files that actually appeared within datasets, with no functionality to produce errors/issues in cases where certain elements were absent, and since this notion of presence/absence was important in our schema, that was one initial additional impetus for diverging with our own tool.

Could you elaborate here (or even as a dedicated issue against bids-validator, which is if not pertinent - could be closed) more on this since I am not fully grasping, since as to me bids-validator must error whenever any REQUIRED component (metadata or file) is missing.

Additionally, with Psych-DS 1.0 at least, we only wanted to validate simple tabular CSV data, and a lot of the structure of the BIDS validator had to do with applying different rules and conventions depending on datatype.

also sounds very intriguing and like something what could be generally applicable to BIDS. Could you elaborate more?

We followed BIDS' lead when it came to our usage of linkML for creating a structured model of our schema

do you have a link to linkML models handy?

[TheChymera]

@bleonar5 some of the links on the PsychDS README are broken, could you share a tree view of a dataset?

reasoning for diverging [...] has to do with complexity. A big part of the ethos of our project is simplicity,

I think that's also part of the ethos of BIDS, perhaps we could look into simplifying BIDS for 2.* as well. What are some of the key complexity concerns which made BIDS 1.* less attractive?

[bleonar5]

@yarikoptic My first response was a bit cursory and based on my memory of our initial rationales for diverging, I'll try to dig in a bit deeper here. I think your summary of our rationale was correct: we wanted to provide similar structures and standards to those that BIDS provides, for researchers that deal with behavioral data rather than complex physiological data. @satra informed us about the BIDS' team's development of a structured schema model in linkML, and this satisfied one of our core desiderata for the project, which was to have an externalized, structured schema that we could reference across validator tools in multiple frameworks (node, R, python). So, we used the combination of pruned-down versions of BIDS' in-development Deno validator and linkML schema as (very helpful) jumping off points for our own development, with proper citations and acknowledgements, of course.

@mekline has had a much longer history with the development of Psych-DS as an independent entity, and could possibly speak to our rationales for divergence much better, and she may be able to share more detailed thoughts on her return. One crucial element that I'm remembering now is a technical difference between the structure of most physio data and the behavioral data that we're interested in. Physiological data is so rich and often tied to multiple measurements over time, that it seems to be a standard assumption (and I think this is reflected in the BIDS spec) that datafiles will be organized around individual subjects/sessions. In a lot of behavioral datasets, this is not the case, as the whole set of responses for a given subject may be representable in a single row, and one datafile may represent the data gathered from an entire experiment. BIDS is complex and my knowledge of/experience with it only extends to the research I did prior to beginning development of the Psych-DS validator, but it seemed to us that following some kind of subject-oriented system of data organization would be necessary for compliance with BIDS, and this was a major rationale for divergence. (@TheChymera, I think this paragraph is the most relevant answer to your second question)

As for the matter of presence/absence of files/directories that I mentioned previously, I think this is actually just an issue with the deno-based validator rather than the older, public-facing validator. And the deno validator is still in development, so it may just be that I mistook a bug/unfinished component for an actual aspect of the BIDS spec. Basically, if you provide an otherwise-valid BIDS dataset that is missing an element (such as the dataset_description.json file) to the web validator, it produces an error as expected (DATASET_DESCRIPTION_JSON_MISSING). If you do the same with the deno validator, it outputs a VALID_DATASET result and does not report the absence of the required file. This is because the validator crawls the filetree of the dataset, finds whatever files/directories are present, and runs a series of checks on them based on the rules in the linkML schema. But if a core file is missing, the crawler never encounters the file in question, so the relevant rules that would assert the necessity of the file's presence are never applied. I could certainly create an issue for this if it's helpful, but I was unsure if it's appropriate given the fact that the validator has not been publicly released, and this feature may be scheduled for later in the development plan.

Here is a link to our linkML schema model as it currently stands (in development). At the moment it is not really intended to be used with the standard linkML validator library, and is more being used as just a structured, machine-readable implementation of our schema.

[bleonar5]

@TheChymera Here is a minimal Psych-DS file structure, from the Psych-DS spec document, whose contents we are in the process of integrating into a more holistic readthedocs site for the project/schema/validator

Thank you for the heads up about the dead links, I will do a once-over on our read me and take care of those ASAP