mne.viz.plot_sensors accepts ch_groups in the type list (of lists) but this is undocumented

[mcvain]

Proposed documentation enhancement

The documentation of mne.viz.plot_sensors says that the ch_groups argument accepts ‘position’ | array of shape (n_ch_groups, n_picks) | None, which can be especially misleading when the user wants to create channel groups containing unequal numbers of channels. Following the documentation which specifies a fixed size of (n_ch_groups, n_picks), I believe the only way to do so currently is to pass an ndarray with invalid channel indices filling up the group(s) to match n_picks.

I initially edited the function so that it also works with an ndarray of dtype=object with unequal numbers of items in each row, but it turns out that the function already works with a list containing uneven-sized lists e.g. [[1, 2], [3, 4, 5, 6]] and therefore already supports channel groups with unequal sizes. This should be made clearer in the doc.

[welcome]

Hello! 👋 Thanks for opening your first issue here! ❤️ We will try to get back to you soon. 🚴🏽‍♂️

[agramfort]

can you share a full code snippet? it will be clearer for me to understand

thanks

[mcvain]

Sure. For example, if I want to use plot_sensors to plot the channels 1,2,3 with a certain color and 4,5,6 with another color, I would see that the documentation accepts an ndarray of (n_ch_groups, n_picks), so I would do this:

import mne
from mne.channels import make_standard_montage
from mne.viz import plot_sensors
import numpy as np

info = create_info(ch_names, sfreq=256, ch_types="eeg")
info.set_montage(montage, on_missing='ignore')
fig = plot_sensors(info, kind='3d', show_names=show_names, show=True,
                        title=title, sphere=None, ch_groups=np.array([[1, 2, 3], [4, 5, 6]]))

which raises a FutureWarning but works as intended.

Now if I wanted to color channels 1, 2, 3 one color and 4, 5, 6, 7, 8 another color, following the documentation, one might try passing an ndarray like this:

fig = plot_sensors(info, kind='3d', show_names=False, show=True, sphere=None, ch_groups=np.array([[1, 2, 3], [4, 5, 6, 7, 8]], dtype=object))

which returns a ValueError due to insufficient type-checking within plot_sensors. Instead, using a list of list(s) works, despite list not being an accepted type in the documentation:

fig = plot_sensors(info, kind='3d', show_names=False, show=True, sphere=None, ch_groups=[[1, 2, 3],[4, 5, 6, 7, 8]])

or, for a single group,

fig = plot_sensors(info, kind='3d', show_names=False, show=True, sphere=None, ch_groups=[[1, 2, 3]])

Therefore the documentation mentioning array of shape (n_ch_groups, n_picks) should be changed to array_like instead.

P.S. Both the FutureWarning and ValueError can be fixed by changing line 1027 from if ch_groups in ['position', 'selection']: to if isinstance(ch_groups, str) and ch_groups in ['position', 'selection']:

[drammock]

agree that this seems bug-like (at least, the documentation doesn't correctly specify how to do something that is already partially supported and quite reasonable to want to do). I agree that array-like is probably the right type spec, and we should also add something like "accepts list-of-lists or an object array to allow channel groups to have different sizes". @mcvain do you have time to make a PR to fix this? It might be a while before one of us gets around to it.

[mcvain]

Yes I will soon.