Merge remote-tracking branch 'upstream/main' into fif-file-extention

* upstream/main:
  DOC: use bibtex in plot_sleep (mne-tools#9044)
  FIX: fix sideways helmet plot (mne-tools#9059)
  FIX: bibtex mne-tools#8933 (mne-tools#9047)
  Fix bibtex citation issue mne-tools#8929. (mne-tools#9051)
  bibtex fix plot_time_frequency_global_field_power (mne-tools#9052)
  Fixed bibtex references in plot_background_statistics (mne-tools#9046)
  Bibtex raw py (mne-tools#9048)
  DOC update footcite maxwell.py (mne-tools#9043)
  update footcite [skip github] [skip azp] (mne-tools#9054)
  Adding bibtex in plot_otp (mne-tools#9049)

doc/changes/latest.inc

@@ -35,8 +35,12 @@ Current (0.23.dev0)
 
 .. |Judy D Zhu| replace:: **Judy D Zhu**
 
+.. |Valerii Chirkov| replace:: **Valerii Chirkov**
+
 Enhancements
 ~~~~~~~~~~~~
+- 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`_)
 
 - Add dbs as new channel type for deep brain stimulation (DBS) recordings (:gh:`8739` **by new contributor** |Richard Koehler|_)

doc/changes/names.inc

@@ -365,3 +365,5 @@
 .. _Dominik Welke: https://github.com/dominikwelke/
 
 .. _Judy D Zhu: https://github.com/JD-Zhu
+
+.. _Valerii Chirkov: https://github.com/vagechirkov

examples/preprocessing/plot_otp.py

@@ -3,8 +3,8 @@
 Plot sensor denoising using oversampled temporal projection
 ===========================================================
 
-This demonstrates denoising using the OTP algorithm [1]_ on data with
-with sensor artifacts (flux jumps) and random noise.
+This demonstrates denoising using the OTP algorithm :footcite:`LarsonTaulu2018`
+on data with with sensor artifacts (flux jumps) and random noise.
 """
 # Author: Eric Larson <larson.eric.d@gmail.com>
 #
@@ -79,6 +79,4 @@ def compute_bias(raw):
 ###############################################################################
 # References
 # ----------
-# .. [1] Larson E, Taulu S (2017). Reducing Sensor Noise in MEG and EEG
-#        Recordings Using Oversampled Temporal Projection.
-#        IEEE Transactions on Biomedical Engineering.
+# .. footbibliography::

examples/time_frequency/plot_time_frequency_erds.py

@@ -5,12 +5,13 @@
 
 This example calculates and displays ERDS maps of event-related EEG data. ERDS
 (sometimes also written as ERD/ERS) is short for event-related
-desynchronization (ERD) and event-related synchronization (ERS) [1]_.
+desynchronization (ERD) and event-related synchronization (ERS)
+:footcite:`PfurtschellerLopesdaSilva1999`.
 Conceptually, ERD corresponds to a decrease in power in a specific frequency
 band relative to a baseline. Similarly, ERS corresponds to an increase in
 power. An ERDS map is a time/frequency representation of ERD/ERS over a range
-of frequencies [2]_. ERDS maps are also known as ERSP (event-related spectral
-perturbation) [3]_.
+of frequencies :footcite:`GraimannEtAl2002`. ERDS maps are also known as ERSP
+(event-related spectral perturbation) :footcite:`Makeig1993`.
 
 We use a public EEG BCI data set containing two different motor imagery tasks
 available at PhysioNet. The two tasks are imagined hand and feet movement. Our
@@ -26,15 +27,7 @@
 References
 ----------
 
-.. [1] G. Pfurtscheller, F. H. Lopes da Silva. Event-related EEG/MEG
-       synchronization and desynchronization: basic principles. Clinical
-       Neurophysiology 110(11), 1842-1857, 1999.
-.. [2] B. Graimann, J. E. Huggins, S. P. Levine, G. Pfurtscheller.
-       Visualization of significant ERD/ERS patterns in multichannel EEG and
-       ECoG data. Clinical Neurophysiology 113(1), 43-47, 2002.
-.. [3] S. Makeig. Auditory event-related dynamics of the EEG spectrum and
-       effects of exposure to tones. Electroencephalography and Clinical
-       Neurophysiology 86(4), 283-293, 1993.
+.. footbibliography::
 """
 # Authors: Clemens Brunner <clemens.brunner@gmail.com>
 #

examples/time_frequency/plot_time_frequency_global_field_power.py

@@ -6,21 +6,24 @@
 ===========================================================
 
 The objective is to show you how to explore spectrally localized
-effects. For this purpose we adapt the method described in [1]_ and use it on
-the somato dataset. The idea is to track the band-limited temporal evolution
+effects. For this purpose we adapt the method described in
+:footcite:`HariSalmelin1997` and use it on the somato dataset.
+The idea is to track the band-limited temporal evolution
 of spatial patterns by using the :term:`global field power` (GFP).
 
 We first bandpass filter the signals and then apply a Hilbert transform. To
 reveal oscillatory activity the evoked response is then subtracted from every
 single trial. Finally, we rectify the signals prior to averaging across trials
 by taking the magniude of the Hilbert.
-Then the :term:`GFP` is computed as described in [2]_, using the sum of the
+Then the :term:`GFP` is computed as described in
+:footcite:`EngemannGramfort2015`, using the sum of the
 squares but without normalization by the rank.
 Baselining is subsequently applied to make the :term:`GFP` comparable
 between frequencies.
 The procedure is then repeated for each frequency band of interest and
 all :term:`GFPs<GFP>` are visualized. To estimate uncertainty, non-parametric
-confidence intervals are computed as described in [3]_ across channels.
+confidence intervals are computed as described in :footcite:`EfronHastie2016`
+across channels.
 
 The advantage of this method over summarizing the Space x Time x Frequency
 output of a Morlet Wavelet in frequency bands is relative speed and, more
@@ -31,15 +34,8 @@
 
 References
 ----------
+.. footbibliography::
 
-.. [1] Hari R. and Salmelin R. Human cortical oscillations: a neuromagnetic
-       view through the skull (1997). Trends in Neuroscience 20 (1),
-       pp. 44-49.
-.. [2] Engemann D. and Gramfort A. (2015) Automated model selection in
-       covariance estimation and spatial whitening of MEG and EEG signals,
-       vol. 108, 328-342, NeuroImage.
-.. [3] Efron B. and Hastie T. Computer Age Statistical Inference (2016).
-       Cambrdige University Press, Chapter 11.2.
 """  # noqa: E501
 # Authors: Denis A. Engemann <denis.engemann@gmail.com>
 #          Stefan Appelhoff <stefan.appelhoff@mailbox.org>

examples/visualization/plot_mne_helmet.py

@@ -28,5 +28,5 @@
     coord_frame='mri')
 evoked.plot_field(maps, time=time, fig=fig, time_label=None, vmax=5e-13)
 mne.viz.set_3d_view(
-    fig, azimuth=40, elevation=87, focalpoint=(0., -0.01, 0.04), roll=-100,
-    distance=0.48)
+    fig, azimuth=40, elevation=87, focalpoint=(0., -0.01, 0.04), roll=-25,
+    distance=0.55)

mne/preprocessing/maxwell.py

@@ -116,8 +116,9 @@ def maxwell_filter(raw, origin='auto', int_order=8, ext_order=3,
 
     Some of this code was adapted and relicensed (with BSD form) with
     permission from Jussi Nurminen. These algorithms are based on work
-    from [1]_ and [2]_. It will likely use multiple CPU cores, see the
-    :ref:`FAQ <faq_cpu>` for more information.
+    from :footcite:`TauluKajola2005` and :footcite:`TauluSimola2006`.
+    It will likely use multiple CPU cores, see the :ref:`FAQ <faq_cpu>`
+    for more information.
 
     .. warning:: Maxwell filtering in MNE is not designed or certified
                  for clinical use.
@@ -166,7 +167,7 @@ def maxwell_filter(raw, origin='auto', int_order=8, ext_order=3,
        | Extended external basis (eSSS)                                              | ✓   |           |
        +-----------------------------------------------------------------------------+-----+-----------+
 
-    Epoch-based movement compensation is described in [1]_.
+    Epoch-based movement compensation is described in :footcite:`TauluKajola2005`.
 
     Use of Maxwell filtering routines with non-Neuromag systems is currently
     **experimental**. Worse results for non-Neuromag systems are expected due
@@ -199,15 +200,7 @@ def maxwell_filter(raw, origin='auto', int_order=8, ext_order=3,
 
     References
     ----------
-    .. [1] Taulu S. and Kajola M. "Presentation of electromagnetic
-           multichannel data: The signal space separation method,"
-           Journal of Applied Physics, vol. 97, pp. 124905 1-10, 2005.
-           https://doi.org/10.1063/1.1935742
-
-    .. [2] Taulu S. and Simola J. "Spatiotemporal signal space separation
-           method for rejecting nearby interference in MEG measurements,"
-           Physics in Medicine and Biology, vol. 51, pp. 1759-1768, 2006.
-           https://doi.org/10.1088/0031-9155/51/7/008
+    .. footbibliography::
     """  # noqa: E501
     logger.info('Maxwell filtering raw data')
     params = _prep_maxwell_filter(
@@ -745,7 +738,7 @@ def _do_tSSS(clean_data, orig_in_data, resid, st_correlation,
     else:
         np.asarray_chkfinite(resid)
         t_proj = _overlap_projector(orig_in_data, resid, st_correlation)
-    # Apply projector according to Eq. 12 in [2]_
+    # Apply projector according to Eq. 12 in :footcite:`TauluSimola2006`
     msg = ('        Projecting %2d intersecting tSSS component%s '
            'for %s' % (t_proj.shape[1], _pl(t_proj.shape[1], ' '), t_str))
     if n_positions > 1:
@@ -1565,12 +1558,14 @@ def _orth_overwrite(A):
 def _overlap_projector(data_int, data_res, corr):
     """Calculate projector for removal of subspace intersection in tSSS."""
     # corr necessary to deal with noise when finding identical signal
-    # directions in the subspace. See the end of the Results section in [2]_
+    # directions in the subspace. See the end of the Results section in
+    # :footcite:`TauluSimola2006`
 
-    # Note that the procedure here is an updated version of [2]_ (and used in
-    # MF's tSSS) that uses residuals instead of internal/external spaces
-    # directly. This provides more degrees of freedom when analyzing for
-    # intersections between internal and external spaces.
+    # Note that the procedure here is an updated version of
+    # :footcite:`TauluSimola2006` (and used in MF's tSSS) that uses residuals
+    # instead of internal/external spaces directly. This provides more degrees
+    # of freedom when analyzing for intersections between internal and
+    # external spaces.
 
     # Normalize data, then compute orth to get temporal bases. Matrices
     # must have shape (n_samps x effective_rank) when passed into svd
@@ -1600,8 +1595,9 @@ def _overlap_projector(data_int, data_res, corr):
     intersect_mask = (S_intersect >= corr)
     del S_intersect
 
-    # Compute projection operator as (I-LL_T) Eq. 12 in [2]_
-    # V_principal should be shape (n_time_pts x n_retained_inds)
+    # Compute projection operator as (I-LL_T) Eq. 12 in
+    # :footcite:`TauluSimola2006` V_principal should be shape
+    # (n_time_pts x n_retained_inds)
     Vh_intersect = Vh_intersect[intersect_mask].T
     V_principal = np.dot(Q_res, Vh_intersect)
     return V_principal
@@ -1876,15 +1872,14 @@ def _compute_sphere_activation_in(degrees):
     Returns
     -------
     a_power : ndarray
-        The a_lm associated for the associated degrees (see [1]_).
+        The a_lm associated for the associated degrees (see
+        :footcite:`KnuutilaEtAl1993`).
     rho_i : float
         The current density.
 
     References
     ----------
-    .. [1] A 122-channel whole-cortex SQUID system for measuring the brain’s
-       magnetic fields. Knuutila et al. IEEE Transactions on Magnetics,
-       Vol 29 No 6, Nov 1993.
+    .. footbibliography::
     """
     r_in = 0.080  # radius of the randomly-activated sphere
 

mne/simulation/raw.py

@@ -166,7 +166,7 @@ def simulate_raw(info, stc=None, trans=None, src=None, bem=None, head_pos=None,
         solution filename (e.g., "sample-5120-5120-5120-bem-sol.fif").
         Can be None if ``forward`` is provided.
     %(head_pos)s
-        See for example [1]_.
+        See for example :footcite:`LarsonTaulu2017`.
     mindist : float
         Minimum distance between sources and the inner skull boundary
         to use during forward calculation.
@@ -237,9 +237,7 @@ def simulate_raw(info, stc=None, trans=None, src=None, bem=None, head_pos=None,
 
     References
     ----------
-    .. [1] Larson E, Taulu S (2017). "The Importance of Properly Compensating
-           for Head Movements During MEG Acquisition Across Different Age
-           Groups." Brain Topogr 30:172–181
+    .. footbibliography::
     """  # noqa: E501
     _validate_type(info, Info, 'info')
     raw_verbose = verbose
@@ -369,7 +367,7 @@ def add_eog(raw, head_pos=None, interp='cos2', n_jobs=1, random_state=None,
     1. Random activation times are drawn from an inhomogeneous poisson
        process whose blink rate oscillates between 4.5 blinks/minute
        and 17 blinks/minute based on the low (reading) and high (resting)
-       blink rates from [1]_.
+       blink rates from :footcite:`BentivoglioEtAl1997`.
     2. The activation kernel is a 250 ms Hanning window.
     3. Two activated dipoles are located in the z=0 plane (in head
        coordinates) at ±30 degrees away from the y axis (nasion).
@@ -382,8 +380,7 @@ def add_eog(raw, head_pos=None, interp='cos2', n_jobs=1, random_state=None,
 
     References
     ----------
-    .. [1] Bentivoglio et al. "Analysis of blink rate patterns in normal
-           subjects" Movement Disorders, 1997 Nov;12(6):1028-34.
+    .. footbibliography::
     """
     return _add_exg(raw, 'blink', head_pos, interp, n_jobs, random_state)
 

mne/source_estimate.py

@@ -1636,6 +1636,7 @@ def estimate_snr(self, info, fwd, cov, verbose=None):
 
         This function should only be used with source estimates with units
         nanoAmperes (i.e., MNE-like solutions, *not* dSPM or sLORETA).
+        See also :footcite:`GoldenholzEtAl2009`.
 
         .. warning:: This function currently only works properly for fixed
                      orientation.
@@ -1672,11 +1673,7 @@ def estimate_snr(self, info, fwd, cov, verbose=None):
 
         References
         ----------
-        .. [1] Goldenholz, D. M., Ahlfors, S. P., Hämäläinen, M. S., Sharon,
-               D., Ishitobi, M., Vaina, L. M., & Stufflebeam, S. M. (2009).
-               Mapping the Signal-To-Noise-Ratios of Cortical Sources in
-               Magnetoencephalography and Electroencephalography.
-               Human Brain Mapping, 30(4), 1077–1086. doi:10.1002/hbm.20571
+        .. footbibliography::
         """
         from .forward import convert_forward_solution, Forward
         from .minimum_norm.inverse import _prepare_forward
@@ -1710,7 +1707,7 @@ def center_of_mass(self, subject=None, hemi=None, restrict_vertices=False,
         """Compute the center of mass of activity.
 
         This function computes the spatial center of mass on the surface
-        as well as the temporal center of mass as in [1]_.
+        as well as the temporal center of mass as in :footcite:`LarsonLee2013`.
 
         .. note:: All activity must occur in a single hemisphere, otherwise
                   an error is raised. The "mass" of each point in space for
@@ -1762,8 +1759,7 @@ def center_of_mass(self, subject=None, hemi=None, restrict_vertices=False,
 
         References
         ----------
-        .. [1] Larson and Lee, "The cortical dynamics underlying effective
-               switching of auditory spatial attention", NeuroImage 2012.
+        .. footbibliography::
         """
         if not isinstance(surf, str):
             raise TypeError('surf must be a string, got %s' % (type(surf),))

mne/stats/regression.py

@@ -158,7 +158,7 @@ def linear_regression_raw(raw, events, event_id=None, tmin=-.1, tmax=1,
     Internally, this constructs a predictor matrix X of size
     n_samples * (n_conds * window length), solving the linear system
     ``Y = bX`` and returning ``b`` as evoked-like time series split by
-    condition. See [1]_.
+    condition. See :footcite:`SmithKutas2015`.
 
     Parameters
     ----------
@@ -237,9 +237,7 @@ def linear_regression_raw(raw, events, event_id=None, tmin=-.1, tmax=1,
 
     References
     ----------
-    .. [1] Smith, N. J., & Kutas, M. (2015). Regression-based estimation of ERP
-           waveforms: II. Non-linear effects, overlap correction, and practical
-           considerations. Psychophysiology, 52(2), 169-189.
+    .. footbibliography::
     """
     from scipy import linalg
     if isinstance(solver, str):

tutorials/discussions/plot_background_statistics.py

@@ -41,9 +41,9 @@
 # some probability (e.g., p < 0.05). This probability is also called the
 # significance level :math:`\alpha`.
 # To think about what this means, let's follow the illustrative example from
-# [1]_ and construct a toy dataset consisting of a 40 x 40 square with a
-# "signal" present in the center with white noise added and a Gaussian
-# smoothing kernel applied.
+# :footcite:`RidgwayEtAl2012` and construct a toy dataset consisting of a
+# 40 x 40 square with a "signal" present in the center with white noise added
+# and a Gaussian smoothing kernel applied.
 
 width = 40
 n_subjects = 10
@@ -168,7 +168,8 @@ def plot_t_p(t, p, title, mcc, axes=None):
 # "Hat" variance adjustment
 # ~~~~~~~~~~~~~~~~~~~~~~~~~
 # The "hat" technique regularizes the variance values used in the t-test
-# calculation [1]_ to compensate for implausibly small variances.
+# calculation :footcite:`RidgwayEtAl2012` to compensate for implausibly small
+# variances.
 ts.append(ttest_1samp_no_p(X, sigma=sigma))
 ps.append(stats.distributions.t.sf(np.abs(ts[-1]), len(X) - 1) * 2)
 titles.append(r'$\mathrm{t_{hat}}$')
@@ -460,7 +461,7 @@ def plot_t_p(t, p, title, mcc, axes=None):
 # "Hat" variance adjustment
 # ~~~~~~~~~~~~~~~~~~~~~~~~~
 # This method can also be used in this context to correct for small
-# variances [1]_:
+# variances :footcite:`RidgwayEtAl2012`:
 titles.append(r'$\mathbf{C_{hat}}$')
 stat_fun_hat = partial(ttest_1samp_no_p, sigma=sigma)
 t_hat, clusters, p_values, H0 = permutation_cluster_1samp_test(
@@ -482,7 +483,8 @@ def plot_t_p(t, p, title, mcc, axes=None):
 # TFCE eliminates the free parameter initial ``threshold`` value that
 # determines which points are included in clustering by approximating
 # a continuous integration across possible threshold values with a standard
-# `Riemann sum <https://en.wikipedia.org/wiki/Riemann_sum>`__ [2]_.
+# `Riemann sum <https://en.wikipedia.org/wiki/Riemann_sum>`__
+# :footcite:`SmithNichols2009`.
 # This requires giving a starting threshold ``start`` and a step
 # size ``step``, which in MNE is supplied as a dict.
 # The smaller the ``step`` and closer to 0 the ``start`` value,
@@ -652,12 +654,6 @@ def plot_t_p(t, p, title, mcc, axes=None):
 #
 # References
 # ----------
-# .. [1] Ridgway et al. 2012, "The problem of low variance voxels in
-#        statistical parametric mapping; a new hat avoids a 'haircut'",
-#        NeuroImage. 2012 Feb 1;59(3):2131-41.
-#
-# .. [2] Smith and Nichols 2009, "Threshold-free cluster enhancement:
-#        addressing problems of smoothing, threshold dependence, and
-#        localisation in cluster inference", NeuroImage 44 (2009) 83-98.
+# .. footbibliography::
 #
 # .. include:: ../../links.inc