topomap mask should style sensor labels differently

[drammock]

#12906 reported a bug in how mask parameter applied to sensor labels in the topomap. That bug was fixed in #13470, but one aspect of #12906 was not addressed:

Case 3 [a mask with 1 true element]: All channel labels should be displayed, with "EEG 001" highlighted or emphasized due to the True value in the mask.

(emphasis added). I agree with that, and think it would be good to make the labels of the True sensors bold or something. But "or something" has a lot of room for bikeshedding / exposing knobs in the API / returning handles so the styling can be tweaked after-the-fact. So let's discuss how that should be done.

Originally posted by @drammock in https://github.com/mne-tools/mne-python/issues/13470#issuecomment-3469528677

[natinew77-creator]

Hi, I would like to work on this enhancement. This looks like a great opportunity to improve visualization clarity!

My plan is:

Locate the plotting function in mne/viz/topomap.py that handles the mask parameter and sensor labels.

Modify the label plotting logic (likely a call to ax.text or similar) to conditionally set the fontweight='bold' (or similar emphasis) only for the sensor labels corresponding to a True value in the provided mask.

Ensure the change is fully tested and adheres to MNE's code style.

Could you please review this plan and assign the issue to me if it is approved? Thank you!

[drammock]

Thanks for your enthusiasm @natinew77-creator! As I said above:

it would be good to make the labels of the True sensors bold or something. But "or something" has a lot of room for bikeshedding / exposing knobs in the API / returning handles

In other words, I'm not yet sure that simply making the labels bold will be the right way to signal emphasis --- we may want to use color, italics, size, or perhaps let the user decide (by exposing a font_properties dict or similar). I can see 2 possible paths forward:

1. someone mocks up the effect of a few different approaches (bold, italic, color, size) with a few different masks (e.g., a low-density and high-density layout, each with a low or high number of masked sensors). They share screenshots, and we discuss which approach is a sensible default.
2. We assume folks are going to want fine-grained control, and just start with an API that takes in a dict of font properties that will get passed through to the relevant matplotlib artist. Something like:

mask_label_style : dict | "bold"
    Font properties applied to the labels of masked sensors.
    Pass an empty :class:`dict` to style labels of masked
    sensors alike to non-masked sensor labels.
    Non-empty ``dict``s will be passed to the underlying matplotlib
    ``axes.text`` call (TODO: confirm this is the actual MPL API
    call used). ``"bold"`` is shorthand for ``dict(fontweight="bold")``.
    Default is ``"bold"``.

[natinew77-creator]

Thanks for the detailed feedback @drammock! I really appreciate the guidance.

I'll start with Path 1 - creating mockups to help drive consensus:

• I'll generate visual comparisons showing bold, italic, color, and size emphasis styles
• I'll test on both low-density and high-density sensor layouts with varying numbers of masked sensors
• I'll share the screenshots here for discussion

Once we agree on a sensible default, I can implement the flexible mask_label_style API approach you outlined.

I'll have the mockups ready soon!

[natinew77-creator]

Here are the mockups comparing different styling approaches, as requested:

EEG Topomap - Few Masked Sensors (~5%)

EEG Topomap - Many Masked Sensors (~30%)

MEG Magnetometer - Few Masked Sensors (~5%)

MEG Magnetometer - Many Masked Sensors (~30%)

---

Observations:

Style	Assessment
Bold	Clear emphasis, works well in all scenarios. Not too visually heavy.
Italic	Subtle - might be too hard to spot quickly.
Red Color	Very visible, but can feel overwhelming when many sensors are masked.
Larger Size	Noticeable, but may cause overlap in dense layouts.
Bold + Color	Maximum emphasis, but might be excessive for typical use.

My recommendation: I'd suggest Bold as the sensible default - it provides clear visual distinction without being overwhelming, and works well regardless of mask density.

The flexible mask_label_style API you proposed would work great, allowing users to customize if they prefer color or other styling.

Happy to implement whichever approach the team prefers!

---