cortex.utils.get_roi_masks

cortex.utils.get_roi_masks(subject, xfmname, roi_list=None, gm_sampler='cortical', split_lr=False, allow_overlap=False, fail_for_missing_rois=True, exclude_empty_rois=False, threshold=None, return_dict=True, overlay_file=None)

Return a dictionary of roi masks

This function returns a single 3D array with a separate numerical index for each ROI,

Parameters:

subjectstring

pycortex subject ID

xfmnamestring

pycortex transformation name

roi_listlist or None

List of names of ROIs to retrieve (e.g. [‘FFA’,’OFA’,’EBA’]). Names should match the ROI layers in the overlays.svg file for the subject specified. If None is provided (default), all available ROIs for the subject are returned. If ‘Cortex’ is included in roi_list*, a mask of all cortical voxels NOT included in other requested rois is included in the output. * works for gm_sampler = ‘cortical’, ‘think’, ‘thick’, or (any scalar value); does not work for mapper-based gray matter samplers.

gm_samplerscalar or string

How to sample the cortical gray matter. Options are: <an integer> - Distance from fiducial surface to define ROI. Reasonable values

for this input range from 1-3.

The following will only work if you have used Freesurfer to define the subject’s surface, and so have separate pial and white matter surfaces: ‘cortical’ - selection of all voxels with centers within the cortical ribbon

(directly computed from distance of each voxel from fiducial surface)

‘thick’ - selection of voxels within ‘thick’ mask (see cortex.get_mask()) ‘thin’ - selection of voxels within ‘thin’ mask (see cortex.get_mask()) ‘cortical-liberal’ - selection of all voxels that have any part within the

cortical ribbon (‘line_nearest’ mapper)

‘cortical-conservative’ - selection of only the closest voxel to each surface

vertex (‘nearest’ mapper)

mapper-based gm_samplers will return floating point values from 0-1 for each voxel (reflecting the fraction of that voxel inside the ROI) unless a threshold is provided.

thresholdfloat [0-1]

value used to convert probabilistic ROI values to a boolean mask for the ROI.

split_lrbool

Whether to separate ROIs in to left and right hemispheres (e.g., ‘V1’ becomes ‘V1_L’ and ‘V1_R’)

allow_overlapbool

Whether to allow ROIs to include voxels in other ROIs (default:False). This should only be relevant if (a) spline shapes defining ROIs in overlays.svg overlap at all, or (b) a low threshold is set for a mapper-based gm_sampler

fail_for_missing_roisbool

Whether to fail if one or more of the rois specified in roi_list are not defined in the overlays.svg file

exclude_empty_roisbool

Whether to fail if an ROI that is present in the overlays.svg file contains no voxels due to the scan not targeting that region of the brain.

return_dictbool

If True (default), function returns a dictionary of ROI masks; if False, a volume with integer indices for each ROI (similar to Freesurfer’s aseg masks) and a dictionary of how the indices map to ROI names are returned.

overlay_filestr or None

If None, use the default overlays.svg file. Otherwise, use the passed overlay file to look for the ROIs.

Returns:

roi_masksdict

Dictionary of arrays; keys are ROI names, values are roi masks.

• OR -

index_volume, index_labelsarray, dict

index_volume is a 3D array with a separate numerical index value for each ROI. Index values in the left hemisphere are negative. (For example, if V1 in the right hemisphere is 1, then V1 in the left hemisphere will be -1). index_labels is a dict that maps roi names to index values (e.g. {‘V1’: 1}).

Notes

Some gm_samplers may fail if you have very high-resolution data (i.e., with voxels on the order of the spacing between vertices in your cortical mesh). In such cases, there may be voxels in the middle of your ROI that are not assigned to the ROI (because no vertex falls within that voxel). For such cases, it is recommended to use ‘cortical’, ‘thick’, or ‘thin’ as your gm_sampler.