Merge branch 'main' into fixed_length_epochs_overlay

.github/workflows/cancel.yml

@@ -0,0 +1,15 @@
+# https://github.com/styfle/cancel-workflow-action#advanced-pull-requests-from-forks
+name: Cancel
+on:
+  workflow_run:
+    # https://api.github.com/repos/mne-tools/mne-python/actions/workflows
+    workflows: ["compat / minimal", "compat / old", "linux / conda", "linux / pip-pre", "macos / conda"]
+    types:
+      - requested
+jobs:
+  cancel:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: styfle/cancel-workflow-action@0.8.0
+      with:
+        workflow_id: ${{ github.event.workflow.id }}

.gitignore

@@ -64,6 +64,7 @@ doc/coverages
 doc/samples
 doc/*.dat
 doc/fil-result
+doc/optipng.exe
 cover
 *.html
 

doc/changes/latest.inc

@@ -36,12 +36,18 @@ Current (0.23.dev0)
 .. |Judy D Zhu| replace:: **Judy D Zhu**
 
 .. |Valerii Chirkov| replace:: **Valerii Chirkov**
+
+.. |Matteo Anelli| replace:: **Matteo Anelli**
+
+.. |Silvia Cotroneo| replace:: **Silvia Cotroneo**
+
 
-.. |Silvia Cotroneo| replace:: *Silvia Cotroneo*
 Enhancements
 ~~~~~~~~~~~~
 - Add parameter ``overlap=0.`` to `mne.Epochs.make_fixed_length_epochs` to allow creating overlapping fixed length epochs (:gh:`9096` **by new contributor** |Silvia Cotroneo|_)
 
+- Add :meth:`mne.Dipole.to_mni` for more convenient  dipole.pos to MNI conversion (:gh:`9043` **by new contributor** |Valerii Chirkov|_)
+
 - Update citations in maxwell.py (:gh:`9043` **by new contributor** |Valerii Chirkov|_)
 
 - New Tutorial for analyzing frequency-tagging data (:gh:`8867` **by new contributor** |Dominik Welke|_ and `kalenkovich`_)
@@ -118,6 +124,10 @@ Enhancements
 
 Bugs
 ~~~~
+- Fix bug with :func:`mne.Epochs.plot_image` where the ``x_label`` was different depending on the evoked parameter (:gh:`9115` **by new contributor** |Matteo Anelli|_)
+
+- Fix bug with restricting :func:`mne.io.Raw.save` saving options to .fif and .fif.gz extensions (:gh:`9062` by |Valerii Chirkov|_)
+
 - Fix bug with :func:`mne.io.read_raw_kit` where missing marker coils were not handled (:gh:`8989` **by new contributor** |Judy D Zhu|_)
 
 - Fix bug with `mne.connectivity.spectral_connectivity` where time axis in Epochs data object was dropped. (:gh:`8839` **by new contributor** |Anna Padee|_)
@@ -200,6 +210,13 @@ Bugs
 
 - Fix :func:`mne.read_dipole` yielding :class:`mne.Dipole` objects that could not be indexed (:gh:`8963` by `Marijn van Vliet`_)
 
+- Fix bug when setting n_jobs > 1 in :func:`mne.Report.parse_folder` (:gh:`9109` by `Martin Schulz`_)
+
+- Fix bug with :func:`mne.Evoked.plot_image` where an incorrect clim parameter did not raise any error (:gh:`9115` **by new contributor** |Matteo Anelli|_)
+
 API changes
 ~~~~~~~~~~~
 - ``mne.read_selection`` has been deprecated in favor of `mne.read_vectorview_selection`. ``mne.read_selection`` will be removed in MNE-Python 0.24 (:gh:`8870` by `Richard Höchenberger`_)
+
+- ``mne.beamformer.tf_dics`` has been deprecated and will be removed in MNE-Python 0.24 (:gh:`9122` by `Britta Westner`_)
+

doc/changes/names.inc

@@ -367,3 +367,5 @@
 .. _Judy D Zhu: https://github.com/JD-Zhu
 
 .. _Valerii Chirkov: https://github.com/vagechirkov
+
+.. _Matteo Anelli: https://github.com/matteoanelli

doc/conf.py

@@ -89,6 +89,7 @@
     'mne_substitutions',
     'sphinx_bootstrap_divs',
     'sphinxcontrib.bibtex',
+    'sphinx_copybutton',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

doc/references.bib

@@ -481,6 +481,19 @@ @article{GraimannEtAl2002
   year = {2002}
 }
 
+@article{GramfortEtAl2010,
+  author = {Alexandre Gramfort and Renaud Keriven and Maureen Clerc},
+  title = {Graph-Based Variability Estimation in Single-Trial Event-Related Neural Responses},
+  journal = {{IEEE} Transactions on Biomedical Engineering},
+  doi = {10.1109/tbme.2009.2037139},
+  url = {https://doi.org/10.1109%2Ftbme.2009.2037139},
+  year = {2010},
+  publisher = {Institute of Electrical and Electronics Engineers ({IEEE})},
+  volume = {57},
+  number = {5},
+  pages = {1051--1061},
+}
+
 @incollection{GramfortEtAl2011,
   address = {{Berlin; Heidelberg}},
   author = {Gramfort, Alexandre and Strohmeier, Daniel and Haueisen, Jens and Hämäläinen, Matti S. and Kowalski, Matthieu},

examples/decoding/plot_ssd_spatial_filters.py

@@ -1,6 +1,6 @@
 """
 ===========================================================
-Compute Sepctro-Spatial Decomposition (SSD) spatial filters
+Compute Spectro-Spatial Decomposition (SSD) spatial filters
 ===========================================================
 
 In this example, we will compute spatial filters for retaining

examples/preprocessing/plot_virtual_evoked.py

@@ -26,14 +26,30 @@
 fname = data_path + '/MEG/sample/sample_audvis-ave.fif'
 evoked = mne.read_evokeds(fname, condition='Left Auditory', baseline=(None, 0))
 
-# go from grad + mag to mag
+###############################################################################
+# First, let's call remap gradiometers to magnometers, and plot
+# the original and remapped topomaps of the magnetometers.
+
+# go from grad + mag to mag and plot original mag
 virt_evoked = evoked.as_type('mag')
 evoked.plot_topomap(ch_type='mag', title='mag (original)', time_unit='s')
+
+###############################################################################
+
+# plot interpolated grad + mag
 virt_evoked.plot_topomap(ch_type='mag', time_unit='s',
                          title='mag (interpolated from mag + grad)')
 
-# go from grad + mag to grad
+###############################################################################
+# Now, we remap magnometers to gradiometers, and plot
+# the original and remapped topomaps of the gradiometers
+
+# go from grad + mag to grad and plot original grad
 virt_evoked = evoked.as_type('grad')
 evoked.plot_topomap(ch_type='grad', title='grad (original)', time_unit='s')
+
+###############################################################################
+
+# plot interpolated grad + mag
 virt_evoked.plot_topomap(ch_type='grad', time_unit='s',
                          title='grad (interpolated from mag + grad)')

examples/preprocessing/plot_xdawn_denoising.py

@@ -7,24 +7,13 @@
 space and then projected back in the sensor space using only the first two
 XDAWN components. The process is similar to an ICA, but is
 supervised in order to maximize the signal to signal + noise ratio of the
-evoked response.
+evoked response :footcite:`RivetEtAl2009, RivetEtAl2011`.
 
 .. warning:: As this denoising method exploits the known events to
              maximize SNR of the contrast between conditions it can lead
              to overfitting. To avoid a statistical analysis problem you
              should split epochs used in fit with the ones used in
              apply method.
-
-References
-----------
-[1] Rivet, B., Souloumiac, A., Attina, V., & Gibert, G. (2009). xDAWN
-algorithm to enhance evoked potentials: application to brain-computer
-interface. Biomedical Engineering, IEEE Transactions on, 56(8), 2035-2043.
-
-[2] Rivet, B., Cecotti, H., Souloumiac, A., Maby, E., & Mattout, J. (2011,
-August). Theoretical analysis of xDAWN algorithm: application to an
-efficient sensor selection in a P300 BCI. In Signal Processing Conference,
-2011 19th European (pp. 1382-1386). IEEE.
 """
 
 # Authors: Alexandre Barachant <alexandre.barachant@gmail.com>
@@ -85,3 +74,8 @@
 
 # Plot image epoch after Xdawn
 plot_epochs_image(epochs_denoised['vis_r'], picks=[230], vmin=-500, vmax=500)
+
+###############################################################################
+# References
+# ----------
+# .. footbibliography::

examples/stats/plot_sensor_regression.py

@@ -10,20 +10,16 @@
 timepoint. This example shows the regression coefficient; the t and p values
 are also calculated automatically.
 
-Here, we repeat a few of the analyses from [1]_. This can be easily performed
-by accessing the metadata object, which contains word-level information about
-various psycholinguistically relevant features of the words for which we have
-EEG activity.
+Here, we repeat a few of the analyses from :footcite:`DufauEtAl2015`. This
+can be easily performed by accessing the metadata object, which contains
+word-level information about various psycholinguistically relevant features
+of the words for which we have EEG activity.
 
-For the general methodology, see e.g. [2]_.
+For the general methodology, see e.g. :footcite:`HaukEtAl2006`.
 
 References
 ----------
-.. [1] Dufau, S., Grainger, J., Midgley, KJ., Holcomb, PJ. A thousand
-   words are worth a picture: Snapshots of printed-word processing in an
-   event-related potential megastudy. Psychological Science, 2015
-.. [2] Hauk et al. The time course of visual word recognition as revealed by
-   linear regression analysis of ERP data. Neuroimage, 2006
+.. footbibliography::
 """
 # Authors: Tal Linzen <linzen@nyu.edu>
 #          Denis A. Engemann <denis.engemann@gmail.com>

examples/visualization/plot_channel_epochs_image.py

@@ -10,7 +10,7 @@
 that does not show any evoked field.
 
 It is also demonstrated how to reorder the epochs using a 1D spectral
-embedding as described in [1]_.
+embedding as described in :footcite:`GramfortEtAl2010`.
 """
 # Authors: Alexandre Gramfort <alexandre.gramfort@inria.fr>
 #
@@ -75,7 +75,4 @@ def order_func(times, data):
 ###############################################################################
 # References
 # ----------
-# .. [1] Graph-based variability estimation in single-trial event-related
-#        neural responses. A. Gramfort, R. Keriven, M. Clerc, 2010,
-#        Biomedical Engineering, IEEE Trans. on, vol. 57 (5), 1051-1061
-#        https://ieeexplore.ieee.org/document/5406156
+# .. footbibliography::

mne/beamformer/_dics.py

@@ -12,7 +12,7 @@
 from ..io.pick import pick_info, pick_channels
 from ..utils import (logger, verbose, warn, _check_one_ch_type,
                      _check_channels_spatial_filter, _check_rank,
-                     _check_option, _validate_type)
+                     _check_option, _validate_type, deprecated)
 from ..forward import _subject_from_forward
 from ..minimum_norm.inverse import combine_xyz, _check_reference, _check_depth
 from ..rank import compute_rank
@@ -493,6 +493,9 @@ def apply_dics_csd(csd, filters, verbose=None):
             frequencies)
 
 
+@deprecated(
+    'tf_dics is deprecated and will be removed in 0.24, use LCMV with '
+    'covariances matrices computed on band-passed data or DICS instead.')
 @verbose
 def tf_dics(epochs, forward, noise_csds, tmin, tmax, tstep, win_lengths,
             subtract_evoked=False, mode='fourier', freq_bins=None,

mne/beamformer/tests/test_dics.py

@@ -566,6 +566,7 @@ def test_apply_dics_timeseries(_load_forward, idx):
 
 @pytest.mark.slowtest
 @testing.requires_testing_data
+@pytest.mark.filterwarnings('ignore:.*tf_dics is dep.*:DeprecationWarning')
 def test_tf_dics(_load_forward):
     """Test 5D time-frequency beamforming based on DICS."""
     fwd_free, fwd_surf, fwd_fixed, _ = _load_forward

mne/datasets/hf_sef/hf_sef.py

@@ -16,7 +16,8 @@ def data_path(dataset='evoked', path=None, force_update=False,
               update_path=True, verbose=None):
     u"""Get path to local copy of the high frequency SEF dataset.
 
-    Gets a local copy of the high frequency SEF MEG dataset [1]_.
+    Gets a local copy of the high frequency SEF MEG dataset
+    :footcite:`NurminenEtAl2017`.
 
     Parameters
     ----------
@@ -44,8 +45,7 @@ def data_path(dataset='evoked', path=None, force_update=False,
 
     References
     ----------
-    .. [1] Nurminen, J., Paananen, H., Mäkelä, J. (2017): High frequency
-           somatosensory MEG dataset. https://doi.org/10.5281/zenodo.889234
+    .. footbibliography::
     """
     key = 'MNE_DATASETS_HF_SEF_PATH'
     name = 'HF_SEF'