WIP: Expose ignore_overlap to evoked plot_topomap function

[rob-luke]

What does this implement/fix?

It is common in fNIRS to have source and detectors in a criss-cross pattern. I try and illustrate this below (excuse the poor ascii art)...

Here sources are indicated by [s], and detectors by[d]. Channels are then formed between the sources and detectors indicated by a -, and by x where two sources and detectors have overlapping channels. For example there is a channel between s2 and d3, and one between s3 and d2 that overlap.

[s2]  -  [d2]  -  [s4] 
      x        x         
[s3]  -  [d3]  -  [s5] 

This approach is used purposely to reduce noise (the overlapping channels should be measuring the same brain region), and for redundancy (its common to have a source or detector that fails or is blocked by hair/scars/etc).

Currently if you have this criss-cross pattern then the location of the channels is very close and MNE throws an error similar to... The following electrodes have overlapping positions, which causes problems during visualization: S2_D3 hbo, S3_D2 hbo, ...

In the future I would like to develop a way to combine overlapping channels in to a single optimal channel. But for now I would just like to be able to force MNE to allow me to view the data as a topomap. So I have exposed the ignore_overlap variable that was available in the lower level topomap function.

Additional information

I am keen to hear other approaches to how I can address this issue. I probably should have opened an issue and discussed the approach before I coded it.

None of the current nirs test data have overlapping channels. I will make sure the next set I upload does.

[rob-luke]

@agramfort and @larsoner appreciate your opinions on the best way to approach this issue.

[larsoner]

For MEG data when we have pairs of gradiometers at the same location, we take the RMS of the sensors and the entire topomap become positive-valued.

Is RMS a good way to look at fNIRS data with overlaps? Or is a simple mean good enough? If RMS, then for fNIRS we can just detect if there are overlaps of fNIRS channels and automatically take the RMS of all channels (just an abs for locations without overlap) in this case.

Eventually we could do an overlap kwarg:

• overlap='auto' as the default, which for anything other than fnirs is an alias for ...
• overlap='error', which is just our current behavior
• overlap='...', which only works for fnirs (for now) and does whatever the right thing is to do for fNIRS data, e.g. mean or whatever

But hopefully if there is just one sane behavior (esp. if that behavior is just mean for fNIRS) we can just special-case the topomap code for fNIRS. That would be cleaner than adding a new kwarg unless we need to do so.

[rob-luke]

Thanks @larsoner. A simple mean would be perfect. Can you point me to where the MEG code is for this behaviour so I can use this as a framework.

[larsoner]

Look for uses of _pair_grad_sensors in mne/viz/topomap.py

[larsoner]

Closing in favor of #7414