DOC: more ICA doc improvements

I’m working on merging the two ICA tutorials into one. Here they are: one two. I want to expand the narrative a lot, explaining how ICA in MNE-Python works and how the user chooses the right parameter settings. Some of the parameters have confusing names like n_components, max_pca_components, n_pca_components. After reading the docstrings, I could not understand what is going on, so I read the source code for a couple hours. Then I read through #4856, #4882, #5054, and #5276. Now I want to make sure I understand everything before I try to (1) improve the docstrings more, and (2) improve the ICA tutorials. Here is my current understanding:

1. pre-whitening: each channel type is standardized to zero-mean, unit-variance. That way, channels with big artifacts are still big relative to other channels of the same type, but across-channel-type signal magnitudes are comparable. If the user supplied noise_cov, that will be used instead to do the pre-whitening. We tacitly assume that individual channels are already zero-mean, but don’t check or enforce it.
2. PCA: the pre-whitened data go into PCA. Only max_pca_components are retained. (max_pca_components must be integer or None)
3. ICA fitting: the PCs are fed into the ICA algorithm. How many of the PCs go in (and how many ICs you get back) is determined by n_components (integer, float, or None).
4. reconstruction: after possibly marking some ICs to be excluded, ica.apply() will reconstruct the sensor signals from the (unexcluded) ICs and possibly some of the PCs as well:
   • If n_components == n_pca_components then reconstruction is based only on the ICs.
   • if n_components < n_pca_components then reconstruction is based on the ICs plus PCs[n_components:n_pca_components]. This has a special case where n_pca_components == max_pca_components (or n_pca_components is None), in which case all of the retained PCs are used in the reconstruction (but the first n_components of them are replaced by the ICs).

questions:

1. Is any part of that summary incorrect?
2. Are there any details missing that you think are important enough to go in the tutorial?
3. Are there any details included that you think are too much information to be in the tutorial?

@cbrnr @mmagnuski @dengemann @agramfort

[agramfort]

It’s not a requirement, but I’d compute all ICs without dim reduction by default because most ICA algorithms (especiall PICARD) are fast enough that this is not necessary.

ok fair enough. Maybe the debate more existing with MEG data where you can have > 300 channels, or even HD EEG.

[cbrnr]

Thanks @drammock for trying to clarify this topic! This is very much needed indeed. On a quick skim, your description is correct.

Regarding what else should go into the tutorial, many questions @sappelhoff brought up pertain to why specific things are the way they are in MNE. I think it is important to include such practical explanations in the tutorial. For example, what if I don’t want to do PCA is a legitimate question, and we could address it by stating that as long as all PCA components are retained this is basically equivalent to not performing PCA at all.

Another important piece of information is to include use cases for supplying different values for n_components, max_pca_components, and n_pca_components. For example, a very basic use case could be to compute ICs for 64-channel EEG data with no dimensionality reduction with the aim to identify artifact components (e.g. EOG) - which parameters should be set?