MRG: Revamp HTML reprs of Raw, Epochs, Evoked, and Info

doc/changes/devel/12583.apichange.rst

@@ -0,0 +1,2 @@
+``mne.Info.ch_names`` will now return an empty list instead of raising a ``KeyError`` if no channels
+are present, by `Richard Höchenberger`_.

doc/changes/devel/12583.newfeature.rst

@@ -0,0 +1,4 @@
+The HTML representations of :class:`~mne.io.Raw`, :class:`~mne.Epochs`,
+and :class:`~mne.Evoked` (which you will see e.g. when working with Jupyter Notebooks or
+:class:`~mne.Report`) have been updated to be more consistent and contain
+slightly more information,  by `Richard Höchenberger`_.

mne/_fiff/meas_info.py

@@ -10,7 +10,7 @@
 import datetime
 import operator
 import string
-from collections import Counter, OrderedDict, defaultdict
+from collections import Counter, OrderedDict
 from collections.abc import Mapping
 from copy import deepcopy
 from io import BytesIO
@@ -1835,84 +1835,18 @@ def _update_redundant(self):
 
     @property
     def ch_names(self):
-        return self["ch_names"]
-
-    def _get_chs_for_repr(self):
-        titles = _handle_default("titles")
-
-        # good channels
-        good_names = defaultdict(lambda: list())
-        for ci, ch_name in enumerate(self["ch_names"]):
-            if ch_name in self["bads"]:
-                continue
-            ch_type = channel_type(self, ci)
-            good_names[ch_type].append(ch_name)
-        good_channels = ", ".join(
-            [f"{len(v)} {titles.get(k, k.upper())}" for k, v in good_names.items()]
-        )
-        for key in ("ecg", "eog"):  # ensure these are present
-            if key not in good_names:
-                good_names[key] = list()
-        for key, val in good_names.items():
-            good_names[key] = ", ".join(val) or "Not available"
-
-        # bad channels
-        bad_channels = ", ".join(self["bads"]) or "None"
+        try:
+            ch_names = self["ch_names"]
+        except KeyError:
+            ch_names = []
 
-        return good_channels, bad_channels, good_names["ecg"], good_names["eog"]
+        return ch_names
 
     @repr_html
-    def _repr_html_(self, caption=None, duration=None, filenames=None):
+    def _repr_html_(self):
         """Summarize info for HTML representation."""
-        if isinstance(caption, str):
-            html = f"<h4>{caption}</h4>"
-        else:
-            html = ""
-
-        good_channels, bad_channels, ecg, eog = self._get_chs_for_repr()
-
-        # TODO
-        # Most of the following checks are to ensure that we get a proper repr
-        # for Forward['info'] (and probably others like
-        # InverseOperator['info']??), which doesn't seem to follow our standard
-        # Info structure used elsewhere.
-        # Proposed solution for a future refactoring:
-        # Forward['info'] should get its own Info subclass (with respective
-        # repr).
-
-        # meas date
-        meas_date = self.get("meas_date")
-        if meas_date is not None:
-            meas_date = meas_date.strftime("%B %d, %Y  %H:%M:%S") + " GMT"
-
-        projs = self.get("projs")
-        if projs:
-            projs = [
-                f'{p["desc"]} : {"on" if p["active"] else "off"}' for p in self["projs"]
-            ]
-        else:
-            projs = None
-
         info_template = _get_html_template("repr", "info.html.jinja")
-        sections = ("General", "Channels", "Data")
-        return html + info_template.render(
-            sections=sections,
-            caption=caption,
-            meas_date=meas_date,
-            projs=projs,
-            ecg=ecg,
-            eog=eog,
-            good_channels=good_channels,
-            bad_channels=bad_channels,
-            dig=self.get("dig"),
-            subject_info=self.get("subject_info"),
-            lowpass=self.get("lowpass"),
-            highpass=self.get("highpass"),
-            sfreq=self.get("sfreq"),
-            experimenter=self.get("experimenter"),
-            duration=duration,
-            filenames=filenames,
-        )
+        return info_template.render(info=self)
 
     def save(self, fname):
         """Write measurement info in fif file.

mne/epochs.py

@@ -17,6 +17,7 @@
 from copy import deepcopy
 from functools import partial
 from inspect import getfullargspec
+from pathlib import Path
 
 import numpy as np
 from scipy.interpolate import interp1d
@@ -2062,12 +2063,6 @@ def __repr__(self):
 
     @repr_html
     def _repr_html_(self):
-        if self.baseline is None:
-            baseline = "off"
-        else:
-            baseline = tuple([f"{b:.3f}" for b in self.baseline])
-            baseline = f"{baseline[0]} – {baseline[1]} s"
-
         if isinstance(self.event_id, dict):
             event_strings = []
             for k, v in sorted(self.event_id.items()):
@@ -2085,7 +2080,15 @@ def _repr_html_(self):
             event_strings = None
 
         t = _get_html_template("repr", "epochs.html.jinja")
-        t = t.render(epochs=self, baseline=baseline, events=event_strings)
+        t = t.render(
+            inst=self,
+            filenames=(
+                [Path(self.filename).name]
+                if getattr(self, "filename", None) is not None
+                else None
+            ),
+            event_counts=event_strings,
+        )
         return t
 
     @verbose

mne/evoked.py

@@ -10,6 +10,7 @@
 
 from copy import deepcopy
 from inspect import getfullargspec
+from pathlib import Path
 from typing import Union
 
 import numpy as np
@@ -467,14 +468,15 @@ def __repr__(self):  # noqa: D105
 
     @repr_html
     def _repr_html_(self):
-        if self.baseline is None:
-            baseline = "off"
-        else:
-            baseline = tuple([f"{b:.3f}" for b in self.baseline])
-            baseline = f"{baseline[0]} – {baseline[1]} s"
-
         t = _get_html_template("repr", "evoked.html.jinja")
-        t = t.render(evoked=self, baseline=baseline)
+        t = t.render(
+            inst=self,
+            filenames=(
+                [Path(self.filename).name]
+                if getattr(self, "filename", None) is not None
+                else None
+            ),
+        )
         return t
 
     @property

mne/forward/forward.py

@@ -225,17 +225,11 @@ def __repr__(self):
 
     @repr_html
     def _repr_html_(self):
-        (
-            good_chs,
-            bad_chs,
-            _,
-            _,
-        ) = self["info"]._get_chs_for_repr()
         src_descr, src_ori = self._get_src_type_and_ori_for_repr()
+
         t = _get_html_template("repr", "forward.html.jinja")
         html = t.render(
-            good_channels=good_chs,
-            bad_channels=bad_chs,
+            info=self["info"],
             source_space_descr=src_descr,
             source_orientation=src_ori,
         )

mne/html_templates/_templates.py

@@ -1,10 +1,105 @@
 # License: BSD-3-Clause
 # Copyright the MNE-Python contributors.
+import datetime
 import functools
+import uuid
+from collections import defaultdict
+from typing import Any, Literal, Union
+
+from .._fiff.pick import channel_type
+from ..defaults import _handle_default
 
 _COLLAPSED = False  # will override in doc build
 
 
+def _format_number(value: Union[int, float]) -> str:
+    """Insert thousand separators."""
+    return f"{value:,}"
+
+
+def _append_uuid(string: str, sep: str = "-") -> str:
+    """Append a UUID to a string."""
+    return f"{string}{sep}{uuid.uuid1()}"
+
+
+def _data_type(obj) -> str:
+    """Return the qualified name of a class."""
+    return obj.__class__.__qualname__
+
+
+def _dt_to_str(dt: datetime.datetime) -> str:
+    """Convert a datetime object to a human-readable string representation."""
+    return dt.strftime("%B %d, %Y at %H:%M:%S %Z")
+
+
+def _format_baseline(inst) -> str:
+    """Format the baseline time period."""
+    if inst.baseline is None:
+        baseline = "off"
+    else:
+        baseline = (
+            f"{round(inst.baseline[0], 3):.3f} – {round(inst.baseline[1], 3):.3f} s"
+        )
+
+    return baseline
+
+
+def _format_time_range(inst) -> str:
+    """Format evoked and epochs time range."""
+    tr = f"{round(inst.tmin, 3):.3f} – {round(inst.tmax, 3):.3f} s"
+    return tr
+
+
+def _format_projs(info) -> list[str]:
+    """Format projectors."""
+    projs = [f'{p["desc"]} ({"on" if p["active"] else "off"})' for p in info["projs"]]
+    return projs
+
+
+def _format_channels(info, ch_type: Literal["good", "bad", "ecg", "eog"]) -> str:
+    """Format channel names."""
+    titles = _handle_default("titles")
+
+    if info.ch_names:
+        # good channels
+        good_names = defaultdict(lambda: list())
+        for ci, ch_name in enumerate(info.ch_names):
+            if ch_name in info["bads"]:
+                continue
+            channel_type_ = channel_type(info, ci)
+            good_names[channel_type_].append(ch_name)
+            del channel_type_
+        good_channels = ", ".join(
+            [f"{len(v)} {titles.get(k, k.upper())}" for k, v in good_names.items()]
+        )
+        for key in ("ecg", "eog"):  # ensure these are present
+            if key not in good_names:
+                good_names[key] = list()
+        for key, val in good_names.items():
+            good_names[key] = ", ".join(val) or "Not available"
+
+        # bad channels
+        bad_channels = ", ".join(info["bads"]) or "None"
+
+        # ECG and EOG
+        ecg = good_names["ecg"]
+        eog = good_names["eog"]
+    else:
+        good_channels = bad_channels = ecg = eog = "None"
+
+    channels = {"good": good_channels, "bad": bad_channels, "ecg": ecg, "eog": eog}
+    return channels[ch_type]
+
+
+def _has_attr(obj: Any, attr: str) -> bool:
+    """Check if an object has an attribute `obj.attr`.
+
+    This is needed because on dict-like objects, Jinja2's `obj.attr is defined` would
+    check for `obj["attr"]`, which may not be what we want.
+    """
+    return hasattr(obj, attr)
+
+
 @functools.lru_cache(maxsize=2)
 def _get_html_templates_env(kind):
     # For _html_repr_() and mne.Report
@@ -19,6 +114,16 @@ def _get_html_templates_env(kind):
     )
     if kind == "report":
         templates_env.filters["zip"] = zip
+
+    templates_env.filters["format_number"] = _format_number
+    templates_env.filters["append_uuid"] = _append_uuid
+    templates_env.filters["data_type"] = _data_type
+    templates_env.filters["dt_to_str"] = _dt_to_str
+    templates_env.filters["format_baseline"] = _format_baseline
+    templates_env.filters["format_time_range"] = _format_time_range
+    templates_env.filters["format_projs"] = _format_projs
+    templates_env.filters["format_channels"] = _format_channels
+    templates_env.filters["has_attr"] = _has_attr
     return templates_env
 
 

mne/html_templates/repr/_channels.html.jinja

@@ -0,0 +1,52 @@
+{% set section = "Channels" %}
+{% set section_class_name = section | lower | append_uuid %}
+
+{# Collapse content during documentation build. #}
+{% if collapsed %}
+{% set collapsed_row_class = "repr-element-faded repr-element-collapsed" %}
+{% else %}
+{% set collapsed_row_class = "" %}
+{% endif %}
+
+<tr class="no-stripes">
+    <th class="repr-section-header repr-section-toggle-col">
+        <button {% if collapsed %} class="collapsed" title="Show section" {% else %} title="Hide section" {% endif %}
+            onclick="toggleVisibility('{{ section_class_name }}', this)">
+            {# This span is for the background SVG icon #}
+            <span class="collapse-uncollapse-caret"></span>
+        </button>
+    </th>
+    </th>
+    <th class="repr-section-header" colspan="2">
+        <strong>{{ section }}</strong>
+    </th>
+</tr>
+<tr class="repr-element {{ section_class_name }} {{ collapsed_row_class }}">
+    <td></td>
+    <td>Good channels</td>
+    <td>{{ info | format_channels("good") }}</td>
+</tr>
+<tr class="repr-element {{ section_class_name }} {{ collapsed_row_class }}">
+    <td></td>
+    <td>Bad channels</td>
+    <td>{{ info | format_channels("bad") }}</td>
+</tr>
+<tr class="repr-element {{ section_class_name }} {{ collapsed_row_class }}">
+    <td></td>
+    <td>EOG channels</td>
+    <td>{{ info | format_channels("eog") }}</td>
+</tr>
+<tr class="repr-element {{ section_class_name }} {{ collapsed_row_class }}">
+    <td></td>
+    <td>ECG channels</td>
+    <td>{{ info | format_channels("ecg") }}</td>
+</tr>
+<tr class="repr-element {{ section_class_name }} {{ collapsed_row_class }}">
+    <td></td>
+    <td>Head shape and sensor digitization</td>
+    {% if info["dig"] is not none %}
+    <td>{{ info["dig"] | length }} points</td>
+    {% else %}
+    <td>Not available</td>
+    {% endif %}
+</tr>