mne_rsa.rsa_epochs#

mne_rsa.rsa_epochs(epochs, rdm_model, noise_cov=None, spatial_radius=None, temporal_radius=None, epochs_rdm_metric='correlation', epochs_rdm_params={}, rsa_metric='spearman', ignore_nan=False, y=None, labels_epochs=None, labels_rdm_model=None, n_folds=1, picks=None, tmin=None, tmax=None, dropped_as_nan=False, n_jobs=1, verbose=False)[source]#

Perform RSA in a searchlight pattern on epochs.

The output is an Evoked object where the “signal” at each sensor is the RSA, computed using all surrounding sensors.

Parameters:

epochsinstance of mne.Epochs

The brain activity during the epochs. The event codes are used to distinguish between items.

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.

noise_covmne.Covariance | None

When specified, the data will by normalized using the noise covariance. This is recommended in all cases, but a hard requirement when the data contains sensors of different types. Defaults to None.

spatial_radiusfloats | None

The spatial radius of the searchlight patch in meters. All sensors within this radius will belong to the searchlight patch. Set to None to only perform the searchlight over time, flattening across sensors. Defaults to None.

temporal_radiusfloat | None

The temporal radius of the searchlight patch in seconds. Set to None to only perform the searchlight over sensors, flattening across time. Defaults to None.

epochs_rdm_metricstr

The metric to use to compute the RDM for the epochs. This can be any metric supported by the scipy.distance.pdist function. See also the epochs_rdm_params parameter to specify and additional parameter for the distance function. Defaults to ‘correlation’.

epochs_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.

Added in version 0.8.

yndarray of int, shape (n_items,) | None

Deprecated, use labels_epochs and labels_rdm_model instead. For each epoch, a number indicating the item to which it belongs. Defaults to None, in which case labels_epochs is used.

labels_epochslist | None

For each epoch, 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 epochs may correspond to the same item, in which case they should have the same label and will either be averaged when computing the data RDM (n_folds=1) or used for cross-validation (n_folds>1). Labels may be of any python type that can be compared with == (int, float, string, tuple, etc). By default (None), the epoch event codes are used as labels.

Added in version 0.10.

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_epochs 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.

Added 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).

picksstr | list | slice | None

Channels to include. Slices and lists of integers will be interpreted as channel indices. In lists, channel type strings (e.g., ['meg', 'eeg']) will pick channels of those types, channel name strings (e.g., ['MEG0111', 'MEG2623'] will pick the given channels. Can also be the string values “all” to pick all channels, or “data” to pick data channels. None (default) will pick all MEG and EEG channels, excluding those marked as “bad”.

tminfloat | None

When set, searchlight patches will only be generated from subsequent time points starting from this time point. This value is given in seconds. Defaults to None, in which case patches are generated starting from the first time point.

tmaxfloat | None

When set, searchlight patches will only be generated up to and including this time point. This value is given in seconds. Defaults to None, in which case patches are generated up to and including the last time point.

dropped_as_nanbool

When this is set to True, the drop log will be used to inject NaN values in the RDMs at the locations where a bad epoch was dropped. This is useful to ensure the dimensions of the RDM are the same, regardless of any bad epochs that were dropped. Make sure to use ignore_nan=True when using RDMs with NaNs in them during subsequent RSA computations. Defaults to False.

Added in version 0.8.

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:

rsaEvoked | list of Evoked | float | ndarray: The correlation values for each searchlight patch. When spatial_radius is set to None, there will only be one virtual sensor. When temporal_radius is set to None, there will only be one time point. When both spatial_radius and temporal_radius are set to None, the result will be a single number (not packed in an Evoked object). When multiple models have been supplied, a list will be returned containing the RSA results for each model.