CSP rank parameter does not behave as expected

[sappelhoff]

First reported in https://mne.discourse.group/t/the-api-reference-of-csp-needs-updata/9018?u=sappelhoff

Link to CSP API docs: https://mne.tools/dev/generated/mne.decoding.CSP.html

I also believe that an error should be generated at time of instantiation of CSP, not when CSP.fit ist being called.

Have a look at rank in the MWE below 👇

# %%
# Imports
import mne
import numpy as np

# load data
sample_path = mne.datasets.sample.data_path() / "MEG" / "sample"
raw = mne.io.read_raw(sample_path / "sample_audvis_raw.fif")
events = mne.read_events(sample_path / "sample_audvis_raw-eve.fif")

# epochs of EEG
raw = raw.pick("eeg")
epochs = mne.Epochs(raw, events[np.isin(events[:, -1], [1, 2, 3, 4])])
epochs

# %%
# Works
CSP = mne.decoding.CSP(n_components=4, rank=dict(eeg=len(epochs.ch_names)))
CSP.fit(epochs.get_data(), epochs.events[:, -1])

# %%
# Works
CSP = mne.decoding.CSP(n_components=4, rank=None)
CSP.fit(epochs.get_data(), epochs.events[:, -1])

# %%
# Fails but should work according to API docs
# TypeError: rank must be an instance of dict or None, got <class 'str'> instead.
CSP = mne.decoding.CSP(n_components=4, rank="info")
CSP.fit(epochs.get_data(), epochs.events[:, -1])

# %%
# Fails but should work according to API docs
# TypeError: rank must be an instance of dict or None, got <class 'str'> instead.
CSP = mne.decoding.CSP(n_components=4, rank="full")
CSP.fit(epochs.get_data(), epochs.events[:, -1])

# %%
# Fails but with uninformative message
# TypeError: rank must be an instance of dict or None, got <class 'str'> instead.
CSP = mne.decoding.CSP(n_components=4, rank="foo")
CSP.fit(epochs.get_data(), epochs.events[:, -1])

mne sys_info 👇

Platform             Windows-11-10.0.22631-SP0
Python               3.12.4 | packaged by conda-forge | (main, Jun 17 2024, 10:04:44) [MSC v.1940 64 bit (AMD64)]
Executable           C:\Users\stefan\AppData\Local\miniforge3\envs\myenv\python.exe
CPU                  Intel64 Family 6 Model 186 Stepping 3, GenuineIntel (12 cores)
Memory               15.7 GB

Core
├☑ mne               1.7.1 (latest release)
├☑ numpy             1.26.4 (unknown linalg bindings (threadpoolctl module not found: No module named 'threadpoolctl'))
├☑ scipy             1.14.0
└☑ matplotlib        3.9.1 (backend=qtagg)

Numerical (optional)
├☑ pandas            2.2.2
└☐ unavailable       sklearn, numba, nibabel, nilearn, dipy, openmeeg, cupy, h5io, h5py

Visualization (optional)
├☑ qtpy              2.4.1 (PySide6=6.6.3)
├☑ pyqtgraph         0.13.7
├☑ mne-qt-browser    0.6.3
└☐ unavailable       pyvista, pyvistaqt, vtk, ipympl, ipywidgets, trame_client, trame_server, trame_vtk, trame_vuetify

Ecosystem (optional)
└☐ unavailable       mne-bids, mne-nirs, mne-features, mne-connectivity, mne-icalabel, mne-bids-pipeline, neo, eeglabio, edfio, mffpy, pybv

cc @tsolesc @Prarthita11

[cbrnr]

Maybe caused by #12476?

[sappelhoff]

• This has been solved by BUG: Fix bug with CSP rank="full" #12694

I will link this in discourse so that the next person running into this has a clear trail of links.