Splitting _brain.py into multiple modules

[payamsash]

Describe the new feature or enhancement

mne/viz/_brain/_brain.py is currently over 5k lines and all in one Brain class which makes adding new features and debugging difficult. also as mentioned by @wmvanvliet:

The _brain.py code is become too long though. We should split it up into multiple files at some point.

``

Describe your proposed implementation

I would suggest using mixing classes (as it also been used at other places like BaseRaw and BaseEpochs) sth like:

@fill_doc
class Brain(
    _SourceDataMixin,    # add_data, add_label, add_annotation, _add_volume_data, ...
    _ObjectsMixin,       # add_forward/dipole/head/skull/volume_labels/foci/sensors/text
    _ScalarDataMixin,    # update_lut, colormap range, time interpolation, _update_glyphs
    _AppearanceMixin,    # set_surf, set_cortex_colormap, silhouette
    _CameraMixin,        # show_view, _set_camera, reset_view
    _PickingMixin,       # picking, hover, glyphs, mpl traces
   ...
)

and a _helpers.py for taking the module level helpers (e.g. _safe_interp1d, _update_limits, ...).

Do you agree with this approach? @larsoner @wmvanvliet , also consider that mixins will be single use. also I would like to wait until we finally decide on the skeleton, for example I'm not sure if we need _events.py for ui_events handlers or should we put plot_time_course into picking or sth like _traces.py.

Describe possible alternatives

.

Additional context

No response

[larsoner]

I think something like this could work, but ideally each of these mixins would help with separability / understandability, too, more so than just moving code. Thinking about _CameraMixin it probably already is mostly separable, but thinking about _SourceDataMixin / _ScalarDataMixin, they'd need to know about and manipulate each other's objects a lot. In other words, ideally the mixins would provide some level of abstraction that functionally disentangles the bits of code as well. To go more in that direction, thinking about the "scene code" (stuff that works without setup_time_viewer) versus the "time-viewer code" (created by setup_time_viewer), how about instead:

First PR

Move the time viewer code into _time_viewer.py (setup_time_viewer through the dock/toolbar/status-bar setup, picking, etc. and related GUI methods). Purely a code move + Mixin class added to Brain, shouldn't need any test updates.

Follow-up PRs

1. Make the scene code stop reaching into the time-viewer code, ideally one spot at a time for reviewability. The idea is that the scene code just says "something changed" (maybe via private UI events?) and the time viewer reacts to it, so the dependency only goes one way. At the end, _brain.py shouldn't reference anything defined in _time_viewer.py.
2. Move-only PRs for other chunks that are already pretty separable. For example, the add_*/remove_* scene objects (head, skull, sensors, dipole, foci, ...) could go into _scene.py, and save_movie etc. into a _movie.py.
3. Replace the nested _all_data dicts with some small dataclasses for the overlays. This is where the _SourceDataMixin / _ScalarDataMixin stuff would go. I think data + colormap limits + time + smoothing should stay together in _brain.py, since they're really one thing. (This one will need some tests adapted, because the tests use these things directly).
4. Longer-term: _TimeViewerMixin could become a separate _TimeViewer object that holds a reference to the Brain. This would get us closer to a model / view / controller setup, but it's a bigger change.

WDYT?