Adding an RSA example not based on decoding in the tutorials

[mathias-sm]

Proposed documentation enhancement

Hi everyone!

First, thanks again for the amazing tool, using mne (and its documentation) is always a pleasure and I often recommend tutorials or documentation pages as reading to other members of my lab.

I recently submitted an article which performs a relatively simple RSA analysis of MEG data using cross-validated mahalanobis. It uses rsatoolbox and ends up being relatively concise: for a single subject, it essentially boils down to the following.

e = mne.read_epochs(BIDSpath("...")).as_type("mag").pick_types(meg="mag")
data = TemporalDataset(
        e.get_data(copy=False),
        descriptors = {"subj": "sub-01"},
        obs_descriptors = {"category": e.metadata["category"], "run": e.metadata["run"]},
        channel_descriptors = {"channels": e.ch_names},
        time_descriptors = {"time": e.times})
rdm = calc_rdm_movie(data, method="crossnobis", descriptor="category", cv_descriptor="run")

# Here I would plot empirical RDMs for a few different timepoints

# Then some code to create models (~15 lines); I would plot the predictors here

# Model the empirical RDM; + refer to articles and `rsatoolbox` for choice of metric
betas = rsatoolbox.model.fitter.fit_regress(models, rdm)

# Some code to plot the output.
plt.plot(e.times, betas)

I know that such example code exists across different packages, including rsatoolbox and mne-rsa, but ultimately what I'm proposing is quite close to the data while benefiting from useful abstractions from both mne and rsatoolbox and I think it might be a useful tutorial, which would also include considerations about how to estimate the empirical RDM, how to measure similarity across RDMs, etc.

If the community thinks that this tutorial would be useful, I am happy to draft and submit a version as a PR. My dataset is public, as is my code, and so I would naturally be inclined to make the tutorial about one subject, one run of my own data. But I could also write this about another dataset if it's easier (although I think that an example with predictors that are not just categorical predictors, like audio versus visual, would make this more appealing). Resources specifically related to my work:

• https://www.biorxiv.org/content/10.1101/2024.03.13.584141v2
• https://openneuro.org/datasets/ds006012/
• https://github.com/mathias-sm/AGeometricShapeRegularityEffectHumanBrain/blob/main/MEG/02_rsa/sensor/01_compute_rdms.py
• https://github.com/mathias-sm/AGeometricShapeRegularityEffectHumanBrain/blob/main/MEG/02_rsa/sensor/02_model_rdms.py

Let me know, and thanks again to everyone behind the mne collection of softwares!

[welcome]

Hello! 👋 Thanks for opening your first issue here! ❤️ We will try to get back to you soon. 🚴

[larsoner]

Currently we have

https://mne.tools/1.8/auto_examples/decoding/decoding_rsa_sgskip.html

That doesn't get rendered because the dataset is gigantic.

How big is your dataset? If it's < 2GB, could we use it in the existing example, and then add some of the stuff you're talking about to that? The idea being, better to build on and improve / fix something that already exists rather than start from scratch if possible. I'm thinking rsatoolbox stuff could be a new section in the above example maybe.

[mathias-sm]

Thanks!

That makes a lot of sense. The raw data is about 3.5GB per participant: about 450M per run with 8 runs. I'm pretty sure that cherry picking one participant and a couple of runs (for cross-validation) could be enough to show simple effects. And I can easily be convinced to work on updating the existing example rather than starting one from scratch, although I am not sure I would want to categorize a tutorial / introduction to RSA analyses under machine learning / decoding section?

[larsoner]

The raw data is about 3.5GB per participant: about 450M per run with 8 runs. I'm pretty sure that cherry picking one participant and a couple of runs (for cross-validation) could be enough to show simple effects

Perfect. In addition to small size -- and it seems like this would land ~1GB which is fine -- we also want examples to execute with low RAM and CPU usage and as quickly as possible. So limiting runs and such usually helps with this, too. So even if the results and outputs are a little messier, as long as the message is still conveyed we write stuff like "here we only use 2 out of the 8 runs for speed" and we're good to go.

although I am not sure I would want to categorize a tutorial / introduction to RSA analyses under machine learning / decoding section?

Hmm then maybe it would make sense to leave the existing analysis where it is. Would still be nice if possible to update it to use the smaller dataset, though, since currently it's not executed or rendered which is a bummer!