Merge pull request #207 from effigies/feat/multi-inheritance

feat: Implement multi-inheritance by passing extra entities to walkBack

Author: rwblair

changelog.d/20250530_082223_markiewicz_multi_inheritance.md

@@ -0,0 +1,52 @@
+<!--
+A new scriv changelog fragment.
+
+Uncomment the section that is right (remove the HTML comment wrapper).
+For top level release notes, leave all the headers commented out.
+-->
+
+### Added
+
+- Support multi-inheritance for associated files.
+  This will allow for multiple `electrodes.tsv` files,
+  distinguished by the `space-` entity. ([#206] [#207])
+
+[#206]: https://github.com/bids-standard/bids-validator/issues/206
+[#207]: https://github.com/bids-standard/bids-validator/pull/207
+
+<!--
+### Changed
+
+- A bullet item for the Changed category.
+
+-->
+<!--
+### Fixed
+
+- A bullet item for the Fixed category.
+
+-->
+<!--
+### Deprecated
+
+- A bullet item for the Deprecated category.
+
+-->
+<!--
+### Removed
+
+- A bullet item for the Removed category.
+
+-->
+<!--
+### Security
+
+- A bullet item for the Security category.
+
+-->
+<!--
+### Infrastructure
+
+- A bullet item for the Infrastructure category.
+
+-->

src/files/inheritance.test.ts

@@ -1,4 +1,5 @@
 import { assert, assertEquals, assertThrows } from '@std/assert'
+import type { BIDSFile } from '../types/filetree.ts'
 import { pathsToTree } from './filetree.ts'
 import { walkBack } from './inheritance.ts'
 
@@ -47,4 +48,28 @@ Deno.test('walkback inheritance tests', async (t) => {
       ])
     },
   )
+  await t.step(
+    'Passing targetEntities enables multiple matches',
+    async () => {
+      const rootFileTree = pathsToTree([
+        '/space-talairach_electrodes.tsv',
+        '/space-talairach_electrodes.json',
+        '/sub-01/ieeg/sub-01_task-rest_ieeg.edf',
+        '/sub-01/ieeg/sub-01_task-rest_ieeg.json',
+        '/sub-01/ieeg/sub-01_space-anat_electrodes.tsv',
+        '/sub-01/ieeg/sub-01_space-anat_electrodes.json',
+        '/sub-01/ieeg/sub-01_space-MNI_electrodes.tsv',
+        '/sub-01/ieeg/sub-01_space-MNI_electrodes.json',
+      ])
+      const dataFile = rootFileTree.get('sub-01/ieeg/sub-01_task-rest_ieeg.edf') as BIDSFile
+      const electrodes = walkBack(dataFile, true, ['.tsv'], 'electrodes', ['space'])
+      const localElectrodes: BIDSFile[] = electrodes.next().value
+      assertEquals(localElectrodes.map((f) => f.path), [
+        '/sub-01/ieeg/sub-01_space-anat_electrodes.tsv',
+        '/sub-01/ieeg/sub-01_space-MNI_electrodes.tsv',
+      ])
+      const rootElectrodes: BIDSFile = electrodes.next().value
+      assertEquals(rootElectrodes.path, '/space-talairach_electrodes.tsv')
+    },
+  )
 })

src/files/inheritance.ts

@@ -1,13 +1,37 @@
 import type { BIDSFile, FileTree } from '../types/filetree.ts'
-import type { Context } from '@bids/schema'
 import { readEntities } from '../schema/entities.ts'
 
-export function* walkBack(
+
+type Ret<T> = T extends [string, ...string[]] ? (BIDSFile | BIDSFile[]) : BIDSFile
+
+/** Find associated files in order of proximity to a source file.
+ *
+ * This function implements the BIDS Inheritance Principle.
+ *
+ * @param {BIDSFile} source
+ *    The source file to start the search from.
+ * @param {boolean} [inherit=true]
+ *    If true, search up the file tree for associated files.
+ *    If false, the associated file must be found in the same directory.
+ * @param {string[]} [targetExtensions='.json']
+ *    The extensions of associated files.
+ * @param {string} [targetSuffix]
+ *    The suffix of associated files. If not provided, it defaults to the suffix of the source file.
+ * @param {string[]} [targetEntities]
+ *    Additional entities permitted in associated files.
+ *    A non-empty value implies that multiple values may be returned.
+ *    By default, associated files must have a subset of the entities in the source file.
+ *
+ * @returns {Generator<BIDSFile | BIDSFile[]>}
+ *    A generator that yields associated files or arrays of files.
+ */
+export function* walkBack<T extends string[]>(
   source: BIDSFile,
   inherit: boolean = true,
   targetExtensions: string[] = ['.json'],
   targetSuffix?: string,
-): Generator<BIDSFile> {
+  targetEntities?: T,
+): Generator<Ret<T>> {
   const sourceParts = readEntities(source.name)
 
   targetSuffix = targetSuffix || sourceParts.suffix
@@ -19,19 +43,24 @@ export function* walkBack(
       return (
         targetExtensions.includes(extension) &&
         suffix === targetSuffix &&
-        Object.keys(entities).every((entity) => entities[entity] === sourceParts.entities[entity])
+        Object.keys(entities).every((entity) =>
+          entities[entity] === sourceParts.entities[entity] || targetEntities?.includes(entity)
+        )
       )
     })
     if (candidates.length > 1) {
       const exactMatch = candidates.find((file) => {
-        const { suffix, extension, entities } = readEntities(file.name)
+        const { entities } = readEntities(file.name)
         return Object.keys(sourceParts.entities).every((entity) =>
           entities[entity] === sourceParts.entities[entity]
         )
       })
       if (exactMatch) {
         exactMatch.viewed = true
         yield exactMatch
+      } else if (targetEntities?.length) {
+        candidates.forEach((file) => (file.viewed = true))
+        yield candidates as Ret<T>
       } else {
         const paths = candidates.map((x) => x.path).sort()
         throw {

src/schema/associations.ts

@@ -1,39 +1,25 @@
-import type {
-  Aslcontext,
-  Associations,
-  Bval,
-  Bvec,
-  Channels,
-  Coordsystem,
-  Events,
-  M0Scan,
-  Magnitude,
-  Magnitude1,
-} from '@bids/schema/context'
+import type { Aslcontext, Associations, Bval, Bvec, Channels, Events } from '@bids/schema/context'
 import type { Schema as MetaSchema } from '@bids/schema/metaschema'
 
-import type { BIDSFile, FileTree } from '../types/filetree.ts'
+import type { BIDSFile } from '../types/filetree.ts'
 import type { BIDSContext } from './context.ts'
-import type { DatasetIssues } from '../issues/datasetIssues.ts'
-import type { readEntities } from './entities.ts'
 import { loadTSV } from '../files/tsv.ts'
 import { parseBvalBvec } from '../files/dwi.ts'
 import { walkBack } from '../files/inheritance.ts'
 import { evalCheck } from './applyRules.ts'
 import { expressionFunctions } from './expressionLanguage.ts'
 
-// type AssociationsLookup = Record<keyof ContextAssociations, { extensions: string[], inherit: boolean, load: ... }
+function defaultAssociation(file: BIDSFile, _options: any): Promise<{ path: string }> {
+  return Promise.resolve({ path: file.path })
+}
 
 /**
- * This object describes associated files for data files in a bids dataset
- * For any given datafile we iterate over every key/value in this object.
- * For each entry we see if any files in the datafiles directory have:
- *   - a suffix that matches the key
- *   - an extension in the entry's extension array.
- *   - that all the files entities and their values match those of the datafile
- * If the entry allows for inheritance we recurse up the filetree looking for other applicable files.
- * The load functions are incomplete, some associations need to read data from a file so they're
- * returning promises for now.
+ * This object describes lookup functions for files associated to data files in a bids dataset.
+ * For any given data file we iterate over the associations defined schema.meta.associations.
+ * If the selectors match the data file, we attempt to find an associated file,
+ * and use the given function to load the data from that file.
+ *
+ * Many associations only consist of a path; this object is for more complex associations.
  */
 const associationLookup = {
   events: async (file: BIDSFile, options: { maxRows: number }): Promise<Events> => {
@@ -60,15 +46,6 @@ const associationLookup = {
       volume_type: columns.get('volume_type') || [],
     }
   },
-  m0scan: (file: BIDSFile, options: any): Promise<M0Scan> => {
-    return Promise.resolve({ path: file.path })
-  },
-  magnitude: (file: BIDSFile, options: any): Promise<Magnitude> => {
-    return Promise.resolve({ path: file.path })
-  },
-  magnitude1: (file: BIDSFile, options: any): Promise<Magnitude1> => {
-    return Promise.resolve({ path: file.path })
-  },
   bval: async (file: BIDSFile, options: any): Promise<Bval> => {
     const contents = await file.text()
     const rows = parseBvalBvec(contents)
@@ -106,9 +83,6 @@ const associationLookup = {
       sampling_frequency: columns.get('sampling_frequency'),
     }
   },
-  coordsystem: (file: BIDSFile, options: any): Promise<Coordsystem> => {
-    return Promise.resolve({ path: file.path })
-  },
 }
 
 export async function buildAssociations(
@@ -117,24 +91,39 @@ export async function buildAssociations(
   const associations: Associations = {}
 
   const schema: MetaSchema = context.dataset.schema as MetaSchema
+  // Augment rule type with an entities field that should be present in BIDS 1.10.1+
+  type ruleType = MetaSchema['meta']['associations'][keyof MetaSchema['meta']['associations']]
+  type AugmentedRuleType = ruleType & {
+    target: ruleType['target'] & { entities?: string[] }
+  }
 
   Object.assign(context, expressionFunctions)
   // @ts-expect-error
   context.exists.bind(context)
 
-  for (const [key, rule] of Object.entries(schema.meta.associations)) {
+  for (const key of Object.keys(schema.meta.associations)) {
+    const rule = schema.meta.associations[key] as AugmentedRuleType
     if (!rule.selectors!.every((x) => evalCheck(x, context))) {
       continue
     }
-    let file
+    let file: BIDSFile | BIDSFile[]
     let extension: string[] = []
     if (typeof rule.target.extension === 'string') {
       extension = [rule.target.extension]
     } else if (Array.isArray(rule.target.extension)) {
       extension = rule.target.extension
     }
     try {
-      file = walkBack(context.file, rule.inherit, extension, rule.target.suffix).next().value
+      file = walkBack(
+        context.file,
+        rule.inherit,
+        extension,
+        rule.target.suffix,
+        rule.target?.entities ?? [],
+      ).next().value
+      if (Array.isArray(file)) {
+        file = file[0]
+      }
     } catch (error) {
       if (
         error && typeof error === 'object' && 'code' in error &&
@@ -150,7 +139,7 @@ export async function buildAssociations(
 
     if (file) {
       // @ts-expect-error
-      const load = associationLookup[key]
+      const load = associationLookup[key] ?? defaultAssociation
       // @ts-expect-error
       associations[key] = await load(file, { maxRows: context.dataset.options?.maxRows }).catch(
         (error: any) => {