Title

IP-Freely: Free manipulation of BIDS datasets according to the Inheritance Principle

Short description and the goals for the OHBM BrainHack

The Inheritance Principle (“IP”) has been a feature of the Brain Imaging Data Structure (BIDS) since its inception. It describes how the metadata relevant to one specific data file may in fact originate from multiple metadata files, and how metadata defined in one location may apply to multiple data files. These can both reduce redundancy and communicate the intrinsic hierarchical structure of the dataset. This however comes at considerable complexity to the specification itself and the software responsible for interfacing with such data. Indeed nearly a decade after its creation, many software APIs for parsing BIDS data still do not support the Inheritance Principle.

There is a dearth of existing software tools for managing the IP. If a dataset that exploits the IP were provided as input to a BIDS App that is naive to the IP, that App could perform improper association of metadata. Existing datasets may contain substantial metadata redundancy, due to not currently having an easy way through which to exploit the IP.

The future of the IP is at a crossroads, particularly as work progresses toward BIDS 2.0:

• On one hand, some would like for the IP to disappear entirely: all metadata relevant to any given data file would need to be stored in a sidecar metadata file alongside that data file, regardless of the extent of duplication.
• On the other, not just preserving the IP but augmenting it could better communicate the complex hierarchical dependencies of complex datasets, particularly derivative data.
• The potential impact that the existence of the Inheritance Principle has (or could have) had on existing datasets is impossible to ascertain.

The goals of this project are:

1. Commence construction of a BIDS App that is responsible for:

   • Detecting the presence or absence of the Inheritance Principle in any given BIDS dataset
   • Manipulating that dataset to either remove all uses of the Inheritance Principle or make maximal use of the Inheritance Principle under some ruleset.

2. Manually create a dataset that encapsulates all of the different manifestations of the Inheritance Principle, with multiple instantiations with and without use of the Principle. This will then act as a reference dataset against which the operation of the software tool can be verified.

Link to the Project

https://github.com/Lestropie/IP-freely

Image/Logo for the OHBM brainhack website

https://raw.githubusercontent.com/ohbm/hackathon2025/refs/heads/main/src/_img/BIDS_IP_Freely.png

Project lead

Robert Smith; GitHub: @Lestropie; Discord: @Lestropie

Main Hub

Brisbane

Link to the Project pitch

No response

Other hubs covered by the leaders

• Brisbane
• Hybrid (Asia / Pacific)
• Hybrid (Europe / Middle East / Africa)
• Hybrid (Americas)

Skills

• Python: Moderate

  The code logic for manipulating metadata will necessitate some competence with Python dictionaries; nothing super complex, but maybe not accessible for someone who has never touched them. Expect to make use of the pathlib module. If any contributor were to have existing expertise with pybids that may also be beneficial.

• BIDS: Variable

  The necessary fundamentals of BIDS are just filesystem structure (directories, entities and suffices) and the idea of a metadata dictionary. However creation of exemplar datasets would be facilitated by someone who:

  • Has experience with BIDS across multiple modalities
  • Has some familiarity with the Inheritance Principle.

• git: Basic preferred

  All contributions will be made through git. Some experience with such would therefore be beneficial. A lack of experience with such is however not a deal-breaker; this project can be an opportunity to walk people through their first commits.

Recommended tutorials for new contributors

• Current status of the Inheritance Principle: https://bids-specification.readthedocs.io/en/stable/common-principles.html#the-inheritance-principle

• Original context that motivated pursuit of augmentation of the Inheritance Principle: Decisions on BIDS derivatives structure bids-standard/bids-bep016#50

• Previously proposed (but rejected) extension of the Inheritance Principle: [ENH] Inheritance principle: Relaxation allowing multiple files per directory bids-standard/bids-specification#1003 (and other threads linked therein)

• Existing repository that contains data-empty exemplar datasets for the purpose of validation: https://github.com/bids-standard/bids-examples

• Discussion regarding potential modification of Inheritance Principle for BIDS 2.0: Replace "inheritance" with "summarization" principle bids-standard/bids-2-devel#65

Good first issues

For anyone not accustomed to open source projects, perhaps the most accessible entrypoint will be the construction of one or more exemplar datasets: Lestropie/IP-freely#5

Twitter summary

Q: What is the Inheritance Principle in BIDS?
A: A simple yet strong relational database mechanism, a source of confusion, a progress block, a feature gap, an instigator of bar fights...
Can we resolve?

Short name for the Discord chat channel (~15 chars)

IP-Freely

Please read and follow the OHBM Code of Conduct

• I agree to follow the OHBM Code of Conduct during the hackathon