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

[effigies]

The BIDS convention is to use dir-{AP,PA,LR,RL} for phase-encoding directions in MRI filenames, as well as PhaseEncodingDirection in JSON sidecars. This duplication has the potential for inconsistency or multiple interpretations of the meaning of AP.

This PR aims to clarify the meaning of dir-<label> when its value matches a cardinal axis, and clearly state that this meaning SHOULD be consistent with the PhaseEncodingDirection.

[oesteban]

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-"`.

[effigies]

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.

[oesteban]

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.

[effigies]

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.

[oesteban]

This is great to make the situation better without introducing backward incompatible changes. I made some suggestions to be more explicit about what the problem is and providing examples, that said, the phrasing will likely require improvements.