mne_rsa.rsa_nifti#

mne_rsa.rsa_nifti(image, rdm_model, spatial_radius=None, image_rdm_metric='correlation', image_rdm_params={}, rsa_metric='spearman', ignore_nan=False, y=None, labels_image=None, labels_rdm_model=None, n_folds=1, roi_mask=None, brain_mask=None, n_jobs=1, verbose=False)[source]#

Perform RSA in a searchlight pattern on Nibabel Nifti-like images.

The output is a 3D Nifti image where the data at each voxel is is the RSA, computed for a patch surrounding the voxel.

Added in version 0.4.

Parameters:

image4D Nifti-like image

The Nitfi image data. The 4th dimension must contain the images for each item.

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.

spatial_radiusfloat | None

The spatial radius of the searchlight patch in meters. All source points within this radius will belong to the searchlight patch. Defaults to None which will use a single searchlight patch.

image_rdm_metricstr

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

image_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_image and labels_rdm_model instead. For each image in the Nifti image object, a number indicating the item to which it belongs. Defaults to None, in which case labels_image is used.

labels_imagelist | None

For each image in the Nifti image object, 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 images objects 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 integers 0:image.shape[3] 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_image 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).

roi_mask3D Nifti-like image | None

When set, searchlight patches will only be generated for the subset of voxels with non-zero values in the given mask. This is useful for restricting the analysis to a region of interest (ROI). Note that while the center of the patches are all within the ROI, the patch itself may extend beyond the ROI boundaries. Defaults to None, in which case patches for all voxels are generated.

brain_mask3D Nifti-like image | None

When set, searchlight patches are restricted to only contain voxels with non-zero values in the given mask. This is useful for make sure only information from inside the brain is used. In contrast to the roi_mask, searchlight patches will not use data outside of this mask. Defaults to None, in which case all voxels are included in the analysis.

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_results3D Nifti1Image | list of 3D Nifti1Image | float | ndarray: The correlation values for each searchlight patch. When spatial_radius is set to None, the result will be a single number (not packed in an SourceEstimate object). When multiple models have been supplied, a list will be returned containing the RSA results for each model.