RSA#

class mvpy.estimators.RSA(grouped: bool = False, estimator: ~typing.Callable = <function euclidean>, n_jobs: int | None = None, verbose: bool = False)[source]#

Implements representational similarity analysis.

Representational similarity analysis computes the geometry of input data \(X\) in their feature space. For example, given input data \(X\) of shape (n_trials, n_channels, n_timepoints), it would compute representational (dis-)similarity matrices of shape (n_trials, n_trials, n_timepoints) through some (dis-)similarity function \(f\).

Generally, performing this over representations of different systems allows drawing second-order comparisons about shared properties of those systems. This is typically done by computing multiple (dis-)similarity matrices from neural and simulated data before comparing the two using, for example, spearmanr() to obtain a measure of how similar some hypothetical simulated system is to the observed neural geometry.

For more information on representational similarity analysis, please see [1] [2].

Parameters:

groupedbool, default=False: Whether to use a grouped RSA (this is required for cross-validated metrics to make sense, irrelevant otherwise).
estimatorCallable, default=mvpy.math.euclidean: The estimator/metric to use for RDM computation.
n_jobsint, default=None: Number of jobs to run in parallel (default = None).
verbosebool, default=False: Whether to print progress information.

Attributes:

rdm_np.ndarray | torch.Tensor: The upper triangle of the representational (dis-)similarity matrix of shape (n_triu_indices[, ...]).
cx_np.ndarray | torch.Tensor: The upper triangular indices of the RDM.
cy_np.ndarray | torch.Tensor: The upper triangular indices of the RDM.
groupedbool: Whether the RSA is grouped.
estimatorCallable: The estimator/metric to use for RDM computation.
n_jobsint: Number of jobs to run in parallel.
verbosebool, default=False: Whether to print progress information.

See also

mvpy.math.cosine, mvpy.math.cosine_d, mvpy.math.cv_euclidean, mvpy.math.cv_mahalanobis, mvpy.math.euclidean, mvpy.math.mahalanobis, mvpy.math.pearsonr, mvpy.math.pearsonr_d, mvpy.math.spearmanr, mvpy.math.spearmanr_d: Available (dis-)similarity functions.

Notes

Computing (dis-)similarity across input data \(X\) may be inherently biassed. For example, distance metrics like euclidean() or mahalanobis() may never truly be zero given the noise inherent to neural responses. Consequently, cross-validation can be applied to compute unbiassed estimators through mvpy.math.cv_euclidean() or mvpy.math.cv_mahalanobis(). To do this, make sure to collect many trials per condition and structure your data \(X\) as (n_trials, n_groups, n_channels, n_timepoints) while setting grouped True.

For more information on cross-validation, please see [3].

References

[1]

Kriegeskorte, N. (2008). Representational similarity analaysis - connecting the branches of systems neuroscience. Frontiers in Systems Neuroscience. 10.3389/neuro.06.004.2008

[2]

Diedrichsen, J., & Kriegeskorte, N. (2017). Representational models: A common framework for understanding encoding, pattern-component, and representational similarity analysis. PLOS Computational Biology, 13, e1005508. 10.1371/journal.pcbi.1005508

[3]

Diedrichsen, J., Provost, S., & Zareamoghaddam, H. (2016). On the distribution of cross-validated mahalanobis distances. arXiv. 10.48550/arXiv.1607.01371

Examples

Let’s assume we have some data with 100 trials and 5 groups, recording 10 channels over 50 time points:

>>> import torch
>>> from mvpy.math import euclidean, cv_euclidean
>>> from mvpy.estimators import RSA
>>> X = torch.normal(0, 1, (100, 5, 10, 50))
>>> rsa = RSA(estimator = euclidean)
>>> rsa.transform(X).shape
torch.Size([4950, 5, 50])

If we want to compute a cross-validated RSA over the groups instead, we can use:

>>> rsa = RSA(grouped = True, estimator = cv_euclidean)
>>> rsa.transform(X).shape
torch.Size([10, 50])

Finally, if we want to plot the full RDM, we can do:

>>> rdm = torch.zeros((5, 5, 50))
>>> rdm[rsa.cx_, rsa.cy_] = rsa.rdm_
>>> import matplotlib.pyplot as plt
>>> plt.imshow(rdm[...,0], cmap = 'RdBu_r')

clone()[source]#

Clone this class.

Returns:

rsamvpy.estimators.RSA: A clone of this class.

fit(X: ndarray | Tensor, *args: Any) → RSA[source]#

Fit the estimator.

Parameters:

Xnp.ndarray | torch.Tensor: The data to compute the RDM for of shape (n_trials[, n_groups], n_channels, n_timepoints).
argsAny: Additional arguments

Returns:

rsamvpy.estimators.RSA: Fitted RSA estimator.

fit_transform(X: ndarray | Tensor, *args: Any) → ndarray | Tensor[source]#

Fit the estimator and transform data into representational similarity.

Parameters:

Xnp.ndarray | torch.Tensor: The data to compute the RDM for of shape (n_trials[, n_groups], n_channels, n_timepoints).
argsAny: Additional arguments

Returns:

rdmnp.ndarray | torch.Tensor: The representational similarity matrix of shape (n_trials, n_trials, n_timepoints) or (n_groups, n_groups, n_timepoints).

full_rdm() → ndarray | Tensor[source]#

Obtain the full representational similartiy matrix.

Returns:

rdmnp.ndarray | torch.Tensor: The representational similarity matrix of shape (n_trials, n_trials, n_timepoints) or (n_groups, n_groups, n_timepoints).

to_numpy()[source]#

Make this estimator use the numpy backend. Note that this method does not support conversion between types.

Returns:

rsasklearn.base.BaseEstimator: The estimator.

to_torch()[source]#

Make this estimator use the torch backend. Note that this method does not support conversion between types.

Returns:

rsasklearn.base.BaseEstimator: The estimator.

transform(X: ndarray | Tensor, *args: Any) → ndarray | Tensor[source]#

Transform the data into representational similarity.

Parameters:

Xnp.ndarray | torch.Tensor: The data to compute the RDM for of shape (n_trials[, n_groups], n_channels, n_timepoints).
argsAny: Additional arguments

Returns:

rdmnp.ndarray | torch.Tensor: The representational similarity matrix of shape (n_trials, n_trials, n_timepoints) or (n_groups, n_groups, n_timepoints).

RSA#

This Page