Improvements to the ICA API

@adam2392 pinging as discussed.

Hello! Following the release of mne-icalabel, I’d like to propose a couple of changes to the ICA API. In mne-icalabel, we used label_components as the main entry-point:

from mne_icalabel import label_components

raw = ...
ica = ...
label_components(raw, ica, method='iclabel')

The name was chosen to be consistent with the methods in an ICA instance: get_components and plot_components. For now, the only available method argument is 'iclabel', but the goal is to add more.

-> Proposed change: add a label_components method to the ICA instance that takes as input self, a raw or epochs instance, and the name of the method to use to label components.

---

But instead of only stopping here and clogging a bit more the MNE API, I’d like to go a bit further. For now, the ICA instance has build-in simple methods to label cardiac, ocular, MEG ref, and muscular-related components: find_bads_eog, find_bads_ecg, find_bads_ref and the newly added find_bads_muscle. Each of those methods’ outputs is very similar to the output of label_components: labels and scores/prediction probabilities.

-> Proposed change: move those simple labeling methods to mne-icalabel, deprecate the find_bads_ methods, and group all labeling methods under a simple ica.label_components method.

IMO, this change would simplify the API and move the maintenance of the related code and documentation to the mne-icalabel repository.

---

And finally, alongside those 2 changes, labels and scores/prediction probabilities could be stored in the ICA instance. For now, only the labels are stored in a dictionary self.labels_ where the key is the method/component type and the value is a list of components IDx that were labelled with this type. Related issue: https://github.com/mne-tools/mne-python/issues/9846

WDYT?

[larsoner]

Proposed change: move those simple labeling methods to mne-icalabel, deprecate the find_bads_ methods, and group all labeling methods under a simple ica.label_components method.

I’m fine with moving this functionality to a unified ica.label_components function, but I’d actually like to 1) keep one-line wrappers for find_bads_*, and 2) advertise that new code should use the unified function. Every deprecation means pain for our users, and I think we can avoid it easily here, especially for code that has been around for 8 years. The maintenance overhead for us in keeping it is low, and I think if we adapt tutorials + docstrings to advertise the new label_components function, users won’t be too confused by our the violation of “one way” principle.

[larsoner]

Moving the code outside of MNE is a great idea though.

Does MNE-ICLabel require PyTorch? If that’s the case, given @hoechenberger’s difficulties with installing PyTorch in https://github.com/mne-tools/mne-installers/pull/123 as it’s quite a big dependency, I’m -1 on depending on MNE-ICLabel for core ICA functionality in MNE-Python. We should only depend on it for ICLabel functionality.

In other words, let’s add ica.label_components in MNE-Python, keep our find_bads_* one-line wrappers for trivial backward compat (no need for deprecation), and just add a small shim in label_components to call to mne-iclabel when a user requests that mode.