[BUG] Fix issue in decomposition plotting to specified axes

doc/whats_new.rst

@@ -23,9 +23,10 @@ Enhancements
 ~~~~~~~~~~~~
 
 - Add a new :class:`~mne_connectivity.decoding.CoherencyDecomposition` class for decomposing connectivity sources using multivariate coherency-based methods, by `Thomas Binns`_ (:pr:`193`).
-- Add new plotting methods :meth:`CoherencyDecomposition.plot_filters() <mne_connectivity.decoding.CoherencyDecomposition.plot_filters>` and :meth:`CoherencyDecomposition.plot_patterns() <mne_connectivity.decoding.CoherencyDecomposition.plot_patterns>` for visualising the decomposed connectivity sources, by `Thomas Binns`_ (:pr:`208`).
+- Add new plotting methods :meth:`CoherencyDecomposition.plot_filters() <mne_connectivity.decoding.CoherencyDecomposition.plot_filters>` and :meth:`CoherencyDecomposition.plot_patterns() <mne_connectivity.decoding.CoherencyDecomposition.plot_patterns>` for visualising the decomposed connectivity sources, by `Thomas Binns`_ (:pr:`208` and :pr:`280`).
 - Add support for computing multiple components of multivariate connectivity in the :func:`~mne_connectivity.spectral_connectivity_epochs` and :func:`~mne_connectivity.spectral_connectivity_time` functions and :class:`~mne_connectivity.decoding.CoherencyDecomposition` class, and add support for storing data with a components dimension in all :class:`~mne_connectivity.Connectivity` classes, by `Thomas Binns`_ and `Eric Larson`_ (:pr:`213`).
 - Add support for :class:`mne.time_frequency.EpochsSpectrum` objects to be passed as data to the :func:`~mne_connectivity.spectral_connectivity_epochs` function, by `Thomas Binns`_ and `Eric Larson`_ (:pr:`220`).
+- Add support for :class:`mne.time_frequency.EpochsTFR` objects to be passed as data to the :func:`~mne_connectivity.spectral_connectivity_epochs` and :func:`~mne_connectivity.spectral_connectivity_time` functions, by `Thomas Binns`_ and `Daniel McCloy`_ (:pr:`232`).
 - Update the cross-references for relevant functions and classes and make data types more explicit throughout the documentation, by `Thomas Binns`_ (:pr:`214`).
 
 Bug

mne_connectivity/decoding/decomposition.py

@@ -604,7 +604,7 @@ def plot_filters(
         """Plot topographic filters of components.
 
         The filters are used to extract discriminant neural sources from the measured
-        data (a.k.a. the backward model). :footcite:`HaufeEtAl2014`.
+        data (a.k.a. the backward model) :footcite:`HaufeEtAl2014`.
 
         Seed and target filters are plotted separately.
 
@@ -714,17 +714,23 @@ def _plot_filters_patterns(
         _validate_type(info, Info, "`info`", "mne.Info")
         if components is None:
             components = np.arange(self.n_components)
+        if axes is not None:
+            _check_option("axes", len(axes), [2], " length")
 
         # plot seeds and targets
         figs = []
-        for group_idx, group_name in zip([0, 1], ["Seeds", "Targets"]):
+        for group_idx, group_name in zip([0, 1], ["seeds", "targets"]):
             # create info for seeds/targets
             group_info = pick_info(info, self.indices[group_idx])
             with group_info._unlock():
                 group_info["sfreq"] = 1.0  # 1 component per time point
             # create Evoked object
             evoked = EvokedArray(plot_data[group_idx], group_info, tmin=0)
             # then call plot_topomap
+            if name_format is None:
+                group_name_format = f"{self._conn_estimator.name}%01d ({group_name})"
+            else:
+                group_name_format = name_format + f" ({group_name})"
             figs.append(
                 evoked.plot_topomap(
                     times=components,
@@ -749,16 +755,13 @@ def _plot_filters_patterns(
                     colorbar=colorbar,
                     cbar_fmt=cbar_fmt,
                     units=units,
-                    axes=axes,
-                    time_format=f"{self._conn_estimator.name}%01d"
-                    if name_format is None
-                    else name_format,
+                    axes=axes[group_idx] if axes is not None else None,
+                    time_format=group_name_format,
                     nrows=nrows,
                     ncols=ncols,
-                    show=False,  # set Seeds/Targets suptitle first
+                    show=False,
                 )
             )
-            figs[-1].suptitle(group_name)  # differentiate seeds from targets
             plt_show(show=show, fig=figs[-1])
 
         return figs

mne_connectivity/decoding/tests/test_decomposition.py

@@ -715,3 +715,7 @@ def test_spectral_decomposition_error_catch(method, mode):
     for plot in (decomp_class.plot_filters, decomp_class.plot_patterns):
         with pytest.raises(TypeError, match="`info` must be an instance of mne.Info"):
             plot({"info": epochs.info})
+        with pytest.raises(ValueError, match="Invalid value for the 'axes' parameter"):
+            plot(epochs.info, axes=[None])
+        with pytest.raises(ValueError, match="Invalid value for the 'axes' parameter"):
+            plot(epochs.info, axes=[None, None, None])

mne_connectivity/utils/docs.py

@@ -434,15 +434,19 @@
 """
 
 docdict["axes_topomap"] = """
-axes : matplotlib.axes.Axes | list of matplotlib.axes.Axes | None (default None)
+axes : length-2 tuple of list of matplotlib.axes.Axes | None (default None)
     The axes to plot to. If `None`, a new figure will be created with the correct number
-    of axes. If not `None`, the number of axes must match ``components``.
+    of axes. If not `None`, there must be two lists containing the axes for the seeds
+    and targets, respectively. In each of these two lists, the number of axes must match
+    ``components`` if ``colorbar=False``, or ``components * 2`` if ``colorbar=True``.
 """
 
 docdict["name_format_topomap"] = r"""
 name_format : str | None (default None)
-    The string format for axes titles. If `None`, uses ``f"{method}%%01d"``, i.e. the
-    method name followed by the component number.
+    The string format for axes titles. If `None`, uses ``f"{method}%01d_{group}"``,
+    i.e., the method name followed by the component number and the group being plotted
+    (seeds or targets). If not `None`, it must contain a formatting specifier for the
+    component number, and the group will be appended to the end.
 """
 
 docdict["nrows_topomap"] = """