Improvements to the ICA API

[mscheltienne]

@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: #9846

WDYT?

[cbrnr]

I like it a lot!

[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.

[hoechenberger]

Yes please no API changes here. Moving the code outside of MNE is a great idea though.

[agramfort]

let's not rush here. Let mne-icalabel get a bit of visibility and user feedback and then let's reevaluate in a few months.

…

Message ID: ***@***.***>

[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 mne-tools/mne-installers#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.

[mscheltienne]

1. Yes of course let's not rush here, the goal is to get opinions for now.
2. Also yes, let's definitely not have PyTorch set as a hard dependency, especially for only one function. When we move the code from find_bads_* to mne-icalabel, we'll set pytorch as a soft dependency for ICLabel, with a warning if it's not installed.

[larsoner]

When we move the code from find_bads_* to mne-icalabel

My proposal above is actually not to do this, but to have as much ica.label_components logic in MNE-Python as possible/reasonable. But maybe I don't understand the end goal...

I am thinking that if a user uses the new API to do ica.label_components('ecg', ...) this will be 100% equivalent to ica.find_bads_ecg(...), and thus not need any iclabel-specific stuff. In other words, it will use the ECG channel in the data to find components as it does now, and does not require any mne-iclabel to be installed.

Then if a user does ica.label_components('ecg', method='iclabel', ...) then it tries to import mne-iclabel and use it to label.

[mscheltienne]

Oh, yes we can do it this way as well. I was proposing to move all IC-labelling stuff to mne-icalabel while removing the hard-dependency for torch from mne-icalabel. This way it can become a core dependency of mne, while not needing any additional dependencies to run.

So compare to your proposal, the idea is to import mne-icalabel (same dep. as mne-python) to use ica.label_components(), and in mne-icalabel, import optional dependencies as torch (or any other extra dependency specific to this model), if needed only.

[larsoner]

I was proposing to move all IC-labelling stuff to mne-icalabel while removing the hard-dependency for torch from mne-icalabel. This way it can become a core dependency of mne, while not needing any additional dependencies to run.

I like this proposal a bit less because if a user does pip install --upgrade mne now ICA is broken for them unless they install mne-iclabel as well. I also like the idea of making the scope of mne-iclabel to do labeling using iclabel, not all forms of labeling. It seems more appropriate, especially since find_bads_ecg and such have been around for so long. Then mne-iclabel can focus on just iclabel functionality, and not have to test all the find_bads_* functions that MNE-Python currently does already.

[adam2392]

So it sounds like the only change we should do is #9846?

Is there a consensus there? What are the next steps to enable storage of "scores" within the ICA labels?

[mscheltienne]

And add the label_components and the one-line wrappers.
I'm surprised pip install --upgrade pkg doesn't install new dependencies for the updated version, but if that is the case, then yes moving the existing code and tests to mne-icalabel only brings downsides.

[larsoner]

I'm surprised pip install --upgrade pkg doesn't install new dependencies for the updated version

It would, but then we'd have to add another hard dependency.

Dependencies aside, though, I like the idea of keeping mne-iclabel's functionality focused on iclabel stuff as opposed to things like find_bads_* that MNE-Python already provides. It makes it clear that core ICA functionality lives in MNE, including label_components, and that the scope of mne-iclabel is iclabel-specific stuff.

[mscheltienne]

So, what is 'iclabel-specific'? We also want to include different models to label components, not just ICLabel. That's why I proposed to move the code from the find_bads_* to the other repo, as in the end they can be considered as simple models to label components.

But anyway, that was just an additional proposal to move some of the code from mne-python to a sub-repo. It's not that important, the core is really label_components and regrouping all labeling methods (inc. find_bads_*) in label_components, no matter where the code of find_bads_* lives.

[hoechenberger]

So, what is 'iclabel-specific'? We also want to include different models to label components, not just ICLabel. That's why I proposed to move the code from the find_bads_* to the other repo, as in the end they can be considered as simple models to label components.

Let's do it the other way around, then:
ICALabel could internally call the MNE find_bads_* methods and expose this as, say, method='mne'.

The package depends on MNE already, so all would be good, I suppose!