DigMontages: information on coordinate systems; and adding a simple rescaling method

[sappelhoff]

I just got some sensor positions in a text file that are in the "CTF" coordinate system. Naturally, I wanted to turn this into a DigMontage. However, when trying to find an appropriate value for the coord_frame parameter, I was faced with two choices:

1. ctf_meg
2. ctf_head

I could not easily find any documentation on the differences between these two coordinate systems. Ideally we would have a page where each coordinate system that we support is described with mentioning at least the origin, and the direction of the three axes (x,y,z) with reference to fiducials/anatomical landmarks, wherever possible. What do you think?

Furthermore, I think mne.channels.DigMontage should get a method called .transform_to (or similar) that takes as input the string label of any supported coordinate system in mne. Alternatively (or additionally), this functionality could also become a parameter upon instantiation of the DigMontage. .apply_trans seems a bit tricky to use for that. Opinions on this?

[larsoner]

I could not easily find any documentation on the differences between these two coordinate systems. Ideally we would have a page where each coordinate system that we support is described with mentioning at least the origin, and the direction of the three axes (x,y,z) with reference to fiducials/anatomical landmarks, wherever possible. What do you think?

Rather than add our own I'd prefer to point to this as it seems like an excellent reference

https://www.fieldtriptoolbox.org/faq/coordsys/

But adding a table with this minimal information for the coord frames we support plus a link to that FAQ would work, too!

Furthermore, I think mne.channels.DigMontage should get a method called .transform_to (or similar) that takes as input the string label of any supported coordinate system in mne. Alternatively (or additionally), this functionality could also become a parameter upon instantiation of the DigMontage. .apply_trans seems a bit tricky to use for that. Opinions on this?

Typically in MNE we have tried to just get sensor positions to the Neuromag head coordinate frame as much as possible. And it happens automatically when you do .set_montage(...) I think.

We could expand this, at least for (probably?) ctf_head. For other stuff like ctf_meg it would be more complicated because then you'd actually need the transformation between CTF head and device coordinate frames, like you'd have to do .transform_to("ctf_meg", transform=mne.transform.Transform("ctf_head", "ctf_meg", <some ndarray>) or similar. Or at least I think this would be the case without having reread all the coord frame definitions...

[sappelhoff]

@larsoner I actually found that we already do have a function to rescale to "head", it is just not exposed:

https://github.com/mne-tools/mne-python/blob/e06873d4d6e0a84bbd7d6b4a01ae4af340c7bedd/mne/channels/montage.py#L700-L738

https://mne.tools/stable/search.html?q=transform_to_head

Can we perhaps expose this function and document it in our API?

And it happens automatically when you do .set_montage(...) I think.

yes, that is the only time this function is called outside of tests.

https://github.com/mne-tools/mne-python/blob/e06873d4d6e0a84bbd7d6b4a01ae4af340c7bedd/mne/channels/montage.py#L1059-L1066

https://github.com/mne-tools/mne-python/blob/e06873d4d6e0a84bbd7d6b4a01ae4af340c7bedd/mne/channels/montage.py#L1105-L1144

[larsoner]

Can we perhaps expose this function and document it in our API?

Sure, I think we just didn't so far because there hasn't been a strong need. But I think I've looked for it before myself as well...

[sappelhoff]

And additionally, I could point to this definition for the ctf_head coordinate frame.

https://mne.tools/stable/documentation/implementation.html#the-head-and-device-coordinate-systems

☝️ see the "Note" in the blue box.

I will push these two improvements soon and then close this issue.