GSoC 2026: Event System meta issue

[Gnefil]

Introduction

This meta issue holds a dynamic log of planned and ongoing tasks around enhancing the event system in MNE.
It is also the Working Product Report for Google Summer of Code 2026.

Details

GSoC Contributor: Lifeng Qiu Lin
Main Supervisor/Mentor: Marijn van Vliet
Organisation: Python Software Foundation - MNE-Python
Project Title: Implement and Improve Bidirectional Event System across MNE plots

Description

The event system allows property transfer between plots dynamically, even from different sources in MNE. The existing architecture is well-structured; however, the integration of the events in plots is not complete. This project emerged as an idea to implement new and appropriate behaviours in diverse kinds of plots, including in future GUIs like the dipole-fitting system, to handle events.

In the end, we expect to see plots interacting in real time when toggling one of them, providing accurate cues in all others after one selection.

Issues solved and PRs implemented

Main Code Contributions

• Channel ordering bug in mne.viz.plot_compare_evokeds when axes="topo" #13924
  • Main changes:
    • Fix misaligned channels in multiple Evoked instances that are treated as aligned bug
    • Fix the non-default-ordering channels placed wrongly as the default ones bug
  • PR: Fix channel ordering #13943
• ENH Equip mne.viz.plot_evoked_topo with TimeChange event #13928
  • Main changes:
    • Enhance plot_evoked_topo with TimeChange behaviour - vertical bar
    • Enhance plot_evoked_topo main and subfigures, both react to TimeChange and is able to publish
    • Enhance ui_events.link, allow recursive option to link the groups the figures belong to too
    • API change in mne.viz.iter_topography, the on_pick callable accepts new parameter orig_fig that refers to the main figure
  • PR: ENH: Implement TimeChange behaviour for evoked_topo and recursive option in link #13968
• ENH: Add TimeChange behaviour in plot_evoked #14024
  • Main changes:
    • Fix in mne.viz.plot_evoked, spatial_colors is not "auto" by default, as described by docs or like mne.Evoked.plot
    • Fix the empty topo map bug when clicking after time range selection in plot_evoked
    • Enhance plot_evoked with TimeChange behaviour - vertical bar, able to subscribe and publish TimeChange event
    • Refactor mne.viz.plot_ica_sources when passing Evoked instance, streamline and plug into existing functions, removing tech debt
    • Enhance the ICA source plot to have the same hover, clicking, event functionalities like plot_evoked
  • PR: ENH: Add TimeChange behaviour to plot_evoked #14025
• ENH: Improve VertexSelect-related functions by passing Source Index in addition to Vertex Index #14094
  • Main changes:
    • Enhance ‎mne/viz/_brain/_brain.py Brain plotting to carry source_id parameter in VertexSelect event
    • Document the convenience of using the nearest source point in a dipole visualisation through a tutorial example
  • PRs:
    • ENH: Let vertexSelect event to carry the estimated source id #14126
    • Vertexselect source index renaming #14154
    • DOC: Example using Vertexselect with source index #14169
• Create a dipole fitting GUI that is better than XFit #11977
  • Continuation of existing PR: XFit-style dipole fitting GUI #13074
  • Main changes:
    • Fix mne/gui/tests/test_dipolefit.py - DipoleFitUI class ChannelsSelection problem when sensors didn't change colour according to user selection
    • Enhance the logic of cloud and actors from mne/viz/_3d.py to record channels from upstream; now each cloud iterates through channel types and coils
    • Enhance the ChannelsSelection to be propagated to outer main figure links when retrieved by subfigures
  • PR: ENH: Reapir and enahnce logic of ChannelsSelect event handling in Xfit-like dipole GUI wmvanvliet/mne-python#25

Issues participated:

• BUG: Unexpected plot discrepancy when plotting as script compared to running in IPython #13956
• ENH: Show the current time as a vertical line in plot_evoked_topo #14032
• BUG: Evoked Topomap broken interactivity #14038

Note

• Not all code logic is commented here for length reasons; see each PR for details
• All new functions come with their respective tests, even when they are not explicitly written in the changelog
• Documentation is provided for each PR, also provided inside the framework in variable length, depending on the scope

Lessons and challenges

Along the way, I faced many challenges and learnt a lot of lessons as a result. I hope sharing them would help future contributors who want to get involved in MNE, or simply another read for one's programming experience.

• One big problem I faced at the beginning was understanding the main pipelines in the framework, as anyone starting on a new code base. In this case, tutorials on the MNE website, the search function, and starting by fixing a small bug, these are things that help a lot.
• One lesson I learnt is to continue implementing the solution until you face a behavioural decision. One could wait for guidance there at early stages, while after getting used to it, choose to proceed with one of the options, and then explain later to the mentor to agree or discard the design (with justification).
• Another interesting challenge is how tangled the calls and variables are in some of the classes or functions, especially the plotting ones, which require lots of decorating. There is no excellent solution to this, but get used to the naming convention (ask if unsure), and try to trace back through the lines and calls.
• Finally, mentor usually has the expertise to know what you are looking for or where to look for a certain thing, which can save a lot of time when you are unfamiliar, but you should carefully weigh the effort and time needed.