BIDS Extension Proposals: A Guide

Why contribute to BIDS?

When and how to start a BIDS Extension Proposal?

Advice for extending BIDS

Limit flexibility, consider tool developers

One of the aims of BIDS is to make reusing data easier. This means that when proposing an extension you need to put yourself in the shoes of someone who will receive a BIDS dataset and attempt to analyze it. Additionally, consider developers that will try to write tools that take BIDS datasets as inputs. It’s worth assessing how much additional code different ways of approaching your extension will lead to.

The most common situation where the trade-off between flexibility and ease of tool building comes up, is choosing file formats. For example, allowing multiple different file formats to be used to represent the same data type is flexible, but requires developers to provide support for all of them. As an example, iEEG-BIDS and EEG-BIDS surveyed the community to find out about most common formats and selected only a few formats based on usage and their openness.

Get the community involved

Try to reach out to colleagues working with the type of data you are trying to add support for. The more eyes you will get on your extension the better it will get.

Be consistent with the main specification

The main specification follows some general rules. For example, see the rules on participant labels.

Try not to deviate from those conventions in your extension.

Avoid backward incompatible changes

BIDS is already incorporated in many tools - proposing a change that will render already released BIDS datasets not BIDS compliant will cause a lot of confusion and will force developers to update their codes. We should strive to avoid such a situation.

Having said that, one day we will have to break backwards compatibility. If you have an idea for a backward incompatible change please add it as an issue to the BIDS 2.0 GitHub repository.

Use existing and common practices/formats

It’s likely that certain data types are commonly stored in a particular way in your subfield. If this is the case try adopting this way unless it makes your extension too inconsistent with the main specification. A good example of such adoption is the bvec/bval file format for storing diffusion metadata.

There are many standardization attempts out there. When proposing your extension consider gathering inspiration and directly linking to other standards. A good example of this is linking metadata fields to corresponding DICOM tags.

Common pitfalls

Relying on merging the extension on a set timeline

We have found that it is very difficult to predict how long a BIDS extension will take to merge into the standard. One challenge that has occurred in the past is a doctoral student requiring acceptance of their work as a requirement for graduation. We do not recommend yoking contributions to the BIDS community (or any volunteer-led open source community) to strict timelines to avoid the uncertainty around domain specific community engagement, feedback from the BIDS maintainers and broader developer community, and responding to those reviews.

Not considering domain- or field-specific guidelines

In many neuroscience fields there have been past developments and efforts to implement standards, either formally or informally; where possible BIDS extension proposals should embrace these rather than trying to come up with alternative standards. The BIDS extension proposal should therefore inventorize and review past and existing work that may be relevant to the BEP.

Not considering DICOM fields

Many of the modalities we use have an associated standard, like DICOM for instance. While BIDS is not specifically about data format, many metadata information are stored in data files and there is rarely a good reason for using a different name than one from other established standards. In using DICOM it is reasonable to check what DICOM has already developed and see if there is overlap. In a similar fashion, when relevant, we recommend having a sourcedata/ folder in example datasets including DICOM files (empty data but with a header, removing any personal data tags if taken from “real” data).

Not building up a user community to support the BEP

Merging BIDS extension proposals only happens following a community review. It is therefore helpful to get the stakeholders on board early on (i.e., while writing the extension proposal) rather than at the review stage. Diversity in the team contributes to the quality of the extension proposal; we recommend that the core team has representatives from 3 different labs, preferably also with a mix of more junior and more senior contributors. You may also consider requesting explicit support letters from external labs.

How to turn on email notifications about suggestions and comments for Google Documents