[DOC] Improve tutorials for generating `-trans.fif`

[eort]

In the process of setting up a source-space-analysis, it took me a really long time to realize all the steps necessary to create a -trans.fif. As I am new to these type of analyses, it could be just me not knowing the terminology and what to look for, but I think there could be a more intuitive description of the procedure here.

Specifically, I needed several readings of the tutorials and attempts in implementing to figure out these things:

• if I haven't created a -trans.fifmyself or use an existing data set for which someone else has created that file, I will have to run mne coreg (i.e. the phrasing in the tutorials implies that normally this file is present, and only in the exceptional case that it is not, I need to take actions. So, it looked for it in different places, and tried to find out how I could extract it)
• getting the head shapes/surfaces with BEM or with make_scalp_surfaces is a prerequisite for running mne coreg
• to obtain the trans.fif I first need to complete other analysis steps (i.e. FS segmentation, BEM)

Proposed documentation enhancement

I don't know what would make the most sense. Relevant doc regarding the trans.fif file can be found in these two tutorials:

• https://mne.tools/stable/overview/cookbook.html#anatomical-information
• https://mne.tools/stable/auto_tutorials/source-modeling/plot_source_alignment.html#plot-source-alignment

The procedure to run mne coreg is currently buried quite deep in the Source alignment tutorial, which is primarily about understanding all the relevant coordinate systems. Perhaps it would make sense to split the tutorial in two? Or add the part Defining the head↔MRI trans using the GUI to "The typical M/EEG workflow" when talking about the trans.fif file?

Also, the figure in the "The typical M/EEG workflow" tutorial is misleading in that it implies getting the MRI-head trans does not depend on any other analysis step before. That is not true as you need Freesurfer to run its segmentation and to set up a BEM model (afaik, at least). So, I think the figure should be adapted to reflect that, and maybe some textual changes in the tutorial could clarify the dependencies.

[drammock]

Thanks for this issue. mne.coreg has been on our list of under-documented functionality for quite some time, and it would be great to have a proper, thorough tutorial that focused on creating a -trans.fif file from scratch. I think if you created that tutorial, then the section "Defining the head↔MRI trans using the GUI" could be removed from the coordinate frames tutorial and replaced by a sentence that links to that new tutorial.

It's also been on our list to take the material in the "cookbook" page and make it easier to find and understand, by splitting it out into proper tutorials. The three steps you mention above seem like about the right size for one tutorial I think.

1. segmentation
2. making the BEM
3. running mne.coreg

Another thing that we've discussed occasionally is creating a video walk-through of using mne.coreg. Planning exactly what steps to show / what dataset to use / what to say in the voice-over narrative is a considerable task, and that task would probably be easier if it were made in standard (static) tutorial format first; part 3 can rely on a few static screenshots for now, and a video walk-through could be added or swapped in at a later date if someone ever gets around to making it.

ping @larsoner who probably has some ideas about what should/shouldn't be covered here.

[larsoner]

At a higher level, at the end of the day I think the important things are that 1) we set up electrode coordinates in the head coordinate frame, and 2) we define the head<->MRI coordinate frame transformation properly. How you do these things will depend on your use case, I think there are three workflows that should cover most people:

1. M/EEG with subject-specific MRI (@eort's case sounds like some variant of this?): FreeSurfer + mne coreg
2. EEG with surrogate MRI
3. ECoG/sEEG/fNIRS with coordinates in the MRI coordinate frame

We have an explicit tutorial for (2) already, and I think we just fixed up (3) during the sprint. So I think what we need is some explicit tutorial for how to do (1), and some way to get people to look at the correct one of these variants. The tutorial(s) for (1) will necessarily cover making the head/scalp surfaces, since these are needed for mne coreg.

You shouldn't actually need a BEM solution or surfaces for head<->MRI -trans.fif generation -- those are needed during forward modeling which happens later.

[eort]

M/EEG with subject-specific MRI (@eort's case sounds like some variant of this?): FreeSurfer + mne coreg

This is indeed my situation. I can draft a tutorial for this case, but so far I only used MEG data. Is the procedure equivalent in EEG or are there some additional steps, i.e. making a montage?

You shouldn't actually need a BEM solution or surfaces for head<->MRI -trans.fif generation -- those are needed during forward modeling which happens later.

I wasn't sure that the BEM-solution step was what needed. I actually ran mne make_scalp_surfaces which created a bem folder and was they key to running the coregistration. What part of the figure above would describe that part? "Setup_source_space"?

So to be clear, the goal is a tutorial on the preprocessing steps necessary to register MRI space with the subject-specific head space on M/EEG data, which essentially includes:

1. segmentation
2. procedure to get surfaces (I might need some pointers to give some useful background information here)
3. coregistration

Plus, some links from/to related tutorials.

[larsoner]

I think that your (1) is really "run recon-all" and we should point people to the FreeSurfer docs on how to do this. Then the MNE tutorial is "after you have a FreeSurfer subject, do X Y Z", which would pretty much be (2) and (3) in your list. (2) should really just be mne make_scalp_surfaces, and (3) should really just be mne coreg.

I'm not 100% the best way to structure this stuff, let's wait to see if @agramfort agrees with my assessment of what use cases we need to document (my 1/2/3 two comments above) and what @drammock thinks a good tutorial structure would be for this. Maybe we should all chat during the next MNE-Python office hours (April 2 I think)? It's probably easiest to iterate over some shared google doc or hackmd with an outline or something, and post the result here for anyone else who is interested to comment on.

[agramfort]

agreed

…

[eort]

Sounds good. Only, April 2 I am not available unfortunately.

[vagechirkov]

Regarding the -trans.fif file generation this tutorial from NiBabel was very useful to me.

[larsoner]

Bumping the milestone on this one, but if someone is motivated to fix/update the docs in the next week or so it could still make it into 0.24