Relaxation of inheritance principle?

[Lestropie]

In working on a fairly wide-sweeping change proposal for BEP 016 (Diffusion derivatives), I've encountered a bit of a snag with respect to the existing spec, and want to see if there are any opinions on the matter in the wider community, since it's near the top of the specification hierarchy.

Tagging BEP016 owners: @oesteban @francopestilli

Relevant section of current spec:
https://github.com/bids-standard/bids-specification/blob/v1.2.0/src/02-common-principles.md#the-inheritance-principle

The problem

A key advantage of diffusion MRI is the sensitisation of images to, and subsequent modelling of, anisotropic information in each voxel. In the context of diffusion models, there are a wide range of formats in which data encapsulating such anisotropic information may be mapped to a NIfTI image (I'm currently up to 9). Many of these could easily be interpreted erroneously if adequate sidecar information were to not be provided alongside the raw image intensities.

I'll demonstrate why this presents a problem with an example. Here's the current state of my working proposal for representing the outcome of the Neurite Orientation Dispersion and Density Imaging (NODDI) model:

my_diffusion_pipeline/
    sub-01/
        dwi/
            sub-01_parameter-icvf_noddi.nii.gz
            sub-01_parameter-isovf_noddi.nii.gz
            sub-01_parameter-od_noddi.nii.gz
            sub-01_parameter-direction_noddi.nii.gz
            sub-01_parameter-direction_noddi.json
            sub-01_noddi.json

"icvf", "isovf" and "od" are 3D images containing quantitative scalar parameters from the model; "direction" is a 4D image with 3 volumes, which encode the estimated fibre orientation in each voxel.

Note that there are two JSON files in one directory here:

1. File "sub-01_noddi.json" contains information regarding the NODDI model, and any parameters related to the fitting of that model, which are therefore applicable to all output parameters from the model.

2. File "sub-01_parameter-direction_noddi.json" contains only data relevant for the correct interpretation of the fibre orientation data contained within image "sub-01_parameter-direction_noddi.nii.gz", which are not applicable to the other parameter images; this includes the data representation used to encode such orientation information within the NIfTI image, and the reference axes with respect to which the directions are defined.

This design however clashes with the existing spec:

Any metadata file ... may be defined at any directory level, but no more than one applicable file may be defined at a given level ...

Non-ideal solutions

Representation of the output of this model whilst conforming to the quoted spec could potentially be achieved with one of the following approaches (none of which I'm wholly content with):

• Concatenating all model parameters into a single 4D image, in some pre-determined order. This would however make the model parameters less navigable, and interpretation of model data more dependent on details contained within the specification describing the order of the parameters, than the proposal above; it would also make it more difficult to store derivatives of some model not yet embedded within the spec in a manner consistent with the spec, as well as more complex models that generate multiple different forms of output parameters.

• Having one JSON file per parameter image, with fields applicable to all parameter images being duplicated across those JSON files. This however feel contrary the the point of having an inheritance principle in the first place (and being a coder I don't like duplication).

• Enforcing particular conventions for orientation data representation for particular models. This however also makes interpretation of derivative data more dependent on details within the spec, and precludes storing data from a novel model in a manner "spiritually consistent" with the spec.

• Creating a sub-directory within dwi/ for the model, with a JSON sitting in the dwi/ directory with the same name as the diffusion model directory (for storing model description and input model parameters), and optionally providing specific JSON files for specific images within the model output directory. One potential disadvantage here, over and above not really conforming to the existing filesystem conventions, is that if such directories were to be named according to some label identifier for the particular model, it would not be possible to store the results of more than one instance of that model for one session (not cleanly anyway).

• Forcing inclusion of relevant labels within the filename; i.e. the name of file "sub-01_parameter-direction_noddi.nii.gz" would need to be extended to include information that I would otherwise prefer to encapsulate within file "sub-01_parameter-direction_noddi.json". File names would get very ugly very quickly.

Proposal

What I am instead proposing is relaxation of the inheritance principle. That is: permitting multiple applicable metadata files of a particular type within a single directory; and for a particular data file (e.g. NIfTI image), the metadata files within that directory applicable to that data file are determined based on:

• All labels present in the metadata file being a precise match to the corresponding label in the data file;

• No labels present in the metadata file that are not present in the data file.

Therefore, for image "sub-01_parameter-direction_noddi.nii.gz", files "sub-01_parameter-direction_noddi.json" and "sub-01_noddi.json" would both be applicable, with precedence applied appropriately.

There's some gotchas that would need to be considered ahead of time in order to make such a change to the spec well-posed - and doing so would perhaps need to wait for a 2.0 spec - but I want to fish for feedback (positive or negative) before putting more energy into something that may not be merge-able.