[INFRA] SCHEMA: Declare entities by concept names, add entity field for filename components

src/schema/entities.yaml

@@ -1,11 +1,13 @@
 ---
-sub:
+subject:
   name: Subject
+  entity: sub
   description: |
     A person or animal participating in the study.
   format: label
-ses:
+session:
   name: Session
+  entity: ses
   description: |
     A logical grouping of neuroimaging and behavioral data consistent across
     subjects.
@@ -24,14 +26,16 @@ ses:
   format: label
 task:
   name: Task
+  entity: task
   format: label
   description: |
     Each task has a unique label that MUST only consist of letters and/or
     numbers (other characters, including spaces and underscores, are not
     allowed).
     Those labels MUST be consistent across subjects and sessions.
-acq:
+acquisition:
   name: Acquisition
+  entity: acq
   description: |
     The `acq-<label>` key/value pair corresponds to a custom label the
     user MAY use to distinguish a different set of parameters used for
@@ -49,45 +53,51 @@ acq:
     FLASH, or between RARE, FLASH, and FLASHsubsampled) remains at the
     discretion of the researcher.
   format: label
-ce:
+ceagent:
   name: Contrast Enhancing Agent
+  entity: ce
   description: |
     The `ce-<label>` key/value can be used to distinguish
     sequences using different contrast enhanced images.
     The label is the name of the contrast agent.
     The key `ContrastBolusIngredient` MAY be also be added in the JSON file,
     with the same label.
   format: label
-rec:
+reconstruction:
   name: Reconstruction
+  entity: rec
   description: |
     The `rec-<label>` key/value can be used to distinguish
     different reconstruction algorithms (for example ones using motion
     correction).
   format: label
-dir:
+direction:
   name: Phase-Encoding Direction
+  entity: dir
   description: |
     The `dir-<label>` key/value can be used to distinguish
     different phase-encoding directions.
   format: label
 run:
   name: Run
+  entity: run
   description: |
     If several scans of the same modality are acquired they MUST be indexed
     with a key-value pair: `_run-1`, `_run-2`, ..., `_run-<index>`
     (only nonnegative integers are allowed for the `<index>`).
     When there is only one scan of a given type the run key MAY be omitted.
   format: index
-mod:
+modality:
   name: Corresponding Modality
+  entity: mod
   description: |
     The `mod-<label>` key/value pair corresponds to modality label for defacing
     masks, e.g., T1w, inplaneT1, referenced by a defacemask image.
     E.g., `sub-01_mod-T1w_defacemask.nii.gz`.
   format: label
 echo:
   name: Echo
+  entity: echo
   description: |
     Multi-echo data MUST be split into one file per echo.
     Each file shares the same name with the exception of the `_echo-<index>`
@@ -98,14 +108,16 @@ echo:
   format: index
 recording:
   name: Recording
+  entity: recording
   description: |
     More than one continuous recording file can be included (with different
     sampling frequencies).
     In such case use different labels.
     For example: `_recording-contrast`, `_recording-saturation`.
   format: label
-proc:
+processing:
   name: Processed (on device)
+  entity: proc
   description: |
     The proc label is analogous to rec for MR and denotes a variant of a file
     that was a result of particular processing performed on the device.
@@ -116,13 +128,15 @@ proc:
   format: label
 space:
   name: Space
+  entity: space
   description: |
     The space label (`*[_space-<label>]_electrodes.tsv`) can be used
     to indicate the way in which electrode positions are interpreted.
     The space label needs to be taken from the list in Appendix VIII.
   format: label
 split:
   name: Split
+  entity: split
   description: |
     In the case of long data recordings that exceed a file size of 2Gb, the
     .fif files are conventionally split into multiple parts.

tools/bids_schema.py

@@ -220,7 +220,7 @@ def save_entities(schema_path, out_file):
         fo.write(intro_text)
         for entity, entity_info in entities.items():
             fo.write('\n')
-            fo.write('## {}'.format(entity))
+            fo.write('## {}'.format(entity_info['entity']))
             fo.write('\n\n')
             fo.write('Full name: {}'.format(entity_info['name']))
             fo.write('\n\n')
@@ -284,9 +284,9 @@ def make_entity_table(schema_path, entities_file='09-entities.md'):
     # Compose header and formats first
     for i, (entity, spec) in enumerate(schema['entities'].items()):
         header.append(spec["name"])
-        formats.append(f'[`{entity}-<{spec["format"]}>`]'
-                       f'({entities_file}#{entity})')
-        entity_to_col[entity] = i + 1
+        formats.append(f'[`{spec["entity"]}-<{spec["format"]}>`]'
+                       f'({entities_file}#{spec["entity"]})')
+        entity_to_col[spec["entity"]] = i + 1
 
     # Go through data types
     for dtype, specs in chain(schema['datatypes'].items(),