[MAINT] Retry improve clarity, thumbnails, and fix mistakes in multivariate examples

doc/references.bib

@@ -72,6 +72,16 @@ @article{EwaldEtAl2012
  year = {2012}
 }
 
+@inproceedings{HaufeEtAl2012,
+  title={Alleviating the influence of weak data asymmetries on granger-causal analyses},
+  author={Haufe, Stefan and Nikulin, Vadim V and Nolte, Guido},
+  doi={10.1007/978-3-642-28551-6_4},
+  booktitle={Latent Variable Analysis and Signal Separation: 10th International Conference, LVA/ICA 2012, Tel Aviv, Israel, March 12-15, 2012. Proceedings 10},
+  pages={25--33},
+  year={2012},
+  organization={Springer}
+}
+
 @article{HaufeEtAl2013,
  author = {Haufe, Stefan and Nikulin, Vadim V and M{\"u}ller, Klaus-Robert and Nolte, Guido},
  doi = {10.1016/j.neuroimage.2012.09.036},

examples/cacoh.py

@@ -12,6 +12,7 @@
 # Authors: Thomas S. Binns <[email protected]>
 #          Mohammad Orabe <[email protected]>
 # License: BSD (3-clause)
+# sphinx_gallery_thumbnail_number = 3
 
 # %%
 import numpy as np
@@ -118,7 +119,7 @@
 # elements are frequency-dependent, however this is omitted for readability.
 #
 # CaCoh is complex-valued in the range :math:`[-1, 1]` where the sign reflects
-# the phase angle of the interaction (akin to coherency). Taking the absolute
+# the phase angle of the interaction (like for coherency). Taking the absolute
 # value is akin to taking the coherence, which is the magnitude of the
 # interaction regardless of phase angle.
 
@@ -384,7 +385,7 @@
 # by computing the singular values of the data and finding those within a
 # factor of :math:`1e^{-6}` relative to the largest singular value.
 #
-# Whilst unlikely, there may be scenarios in which this threshold may be too
+# Whilst unlikely, there may be scenarios in which this threshold is too
 # lenient. In these cases, you should inspect the singular values of your data
 # to identify an appropriate degree of dimensionality reduction to perform,
 # which you can then specify manually using the ``rank`` argument. The code
@@ -411,16 +412,17 @@
 # imaginary part of coherency such as MIC and MIM.
 #
 # In short, if you want to examine connectivity between signals from the same
-# modality, you should consider using another method instead of CaCoh. Rather,
-# methods based on the imaginary part of coherency such as MIC and MIM should
-# be used to avoid spurious connectivity estimates stemming from e.g. volume
-# conduction artefacts.
+# modality or from different modalities using a shared reference, you should
+# consider using another method instead of CaCoh. Rather, methods based on the
+# imaginary part of coherency such as MIC and MIM should be used to avoid
+# spurious connectivity estimates stemming from e.g. volume conduction
+# artefacts.
 #
 # On the other hand, if you want to examine connectivity between signals from
-# different modalities, CaCoh is a more appropriate method than MIC/MIM. This
-# is because volume conduction artefacts are of less concern, and CaCoh does
-# not risk biasing connectivity estimates towards interactions with particular
-# phase lags like MIC/MIM.
+# different modalities using different references, CaCoh is a more appropriate
+# method than MIC/MIM. This is because volume conduction artefacts are of less
+# concern, and CaCoh does not risk biasing connectivity estimates towards
+# interactions with particular phase lags like MIC/MIM.
 #
 # These scenarios are described in more detail in the
 # :doc:`compare_coherency_methods` example.

examples/compare_coherency_methods.py

@@ -314,7 +314,7 @@ def plot_connectivity_circle():
 # |
 #
 # Equally, when there are no non-physiological zero time-lag interactions, one
-# should not used methods based on only the imaginary part of coherency. There
+# should not use methods based on only the imaginary part of coherency. There
 # are two key reasons:
 #
 # **1. Discarding physiological zero time-lag interactions**

examples/granger_causality.py

@@ -12,6 +12,7 @@
 
 # Author: Thomas S. Binns <[email protected]>
 # License: BSD (3-clause)
+# sphinx_gallery_thumbnail_number = 3
 
 # %%
 
@@ -251,9 +252,11 @@
 # as follows: if temporal order is crucial in distinguishing a driver from a
 # recipient, then reversing the temporal order should reduce, if not flip, an
 # estimate of directed connectivity. In practice, time-reversal is implemented
-# as a transposition of the autocovariance sequence used to compute GC. Several
-# studies have shown that that such an approach can reduce the degree of
-# false-positive connectivity estimates (even performing favourably against
+# as a transposition of the autocovariance sequence used to compute GC
+# :footcite:`HaufeEtAl2012`.
+#
+# Several studies have shown that that such an approach can reduce the degree
+# of false-positive connectivity estimates (even performing favourably against
 # other methods such as the phase slope index) :footcite:`VinckEtAl2015` and
 # retain the ability to correctly identify the net direction of information
 # flow akin to net GC :footcite:`WinklerEtAl2016,HaufeEtAl2013`. This approach
@@ -305,7 +308,7 @@
 trgc = net_gc - net_gc_tr
 
 ###############################################################################
-# Plotting the TRGC results, reveals a very different picture compared to net
+# Plotting the TRGC results reveals a very different picture compared to net
 # GC. For one, there is now a dominance of information flow ~6 Hz from
 # occipital to parietal sensors (indicated by the negative-valued Granger
 # scores). Additionally, the peak ~10 Hz is less dominant in the spectrum, with
@@ -379,7 +382,7 @@
 # by computing the singular values of the data and finding those within a
 # factor of :math:`1e^{-6}` relative to the largest singular value.
 #
-# Whilst unlikely, there may be scenarios in which this threshold may be too
+# Whilst unlikely, there may be scenarios in which this threshold is too
 # lenient. In these cases, you should inspect the singular values of your data
 # to identify an appropriate degree of dimensionality reduction to perform,
 # which you can then specify manually using the ``rank`` argument. The code

examples/handling_ragged_arrays.py

@@ -24,17 +24,18 @@
 # considered together, and the number of signals designated as seeds and
 # targets does not have to be equal within or across connections. Issues can
 # arise from this when storing information associated with connectivity in
-# arrays, as the number of entries within each dimension can vary within and
-# across connections depending on the number of seeds and targets. Such arrays
-# are 'ragged', and support for ragged arrays is limited in NumPy to the
-# ``object`` datatype. Not only is working with ragged arrays is cumbersome,
-# but saving arrays with ``dtype='object'`` is not supported by the h5netcdf
-# engine used to save connectivity objects. The workaround used in
-# MNE-Connectivity is to pad ragged arrays with some known values according to
-# the largest number of entries in each dimension, such that there is an equal
-# amount of information across and within connections for each dimension of the
 # arrays.
 #
+# Such arrays are 'ragged', and support for ragged arrays is limited in NumPy
+# to the ``object`` datatype. Not only is working with ragged arrays
+# cumbersome, but saving arrays with ``dtype='object'`` is not supported by the
+# h5netcdf engine used to save connectivity objects.
+#
+# The workaround used in MNE-Connectivity is to pad ragged arrays with some
+# known values according to the largest number of entries in each dimension,
+# such that there is an equal amount of information across and within
+# connections for each dimension of the arrays.
+#
 # As an example, consider we have 5 channels and want to compute 2 connections:
 # the first between channels in indices 0 and 1 with those in indices 2, 3,
 # and 4; and the second between channels 0, 1, 2, and 3 with channel 4. The
@@ -56,7 +57,7 @@
 #
 #   # tuple of tuples
 #   ragged_indices = (((0, 1   ), (0, 1, 2, 3)),
-#                     ((2, 3, 4), (4         )))
+#                     ((2, 3, 4), (4,        )))
 #
 #   # tuple of arrays
 #   ragged_indices = (np.array([[0, 1   ], [0, 1, 2, 3]], dtype='object'),
@@ -68,7 +69,9 @@
 # Just as for bivariate connectivity, the length of ``indices[0]`` and
 # ``indices[1]`` is equal (i.e. the number of connections), however information
 # about the multiple channel indices for each connection is stored in a nested
-# array. Importantly, these indices are ragged, as the first connection will be
+# array.
+#
+# Importantly, these indices are ragged, as the first connection will be
 # computed between 2 seed and 3 target channels, and the second connection
 # between 4 seed and 1 target channel(s). The connectivity functions will
 # recognise the indices as being ragged, and pad them to a 'full' array by
@@ -86,15 +89,18 @@
 # MNE-Connectivity combine information across the different channels into a
 # single (time-)frequency-resolved connectivity spectrum, regardless of the
 # number of seed and target channels, so ragged arrays are not a concern here.
+#
 # However, the maximised imaginary part of coherency (MIC) method also returns
 # spatial patterns of connectivity, which show the contribution of each channel
 # to the dimensionality-reduced connectivity estimate (explained in more detail
 # in :doc:`mic_mim`). Because these patterns are returned for each channel,
 # their shape can vary depending on the number of seeds and targets in each
-# connection, making them ragged. To avoid this, the patterns are padded along
-# the channel axis with the known and invalid entry ``np.nan``, in line with
-# that applied to ``indices``. Extracting only the valid spatial patterns from
-# the connectivity object is trivial, as shown below:
+# connection, making them ragged.
+#
+# To avoid this, the patterns are padded along the channel axis with the known
+# and invalid entry ``np.nan``, in line with that applied to ``indices``.
+# Extracting only the valid spatial patterns from the connectivity object is
+# trivial, as shown below:
 
 # %%
 

examples/mic_mim.py

@@ -15,6 +15,7 @@
 
 # Author: Thomas S. Binns <[email protected]>
 # License: BSD (3-clause)
+# sphinx_gallery_thumbnail_number = 3
 
 # %%
 
@@ -55,13 +56,13 @@
 # :footcite:`EwaldEtAl2012` depending on the degree of source mixing in the
 # signals.
 #
-# To overcome this limitation, spatial filters derived from eigendecompositions
-# allows connectivity to be analysed in a multivariate manner, removing the
-# source mixing-dependent bias and increase the signal-to-noise ratio of
-# connectivity estimates :footcite:`EwaldEtAl2012`. This approach goes beyond
-# simply aggregating information across all possible combinations of signals,
-# extracting the underlying components of connectivity in a frequency-resolved
-# manner.
+# To overcome these limitations, spatial filters derived from
+# eigendecompositions allow connectivity to be analysed in a multivariate
+# manner, removing the source mixing-dependent bias and increasing the
+# signal-to-noise ratio of connectivity estimates :footcite:`EwaldEtAl2012`.
+# This approach goes beyond simply aggregating information across all possible
+# combinations of signals, instead extracting the underlying components of
+# connectivity in a frequency-resolved manner.
 #
 # This leads to the following methods: the maximised imaginary part of
 # coherency (MIC); and the multivariate interaction measure (MIM). These
@@ -136,9 +137,9 @@
 # eigendecomposition of information from the cross-spectral density (Eq. 7 of
 # :footcite:`EwaldEtAl2012`):
 #
-# :math:`\textrm{MIC}=\frac{\boldsymbol{\alpha}^T \boldsymbol{E \beta}}
+# :math:`\textrm{MIC}=\Large{\frac{\boldsymbol{\alpha}^T \boldsymbol{E \beta}}
 # {\parallel\boldsymbol{\alpha}\parallel \parallel\boldsymbol{\beta}
-# \parallel}`,
+# \parallel}}`,
 #
 # where :math:`\boldsymbol{\alpha}` and :math:`\boldsymbol{\beta}` are the
 # spatial filters for the seeds and targets, respectively, and
@@ -265,16 +266,17 @@
 #
 # :math:`\textrm{MIM}=tr(\boldsymbol{EE}^T)`,
 #
-# where again the frequency dependence is omitted. Unlike MIC, MIM is
-# positive-valued and can be > 1. Without normalisation, MIM can be
-# thought of as reflecting the total interaction between the seeds and targets.
-# MIM can be normalised to lie in the range :math:`[0, 1]` by dividing the
-# scores by the number of unique channels in the seeds and targets. Normalised
-# MIM represents the interaction *per channel*, which can be biased by factors
-# such as the presence of channels with little to no interaction. In line with
-# the preferences of the method's authors :footcite:`EwaldEtAl2012`, since
-# normalisation alters the interpretability of the results, **normalisation is
-# not performed by default**.
+# where again the frequency dependence is omitted.
+#
+# Unlike MIC, MIM is positive-valued and can be > 1. Without normalisation, MIM
+# can be thought of as reflecting the total interaction between the seeds and
+# targets. MIM can be normalised to lie in the range :math:`[0, 1]` by dividing
+# the scores by the number of unique channels in the seeds and targets.
+# Normalised MIM represents the interaction *per channel*, which can be biased
+# by factors such as the presence of channels with little to no interaction. In
+# line with the preferences of the method's authors :footcite:`EwaldEtAl2012`,
+# since normalisation alters the interpretability of the results,
+# **normalisation is not performed by default**.
 #
 # Here we see MIM reveal the strongest connectivity component to be around 10
 # Hz, with the higher frequency 13-18 Hz connectivity no longer being so
@@ -411,7 +413,7 @@
 # by computing the singular values of the data and finding those within a
 # factor of :math:`1e^{-6}` relative to the largest singular value.
 #
-# Whilst unlikely, there may be scenarios in which this threshold may be too
+# Whilst unlikely, there may be scenarios in which this threshold is too
 # lenient. In these cases, you should inspect the singular values of your data
 # to identify an appropriate degree of dimensionality reduction to perform,
 # which you can then specify manually using the ``rank`` argument. The code
@@ -439,14 +441,15 @@
 # coherency/coherence, such as CaCoh.
 #
 # In short, if you want to examine connectivity between signals from the same
-# modality, you should consider using MIC and MIM to avoid spurious
-# connectivity estimates stemming from e.g. volume conduction artefacts.
+# modality or from different modalities using a shared reference, you should
+# consider using MIC and MIM to avoid spurious connectivity estimates stemming
+# from e.g. volume conduction artefacts.
 #
 # On the other hand, if you want to examine connectivity between signals from
-# different modalities, CaCoh is a more appropriate method than MIC/MIM. This
-# is because voilume conduction artefacts are of less concern, and CaCoh does
-# not risk biasing connectivity estimates towards interactions with particular
-# phase lags like MIC/MIM.
+# different modalities using different references, CaCoh is a more appropriate
+# method than MIC/MIM. This is because volume conduction artefacts are of less
+# concern, and CaCoh does not risk biasing connectivity estimates towards
+# interactions with particular phase lags like MIC/MIM.
 #
 # These scenarios are described in more detail in the
 # :doc:`compare_coherency_methods` example.

mne_connectivity/spectral/epochs.py

@@ -924,7 +924,7 @@ def spectral_connectivity_epochs(
         :footcite:`BarnettSeth2015,WinklerEtAl2016` given by the same equation
         as for 'gc', but where the autocovariance sequence from which the
         autoregressive model is produced is transposed to mimic the reversal of
-        the original signal in time.
+        the original signal in time :footcite:`HaufeEtAl2012`.
 
     References
     ----------

mne_connectivity/spectral/time.py

@@ -332,7 +332,7 @@ def spectral_connectivity_time(
         :footcite:`BarnettSeth2015,WinklerEtAl2016` given by the same equation
         as for 'gc', but where the autocovariance sequence from which the
         autoregressive model is produced is transposed to mimic the reversal of
-        the original signal in time.
+        the original signal in time :footcite:`HaufeEtAl2012`.
 
     Parallel computation can be activated by setting the ``n_jobs`` parameter.
     Under the hood, this utilizes the ``joblib`` library. For effective