ENH: Add support for plotting ICA source timecourses in Report.add_ica (#13697)

Author: Aniketsy

doc/changes/dev/13697.newfeature.rst

@@ -0,0 +1 @@
+Add ICA source timecourse plots to :func:`mne.Report.add_ica`, by `Aniket Singh Yadav`_.

mne/report/report.py

@@ -2018,6 +2018,22 @@ def _add_ica_components(self, *, ica, picks, image_format, section, tags, replac
                 replace=replace,
             )
 
+    def _add_ica_sources(
+        self, *, ica, inst, picks, image_format, section, tags, replace
+    ):
+        with use_browser_backend("matplotlib"):
+            fig = ica.plot_sources(inst=inst, picks=picks, show=False)
+        self._add_figure(
+            fig=fig,
+            title="Sources",
+            caption=None,
+            image_format=image_format,
+            tags=tags,
+            section=section,
+            replace=replace,
+            own_figure=True,
+        )
+
     def _add_ica(
         self,
         *,
@@ -2034,6 +2050,7 @@ def _add_ica(
         tags,
         n_jobs,
         replace,
+        plot_sources=False,
     ):
         if _path_like(ica):
             ica = read_ica(ica)
@@ -2164,6 +2181,26 @@ def _add_ica(
                 replace=replace,
             )
 
+        # Sources plot
+        if plot_sources:
+            if inst is None:
+                raise ValueError(
+                    "Cannot plot ICA sources because inst=None. "
+                    "Please pass a Raw, Epochs, or Evoked instance to "
+                    "add_ica() to enable source plotting, or pass "
+                    "plot_sources=False."
+                )
+
+            self._add_ica_sources(
+                ica=ica,
+                inst=inst,
+                picks=picks,
+                image_format=image_format,
+                section=section,
+                tags=tags,
+                replace=replace,
+            )
+
     @fill_doc
     def add_ica(
         self,
@@ -2179,6 +2216,7 @@ def add_ica(
         n_jobs=None,
         tags=("ica",),
         replace=False,
+        plot_sources=False,
     ):
         """Add (a fitted) `~mne.preprocessing.ICA` to the report.
 
@@ -2205,6 +2243,12 @@ def add_ica(
         %(n_jobs)s
         %(tags_report)s
         %(replace_report)s
+        plot_sources : bool
+            Whether to add a plot of the ICA source time-courses using
+            :meth:`mne.preprocessing.ICA.plot_sources`. Requires ``inst``
+            to be provided. Defaults to ``False``.
+
+            .. versionadded:: 1.12
 
         Notes
         -----
@@ -2225,6 +2269,7 @@ def add_ica(
             section=title,
             n_jobs=n_jobs,
             replace=replace,
+            plot_sources=plot_sources,
         )
 
     def remove(self, *, title=None, tags=None, remove_all=False):

mne/report/tests/test_report.py

@@ -1031,8 +1031,10 @@ def test_manual_report_2d(tmp_path, invisible_fig):
         eog_evoked=ica_eog_evoked,
         ecg_scores=ica_ecg_scores,
         eog_scores=ica_eog_scores,
+        plot_sources=True,
     )
-    assert "ICA component 2" in r._content[-1].html
+    assert "ICA component 2" in r._content[-2].html
+    assert "Sources" in r._content[-1].html
     epochs_baseline = epochs_without_metadata.copy().load_data()
     epochs_baseline.apply_baseline((None, 0))
     r.add_ica(
@@ -1042,6 +1044,16 @@ def test_manual_report_2d(tmp_path, invisible_fig):
         picks=[0],
     )
     r.add_ica(ica=ica, title="my ica with picks=None", inst=epochs_baseline, picks=None)
+
+    # plot_sources=True with inst=None should raise a ValueError
+    with pytest.raises(ValueError, match="Cannot plot ICA sources because inst=None"):
+        r.add_ica(
+            ica=ica,
+            title="my ica sources no inst",
+            inst=None,
+            plot_sources=True,
+        )
+
     r.add_covariance(cov=cov, info=raw_fname, title="my cov")
     r.add_forward(
         forward=fwd_fname,

tutorials/intro/70_report.py

@@ -231,6 +231,8 @@
 #
 # Lastly, by passing ``n_jobs``, you may largely speed up the generation of
 # the properties plots by enabling parallel execution.
+# To additionally include ICA source time-courses in the report, pass
+# ``plot_sources=True``. This requires ``inst`` to be provided.
 #
 # .. warning::
 #    In the following example, we request a small number of ICA components
@@ -262,6 +264,7 @@
     title="ICA cleaning",
     picks=ica.exclude,  # plot the excluded EOG components
     inst=raw,
+    plot_sources=True,
     eog_evoked=eog_epochs.average(),
     eog_scores=eog_scores,
     n_jobs=None,  # could be increased!