This content is being posted as a draft Pull Request in order to demonstrate the volume of changes generated during the OHBM 2025 Hackathon.
The code still requires further modification before the tool can be considered ready for broader uptake.

The following is a list of items flagged within the code base that need to be either addressed prior to making this first merge to master, or need to have a standalone Issue created to be addressed later.

• Check expected behaviour of metadata files other than JSON

  • Do all such files obey the "use only the nearest" rule under the Inheritance Principle,
    or are there some where it would be a violation for there to be more than one potential match
    regardless of what is stated within the Inheritance Principle?

  • Does this behaviour change as a function of Inheritance Principle ruleset?

  • Are there metadata file types outside of the MRI space I'm not aware of?

• Refactor detection of IP violations between full-graph and standalone-file functions

  Currently, the code responsible for generating a list of applicable metadata files per data file takes partial responsibility for detecting violations of the specified Inheritance Principle ruleset while the list is being generated.
  This however turned out to be the wrong location for much of that code.
  What I want instead is:

  1. Function that generates, for a specified data file, all possibly applicable metadata files, without observation of any specific IP ruleset.

  2. Function that, for a specified data files:

     1. Generates the list of candidate metadata files (step 1).
     2. Checks for violations of the IP for just that mapping.
     3. Prunes the lists if necessary: depending on metadata file extension, it may be only the "closest" metadata file that is ultimately deemed applicable

  3. Class Graph, which:

     1. Generates the list of candidate metadata files for all data files (step 1).
     2. Generates the full inverse mapping.
     3. Checks for all violations of the IP, since step 1 will no longer perform a partial check of such.
     4. Option to in-place prune the whole graph.

  This will have the added benefit of better distinguishing between errors that relate to general parsing of the BIDS dataset, and those that relate specifically to the Inheritance Principle.
  Currently these are distinguished by their relative Exception classes, but I think it would be better if they occurred at different points during processing.

  This may also come with corresponding changes to function names; eg. metadata "applicability".

• Implement check for currently overlooked Inheritance Principle rule.

  A metadata file is not permitted to be potentially applicable to some data file based on only looking at their relative file names, but for the metadata file to not reside in a parent directory of / the same directory as the data file.

• Improve checks of metadata association graph equivalency

  For proposal ruleset "I1195" where highly complex inheritance is permitted, it is possible for two metadata files that reside in the same directory and have an equal number of entities to one another to both be applicable to the same data file (as long as they do not have any metadata key-value clashes).
  This however poses a problem for comparing file association graphs for equivalence, where metadata files associated with a data file are inferred to be ordered.
  A more robust check would involve either:

  • Enforcing an equivalent order of these lists when that order is consequential, and not enforcing such an order when it is not.
  • For all lists, enforce equivalent order of entries only when that order can be disambiguated; for entries in the same directory and with the same number of entities, do not interpret permutation of those entries as inequivalence of the graphs.

• More elegant solution for loading non-JSON metadata

  For instance, along with other attributes ascribed to the different metadata file extensions
  could be the property that files of a given extension can be read as plaintext matrix data
  (eg. .bvec / .bval)

• Change how key-value metadata overrides are identified?

  Currently this is done through a stand-alone function.
  That works, and is technically faster and uses less RAM than a full metadata load, but isn't as general.
  Having a function return a tuple containing firstly all of the metadata, and secondly the set of overrides, would allow both of these steps to be done in one go.

• Implement checks comparing behaviour of full graph representation and individual functions

  While evaluation of the full graph makes sense for validation of datasets and for evaluating IP rulesets, it is likely to be a common use case of this package to simply query what metadata are associated with a nominated data file. The testing therefore needs to ensure that the outcomes from running these functions individually are exactly the same as what is captured by the full graph.

• Check ability of individual fetch functions to detect IP violations

  Checking whether a dataset violates the IP ruleset in some way is much easier when the full association graph is stored in memory. It is however desired that if a developer chooses to make direct use of the functions that access the metadata per data file / the data files to which a metadata file applies, any violations of the IP under some nominated ruleset will nevertheless be captured.

  My expectation is that it won't be possible for those functions to catch all such violations. I do however want to confirm that the set of violations that they fail to identify is acceptable.