MRG, API: Deprecate max_pca_components

doc/_static/diagrams/ica.dot

@@ -20,8 +20,9 @@ digraph ICAdiagram {
           fontsize=12
           fontname="Source Code Pro"]
 
-    /* starting node */
+    /* starting nodes */
     sensor [label="Sensor data" shape="box" fillcolor="#bbbbbb"]
+    cov [label="Noise cov" shape="box" fillcolor="#bbbbbb"]
 
     /* ICA.FIT() */
     subgraph cluster_0 {
@@ -30,17 +31,20 @@ digraph ICAdiagram {
         fontcolor="#009988"
         penwidth=1.5
 
+
         /* PRE-WHITENING */
         subgraph cluster_1 {
-            label="Pre-whitening"
+            label="Whitening"
             style="dashed"
             fontname="Source Sans Pro"
             color="gray50"
             fontcolor="gray50"
             /* nodes & edges */
+            pre [label="Pre-\nwhiten" fontsize=11 shape="circle" fillcolor="#ee7733"]
+            pre -> pca
             pca        [label="PCA"                   shape="circle" fillcolor="#ee7733"]
             pcs        [label="Principal\ncomponents" shape="box"    fillcolor="#33bbee"]
-            pca -> pcs [label="max_pca_components\r"]
+            pca -> pcs
         }
 
         /* nodes & edges */
@@ -60,7 +64,8 @@ digraph ICAdiagram {
     }
 
     /* subgraph-crossing edges */
-    sensor -> pca  [label="all sensor channels\r" fontsize=14 fontname="Source Sans Pro"]
+    sensor -> pre  [label="all sensor channels\r" fontsize=14 fontname="Source Sans Pro"]
+    cov -> pre     [label="covariance or std. dev.\r" fontsize=14 fontname="Source Sans Pro"]
     pcs -> ica     [label="n_components\l"]
     ics -> recon   [constraint=false color="#ee3377"
                     xlabel="Retained ICs:\ln_components -\llen(ICA.exclude)\l"]

doc/changes/latest.inc

@@ -15,11 +15,11 @@ Current (0.22.dev0)
 Enhancements
 ~~~~~~~~~~~~
 
-- Speed up :class:`mne.decoding.TimeDelayingRidge` with edge correction using Numba by `Eric Larson`_ (:gh:`8323`)
+- Add ``n_pca_components`` argument to :func:`mne.viz.plot_ica_overlay` by `Eric Larson`_ (:gh:`8351`)
 
-- The ``max_pca_components`` argument of `~mne.preprocessing.ICA` can now be a float between 0.0 and 1.0, allowing users to specify a relative amount of cumulative explained variance. This can be used to exclude "unimportant" principal components, thereby conducting a rank reduction of the data, by `Richard Höchenberger`_ (:gh:`8321`)
+- Add ``proj`` argument to :func:`mne.make_fixed_length_epochs` by `Eric Larson`_ (:gh:`8351`)
 
-- `~mne.preprocessing.ICA` has gained a new attribute ``max_pca_components_``, which will be set when calling `~mne.preprocessing.ICA.fit`, by `Richard Höchenberger`_ (:gh:`8321`)
+- Speed up :class:`mne.decoding.TimeDelayingRidge` with edge correction using Numba by `Eric Larson`_ (:gh:`8323`)
 
 Bugs
 ~~~~
@@ -52,7 +52,11 @@ Bugs
 
 - Fix bug that `~mne.viz.plot_ica_overlay` would sometimes not create red traces, by `Richard Höchenberger`_ (:gh:`8341`)
 
+- Fix bug with :class:`~mne.preprocessing.ICA` where ``n_components=None, n_pca_components=None`` could lead to unstable unmixing matrix inversion by making ``n_components=None`` also use the lesser of ``n_components=0.999999`` and ``n_components=n_pca_components`` by `Eric Larson`_ (:gh:`8351`)
+
+- The ``ica.n_pca_components`` property is no longer be updated during :meth:`mne.preprocessing.ICA.fit`, instead ``ica.n_components_`` will be added to the instance by `Eric Larson`_ (:gh:`8351`)
+
 API changes
 ~~~~~~~~~~~
 
-...
+- The ``max_pca_components`` argument of :class:`~mne.preprocessing.ICA` has been deprecated, use ``n_pca_components`` instead by `Eric Larson`_

mne/epochs.py

@@ -1941,17 +1941,7 @@ class Epochs(BaseEpochs):
         Valid keys are 'grad' | 'mag' | 'eeg' | 'eog' | 'ecg', and values
         are floats that set the minimum acceptable peak-to-peak amplitude.
         If flat is None then no rejection is done.
-    proj : bool | 'delayed'
-        Apply SSP projection vectors. If proj is 'delayed' and reject is not
-        None the single epochs will be projected before the rejection
-        decision, but used in unprojected state if they are kept.
-        This way deciding which projection vectors are good can be postponed
-        to the evoked stage without resulting in lower epoch counts and
-        without producing results different from early SSP application
-        given comparable parameters. Note that in this case baselining,
-        detrending and temporal decimation will be postponed.
-        If proj is False no projections will be applied which is the
-        recommended value if SSPs are not used for cleaning the data.
+    %(proj_epochs)s
     %(decim)s
     reject_tmin : scalar | None
         Start of the time window used to reject epochs (with the default None,
@@ -2591,17 +2581,7 @@ def read_epochs(fname, proj=True, preload=True, verbose=None):
         The epochs filename to load. Filename should end with -epo.fif or
         -epo.fif.gz. If a file-like object is provided, preloading must be
         used.
-    proj : bool | 'delayed'
-        Apply SSP projection vectors. If proj is 'delayed' and reject is not
-        None the single epochs will be projected before the rejection
-        decision, but used in unprojected state if they are kept.
-        This way deciding which projection vectors are good can be postponed
-        to the evoked stage without resulting in lower epoch counts and
-        without producing results different from early SSP application
-        given comparable parameters. Note that in this case baselining,
-        detrending and temporal decimation will be postponed.
-        If proj is False no projections will be applied which is the
-        recommended value if SSPs are not used for cleaning the data.
+    %(proj_epochs)s
     preload : bool
         If True, read all epochs from disk immediately. If False, epochs will
         be read on demand.
@@ -2641,17 +2621,7 @@ class EpochsFIF(BaseEpochs):
     fname : str | file-like
         The name of the file, which should end with -epo.fif or -epo.fif.gz. If
         a file-like object is provided, preloading must be used.
-    proj : bool | 'delayed'
-        Apply SSP projection vectors. If proj is 'delayed' and reject is not
-        None the single epochs will be projected before the rejection
-        decision, but used in unprojected state if they are kept.
-        This way deciding which projection vectors are good can be postponed
-        to the evoked stage without resulting in lower epoch counts and
-        without producing results different from early SSP application
-        given comparable parameters. Note that in this case baselining,
-        detrending and temporal decimation will be postponed.
-        If proj is False no projections will be applied which is the
-        recommended value if SSPs are not used for cleaning the data.
+    %(proj_epochs)s
     preload : bool
         If True, read all epochs from disk immediately. If False, epochs will
         be read on demand.
@@ -3218,7 +3188,8 @@ def average_movements(epochs, head_pos=None, orig_sfreq=None, picks=None,
 
 @verbose
 def make_fixed_length_epochs(raw, duration=1., preload=False,
-                             reject_by_annotation=True, verbose=None):
+                             reject_by_annotation=True, proj=True,
+                             verbose=None):
     """Divide continuous raw data into equal-sized consecutive epochs.
 
     Parameters
@@ -3231,6 +3202,9 @@ def make_fixed_length_epochs(raw, duration=1., preload=False,
     %(reject_by_annotation_epochs)s
 
         .. versionadded:: 0.21.0
+    %(proj_epochs)s
+
+        .. versionadded:: 0.22.0
     %(verbose)s
 
     Returns
@@ -3246,4 +3220,5 @@ def make_fixed_length_epochs(raw, duration=1., preload=False,
     delta = 1. / raw.info['sfreq']
     return Epochs(raw, events, event_id=[1], tmin=0, tmax=duration - delta,
                   baseline=None, preload=preload,
-                  reject_by_annotation=reject_by_annotation, verbose=verbose)
+                  reject_by_annotation=reject_by_annotation, proj=proj,
+                  verbose=verbose)