Repository: mne-tools/mne-python

Issue:
ICA tutorial text is out-of-sync with the figures/output
I noticed today that in the `corrmap` section of the ICA tutorial, the results have changed such that the text is no longer accurate.

- here is [the relevant section in version 0.22](https://mne.tools/0.22/auto_tutorials/preprocessing/plot_40_artifact_correction_ica.html#selecting-ica-components-using-template-matching) where the intial call to `corrmap` misses finding a component for one subject
- here is [the same section on current stable](https://mne.tools/stable/auto_tutorials/preprocessing/40_artifact_correction_ica.html#selecting-ica-components-using-template-matching) where a component is found for all 4 subjects, making the text inaccurate.

I have no idea what could have caused the corrmap results to change, but I think @hoechenberger and maybe @cbrnr worked on some changes to the ICA defaults in the last year that might be the cause?  Can either of you think offhand why this happened, or have a suggestion as to what to do to fix it?  The basic options seem to be

1. update the tutorial to just state what the new results show, and remove the subsequent section where we tweak the corrmap parameters until we get a component for all subjs
2. pass different params to ICA (?) in the tutorial such that we get the old results back, and otherwise leave the tutorial unchanged

I lean toward option 1 because the first-pass results now are actually better than they used to be... however I also thought the param-tweaking part of the tutorial was instructive in a nice way that our tutorials often aren't (i.e., too often everything works and looks beautiful with no tweaking); hence I'm reluctant to delete it.


Discussion:
Offhand, I think the only thing that @hoechenberger changed recently was the `max_iter` parameter, which for `fastica` is now `1000` and was `200` previously. Maybe changing this back to `200` already reproduces the previous results?

I also think that tweaking parameters is instructive, but we should still keep the default arguments as the first step. We could add a paragraph where we show the influence of the `max_iter` argument, and then show how to tweak the correlation threshold. Although that's a bit silly when the real problem is ICA convergence, provided that bumping `max_iter` really is the issue here.
@larsoner had also fixed some issues related to algebraic stability when using rank-deficient data. Could also have had an impact.
Looks like `stable` is the same way, and we fixed the PCA component selection step in 0.23 so that's probably the culprit

+1 for (1) above

Resolving patch:
diff --git a/tutorials/preprocessing/40_artifact_correction_ica.py b/tutorials/preprocessing/40_artifact_correction_ica.py
--- a/tutorials/preprocessing/40_artifact_correction_ica.py
+++ b/tutorials/preprocessing/40_artifact_correction_ica.py
@@ -527,11 +527,8 @@
 # %%
 # The first figure shows the template map, while the second figure shows all
 # the maps that were considered a "match" for the template (including the
-# template itself). There were only three matches from the four subjects;
-# notice the output message ``No maps selected for subject(s) 1, consider a
-# more liberal threshold``.  By default the threshold is set automatically by
-# trying several values; here it may have chosen a threshold that is too high.
-# Let's take a look at the ICA sources for each subject:
+# template itself). There is one match for each subject, but it's a good idea
+# to also double-check the ICA sources for each subject:
 
 for index, (ica, raw) in enumerate(zip(icas, raws)):
     fig = ica.plot_sources(raw, show_scrollbars=False)
@@ -539,17 +536,15 @@
     fig.suptitle('Subject {}'.format(index))
 
 # %%
-# Notice that subject 1 *does* seem to have an IC that looks like it reflects
-# blink artifacts (component ``ICA000``). Notice also that subject 3 appears to
-# have *two* components that are reflecting ocular artifacts (``ICA000`` and
-# ``ICA002``), but only one was caught by `~mne.preprocessing.corrmap`.
-# Let's try setting the threshold manually:
+# Notice that subjects 2 and 3 each seem to have *two* ICs that reflect ocular
+# activity (components ``ICA000`` and ``ICA002``), but only one was caught by
+# `~mne.preprocessing.corrmap`. Let's try setting the threshold manually:
 
 corrmap(icas, template=(0, eog_inds[0]), threshold=0.9)
 
 # %%
-# Now we get the message ``At least 1 IC detected for each subject`` (which is
-# good). At this point we'll re-run `~mne.preprocessing.corrmap` with
+# This time it found 2 ICs for each of subjects 2 and 3 (which is good).
+# At this point we'll re-run `~mne.preprocessing.corrmap` with
 # parameters ``label='blink', plot=False`` to *label* the ICs from each subject
 # that capture the blink artifacts (without plotting them again).
 
@@ -560,12 +555,12 @@
 # %%
 # Notice that the first subject has 3 different labels for the IC at index 0:
 # "eog/0/Fpz", "eog", and "blink". The first two were added by
-# `~mne.preprocessing.ICA.find_bads_eog`; the "blink" label was added by
-# the last call to `~mne.preprocessing.corrmap`. Notice also that each
-# subject has at least one IC index labelled "blink", and subject 3 has two
+# `~mne.preprocessing.ICA.find_bads_eog`; the "blink" label was added by the
+# last call to `~mne.preprocessing.corrmap`. Notice also that each subject has
+# at least one IC index labelled "blink", and subjects 2 and 3 each have two
 # components (0 and 2) labelled "blink" (consistent with the plot of IC sources
-# above). The ``labels_`` attribute of `~mne.preprocessing.ICA` objects
-# can also be manually edited to annotate the ICs with custom labels. They also
+# above). The ``labels_`` attribute of `~mne.preprocessing.ICA` objects can
+# also be manually edited to annotate the ICs with custom labels. They also
 # come in handy when plotting:
 
 icas[3].plot_components(picks=icas[3].labels_['blink'])


Test patch: