mne_rsa.rsa_array#

mne_rsa.rsa_array(X, rdm_model, patches=None, data_rdm_metric='correlation', data_rdm_params={}, rsa_metric='spearman', ignore_nan=False, y=None, n_folds=1, n_jobs=1, verbose=False)[source]#

Perform RSA on an array of data, possibly in a searchlight pattern.

Parameters:
Xndarray, shape (n_items, n_series, n_times)

An array containing the data.

rdm_modelndarray, shape (n, n) | (n * (n - 1) // 2,) | list of ndarray

The model RDM, see compute_rdm(). For efficiency, you can give it in condensed form, meaning only the upper triangle of the matrix as a vector. See scipy.spatial.distance.squareform(). To perform RSA against multiple models at the same time, supply a list of model RDMs.

Use compute_rdm() to compute RDMs.

patchesgenerator of tuples | None

Searchlight patches as generated by searchlight. If None, no searchlight is used. Defaults to None.

data_rdm_metricstr

The metric to use to compute the data RDMs. This can be any metric supported by the scipy.distance.pdist function. Defaults to ‘correlation’.

data_rdm_paramsdict

Extra arguments for the distance metric used to compute the RDMs. Refer to scipy.spatial.distance for a list of all other metrics and their arguments. Defaults to an empty dictionary.

rsa_metricstr

The RSA metric to use to compare the RDMs. Valid options are:

  • ‘spearman’ for Spearman’s correlation (the default)

  • ‘pearson’ for Pearson’s correlation

  • ‘kendall-tau-a’ for Kendall’s Tau (alpha variant)

  • ‘partial’ for partial Pearson correlations

  • ‘partial-spearman’ for partial Spearman correlations

  • ‘regression’ for linear regression weights

Defaults to ‘spearman’.

ignore_nanbool

Whether to treat NaN’s as missing values and ignore them when computing the distance metric. Defaults to False.

New in version 0.8.

yndarray of int, shape (n_items,) | None

(Deprecated) For each item, a number indicating the class to which the item belongs. When None, each item is assumed to belong to a different class. Defaults to None.

labels_rdm_model: list | None

For each row in rdm_model, a label that identifies the item to which it corresponds. This is used in combination with labels_X to align the data and model RDMs before comparing them. Each row should have a unique label. Labels may be of any python type that can be compared with == (int, float, string, tuple, etc). By default (None), the integers 0:n_rows are used as labels.

New in version 0.10.

labels_Xlist | None

For each element in X (=the first dimension), a label that identifies the item to which it corresponds. This is used in combination with labels_rdm_model to align the data and model RDMs before comparing them. Multiple elements in X may correspond to the same item, in which case they should have the same label and will be averaged when computing the data RDM. Labels may be of any python type that can be compared with == (int, float, string, tuple, etc). By default (None), the integers 0:len(X) are used as labels.

New in version 0.10.

n_foldsint | sklearn.model_selection.BaseCrollValidator | None

Number of cross-validation folds to use when computing the distance metric. Folds are created based on the y parameter. Specify None to use the maximum number of folds possible, given the data. Alternatively, you can pass a Scikit-Learn cross validator object (e.g. sklearn.model_selection.KFold) to assert fine-grained control over how folds are created. Defaults to 1 (no cross-validation).

n_jobsint

The number of processes (=number of CPU cores) to use. Specify -1 to use all available cores. Defaults to 1.

verbosebool

Whether to display a progress bar. In order for this to work, you need the tqdm python module installed. Defaults to False.

Returns:
rsa_valsndarray, shape ([n_series,] [n_times,] [n_model_rdms])

The RSA value for each searchlight patch. When spatial_radius is set to None, there will only be no n_series dimension. When temporal_radius is set to None, there will be no time dimension. When multiple models have been supplied, the last dimension will contain RSA results for each model.