Merge branch 'master' into expand-acq-definition

Author: julia-pfarr

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])]

src/schema/rules/files/deriv/preprocessed_data.yaml

@@ -26,12 +26,21 @@ anat_defacemask_common:
     space: optional
     description: optional
 
-anat_multiecho_common:
+anat_megre_common:
   selectors:
     - dataset.dataset_description.DatasetType == 'derivative'
-  $ref: rules.files.raw.anat.multiecho
+  $ref: rules.files.raw.anat.megre
   entities:
-    $ref: rules.files.raw.anat.multiecho.entities
+    $ref: rules.files.raw.anat.megre.entities
+    space: optional
+    description: optional
+
+anat_mese_common:
+  selectors:
+    - dataset.dataset_description.DatasetType == 'derivative'
+  $ref: rules.files.raw.anat.mese
+  entities:
+    $ref: rules.files.raw.anat.mese.entities
     space: optional
     description: optional
 

src/schema/rules/files/raw/anat.yaml

@@ -85,9 +85,8 @@ defacemask:
     modality: optional
     chunk: optional
 
-multiecho:
+megre:
   suffixes:
-    - MESE
     - MEGRE
   extensions:
     - .nii.gz
@@ -107,6 +106,28 @@ multiecho:
     part: optional
     chunk: optional
 
+mese:
+  suffixes:
+    - MESE
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+  datatypes:
+    - anat
+  entities:
+    subject: required
+    session: optional
+    task: optional
+    acquisition: optional
+    ceagent: optional
+    reconstruction: optional
+    direction: optional
+    run: optional
+    echo: required
+    part: optional
+    chunk: optional
+
 multiflip:
   suffixes:
     - VFA

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()