DOCSEARCHbyAlgolia
Submit Docs

rsatoolbox: Representational Similarity Analysis in Python

repository·main·Indexed 42 days ago

https://github.com/rsagroup/rsatoolbox

A Python library for Representational Similarity Analysis (RSA) 3.0, used to compare representational structures in neural or behavioral data. It provides tools for creating Dataset and RDMs objects, calculating Representational Dissimilarity Matrices, and performing model inference using fixed, selection, and weighted models. The toolbox includes specialized bootstrapping methods (eval_bootstrap, eval_dual_bootstrap) for uncertainty estimation and cross-validation for flexible models, as well as utilities for loading fMRIprep runs and creating GLM design matrices.

Tokens
31.8K
Snippets
105
Records
129
Agent score
53%

What's inside rsatoolbox

  1. Overview of the rsatoolbox.rdm package

    main

    The rsatoolbox.rdm package provides tools for Representational Dissimilarity Matrix (RDM) computations and manipulations. It is organized into several specialized submodules for different stages of the RDM workflow, including calculation, transformation, and comparison.

    Key submodules include:

    • rsatoolbox.rdm.calc: Core RDM calculation functions.
    • rsatoolbox.rdm.calc_unbalanced: RDM calculations specifically for unbalanced designs.
    • rsatoolbox.rdm.combine: Tools for combining multiple RDMs.
    • rsatoolbox.rdm.compare: Methods for comparing different RDMs.
    • rsatoolbox.rdm.rdms: Utilities for handling RDM objects.
    • rsatoolbox.rdm.transform: Functions to transform existing RDMs.
    • rsatoolbox.rdm.pairs: Utilities for working with pairs of stimuli/conditions.

  2. Explore the rsatoolbox.util submodules

    main

    The rsatoolbox.util package provides a collection of utility modules designed to support Representational Similarity Analysis (RSA) workflows. Depending on your task, you should use one of the following specialized submodules:

    • rsatoolbox.util.data_utils: Data manipulation and preparation.
    • rsatoolbox.util.descriptor_utils: Utilities for handling descriptors.
    • rsatoolbox.util.file_io: File input/output operations.
    • rsatoolbox.util.inference_util: Tools for statistical inference.
    • rsatoolbox.util.matrix: Matrix-related operations.
    • rsatoolbox.util.pooling: Pooling operations.
    • rsatoolbox.util.rdm_utils: Utilities specifically for Representational Dissimilarity Matrices (RDMs).
    • rsatoolbox.util.searchlight: Tools for searchlight analysis.
    • rsatoolbox.util.weighted_mds: Utilities for Weighted Multidimensional Scaling.

  3. Use `rsatoolbox.data.TemporalDataset` for time-series data

    main

    For data containing a temporal dimension (e.g., EEG timecourses), use the rsatoolbox.data.TemporalDataset class. This is a subclass of Dataset.

    Data Shape

    The measurements array must have the shape (n_observations, n_channels, n_timepoints).

    Temporal Descriptors

    In addition to channel_descriptors and obs_descriptors, you must provide time_descriptors to define the temporal dimension (e.g., a time vector).

    Temporal Manipulation

    TemporalDataset includes additional methods for handling the time dimension:

    • split_time: Split the data along the time axis.
    • subset_time: Select a subset of timepoints.
    • bin_time: Bin the temporal data.
    • convert_to_dataset: Convert the temporal dataset into a standard Dataset (collapsing the time dimension).
    import numpy, rsatoolbox

channel_names = ['Oz', 'O1', 'O2', 'PO3', 'PO4', 'POz']
stimulus = [0, 1, 2, 3, 4, 0, 1, 2, 3, 4]
sampling_rate = 30
t = numpy.arange(-.5, 1.5, 1/sampling_rate)

n_observations = len(stimulus)
n_channels = len(channel_names)
n_timepoints = len(t)

measurements = numpy.random.randn(n_observations, n_channels, n_timepoints)

data = rsatoolbox.data.TemporalDataset(
    measurements,
    channel_descriptors={'names': channel_names},
    obs_descriptors={'stimulus': stimulus},
    time_descriptors={'time': t}
)

  4. Define and use models in rsatoolbox

    main

    To perform Representational Similarity Analysis (RSA), you must define models using classes found in rsatoolbox.model. Every model type must implement three core functions:

    1. predict(theta): Returns the model's prediction as a vectorized numpy array for efficient computation.
    2. predict_rdm(theta): Returns the model's prediction as an RDMs object.
    3. fit(data_rdms): Estimates the parameter vector theta based on provided data RDMs.

    Note that predict and predict_rdm take a parameter vector theta as input. For fixed models, theta is ignored. For flexible models (weighted, selection, interpolation), fit is used to determine the optimal theta.

    import rsatoolbox
# Models are typically initialized with a name and an RDMs object
model = rsatoolbox.model.ModelFixed('name', rdm_object)

  5. Calculate Crossnobis dissimilarity

    main

    The crossnobis dissimilarity is an unbiased estimator of the squared Mahalanobis distance. It is calculated by multiplying pattern estimates across different runs (cross-validation) rather than within a single run.

    Key Advantages:

    • Unbiased: If the true distance is zero, the estimated distance will average to zero. It can even produce negative values if the patterns differ only by noise.
    • Robust to noise variance: It removes biases caused by unequal noise across conditions (e.g., different trial counts) or correlated noise within a single imaging run.
    • Statistical testing: Because it has a meaningful zero point, you can perform t-tests against zero to determine if reliable information exists in a single step.

  6. Estimate uncertainty using bootstrapping

    main

    Bootstrapping is used to estimate variance when you want to generalize to new conditions or when using fitted models. There are three main bootstrapping methods in rsatoolbox.inference:

    1. Generalization over conditions: eval_bootstrap_pattern

    Estimates uncertainty by resampling conditions. Use this when you want to generalize to the population of conditions for the exact subjects measured.

    • N: Number of bootstrap samples.
    • pattern_descriptor (optional): Groups patterns together. If a name is passed, patterns with equal entries are included/excluded together.
    • boot_noise_ceil: Boolean. If True, bootstraps the noise ceiling (more accurate but slower).

    2. Generalization over both subjects and conditions: dual_bootstrap

    Uses a 2D bootstrap method to evaluate variances under simultaneous and separate resampling of subjects and conditions.

    • rdm_descriptor: Allows sampling RDMs together (similar to pattern_descriptor).
    • k_pattern and k_rdm: Control cross-validation folds along the two dimensions. Set to None for defaults, or 1 to turn off cross-validation.

    3. Generalization over subjects: eval_bootstrap_rdm

    Estimates variance caused by random sampling of subjects. Note: This is expected to yield similar results to eval_fixed, so it is generally not recommended for that specific purpose.

  7. How to choose an RDM comparison measure

    main

    Choosing a similarity measure depends on the relationship you want to capture between model RDMs and reference RDMs:

    1. Strict Distance: The most stringent approach is to compute a direct distance, but this is often difficult due to varying signal-to-noise ratios.
    2. Scaling Invariance: Use Cosine Similarity if you want to allow for an overall scaling of the RDMs.
    3. Mean Invariance: Use Pearson Correlation if you want to drop the assumption that a predicted difference of 0 corresponds to a measured dissimilarity of 0 (i.e., removing the average dissimilarity).
    4. Covariance Awareness: Use Whitened measures ('corr_cov' or 'cosine_cov') to account for the correlations between different entries in the RDM caused by shared measurements.
    5. Non-linear Relationships: Use rank correlations like Kendall's tau ('tau-a') or Spearman's rho ('rho-a') to drop the assumption of a linear relationship.

    Recommendation: For rank correlations, rho-a (Spearman's $\rho_a$) is generally preferred over standard Spearman's $\rho$ because it avoids bias from tied ranks and is computationally more efficient.

  8. Typical RSA toolbox workflow

    main

    A standard Representational Similarity Analysis (RSA) workflow in rsatoolbox follows these sequential steps:

    1. Data Extraction: Load or prepare your data into a rsatoolbox.data.Dataset object.
    2. RDM Calculation: Use rsatoolbox.rdm.calc to calculate a Representational Dissimilarity Matrix (RDM) from the dataset using various dissimilarity measures.
    3. Model Definition: Define RSA models using objects from the rsatoolbox.model class.
    4. Inference: Fit models to the RDMs and evaluate them using the rsatoolbox.inference.evaluate module. The evaluation results are stored in a rsatoolbox.inference.results object.
    5. Visualization: Use the rsatoolbox.vis subpackage to visualize datasets, RDMs, models, and inference results.
    6. Simulation (Optional): Use rsatoolbox.sim.simulation to generate artificial datasets for testing or benchmarking.

  10. Perform cross-validation for flexible models

    main

    When evaluating models with flexible parameters, use cross-validation to control for model complexity and prevent overfitting. This process is split into two steps: choosing the folds and performing the cross-validation.

    1. Choose the folds

    Use functions in rsatoolbox.inference.sets to create training and test sets. Common types include:

    • leave_one_out: Each individual observation is used as a fold.
    • k_fold: Sets a specific number of folds of roughly equal size.
    • of_k: Assigns a specific number of observations to each fold.

    2. Perform cross-validation

    Use rsatoolbox.inference.crossval to execute the evaluation.

    Parameters:

    • models: List of models.
    • rdms_data: The data RDMs.
    • train_set, test_set, ceil_set: The sets generated in step 1.
    • method: The RDM similarity measure (e.g., 'corr').
    # Example: Leave-one-out cross-validation
train_set, test_set, ceil_set = rsatoolbox.inference.sets_leave_one_out_rdm(rdms_data)
results_cv = rsatoolbox.inference.crossval(
    models, 
    rdms_data, 
    train_set, 
    test_set, 
    ceil_set=ceil_set, 
    method='corr'
)

  12. Build and check the documentation

    main

    To build the project documentation locally, ensure you have pandoc installed on your system. Follow these steps:

    1. Install the documentation requirements: pip install docs/requirements.txt
    2. Navigate to the documentation directory: cd docs/
    3. Build the HTML documentation: make html

    If you are adding, removing, or renaming a module, you must create or adapt a stub for autodoc to ensure the documentation remains accurate.

    pip install docs/requirements.txt
cd docs/
make html