Merge remote-tracking branch 'upstream/main' into fix_fnirschannelmerge

* upstream/main: BUG: Avoid warning in report.add_ica (mne-tools#11232) testing new features of website theme [circle deploy] (mne-tools#11033) BUG: Fix regression with run_subprocess (mne-tools#11230) DOC: fix mne-kit-gui package name (mne-tools#11231)
larsoner · Oct 11, 2022 · 54a0c3c · 54a0c3c
2 parents 6f62a9d + 0a0e00f
commit 54a0c3c
Show file tree

Hide file tree

Showing 15 changed files with 139 additions and 110 deletions.
diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html
@@ -5,76 +5,16 @@
     {{ super() }}
 {% endblock %}
 
-{%- block content %}
-
-  <!-- checkbox to toggle primary sidebar -->
-  <input type="checkbox" class="sidebar-toggle" name="__primary" id="__primary">
-  <label class="overlay overlay-primary" for="__primary"></label>
-
-  <!-- Checkboxes to toggle the secondary sidebar -->
-  <input type="checkbox" class="sidebar-toggle" name="__secondary" id="__secondary">
-  <label class="overlay overlay-secondary" for="__secondary"></label>
-
-  <!-- A search field pop-up that will only show when the search button is clicked -->
-
-  <div class="search-button__wrapper">
-    <div class="search-button__overlay"></div>
-    <div class="search-button__search-container">
-      {% include "../components/search-field.html" %}
-    </div>
-  </div>
-
-  {% include "sections/announcement.html" %}
-
-  {% block docs_navbar %}
-  <nav class="bd-header navbar navbar-light navbar-expand-lg bg-light fixed-top bd-navbar" id="navbar-main">
-    {%- include "sections/header.html" %}
-  </nav>
-  {% endblock %}
-
-  <div class="bd-container container-xl">
-    <div class="bd-container__inner row">
-      {% include "sections/sidebar-primary.html" %}
-      <!-- ↓↓↓↓↓ this chunk is customized ↓↓↓↓↓ -->
-      {% if pagename != 'index' %}
-        {% include "sections/sidebar-secondary.html" %}
-      {% endif %}
-      <!-- ↑↑↑ this chunk is customized ↑↑↑ -->
-
-      {% block docs_main %}
-      <div class="bd-content col">
-
-        <div class="bd-header-article">
-            {% include "sections/header-article.html" %}
-        </div>
-
-        <!-- ↓↓↓↓↓ this chunk is customized ↓↓↓↓↓ -->
-        {% block docs_body %}
-          <div>
-            {% block body %} {% endblock %}
-            {% if pagename == 'index' %}
-              {%- include 'homepage.html' -%}
-            {% endif %}
-          </div>
-        {% endblock %}
-        <!-- ↑↑↑ this chunk is customized ↑↑↑ -->
-
-        {% if theme_show_prev_next %}
-        <footer class="bd-footer-article">
-            {% include "sections/footer-article.html" %}
-        </footer>
-        {% endif %}
-      </div>
-      {% endblock %}
-    </div>
-  </div>
+{% block docs_body %}
+<div>
+  {% block body %} {% endblock %}
+  {% if pagename == 'index' %}
+    {%- include 'homepage.html' -%}
+  {% endif %}
+</div>
+{% endblock %}
 
-  {# Scripts placed at the end of the page to cut down on time to first content #}
-  <!-- ↓↓↓↓↓ this chunk is customized ↓↓↓↓↓ -->
-  {%- block scripts_end %}
+{%- block scripts_end %}
     <script src="https://mne.tools/versionwarning.js"></script>
     {{ super() }}
-  {%- endblock %}
-  <!-- ↑↑↑ this chunk is customized ↑↑↑ -->
-
 {%- endblock %}
diff --git a/doc/changes/latest.inc b/doc/changes/latest.inc
@@ -49,6 +49,7 @@ Enhancements
 - Add ``unscale`` option to :func:`mne.head_to_mri` to facilitate working with surrogate MRI data (:gh:`11185` by `Eric Larson`_)
 - Add ``encoding`` parameter to :func:`mne.io.read_raw_edf` and :func:`mne.io.read_raw_bdf` to support custom (non-UTF8) annotation channel encodings (:gh:`11154` by `Clemens Brunner`_)
 - :class:`mne.preprocessing.ICA` gained a new method, :meth:`~mne.preprocessing.ICA.get_explained_variance_ratio`, that allows the retrieval of the proportion of variance explained by ICA components (:gh:`11141` by `Richard Höchenberger`_)
+- Add ``on_baseline`` to :meth:`mne.preprocessing.ICA.apply`, :meth:`mne.preprocessing.ICA.plot_overlay`, and :func:`mne.viz.plot_ica_overlay` to allow reapplying baseline correction after applying ICA (:gh:`11232` by `Eric Larson`_)
 - Add config option ``MNE_REPR_HTML`` to disable HTML repr in notebook environments (:gh:`11159` by `Clemens Brunner`_)
 
 Bugs
@@ -76,6 +77,7 @@ Bugs
 - Fix bug in :meth:`mne.preprocessing.ICA.find_bads_muscle` where epochs caused an error when passed as the ``inst`` (:gh:`11197` by `Alex Rockhill`_)
 - Fix bug in readers where EEG coordinates were assumed to be in head coordinates but no fiducial points were present. Estimated fiducial locations will now be added automatically to reflect the assumption of locations being in the head coordinate frame (:gh:`11212` by `Stefan Appelhoff`_ and `Eric Larson`_)
 - The duration of raw data sometimes wasn't displayed correctly in Jupyter notebooks by omitting fractions of a second. We now always round up to the next full second so a duration of less than 1 second will not be displayed as a duration of zero anymore (:gh:`11203` by `Richard Höchenberger`_)
+- Fix bug in :meth:`mne.Report.add_ica` and where baselines were not reapplied to the data when ``inst`` is Epochs or Evoked (:gh:`11232` by `Eric Larson`_)
 
 API changes
 ~~~~~~~~~~~

diff --git a/doc/conf.py b/doc/conf.py
@@ -615,17 +615,20 @@ def append_attr_meth_examples(app, what, name, obj, options, lines):
              url='https://discord.gg/rKfvxTuATa',
              icon='fab fa-discord')
     ],
-    'icon_links_label': 'Quick Links',  # for screen reader
+    'icon_links_label': 'External Links',  # for screen reader
     'use_edit_page_button': False,
     'navigation_with_keys': False,
     'show_toc_level': 1,
     'navbar_end': ['theme-switcher', 'version-switcher', 'navbar-icon-links'],
     'footer_items': ['copyright'],
+    'secondary_sidebar_items': ['page-toc', 'searchbox'],
     'analytics': dict(google_analytics_id='UA-37225609-1'),
     'switcher': {
         'json_url': 'https://mne.tools/dev/_static/versions.json',
         'version_match': switcher_version_match,
-    }
+    },
+    'pygment_light_style': 'default',
+    'pygment_dark_style': 'github-dark',
 }
 
 # The name of an image file (relative to this directory) to place at the top

diff --git a/doc/install/installers.rst b/doc/install/installers.rst
@@ -15,6 +15,7 @@ Got any questions? Let us know on the `MNE Forum`_!
 
     .. tab-item:: Linux
         :class-content: text-center
+        :name: linux-installers
 
         .. button-link:: https://github.com/mne-tools/mne-installers/releases/download/v1.1.1/MNE-Python-1.1.1_0-Linux.sh
             :ref-type: ref
@@ -35,6 +36,7 @@ Got any questions? Let us know on the `MNE Forum`_!
 
     .. tab-item:: macOS (Intel)
         :class-content: text-center
+        :name: macos-intel-installers
 
         .. button-link:: https://github.com/mne-tools/mne-installers/releases/download/v1.1.1/MNE-Python-1.1.1_0-macOS_Intel.pkg
             :ref-type: ref
@@ -50,6 +52,7 @@ Got any questions? Let us know on the `MNE Forum`_!
 
     .. tab-item:: macOS (Apple Silicon)
         :class-content: text-center
+        :name: macos-apple-installers
 
         .. button-link:: https://github.com/mne-tools/mne-installers/releases/download/v1.1.1/MNE-Python-1.1.1_0-macOS_M1.pkg
             :ref-type: ref
@@ -65,6 +68,7 @@ Got any questions? Let us know on the `MNE Forum`_!
 
     .. tab-item:: Windows
         :class-content: text-center
+        :name: windows-installers
 
         .. button-link:: https://github.com/mne-tools/mne-installers/releases/download/v1.1.1/MNE-Python-1.1.1_0-Windows.exe
             :ref-type: ref
@@ -131,7 +135,9 @@ interpreter.
         platform = "windows";
       }
       if (navigator.userAgent.indexOf("Mac") !== -1) {
-        platform = "macos";
+        // there's no good way to distinguish intel vs M1 in javascript so we
+        // just default to showing the first of the 2 macOS tabs
+        platform = "macos-intel";
       }
      $(document).ready(function(){
          let all_tab_nodes = document.querySelectorAll(
@@ -140,9 +146,11 @@ interpreter.
              child => child.nodeName === "INPUT");
          let tab_label_nodes = [...document.querySelectorAll('.sd-tab-label')];
          let correct_label = tab_label_nodes.filter(
-             label => label.textContent.trim().toLowerCase() === platform)[0];
-         let hash = correct_label.getAttribute('for');
-         let correct_input = input_nodes.filter(node => node.id === hash)[0];
+             // label.id is drawn from :name: property in the rST, which must
+             // be unique across the whole site (*sigh*)
+             label => label.id.startsWith(platform))[0];
+         let input_id = correct_label.getAttribute('for');
+         let correct_input = input_nodes.filter(node => node.id === input_id)[0];
          correct_input.checked = true;
      });
      </script>
diff --git a/doc/install/manual_install_python.rst b/doc/install/manual_install_python.rst
@@ -24,6 +24,7 @@ conda to ``/home/user/anaconda3``):
     :class: platform-selector-tabset
 
     .. tab-item:: Linux
+        :name: linux-manual-install
 
         .. code-block:: console
 
@@ -37,6 +38,7 @@ conda to ``/home/user/anaconda3``):
 
 
     .. tab-item:: macOS
+        :name: macos-manual-install
 
         .. code-block:: console
 
@@ -50,6 +52,7 @@ conda to ``/home/user/anaconda3``):
 
 
     .. tab-item:: Windows
+        :name: windows-manual-install
 
         Most of our instructions start with ``$``, which indicates
         that the commands are designed to be run from a ``bash`` command shell.
@@ -142,9 +145,11 @@ conda to ``/home/user/anaconda3``):
              child => child.nodeName === "INPUT");
          let tab_label_nodes = [...document.querySelectorAll('.sd-tab-label')];
          let correct_label = tab_label_nodes.filter(
-             label => label.textContent.trim().toLowerCase() === platform)[0];
-         let hash = correct_label.getAttribute('for');
-         let correct_input = input_nodes.filter(node => node.id === hash)[0];
+             // label.id is drawn from :name: property in the rST, which must
+             // be unique across the whole site (*sigh*)
+             label => label.id.startsWith(platform))[0];
+         let input_id = correct_label.getAttribute('for');
+         let correct_input = input_nodes.filter(node => node.id === input_id)[0];
          correct_input.checked = true;
      });
      </script>
diff --git a/mne/commands/mne_kit2fiff.py b/mne/commands/mne_kit2fiff.py
@@ -63,7 +63,7 @@ def run():
             from mne_kit_gui import kit2fiff  # noqa
         except ImportError:
             raise ImportError(
-                'The mne_kit_gui package is required, install it using '
+                'The mne-kit-gui package is required, install it using '
                 'conda or pip') from None
         kit2fiff()
         sys.exit(0)

diff --git a/mne/preprocessing/ica.py b/mne/preprocessing/ica.py
@@ -59,7 +59,8 @@
                      copy_function_doc_to_method_doc, _pl, warn, Bunch,
                      _check_preload, _check_compensation_grade, fill_doc,
                      _check_option, _PCA, int_like, _require_version,
-                     _check_all_same_channel_names)
+                     _check_all_same_channel_names, _check_on_missing,
+                     _on_missing)
 
 from ..fixes import _safe_svd
 from ..filter import filter_data
@@ -1896,7 +1897,7 @@ def find_bads_eog(self, inst, ch_name=None, threshold=3.0, start=None,
 
     @verbose
     def apply(self, inst, include=None, exclude=None, n_pca_components=None,
-              start=None, stop=None, verbose=None):
+              start=None, stop=None, *, on_baseline='warn', verbose=None):
         """Remove selected components from the signal.
 
         Given the unmixing matrix, transform the data,
@@ -1927,6 +1928,7 @@ def apply(self, inst, include=None, exclude=None, n_pca_components=None,
         stop : int | float | None
             Last sample to not include. If float, data will be interpreted as
             time in seconds. If None, data will be used to the last sample.
+        %(on_baseline_ica)s
         %(verbose)s
 
         Returns
@@ -1963,15 +1965,26 @@ def apply(self, inst, include=None, exclude=None, n_pca_components=None,
         _check_compensation_grade(self.info, inst.info, 'ICA', kind,
                                   ch_names=self.ch_names)
 
+        _check_on_missing(on_baseline, 'on_baseline', extras=('reapply',))
+        reapply_baseline = False
         if isinstance(inst, (BaseEpochs, Evoked)):
             if getattr(inst, 'baseline', None) is not None:
-                warn('The data you passed to ICA.apply() was '
-                     'baseline-corrected. Please note that ICA can introduce '
-                     'DC shifts, therefore you may wish to consider '
-                     'baseline-correcting the cleaned data again.')
+                if on_baseline == 'reapply':
+                    reapply_baseline = True
+                else:
+                    msg = (
+                        'The data you passed to ICA.apply() was '
+                        'baseline-corrected. Please note that ICA can '
+                        'introduce DC shifts, therefore you may wish to '
+                        'consider baseline-correcting the cleaned data again.'
+                    )
+                    _on_missing(on_baseline, msg, 'on_baseline')
 
         logger.info(f'Applying ICA to {kind} instance')
-        return meth(**kwargs)
+        out = meth(**kwargs)
+        if reapply_baseline:
+            out.apply_baseline(inst.baseline)
+        return out
 
     def _check_exclude(self, exclude):
         if exclude is None:
@@ -2220,10 +2233,12 @@ def plot_scores(self, scores, exclude=None, labels=None, axhline=None,
 
     @copy_function_doc_to_method_doc(plot_ica_overlay)
     def plot_overlay(self, inst, exclude=None, picks=None, start=None,
-                     stop=None, title=None, show=True, n_pca_components=None):
+                     stop=None, title=None, show=True, n_pca_components=None,
+                     *, on_baseline='warn', verbose=None):
         return plot_ica_overlay(self, inst=inst, exclude=exclude, picks=picks,
                                 start=start, stop=stop, title=title, show=show,
-                                n_pca_components=n_pca_components)
+                                n_pca_components=n_pca_components,
+                                on_baseline=on_baseline, verbose=verbose)
 
     @verbose
     def _check_n_pca_components(self, _n_pca_comp, verbose=None):

diff --git a/mne/report/report.py b/mne/report/report.py
@@ -1407,7 +1407,7 @@ def _add_ica_overlay(
         else:  # Epochs
             inst_ = inst.average()
 
-        fig = ica.plot_overlay(inst=inst_, show=False)
+        fig = ica.plot_overlay(inst=inst_, show=False, on_baseline='reapply')
         del inst_
         tight_layout(fig=fig)
         _constrain_fig_resolution(

diff --git a/mne/report/tests/test_report.py b/mne/report/tests/test_report.py
@@ -790,14 +790,21 @@ def test_manual_report_2d(tmp_path, invisible_fig):
     with pytest.raises(RuntimeError, match='not preloaded'):
         r.add_ica(ica=ica, title='ica', inst=raw)
     r.add_ica(
-        ica=ica, title='my ica with inst',
+        ica=ica, title='my ica with raw inst',
         inst=raw.copy().load_data(),
         picks=[0],
         ecg_evoked=ica_ecg_evoked,
         eog_evoked=ica_eog_evoked,
         ecg_scores=ica_ecg_scores,
         eog_scores=ica_eog_scores
     )
+    epochs_baseline = epochs_without_metadata.copy().load_data()
+    epochs_baseline.apply_baseline((None, 0))
+    r.add_ica(
+        ica=ica, title='my ica with epochs inst',
+        inst=epochs_baseline,
+        picks=[0],
+    )
     r.add_covariance(cov=cov, info=raw_fname, title='my cov')
     r.add_forward(forward=fwd_fname, title='my forward', subject='sample',
                   subjects_dir=subjects_dir)

diff --git a/mne/utils/check.py b/mne/utils/check.py
@@ -977,9 +977,9 @@ def _suggest(val, options, cutoff=0.66):
         return ' Did you mean one of %r?' % (options,)
 
 
-def _check_on_missing(on_missing, name='on_missing'):
+def _check_on_missing(on_missing, name='on_missing', *, extras=()):
     _validate_type(on_missing, str, name)
-    _check_option(name, on_missing, ['raise', 'warn', 'ignore'])
+    _check_option(name, on_missing, ['raise', 'warn', 'ignore'] + list(extras))
 
 
 def _on_missing(on_missing, msg, name='on_missing', error_klass=None):

diff --git a/mne/utils/docs.py b/mne/utils/docs.py
@@ -2187,6 +2187,15 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75):
     .. versionadded:: 0.12
 """
 
+docdict['on_baseline_ica'] = """
+on_baseline : str
+    How to handle baseline-corrected epochs or evoked data.
+    Can be ``'raise'`` to raise an error, ``'warn'`` (default) to emit a
+    warning, ``'ignore'`` to ignore, or "reapply" to reapply the baseline
+    after applying ICA.
+
+    .. versionadded:: 1.2
+"""
 docdict['on_defects'] = """
 on_defects : 'raise' | 'warn' | 'ignore'
     What to do if the surface is found to have topological defects.