ENH: group triaxial OPM topomaps by orientation

[PragnyaKhandelwal]

Reference issue (if any)

Closes #13781

What does this implement/fix?

Final fix for #13781: adds caller-facing grouped rendering for colocated triaxial OPM channels so orientation information is shown explicitly across visualization entry points.

Implemented:

• Grouped radial and tangential rendering in Evoked topomap.
• Grouped rendering and connector handling in Evoked joint plots.
• Grouped radial and tangential rendering in ICA component topomaps.
• Regression tests updated for topomap, joint, and ICA triaxial OPM behavior.

Additional information

• Manual visual check done for:

  • Evoked.plot_topomap grouped radial/tangential maps
  • Evoked.plot_joint grouped maps + connector lines
  • ICA.plot_components grouped radial/tangential titles

• A local helper script was used for manual visual smoke-checking on synthetic triaxial OPM data. I can share it if needed.

• Visual outputs:

  • Evoked topomap grouped view:

• Joint plot grouped view:

• ICA grouped components view:

[PragnyaKhandelwal]

Hi @larsoner....Just a friendly ping on this final wrap-up for the OPM topomaps. I've included visual outputs in the PR description showing the new grouped views. Ready to review whenever you have a chance!

[larsoner]

Code looks reasonable at first look. But now I'm wondering whether or not this can be combined / refactored with the mag/grad code for Neuromag systems. The problem is similar there: there are three sensors per location, one radial (magnetometer) and two tangential (gradiometers) and we plot the mags in one plot and the RMS of the gradiometers in another.

Do you think it's worth looking into that refactoring in this PR? Or would it be better to review + merge this PR as-is and then refactor afterward?

[PragnyaKhandelwal]

Thanks @larsoner! I completely agree that unifying the OPM and Neuromag mag/grad logic is the right architectural direction since the underlying radial/tangential problem is so similar.
Since this current PR is already quite dense with the OPM-specific tests and rendering logic, I think it would be cleaner to merge this as-is to close out #13781 without risking scope creep. We can then track the Neuromag unification in a fresh issue or PR.
As a quick heads-up on my end: my university final exams are starting this week and run through May 24th, so I will be stepping away from the keyboard for the next few weeks to focus on those. I would love to tackle that Neuromag refactor as my very first task once I am back! Does that sound like a good plan to you?

[larsoner]

Yeah that sounds reasonable to me!

One last request, can you modify some example(s)/tutorial(s) in a way that shows this new functionality?

[PragnyaKhandelwal]

Thanks @larsoner! I've added a new example demonstrating the grouped triaxial OPM topomaps using plot_topomap() and plot_joint() as requested.

Well I initially tried using the ucl_opm_auditory dataset, but it caused the Sphinx Gallery CI build to time out, so I swapped it to generate a fast, synthetic triaxial dataset instead to keep the docs build snappy.

Ready for final review and merge once these last CI checks turn green!

[larsoner]

Well I initially tried using the ucl_opm_auditory dataset, but it caused the Sphinx Gallery CI build to time out, so I swapped it to generate a fast, synthetic triaxial dataset instead to keep the docs build snappy.

Hmmm that's a problem, that's a real dataset and it should work on real data. Can you try running it with memory profiler for example to see if memory usage goes too high? It really shouldn't for evoked data... if you can push a commit that should work (or revert to one that should) I can also look

A fake triaxial dataset I think is less useful for people.