mne_rsa.rsa_stcs#
- mne_rsa.rsa_stcs(stcs, rdm_model, src=None, spatial_radius=None, temporal_radius=None, stc_rdm_metric='correlation', stc_rdm_params={}, rsa_metric='spearman', ignore_nan=False, y=None, labels_stcs=None, labels_rdm_model=None, n_folds=1, sel_vertices=None, sel_vertices_by_index=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.
- 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. Seescipy.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.- srcinstance of mne.SourceSpaces | None
The source space used by the source estimates specified in the
stcs
parameter. Only needed whenspatial_radius
is used to create spatial searchlight patches. Defaults to None.- spatial_radiusfloat | None
The spatial radius of the searchlight patch in meters. All source points within this radius will belong to the searchlight patch. When this is set,
src
also must be set to the correct source space. 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.
- stc_rdm_metricstr
The metric to use to compute the RDM for the source estimates. This can be any metric supported by the scipy.distance.pdist function. See also the
stc_rdm_params
parameter to specify and additional parameter for the distance function. Defaults to ‘correlation’.- stc_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_stcs
andlabels_rdm_model
instead. For each source estimate, a number indicating the item to which it belongs. Defaults toNone
, in which caselabels_stcs
is used.- labels_stcslist | None
For each source estimate, 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 source estimates 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 integers0:len(evokeds)
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 withlabels_stcs
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 integers0: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. SpecifyNone
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_verticesmne.Label | list of mne.Label | list of ndarray | None
When set, searchlight patches will only be generated for the subset of ROI labels, or vertices/voxels with the given vertex numbers. When giving vertex numbers, supply a list of numpy arrays with for each hemisphere, the selected vertex numbers. For volume source spaces, supple a list with only a single element, with that element being the ndarray with vertex numbers. See also
sel_vertices_by_index
for an alternative manner of selecting vertices.- sel_vertices_by_indexndarray of int, shape (n_vertices,)
When set, searchlight patches will only be generated for the subset of vertices with the given indices in the
stc.data
array. See alsosel_vertices
for an alternative manner of selecting vertices.- 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 | float | ndarray
The correlation values for each searchlight patch. When spatial_radius 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 SourceEstimate object). When multiple models have been supplied, an array will be returned containing the RSA results for each model.
See also