Add a note on fig.mne.colorbar in the docs of plot_connectivity_circle

[ruuskas]

This is related to PR 13019 in MNE-Python and closes #262.

I also tried changing the example mne_inverse_label_connectivity.py to add an example use case. However, it appears that since the figure is rendered before the plot_connectivity_circle function exits, changes made afterwards do not become visible in the figure unless fig.show() is called, which leads to showing the figure twice. Workarounds to prevent this of course exist but might clutter the example unnecessarily. Thoughts?

[drammock]

thanks @ruuskas, looks good. For this one we'll wait to merge until the upstream change is in and we've formalized what the namespace structure will be like (so that we're certain that fig.mne.colorbar is the correct way to access this)

Marking as "request changes" just as a reminder that we shouldn't merge yet.

[drammock]

I also tried changing the example mne_inverse_label_connectivity.py to add an example use case. However, it appears that since the figure is rendered before the plot_connectivity_circle function exits, changes made afterwards do not become visible in the figure unless fig.show() is called, which leads to showing the figure twice.

I think the right approach in this case is to do plot_connectivity_circle(..., show=False) and then tweak the colorbar and then call fig.show() afterward.

[drammock]

wait to merge until the upstream change is in and we've formalized what the namespace structure will be like (so that we're certain that fig.mne.colorbar is the correct way to access this)

I don't think we've made any progress on formalizing the fig.mne namespace. It's kind of a big job as it needs to take into account all the possible plot types (at least the matplotlib ones, and maybe the pyvista ones too?). So I'm sorta inclined to just put this one in as fig.mne.colorbar even though I know this may not be ideal since some of our figures have multiple colorbars.

One possible "shortcut" to preventing too much churn later would be to create separate namespaces for each plotting function, so, e.g.: fig.mne.plot_connectivity_circle.colorbar in this case. That way we can incrementally add different plotting functions to the namespace, and hopefully maintain some consistency by looking at what's been done so far whenever it's time to add something new. WDYT?

[ruuskas]

I don't think we've made any progress on formalizing the fig.mne namespace. It's kind of a big job as it needs to take into account all the possible plot types (at least the matplotlib ones, and maybe the pyvista ones too?). So I'm sorta inclined to just put this one in as fig.mne.colorbar even though I know this may not be ideal since some of our figures have multiple colorbars.

One possible "shortcut" to preventing too much churn later would be to create separate namespaces for each plotting function, so, e.g.: fig.mne.plot_connectivity_circle.colorbar in this case. That way we can incrementally add different plotting functions to the namespace, and hopefully maintain some consistency by looking at what's been done so far whenever it's time to add something new. WDYT?

Is it often the case that e.g. colorbars from multiple plotting functions co-exist inside the same Figure instance? If not, then fig.mne.plot_something.colorbar feels a bit redundant. If a single plotting function call added multiple colorbars, I guess the logical thing would be to put them in a list.

[ruuskas]

I think the right approach in this case is to do plot_connectivity_circle(..., show=False) and then tweak the colorbar and then call fig.show() afterward.

True! I made a very small addition there.

[drammock]

Is it often the case that e.g. colorbars from multiple plotting functions co-exist inside the same Figure instance?

it's at least possible, as we have some plotting functions that can take a list of axes and use one of them for a colorbar. A maybe not-too-far-fetched example would be one or more scalp topographies combined with an epochs image plot. For journals that like large multi-panel "narrative" figures it seems (to me at least) not so far-fetched.

If not, then fig.mne.plot_something.colorbar feels a bit redundant.

This certainly could lead to unnecessary complication (though I think not redundancy, strictly speaking). It's motivated by (1) not having the time to flesh out a full namespace for all our plotting functions right now, and (2) wanting to avoid changing the namespace later in a way that will require users to edit their scripts.

If a single plotting function call added multiple colorbars, I guess the logical thing would be to put them in a list.

Agree that one function call yielding multiple colorbars should put them in a list.