Merge pull request bids-standard#2097 from effigies/feat/nifti-axis-codes

[ENH] Specify that dir-<label> should correspond to PhaseEncodingDirection

Author: effigies

src/schema/meta/context.yaml

@@ -316,6 +316,7 @@ properties:
       - xyzt_units
       - qform_code
       - sform_code
+      - axis_codes
     additionalProperties: false
     properties:
       dim_info:
@@ -404,6 +405,17 @@ properties:
         name: 'sform code'
         description: 'Use of the affine fields.'
         type: integer
+      axis_codes:
+        name: 'axis codes'
+        description: >
+          Orientation labels indicating primary direction of data axes defined
+          with respect to the object of interest.
+        type: array
+        minItems: 3
+        maxItems: 3
+        items:
+          type: string
+          enum: ['R', 'L', 'A', 'P', 'S', 'I']
       mrs:
         name: 'NIfTI-MRS extension'
         description: 'NIfTI-MRS JSON fields'

src/schema/objects/entities.yaml

@@ -83,7 +83,23 @@ direction:
     This entity represents the `"PhaseEncodingDirection"` metadata field.
     Therefore, if the `dir-<label>` entity is present in a filename,
     `"PhaseEncodingDirection"` MUST be defined in the associated metadata.
-    Please note that the `<label>` does not need to match the actual value of the field.
+
+    Labels need not follow any particular convention and in case of conflict,
+    JSON metadata MUST take precedence in interpreting an image.
+
+    For example, `dir-j0` and `dir-j1` can indicate `"PhaseEncodingDirection": "j"` and `"j-"` (or vice versa),
+    identifying the phase-encoding axis while avoiding indicating polarity.
+    However, in case of a dataset indicating `dir-j0` with `"PhaseEncodingDirection": "i"`, the
+    JSON metadata overrides the entity `dir-` setting.
+
+    The use of generic labels, such as `dir-reference` and `dir-reversed`, is RECOMMENDED
+    to avoid any possible inconsistency.
+
+    To avoid inconsistency, if the `<label>` is `AP`, `PA`, `LR`, `RL`, `SI`, or `IS`,
+    then the `"PhaseEncodingDirection"` SHOULD correspond to the data
+    axis that most closely aligns with the cardinal direction and orientation.
+    For example, `dir-PA` and `dir-AP` for an image in RAS+ orientation SHOULD have
+    `"PhaseEncodingDirection": "j"` and `"j-"`, respectively.
   type: string
   format: label
 echo:

src/schema/rules/checks/nifti.yaml

@@ -49,3 +49,19 @@ XformCodes0:
     - nifti_header != null
   checks:
     - nifti_header.qform_code != 0 || nifti_header.sform_code != 0
+
+NiftiPEDir:
+  issue:
+    code: NIFTI_PE_DIRECTION_CONSISTENCY
+    message: |
+      The PhaseEncodingDirection and affine orientation indicate
+      that the entity value (one of AP, PA, RL, LR, SI, IS) may be inaccurate.
+    level: warning
+  selectors:
+    - type(nifti_header.axis_codes) != "null"
+    - intersects([entities.direction], ["AP", "PA", "RL", "LR", "SI", "IS"])
+    - sidecar.PhaseEncodingDirection
+  checks:
+    - |
+      entities.direction[2 - length(sidecar.PhaseEncodingDirection)]
+      == nifti_header.axis_codes[index(["i", "j", "k"], sidecar.PhaseEncodingDirection[0])]

tools/schemacode/tests/test_context_types.py

@@ -75,6 +75,7 @@ def test_assignability() -> None:
         xyzt_units=xyzt_units,
         qform_code=1,
         sform_code=1,
+        axis_codes=("L", "P", "S"),
     )
 
     ome: p.Ome = ctx.Ome()