In Report.add_ica, replace "n_components" with more versatile "picks"…

… param (mne-tools#9862)

doc/changes/latest.inc

@@ -183,7 +183,7 @@ Enhancements
 
 - Add options ``tol`` and ``accuracy`` to :func:`mne.fit_dipole` to control optimization (:gh:`9810` by `Eric Larson`_)
 
-- Completely revamp the `~mne.Report` experience: new HTML layout, many new methods, more flexibility; the functionality is demonstrated in :ref:`tut-report` (:gh:`9754`, :gh:`9828`, :gh:`9847`, :gh:`9860`, :gh:`9861` by `Richard Höchenberger`_, `Eric Larson`_, and `Alex Gramfort`_)
+- Completely revamp the `~mne.Report` experience: new HTML layout, many new methods, more flexibility; the functionality is demonstrated in :ref:`tut-report` (:gh:`9754`, :gh:`9828`, :gh:`9847`, :gh:`9860`, :gh:`9861`, :gh:`9862` 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/report/report.py

@@ -1371,7 +1371,7 @@ def _render_ica_properties(self, *, ica, picks, inst, n_jobs, image_format,
 
             captions.append(caption)
 
-        title = 'ICA components'
+        title = 'ICA component properties'
         # Only render a slider if we have more than 1 component.
         if len(figs) == 1:
             img = _fig_to_img(fig=figs[0], image_format=image_format)
@@ -1442,7 +1442,7 @@ def _render_ica_components(self, *, ica, picks, image_format, tags):
 
         return topographies_html
 
-    def _render_ica(self, *, ica, inst, n_components, ecg_evoked,
+    def _render_ica(self, *, ica, inst, picks, ecg_evoked,
                     eog_evoked, ecg_scores, eog_scores, title, image_format,
                     tags, n_jobs):
         if _path_like(ica):
@@ -1539,7 +1539,6 @@ def _render_ica(self, *, ica, inst, n_components, ecg_evoked,
             eog_html = ''
 
         # Component topography plots
-        picks = None if n_components is None else list(range(n_components))
         topographies_html = self._render_ica_components(
             ica=ica, picks=picks, image_format=image_format, tags=tags
         )
@@ -1571,7 +1570,7 @@ def _render_ica(self, *, ica, inst, n_components, ecg_evoked,
 
     @fill_doc
     def add_ica(
-        self, ica, title, *,  inst, n_components=None, ecg_evoked=None,
+        self, ica, title, *,  inst, picks=None, ecg_evoked=None,
         eog_evoked=None, ecg_scores=None, eog_scores=None, n_jobs=1,
         tags=('ica',), replace=False
     ):
@@ -1587,9 +1586,8 @@ def add_ica(
             The data to use for visualization of the effects of ICA cleaning.
             To only plot the ICA component topographies, explicitly pass
             ``None``.
-        n_components : int | None
-            The number of components for which to produce plots. If ``None``,
-            plot all components.
+        %(picks_ica)s  If ``None``, plot all components. This only affects
+            the behavior of the component topography and properties plots.
         ecg_evoked, eog_evoked : path-line | mne.Evoked | None
             Evoked signal based on ECG and EOG epochs, respectively. If passed,
             will be used to visualize the effects of artifact rejection.
@@ -1609,7 +1607,7 @@ def add_ica(
         tags = tuple(tags)
 
         dom_id, html = self._render_ica(
-            ica=ica, inst=inst, n_components=n_components,
+            ica=ica, inst=inst, picks=picks,
             ecg_evoked=ecg_evoked, eog_evoked=eog_evoked,
             ecg_scores=ecg_scores, eog_scores=eog_scores,
             title=title, image_format=self.image_format, tags=tags,

mne/report/tests/test_report.py

@@ -716,7 +716,7 @@ def test_manual_report_2d(tmpdir, invisible_fig):
     r.add_ica(
         ica=ica, title='my ica with inst',
         inst=raw.copy().load_data(),
-        n_components=1,
+        picks=[0],
         ecg_evoked=ica_ecg_evoked,
         eog_evoked=ica_eog_evoked,
         ecg_scores=ica_ecg_scores,

mne/utils/docs.py

@@ -619,6 +619,10 @@
 docdict['picks_good_data_noref'] = f'{picks_base} good data channels {noref}'
 docdict['picks_nostr'] = f"""picks : list | slice | None
     {picks_intro} None (default) will pick all channels. {reminder_nostr}"""
+docdict['picks_ica'] = """
+picks : int | list of int | slice | None
+    Indices of the ICA components to visualize.
+"""
 
 # Units
 docdict['units'] = """

mne/viz/topomap.py

@@ -1081,9 +1081,7 @@ def plot_ica_components(ica, picks=None, ch_type=None, res=64,
     ----------
     ica : instance of mne.preprocessing.ICA
         The ICA solution.
-    picks : int | list of int | slice | None
-        Indices of the ICA components to visualize. If ``None``, all components
-        are plotted in batches of 20.
+    %(picks_ica)s  If ``None``, all components are plotted in batches of 20.
     ch_type : 'mag' | 'grad' | 'planar1' | 'planar2' | 'eeg' | None
         The channel type to plot. For 'grad', the gradiometers are
         collected in pairs and the RMS for each pair is plotted.

tutorials/intro/70_report.py

@@ -203,8 +203,8 @@
 #
 # .. note:: :meth:`mne.Report.add_ica` only works with fitted ICAs.
 #
-# You can optionally specify for many components to show in the generated
-# plots by passing ``n_components``. By default, all components will be
+# You can optionally specify for which components to produce topography and
+# properties plots by passing ``picks``. By default, all components will be
 # shown. It is also possible to pass evoked signals based on ECG and EOG events
 # via ``ecg_evoked`` and ``eog_evoked``. This allows you directly see the
 # effects of ICA component removal on these artifactual signals.
@@ -252,7 +252,7 @@
 report.add_ica(
     ica=ica,
     title='ICA cleaning',
-    n_components=2,  # only plot the first two components
+    picks=[0, 1],  # only plot the first two components
     inst=raw_eeg_cropped,
     eog_evoked=eog_epochs.average(),
     eog_scores=eog_scores,