Add option to show a zero line in browser

[cbrnr]

This PR adds an option to show a zero line (toggleable with "0") to the Matplotlib backend. I've implemented this feature for the Qt backend in mne-tools/mne-qt-browser#423.

Short example:

import numpy as np

import mne

mne.viz.set_browser_backend("matplotlib")

sfreq = 200.0
n_channels = 20
t = np.arange(int(60 * sfreq)) / sfreq

rng = np.random.default_rng(0)
offsets = rng.uniform(-100e-6, 100e-6, size=n_channels)
data = rng.standard_normal((n_channels, t.size)) * 20e-6 + offsets[:, np.newaxis]

ch_names = [f"EEG {i + 1}" for i in range(n_channels)]
info = mne.create_info(ch_names, sfreq, "eeg")
raw = mne.io.RawArray(data, info)

raw.plot(show_zero_line=True, scalings=dict(eeg=100e-6), n_channels=5, block=True)

[cbrnr]

The docs error (AssertionError: Duplicates in PYPI_PACKAGES and installer packages: ['mne-kit-gui']) is very likely unrelated.

The Azure error is also unrelated (hitting 403: rate limit exceeded).

[larsoner]

Hmm somehow it's hard for me to parse this. I expected at first that hitting "d" would change the position of the line in the plot. I think calling it "true zero" made me think of "where zero actually is for the signal". So maybe

Suggested change

	initialized. The zero line marks the true zero of each channel's own
	displayed trace, independent of any DC removal or highpass filtering
	already applied to the data. Can be toggled after initialization by
	initialized. The zero line marks the centering point of each channel's
	**displayed trace**, independent of any DC removal or highpass filtering
	already applied to the data. Can be toggled after initialization by

I wonder if there is value in having a third mode where toggling DC removal changes where the "zero line" is displayed so that it's actually at where the zero level is for that channel (in other words, treating "DC removal" as more of a visual vertical translation rather than a subtraction of any values from the trace)

[cbrnr]

Yeah, I thought about that as well. Can you think of a good way to visually distinguish the two modes that show the line? Otherwise it might be confusing if the line doesn't simple toggle when pressing "0".

[larsoner]

Maybe dashed for one (fixed location at the ch_name) and dotted for the other (where true zero is for the signal)?

[cbrnr]

Yes, this might work. Or maybe even clearer, dashed for the fixed location and solid for the true zero? True and solid is intuitive I think.

[larsoner]

Sure that works! That way the fixed looks more like an axis line anyway, which is what is basically is at that point

[cbrnr]

But does it make sense to show a zero line at the channel midpoint when DC removal is off? Could we couple the zero line to the currently set DC removal?

[cbrnr]

I now set the style of the zero line depending on whether DC removal is on or off. If it's off, we show the true zero line as a solid line. When it's on, we show a "virtual" zero line as a dashed line. Yes, if the signal has an actual mean of zero, the virtual mean will be equal to the true mean, but let's not overcomplicate this. Also, the difference between solid and dashed is pretty hard to spot, but I think it looks OK.

[larsoner]

Hmm okay I had something slightly different in mind. With DC removal off, this is what we see:

So for example, "true zero" for EEG 1 is generally below the rest of the data (so it is biased positively), and true zero for EEG 2 is generally above the rest of the data (so the signal is actually biased negatively (which is true since offsets[:2] is [ 2.73923375e-05 -4.60426572e-05]). I expected when hitting "d" to reenable DC removal that the line, this relationship between the "zero point" and the data would stay the same. But it doesn't, it stays at the "plotting baseline" / offset, i.e., always at the same y location as the channel label:

So in both of these cases, these line show the plotting baseline, which sometimes corresponds to the true signal zero level (when DC removal is off), or not (when DC removal is on).

What I was thinking of would add a bit of different information -- thinking of "DC removal" as just a visual plotting thing, the "zero line" would keep its position relative to the data. So in this last view, that would be like this:

i.e., you can tell where true signal zero is relative to the data (that is what the line represents in this mode, rather than the plotting baseline). Like EEG2 you can immediately tell is actually (almost) all negative, because the "zero line" is above it -- but it displays locally centered relative to the plotting baseline/offset. Does that make sense?

Diff to produce above

larsoner:~/python/mne-python$ git diff
diff --git a/mne/viz/_figure.py b/mne/viz/_figure.py
index 954b90c9e9..b14a194d75 100644
--- a/mne/viz/_figure.py
+++ b/mne/viz/_figure.py
@@ -401,10 +401,11 @@ class BrowserBase(ABC):
         # get only the channels we're displaying
         data = data[picks]
         # remove DC
+        self.mne.dc_values = np.nanmean(data[..., time_slice], axis=1)
         if self.mne.remove_dc:
             if thread:
                 thread.processText.emit("Removing DC...")
-            data -= np.nanmean(data[..., time_slice], axis=1, keepdims=True)
+            data -= self.mne.dc_values[:, np.newaxis]
         # apply filter
         if self.mne.filter_coefs is not None:
             if thread:
@@ -426,6 +427,7 @@ class BrowserBase(ABC):
         norms[white] = self.mne.scalings["whitened"]
         norms[norms == 0] = 1
         data /= 2 * norms[:, np.newaxis]
+        self.mne.dc_values /= 2 * norms
 
         return data
 
diff --git a/mne/viz/_mpl_figure.py b/mne/viz/_mpl_figure.py
index 2e546d4bc6..74cea3f0a6 100644
--- a/mne/viz/_mpl_figure.py
+++ b/mne/viz/_mpl_figure.py
@@ -2280,8 +2280,11 @@ class MNEBrowseFigure(BrowserBase, MNEFigure):
             this_type = ch_types[ii]
             this_offset = offsets[ii]
             if self.mne.zero_line_visible:
+                dc_y = this_offset
+                if self.mne.remove_dc:
+                    dc_y = dc_y + self.mne.dc_values[ii] * self.mne.scale_factor
                 self.mne.zero_lines[ii].set_xdata(time_range)
-                self.mne.zero_lines[ii].set_ydata((this_offset, this_offset))
+                self.mne.zero_lines[ii].set_ydata((dc_y, dc_y))
                 self.mne.zero_lines[ii].set_linestyle(
                     "dashed" if self.mne.remove_dc else "solid"
                 )

If you agree this is also a useful mode, then we have to figure out how to enable it. One way would be that "toggle zero line" could actually be a three-state switch: off (main), on-showing-plotting-baseline (currently added), on-showing-signal-zero (new mode I demonstrated)?

[cbrnr]

Yes, I agree that this is better and it was what I initially wanted. However, I think three toggle states are confusing, so I left it at on/off, but on now always shows the true zero even when DC removal is true.

[larsoner]

Failures are unrelated so in it goes, thanks @cbrnr !