Cross-figure event passing system

[wmvanvliet]

Proposed in #11678, this PR works on the actual implementation of mne.viz.ui_events. The idea is to run our own event passing system so that figures can talk to each other. For example, if you change the time slider on one figure, the time in other figures is updated accordingly.

TODO:

• the core of the event system:
  • publish
  • subscribe
  • unsubscribe
  • link,
  • unlink
  • disable_ui_events context manager
• implementation of the TimeChange event for plot_topomap(time='interactive')
• make all unit tests pass again
• example of linking topomap plots and a custom plot
• (developer) documentation of the ui-event system
• add UI-Events section in the API docs for figures implementing ui-events
• update What's new
• Move to new folder tutorials/visualization
• Move publication figure example to tutorials/visualization with a redirect (in doc/conf.py)
• wait for 1.5 release

Follow-up PRs:

• @legacy the link_brains function and replace their internals with UI event passing (WIP: Add UI event support for Brain class #11891)
• Add example of raw<->epochs linking
• Add example of brain linking

Closes #11678

[wmvanvliet]

@larsoner is right, we need a better name than just "event" because that is easily confused with MEG event markers.

edit: this change has now been made.

[larsoner]

I think I prefer UIEvent. Another option would be FigEvent

[hoechenberger]

What is the current status / plan here?

[wmvanvliet]

Status is that the basic ui-event system seems to be working nicely. However, there are unit tests failing still (that somehow worked when testing locally?).

The plan for this PR is to only implement the ui-event system and the time_change event for Brain and plot_topomap, so it is manageable to review. Then in subsequent PRs we can start implementing ui-events for more of our plots. I've started a TODO section in the PR description up top.

[wmvanvliet]

In the upcoming developer sprint, the ui-event system can be a nice thing to work on.

[wmvanvliet]

Leaving this for 1.6 sounds good. This PR only makes sense in combination with a bunch of others that integrate the UI events into the interactive figures.

[larsoner]

@wmvanvliet FYI I edited the top comment with a tentative plan, feel free to adjust as you see fit

[wmvanvliet]

Working on Brain overhaul brought up a new issue with UI events that needs implementing: a way to temporarily disable them.

An issue with the design of the UI event system is how it interacts with GUI elements:

1. figure receives UI event requesting new value
2. figure updates plot and GUI elements to match new value
3. GUI element's set.value() call causes new UI event to fire
4. infinite loop :(

I thought the loop could be prevented by basically adding boilerplate to the event handlers checking whether new_value == old_value and silently dropping the event if that was the case. However, now I come across GUI elements that subtly change the value. For example:

1. figure receives UI event requesting a new value of 1.3453
2. figure updates plot and GUI text box that rounds the value to 1.35
3. text box value set_value() causes new UI event to fire with value of 1.35
4. figure receives UI event requesting a new value of 1.35
5. figure updates plot and GUI text box to 1.35 :(

I guess a more elegant solution is a context manager disable_ui_events that will temporarily silence the production of UI events. An event handler can wrap its GUI updating code with that to prevent loops.

[mscheltienne]

A signal blocker, disable_ui_events, similar to QSignalBlocker in Qt seems appropriate.

[larsoner]

Good to go again @wmvanvliet ? We cut 1.5 yesterday so this can be merged after one final review I think

[larsoner]

FYI to avoid this global business another (quicker/easier usually) approach is to use something mutable like a list:

callback_calls = list()

def callback(event):
    callback_calls.append(event)

...
assert len(callback_calls)  # or whatever

It automatically deals with this scoping stuff. I'll push a commit to do it then mark for merge when green, but if you really like the global approach I can live with it (and you can put it back in the next PR)!

[wmvanvliet]

No strong feelings about it :)

[larsoner]

This isn't really an API change the way we use it in latest.inc... it's a feature. API is really for deprecations

[wmvanvliet]

Cool! Now we can build lots of PRs on top of this. Adding interactivity everywhere.

[hoechenberger]

Great!