mne_rsa.rsa_stcs

mne_rsa.rsa_stcs(stcs, dsm_model, src, spatial_radius=0.04, temporal_radius=0.1, stc_dsm_metric='correlation', stc_dsm_params={}, rsa_metric='spearman', ignore_nan=False, y=None, n_folds=1, sel_vertices=None, tmin=None, tmax=None, n_jobs=1, verbose=False)[source]

Perform RSA in a searchlight pattern on MNE-Python source estimates.

The output is a source estimate where the “signal” at each source point is the RSA, computed for a patch surrounding the source point. Source estimate objects can be either defined along a cortical surface (SourceEstimate objects) or volumetric (VolSourceEstimate objects). For surface source estimates, distances between vertices are measured in 2D space, namely as the length of the path along the surface from one vertex to another. For volume source estimates, distances are measured in 3D space as a straight line from one voxel to another.

Parameters:
stcslist of mne.SourceEstimate | list of mne.VolSourceEstimate

For each item, a source estimate for the brain activity.

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

The model DSM, see compute_dsm(). 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 DSMs.

Use compute_dsm() to compute DSMs.

srcinstance of mne.SourceSpaces

The source space used by the source estimates specified in the stcs parameter.

spatial_radiusfloat | None

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

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

stc_dsm_metricstr

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

stc_dsm_paramsdict

Extra arguments for the distance metric used to compute the DSMs. 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 DSMs. 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

For each source estimate, a number indicating the item to which it belongs. When None, each source estimate is assumed to belong to a different item. Defaults to None.

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

sel_verticeslist of int | None

When set, searchlight patches will only be generated for the subset of vertices/voxels with the given indices. Defaults to None, in which case patches for all vertices/voxels are generated.

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.

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:
stcSourceEstimate | VolSourceEstimate | list of SourceEstimate | list of VolSourceEstimate

The correlation values for each searchlight patch. When spatial_radius is set to None, there will only be one vertex. When temporal_radius is set to None, there will only be one time point. When multiple models have been supplied, a list will be returned containing the RSA results for each model.

See also

compute_dsm