WIP: Overhaul CoordinateSystem details for MRI, MEG, EEG, iEEG

[sappelhoff]

closes #661

History: Several months ago we improved the validator to finally check the *CoordinateSystem fields in (i)MEEG *coordsystem.json files (https://github.com/bids-standard/bids-validator/pull/1096, https://github.com/bids-standard/bids-validator/pull/1097)

This revealed issues with several existing bids-datasets (bids-standard/bids-examples#215), where dataset curators did not follow the rules outlined in the specification appendix VIII. The formalization of those rules in the bids-validator merely revealed that.

Several discussions later, we know several problems that need to be fixed (#520, #661, https://github.com/bids-standard/bids-specification/wiki/Coordinate-Systems-for-MEG-EEG-iEEG).

In this PR I propose some fixes:

UPDATE: Many of the proposed fixes that were uncontroversial have been merged in #717 ... the remaining changes are left here for potential discussion later.

New Image keyword

Occasionally, people wanted to say their coordinates are to be interpreted with respect to some image, and then specified for example T1w as the CoordinateSystem, and pointed to that image using the IntendedForfield.

T1w is currently not an accepted CoordinateSystem keyword. Instead of adding it to the list, I suggest a generic Image keyword. Users can specify Image as a value to CoordinateSystem if they supply a path to an image in the bids dataset using the IntendedFor field (this becomes REQUIRED in that case). Users could also point to a CT, or whatever image they deem sensible/meaningful.

Allow units other than "voxel" for MRI AnatomicalLandmarkCoordinates

In MRI, users can specify a field AnatomicalLandmarkCoordinates in voxels. This field can also be specified in MEG, EEG, and iEEG --> but there it's in mm, cm, or m.

With this PR I introduce AnatommicalLandmarkCoordinateUnits to the MRI spec, where users can specify mm, cm, m, or voxels. If that field is not specified, it defaults to voxels - so this is a completely backward compatible change. In the future we may consider RECOMMENDING to not use voxels.

for context see also #661 (comment)

[effigies]

A couple objections. First, I don't think we want so many options for coordinate units in MRI. Second, I think SpatialReference will be a better tool than IntendedFor.

Otherwise, these seem like fine proposals.

[effigies]

I'm extremely hesitant to allow anything besides voxels and mm. Particularly cm, which is not a valid NIfTI unit. I can't see meters being useful in any animal.

If non-voxel units are used, should we insist that the NIfTI xyzt_units field match units? For instance, if somebody specifies mm here, it might be sensible not to allow them to define their image affine in microns.

Additional changes:

1. Typo. if -> is
2. voxels to voxel. I did a quick search and it's hard to find clear guidance, but I think when describing a unit without a quantity, the singular is usually used. Happy to be corrected, if a reference can be found.

Suggested change

	| AnatomicalLandmarkCoordinateUnits | RECOMMENDED | [string][] | Can be `"mm"`, `"cm"`, `"m"`, or `"voxels"`, but defaults to `"voxels"` if not specified. If the value if `"voxels"`, the first voxel has index 0,0,0. This is the unit in which `AnatomicalLandmarkCoordinates` should be interpreted. |
	| AnatomicalLandmarkCoordinateUnits | RECOMMENDED | [string][] | Can be `"mm"`, `"cm"`, `"m"`, or `"voxel"`, but defaults to `"voxel"` if not specified. If the value is `"voxel"`, the first voxel has index 0,0,0. This is the unit in which `AnatomicalLandmarkCoordinates` should be interpreted. |

[effigies]

Voxel index is well-defined, but I think it would be prudent to indicate that non-voxel distances increase to the right, anterior and superior. I could imagine someone seeing an LPS image and thinking that the distances are also LPS.

[effigies]

Would add a note here that these would need AnatomicalLandmarkCoordinates to be defined to interpret as distances from the origin rather than voxel locations.

[effigies]

Suggested change

	as `Image`, and `IndendedFor` with the path to that image in the
	as `Image`, and `IntendedFor` with the path to that image in the

New fields shouldn't be described only in appendices. This also seems like a reversal of the usual way that IntendedFor is used. The fieldmap is an adjunct to the image it is intended for. Here the anatomical appears to be the adjunct of the MEG/EEG data that are "intended for" it. What about co-opting the SpatialReference field from derivatives?

[sappelhoff]

Thanks a lot for your feedback @effigies. I investigated the IntendedFor field a bit, see below:

I get the feeling that the different IntendedFor fields should be harmonized.

I think this should be its own issue - for the sake of this PR, I will see how much "easy improvement" I can salvage without touching/impacting IntendedFor.

in particular, we should clarify that IntendedFor contains a filepath (str) or list of filepaths ... and how these filepaths are to be made up ... if absolute or relative ... to what reference if relative, etc. see #471

Also I think all of those should accept a str or array of str (currently some only accept str).

Lastly, the "descriptions" should be homogenized ... and then the special aspect of using "IntendedFor" with a particular usecase can be added at the end of the description ... or something similar. Just to get rid of this currently confusing diversity in descriptions.

linking fieldmap data (Recommended, str or array of str)

https://bids-specification.readthedocs.io/en/latest/04-modality-specific-files/01-magnetic-resonance-imaging-data.html#using-intendedfor-metadata

Contains one or more filenames with paths relative to the participant subfolder. The path needs to use forward slashes instead of backward slashes. This field is OPTIONAL, and in case the fieldmaps do not correspond to any particular scans, it does not have to be filled.

link ASL timeseries and m0 scan (Required, str or array or str)

https://bids-specification.readthedocs.io/en/latest/04-modality-specific-files/01-magnetic-resonance-imaging-data.html#m0scan-metadata-fields

One or more filenames with paths relative to the subject subfolder, with forward slashes, referring to ASL time series for which the *_m0scan.nii[.gz] is intended.

MEG: link MRI(s) (Optional, str or array of str)

https://bids-specification.readthedocs.io/en/latest/04-modality-specific-files/02-magnetoencephalography.html#coordinate-system-json-_coordsystemjson

Path or list of path relative to the subject subfolder pointing to the structural MRI, possibly of different types if a list is specified, to be used with the MEG recording. The path(s) need(s) to use forward slashes instead of backward slashes (for example, ses-/anat/sub-01_T1w.nii.gz).

EEG: Link MRI/CT (Optional, str)

https://bids-specification.readthedocs.io/en/latest/04-modality-specific-files/03-electroencephalography.html#coordinate-system-json-_coordsystemjson

Relative path to associate the electrodes, landmarks and fiducials to an MRI/CT.

iEEG: Link MRI7CT/Photograph (Recommended, str)

https://bids-specification.readthedocs.io/en/latest/04-modality-specific-files/04-intracranial-electroencephalography.html#coordinate-system-json-_coordsystemjson

This can be an MRI/CT or a file containing the operative photo, x-ray or drawing with path relative to the project folder. If only a surface reconstruction is available, this should point to the surface reconstruction file. Note that this file should have the same coordinate system specified in iEEGCoordinateSystem. For example, T1: sub-/ses-/anat/sub-01_T1w.nii.gz Surface: /derivatives/surfaces/sub-/ses-/anat/sub-01_T1w_pial.R.surf.gii Operative photo: /sub-/ses-/ieeg/sub-0001_ses-01_acq-photo1_photo.jpg Talairach: /derivatives/surfaces/sub-Talairach/ses-01/anat/sub-Talairach_T1w_pial.R.surf.gii

[sappelhoff]

closing for now, as all urgent points have been addressed in #717 - all remaining discussion can continue in due time - drawing on the help page I created here: https://github.com/bids-standard/bids-specification/wiki/Coordinate-Systems-for-MEG-EEG-iEEG