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)[source]

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

Returns