Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1813101
feat(schema): Add nifti_header.axis_codes to context
effigies Apr 1, 2025
70d17ae
feat(schema): Add rule to detect inconsistent PE directions
effigies Apr 2, 2025
a8a1c2b
[ENH] Specify that dir-<label> should correspond to PhaseEncodingDire…
effigies Apr 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions src/schema/meta/context.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -317,6 +317,7 @@ properties:
- xyzt_units
- qform_code
- sform_code
- axis_codes
additionalProperties: false
properties:
dim_info:
Expand Down Expand Up @@ -405,6 +406,15 @@ 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.'
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'
Expand Down
7 changes: 6 additions & 1 deletion src/schema/objects/entities.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,12 @@ 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.

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-AP` for an image in RAS+ orientation SHOULD have
`"PhaseEncodingDirection": "j-"`.
Comment on lines +87 to +91
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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-AP` for an image in RAS+ orientation SHOULD have
`"PhaseEncodingDirection": "j-"`.
It is RECOMMENDED not to encode the actual phase-encoding direction
with the `<label>` to preempt conflicts with the `"PhaseEncodingDirection"`
metadata.
For example, this can be achieved by using indexes: `dir-0`, `dir-1` or
labels without specifying the direction such as `dir-reference` and `dir-reversed`.
Nonetheless, if `<label>` encodes the metadata by taking values such as
`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-AP` for an image in RAS+ orientation SHOULD have
`"PhaseEncodingDirection": "j-"`.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is introducing a new RECOMMENDation that entity values should not indicate the values of the associated metadata. This is not generally stated in BIDS, and runs counter to common usage; if you would like to make that proposal, I would probably start an issue or a mailing list thread to see if there's much support for it.

I don't want to try to introduce it here. Beyond it being out-of-scope for this fairly narrow attempt to warn on inconsistency, it would introduce a warning even when the metadata is consistent, which seems user-hostile.

That said, we can expand the previous "Please note that the <label> does not need to match the actual value of the field." into a brief discussion of non-axis-code conventions:

Suggested change
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-AP` for an image in RAS+ orientation SHOULD have
`"PhaseEncodingDirection": "j-"`.
Labels need not follow any particular convention,
and JSON metadata MUST take precedence in interpreting an image.
Generic labels, such as `dir-reference` and `dir-reversed` avoid any possible inconsistency.
`dir-j0` and `dir-j1` can indicate `"PhaseEncodingDirection": "j"` and `"j-"` (or vice versa),
identifying the phase-encoding axis while avoiding indicating polarity.
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:
Expand Down
15 changes: 15 additions & 0 deletions src/schema/rules/checks/nifti.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,3 +49,18 @@ XformCodes0:
- nifti_header != null
checks:
- nifti_header.qform_code != 0 || nifti_header.sform_code != 0

NiftiPEDir:
issue:
code: NIFTI_PE_DIRECTION_CONSISTENCY
message: |
Phase encoding direction is inconsistent with `dir-` entity.
Copy link
Collaborator

@oesteban oesteban Apr 6, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should not make this a confident statement:

Suggested change
Phase encoding direction is inconsistent with `dir-` entity.
Phase encoding direction may be inconsistent with `dir-` entity.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not opposed to this, but I don't understand the case where this is triggered and the direction isn't inconsistent. We can expand on this text to explain why it's inconsistent in general terms, though we don't have a way to vary the text based on the values of fields.

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