Rework Reports (new history)

doc/changes/latest.inc

@@ -181,6 +181,10 @@ Enhancements
 
 - Add full ECoG dataset to MNE-misc-data and demonstrate its use in :ref:`ex-electrode-pos-2d` and :ref:`tut-ieeg-localize` (:gh:`9784` by `Alex Rockhill`_)
 
+- Completely revamp the `~mne.Report` experience: new HTML layout, many new methods, more flexibility; the functionality is demonstrated in :ref:`tut-report` (:gh:`9754` by `Richard Höchenberger`_, `Eric Larson`_, and `Alex Gramfort`_)
+
+- Add basic HTML representations of `~mne.Forward` and `~mne.minimum_norm.InverseOperator` instances for a nicer Jupyter experience (:gh:`9754` by `Richard Höchenberger`_)
+
 - `mne.io.read_raw_brainvision` now handles ASCII data with comma-separated values, as may be exported from BrainVision Analyzer (:gh:`9795` by `Richard Höchenberger`_)
 
 - Add :func:`mne.preprocessing.ieeg.project_sensors_onto_brain` to project ECoG sensors onto the pial surface to compensate for brain shift (:gh:`9800` by `Alex Rockhill`_)
@@ -265,6 +269,10 @@ Bugs
 
 - Fix bug where `mne.Annotations` were not appending channel names when being added together (:gh:`9780` by `Adam Li`_)
 
+- `mne.viz.plot_evoked_joint` now correctly handles a ``times='peaks'`` parameter value (:gh:`9754` by `Richard Höchenberger`_)
+
+- In `mne.viz.plot_compare_evokeds`, slightly adjust the x-axis limit calculation to avoid drawing an axis that is too short (:gh:`9754` by `Richard Höchenberger`_)
+
 API changes
 ~~~~~~~~~~~
 - In `mne.compute_source_morph`, the ``niter_affine`` and ``niter_sdr`` parameters have been replaced by ``niter`` and ``pipeline`` parameters for more consistent and finer-grained control of registration/warping steps and iteration (:gh:`9505` by `Alex Rockhill`_ and `Eric Larson`_)
@@ -277,4 +285,22 @@ API changes
 
 - :func:`mne.inverse_sparse.mixed_norm` now simply warns when source estimates contain no dipole, e.g. if data are too noisy and alpha is based on SURE (:gh:`9685` by `Alex Gramfort`_)
 
+- :class:`mne.Report` modernization has led to multiple deprecations (:gh:`9754` by `Richard Höchenberger`_):
+
+  - :meth:`mne.Report.add_figs_to_section` and :meth:`mne.Report.add_slider_to_section` have been deprecated in favor of :meth:`mne.Report.add_figure`
+
+  - :meth:`mne.Report.add_images_to_section` has been deprecated in favor of :meth:`mne.Report.add_image`
+
+  - :meth:`mne.Report.add_bem_to_section` has been deprecated in favor of :meth:`mne.Report.add_bem`
+
+  - :meth:`mne.Report.add_htmls_to_section` has been deprecated in favor of :meth:`mne.Report.add_html`
+
+  - In :meth:`mne.Report.parse_folder`, the ``sort_sections`` parameter has been deprecated in favor of ``sort_content``
+
+  - In :meth:`mne.Report.remove`, the ``caption`` and ``section`` parameters have been deprecated in favor of ``title`` and ``tags``, respectively
+
+  - The ``mne.Report.sections`` attribute has been deprecated in favor of ``mne.Report.tags``
+
+  - The ``mne.Report.fnames`` attribute has been deprecated without replacement
+
 - The output folder name for HF_SEF datasets is now ``hf_sef`` instead of ``HF_SEF`` (:gh:`9763` by `Adam Li`_)

mne/channels/channels.py

@@ -819,8 +819,8 @@ def pick_channels(self, ch_names, ordered=False):
         picks = pick_channels(self.info['ch_names'], ch_names, ordered=ordered)
         return self._pick_drop_channels(picks)
 
-    @fill_doc
-    def pick(self, picks, exclude=()):
+    @verbose
+    def pick(self, picks, exclude=(), *, verbose=None):
         """Pick a subset of channels.
 
         Parameters
@@ -829,6 +829,9 @@ def pick(self, picks, exclude=()):
         exclude : list | str
             Set of channels to exclude, only used when picking based on
             types (e.g., exclude="bads" when picks="meg").
+        %(verbose)s
+
+            .. versionadded:: 0.24.0
 
         Returns
         -------
@@ -920,7 +923,8 @@ def drop_channels(self, ch_names):
         idx = np.setdiff1d(np.arange(len(self.ch_names)), bad_idx)
         return self._pick_drop_channels(idx)
 
-    def _pick_drop_channels(self, idx):
+    @verbose
+    def _pick_drop_channels(self, idx, *, verbose=None):
         # avoid circular imports
         from ..io import BaseRaw
         from ..time_frequency import AverageTFR, EpochsTFR

mne/data/html_templates.py

@@ -2,7 +2,7 @@
 
 
 info_template = Template("""
-<table class="table table-hover">
+<table class="table table-hover table-striped table-sm table-responsive small">
     <tr>
         <th>Measurement date</th>
         {{if meas_date is not None}}
@@ -82,7 +82,7 @@
 """)
 
 epochs_template = Template("""
-<table class="table table-hover">
+<table class="table table-hover table-striped table-sm table-responsive small">
     <tr>
         <th>Number of events</th>
         <td>{{len(epochs.events)}}</td>
@@ -105,3 +105,41 @@
     </tr>
 </table>
 """)
+
+forward_template = Template("""
+<table class="table table-hover table-striped table-sm table-responsive small">
+    <tr>
+        <th>Good channels</th>
+        <td>{{good_channels}}</td>
+    </tr>
+    <tr>
+        <th>Bad channels</th>
+        <td>{{bad_channels}}</td>
+    </tr>
+    <tr>
+        <th>Source space</th>
+        <td>{{source_space_descr}}</td>
+    </tr>
+    <tr>
+        <th>Source orientation</th>
+        <td>{{source_orientation}}</td>
+    </tr>
+</table>
+""")
+
+inverse_operator_template = Template("""
+<table class="table table-hover table-striped table-sm table-responsive small">
+    <tr>
+        <th>Channels</th>
+        <td>{{channels}}</td>
+    </tr>
+    <tr>
+        <th>Source space</th>
+        <td>{{source_space_descr}}</td>
+    </tr>
+    <tr>
+        <th>Source orientation</th>
+        <td>{{source_orientation}}</td>
+    </tr>
+</table>
+""")

mne/defaults.py

@@ -151,6 +151,16 @@
         58,  # Right-Accumbens-area
 
         60,  # Right-VentralDC
+    ),
+    report_stc_plot_kwargs=dict(
+        views=('lateral', 'medial'),
+        hemi='split',
+        backend='pyvistaqt',
+        time_viewer=False,
+        show_traces=False,
+        size=(450, 450),
+        background='white',
+        time_label=None
     )
 )
 

mne/evoked.py

@@ -136,6 +136,7 @@ def __init__(self, fname, condition=None, proj=True,
         # project and baseline correct
         if proj:
             self.apply_proj()
+        self.filename = fname
 
     @property
     def kind(self):

mne/fixes.py

@@ -12,7 +12,6 @@
 #          Lars Buitinck <L.J.Buitinck@uva.nl>
 # License: BSD
 
-from distutils.version import LooseVersion
 import functools
 import inspect
 from math import log
@@ -23,6 +22,39 @@
 import numpy as np
 
 
+###############################################################################
+# distutils
+
+# distutils has been deprecated since Python 3.10 and is scheduled for removal
+# from the standard library with the release of Python 3.12. For version
+# comparisons, we use setuptools's `parse_version` if available.
+
+def _compare_version(version_a, operator, version_b):
+    """Compare two version strings via a user-specified operator.
+
+    Parameters
+    ----------
+    version_a : str
+        First version string.
+    operator : '==' | '>' | '<' | '>=' | '<='
+        Operator to compare ``version_a`` and ``version_b`` in the form of
+        ``version_a operator version_b``.
+    version_b : str
+        Second version string.
+
+    Returns
+    -------
+    bool
+        The result of the version comparison.
+    """
+    try:
+        from pkg_resources import parse_version as parse
+    except ImportError:
+        from distutils.version import LooseVersion as parse
+
+    return eval(f'parse("{version_a}") {operator} parse("{version_b}")')
+
+
 ###############################################################################
 # Misc
 
@@ -928,7 +960,7 @@ def _crop_colorbar(cbar, cbar_vmin, cbar_vmax):
     # _outline was removed in
     # https://github.com/matplotlib/matplotlib/commit/03a542e875eba091a027046d5ec652daa8be6863
     # so we use the code from there
-    if LooseVersion(matplotlib.__version__) >= LooseVersion("3.2.0"):
+    if _compare_version(matplotlib.__version__, '>=', '3.2.0'):
         cbar.ax.set_ylim(cbar_vmin, cbar_vmax)
         X = cbar._mesh()[0]
         X = np.array([X[0], X[-1]])
@@ -959,7 +991,7 @@ def _crop_colorbar(cbar, cbar_vmin, cbar_vmax):
 # Here we choose different defaults to speed things up by default
 try:
     import numba
-    if LooseVersion(numba.__version__) < LooseVersion('0.40'):
+    if _compare_version(numba.__version__, '<', '0.40'):
         raise ImportError
     prange = numba.prange
     def jit(nopython=True, nogil=True, fastmath=True, cache=True,

mne/forward/forward.py

@@ -49,6 +49,7 @@
                      _validate_type, _check_compensation_grade, _check_option,
                      _check_stc_units, _stamp_to_dt, _on_missing)
 from ..label import Label
+from ..data.html_templates import forward_template
 
 
 class Forward(dict):
@@ -66,25 +67,15 @@ def copy(self):
         """Copy the Forward instance."""
         return Forward(deepcopy(self))
 
-    def __repr__(self):
-        """Summarize forward info instead of printing all."""
-        entr = '<Forward'
-
-        nchan = len(pick_types(self['info'], meg=True, eeg=False, exclude=[]))
-        entr += ' | ' + 'MEG channels: %d' % nchan
-        nchan = len(pick_types(self['info'], meg=False, eeg=True, exclude=[]))
-        entr += ' | ' + 'EEG channels: %d' % nchan
-
+    def _get_src_type_and_ori_for_repr(self):
         src_types = np.array([src['type'] for src in self['src']])
+
         if (src_types == 'surf').all():
-            entr += (' | Source space: Surface with %d vertices'
-                     % self['nsource'])
+            src_type = 'Surface with %d vertices' % self['nsource']
         elif (src_types == 'vol').all():
-            entr += (' | Source space: Volume with %d grid points'
-                     % self['nsource'])
+            src_type = 'Volume with %d grid points' % self['nsource']
         elif (src_types == 'discrete').all():
-            entr += (' | Source space: Discrete with %d dipoles'
-                     % self['nsource'])
+            src_type = 'Discrete with %d dipoles' % self['nsource']
         else:
             count_string = ''
             if (src_types == 'surf').any():
@@ -95,20 +86,45 @@ def __repr__(self):
                 count_string += '%d discrete, ' \
                                 % (src_types == 'discrete').sum()
             count_string = count_string.rstrip(', ')
-            entr += (' | Source space: Mixed (%s) with %d vertices'
-                     % (count_string, self['nsource']))
+            src_type = ('Mixed (%s) with %d vertices'
+                        % (count_string, self['nsource']))
 
         if self['source_ori'] == FIFF.FIFFV_MNE_UNKNOWN_ORI:
-            entr += (' | Source orientation: Unknown')
+            src_ori = 'Unknown'
         elif self['source_ori'] == FIFF.FIFFV_MNE_FIXED_ORI:
-            entr += (' | Source orientation: Fixed')
+            src_ori = 'Fixed'
         elif self['source_ori'] == FIFF.FIFFV_MNE_FREE_ORI:
-            entr += (' | Source orientation: Free')
+            src_ori = 'Free'
+
+        return src_type, src_ori
 
+    def __repr__(self):
+        """Summarize forward info instead of printing all."""
+        entr = '<Forward'
+
+        nchan = len(pick_types(self['info'], meg=True, eeg=False, exclude=[]))
+        entr += ' | ' + 'MEG channels: %d' % nchan
+        nchan = len(pick_types(self['info'], meg=False, eeg=True, exclude=[]))
+        entr += ' | ' + 'EEG channels: %d' % nchan
+
+        src_type, src_ori = self._get_src_type_and_ori_for_repr()
+        entr += f' | Source space: {src_type}'
+        entr += f' | Source orientation: {src_ori}'
         entr += '>'
 
         return entr
 
+    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()
+        html = forward_template.substitute(
+            good_channels=good_chs,
+            bad_channels=bad_chs,
+            source_space_descr=src_descr,
+            source_orientation=src_ori
+        )
+        return html
+
     @property
     def ch_names(self):
         return self['info']['ch_names']

mne/inverse_sparse/mxne_optim.py

@@ -73,22 +73,6 @@ def prox_l21(Y, alpha, n_orient, shape=None, is_stft=False):
         The output data.
     active_set : array of bool, shape (n_sources, )
         Mask of active sources
-
-    Examples
-    --------
-    >>> Y = np.tile(np.array([0, 4, 3, 0, 0], dtype=np.float64), (2, 1))
-    >>> Y = np.r_[Y, np.zeros_like(Y)]
-    >>> print(Y)  # doctest:+SKIP
-    [[ 0.  4.  3.  0.  0.]
-     [ 0.  4.  3.  0.  0.]
-     [ 0.  0.  0.  0.  0.]
-     [ 0.  0.  0.  0.  0.]]
-    >>> Yp, active_set = prox_l21(Y, 2, 2)
-    >>> print(Yp)  # doctest:+SKIP
-    [[0.         2.86862915 2.15147186 0.         0.        ]
-     [0.         2.86862915 2.15147186 0.         0.        ]]
-    >>> print(active_set)
-    [ True  True False False]
     """
     if len(Y) == 0:
         return np.zeros_like(Y), np.zeros((0,), dtype=bool)

mne/io/meas_info.py

@@ -818,13 +818,8 @@ def pick_channels(self, ch_names, ordered=False):
     def ch_names(self):
         return self['ch_names']
 
-    def _repr_html_(self, caption=None):
-        """Summarize info for HTML representation."""
+    def _get_chs_for_repr(self):
         titles = _handle_default('titles')
-        if isinstance(caption, str):
-            html = f'<h4>{caption}</h4>'
-        else:
-            html = ''
 
         # good channels
         channels = {}
@@ -858,6 +853,17 @@ def _repr_html_(self, caption=None):
         else:
             bad_channels = 'None'
 
+        return good_channels, bad_channels, ecg, eog
+
+    def _repr_html_(self, caption=None):
+        """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()
+
         # meas date
         meas_date = self['meas_date']
         if meas_date is not None: