MNE-RSA#

This is a Python package for performing representational similarity analysis (RSA) using MNE-Python data structures. The main use-case is to perform RSA using a “searchlight” approach through time and/or a volumetric or surface source space.

Read more on RSA in the paper that introduced the technique:

Nikolaus Kriegeskorte, Marieke Mur and Peter Bandettini (2008). Representational similarity analysis - connecting the branches of systems neuroscience. Frontiers in Systems Neuroscience, 2(4). https://doi.org/10.3389/neuro.06.004.2008

_images/rsa.png _images/rsa_dark.png

Installation#

The package can be installed either through PIP: pip install mne-rsa

or through conda using the conda-forge channel: conda install -c conda-forge mne-rsa

Use cases#

This is what the package can do for you:

  • Compute RDMs on arbitrary data

  • Compute RDMs in a searchlight across:

    • vertices/voxels and samples (source level)

    • sensors and samples (sensor level)

    • vertices/voxels only (source level)

    • sensors only (sensor level)

    • samples only (source and sensor level)

  • Use cross-validated distance metrics when computing RDMs

  • And of course: compute RSA between RDMs

Supported metrics for comparing RDMs:

  • Spearman correlation (the default)

  • Pearson correlation

  • Kendall’s Tau-A

  • Linear regression (when comparing multiple RDMs at once)

  • Partial correlation (when comparing multiple RDMs at once)

Example usage#

Basic example of performing RSA on the EEG “kiloword” data using a sliding window across time:

import mne
import mne_rsa
data_path = mne.datasets.kiloword.data_path(verbose=True)
epochs = mne.read_epochs(data_path / "kword_metadata-epo.fif")
# Create model RDMs based on each stimulus property
columns = epochs.metadata.columns[1:]  # Skip the first column: WORD
model_rdms = [mne_rsa.compute_rdm(epochs.metadata[col], metric="euclidean") for col in columns]
# Perform RSA in a sliding window across time
rsa_results = mne_rsa.rsa_epochs(epochs, model_rdms, temporal_radius=0.01)
# Plot the result
mne.viz.plot_compare_evokeds({column: result for column, result in zip(columns, rsa_results)},
                             picks="rsa", legend="lower center", title="RSA result")
_images/rsa_result.png _images/rsa_result_dark.png

Documentation#

For a detailed guide on how RSA is performed using MNE-RSA, see the Tutorials.

For quick guides on how to do specific things, see the Examples.

Finally, there is the API reference documentation.

Integration with other packages#

The main use-case for this package to perform RSA analysis on EEG and MEG data. Hence, integration functions with MNE-Python are provided. There is also some integration with nipy for fMRI that should do well in a nilearn setup.

Performance#

This package aims to be fast and memory efficient. An important design feature is that under the hood, everything operates on generators. The searchlight routines produce a generator of RDMs which are consumed by a generator of RSA values. Parallel processing is also supported, so you can use all of your CPU cores.

Support#

This free software comes without any form of official support. However, if you think you have encountered a bug or have a particularly great idea for improvements, please open an issue on Github. For questions and help with your analysis, you are welcome to post on the MNE forum.

Contributing#

Development of the package happens on Github. Everyone is welcome to raise issues or contribute pull requests.

Here is how to install the additional required packages for developing MNE-RSA and set up the package in development mode:

git clone git@github.com:mne-tools/mne-rsa.git
cd mne-rsa
pip install -r requirements-dev.txt
pip install -e .

To run the test suite, execute pytest in the main mne-rsa folder. To build the documentation, execute make html in the mne-rsa/doc folder (or on Windows: sphinx-build . _build/html).

Citation#

If you end up using this package for the data analysis that is part of a scientific article, please cite:

Marijn van Vliet, Takao Shimizu, Stefan Appelhoff, Yuan-Fang Zhao, & Richard Höchenberger. (2024). mne-tools/mne-rsa: Version 0.9.1 (0.9.1). Zenodo. https://doi.org/10.5281/zenodo.11258133