Collection of 3D volume masks, indexed by integers or strings.
Voxels in a mask are represented sparsely, that is by linear indices in the [0, n-1] range, where n is the number of voxels in the volume.
A typical use case is storing voxel selection results, which can subsequently be used for running searchlights. An alternative use case is storing a set of regions-of-interest masks.
Because this class extends Mapping, it can be indexed as any other mapping (like dicts). Currently masks cannot be removed, however, and adding masks is performed through the add(...) function rather than item assignment.
In some functions the terminology ‘source’ and ‘target’ is used. A source refers to the label associated with masks (and can be used as a key in the mapping), while a target is an element from the value associated in this mapping (i.e. typically a target is a linear voxel index).
Besides storing voxel indices, each mask can also have additional
‘auxiliary’ information associated, such as distance from the center or its relative position in grey matter.
Methods
add(src, nbrs[, aux]) | Add a volume mask |
aux_get(*args, **kwargs) | DEPRECATED: use .get_aux instead |
aux_keys() | Names of auxiliary labels |
get(src) | Return the linear voxel indices of a mask |
get_aux(src, label) | Auxiliary information of a mask |
get_dataset_feature_mask(ds[, keys]) | For a dataset return a mask of features that were selected |
get_mask([keys]) | Return a mask for voxels that are included in one or more masks |
get_minimal_dataset(ds[, keys]) | For a dataset return only portion with features which were selected |
get_nifti_image_mask([keys]) | Return a NIfTI image with the voxels included in any mask |
get_targets() | Return list of voxels that are in one or more masks |
get_tuple_list(src, *labels) | Return a list of tuples with mask indices and/or aux information. |
get_tuple_list_dict(*args, **kwargs) | DEPRECATED: use .get_tuple_list instead |
get_voxel_indices([keys]) | Returns voxel indices at least once selected |
is_same_layout(other) | Check whether another instance has the same spatial layout |
items() | |
iteritems() | |
iterkeys() | |
itervalues() | |
keys() | |
merge(other) | Add masks from another instance |
source2nearest_target(source) | Find the voxel nearest to a mask center |
target2nearest_source(target[, ...]) | Find the voxel nearest to a mask center |
target2sources(nbr) | Find the indices of masks that map to a linear voxel index |
values() | |
xyz_source([ss]) | Computes the x,y,z coordinates of one or more mask centers |
xyz_target([ts]) | Compute the x,y,z coordinates of one or more voxels |
Initialize a VolumeMaskDictionary
Parameters : | vg: volgeom.VolGeom or fmri_dataset-like or str :
source: Surface.surf or numpy.ndarray or None :
meta: dict or None :
src2nbr: dict or None :
src2aux: dict or None :
|
---|
Methods
add(src, nbrs[, aux]) | Add a volume mask |
aux_get(*args, **kwargs) | DEPRECATED: use .get_aux instead |
aux_keys() | Names of auxiliary labels |
get(src) | Return the linear voxel indices of a mask |
get_aux(src, label) | Auxiliary information of a mask |
get_dataset_feature_mask(ds[, keys]) | For a dataset return a mask of features that were selected |
get_mask([keys]) | Return a mask for voxels that are included in one or more masks |
get_minimal_dataset(ds[, keys]) | For a dataset return only portion with features which were selected |
get_nifti_image_mask([keys]) | Return a NIfTI image with the voxels included in any mask |
get_targets() | Return list of voxels that are in one or more masks |
get_tuple_list(src, *labels) | Return a list of tuples with mask indices and/or aux information. |
get_tuple_list_dict(*args, **kwargs) | DEPRECATED: use .get_tuple_list instead |
get_voxel_indices([keys]) | Returns voxel indices at least once selected |
is_same_layout(other) | Check whether another instance has the same spatial layout |
items() | |
iteritems() | |
iterkeys() | |
itervalues() | |
keys() | |
merge(other) | Add masks from another instance |
source2nearest_target(source) | Find the voxel nearest to a mask center |
target2nearest_source(target[, ...]) | Find the voxel nearest to a mask center |
target2sources(nbr) | Find the indices of masks that map to a linear voxel index |
values() | |
xyz_source([ss]) | Computes the x,y,z coordinates of one or more mask centers |
xyz_target([ts]) | Compute the x,y,z coordinates of one or more voxels |
Add a volume mask
Parameters : | src: int or str :
nbrs: list of int :
aux: dict or None :
|
---|
DEPRECATED: use .get_aux instead
Names of auxiliary labels
Returns : | keys: list of str :
|
---|
Return the linear voxel indices of a mask
Parameters : | src: int :
|
---|---|
Returns : | idxs: list of int :
|
Auxiliary information of a mask
Parameters : | src: int :
label: str :
|
---|---|
Returns : | vals: list :
|
For a dataset return a mask of features that were selected at least once
Parameters : | ds: Dataset :
keys: list or None :
|
---|---|
Returns : | mask: np.ndarray (boolean) :
|
Notes
When using surface-based searchlights, a use case of this function is to get the voxels that were associated with the searchlights in a subset of all nodes on a cortical surface.
Return a mask for voxels that are included in one or more masks
Parameters : | keys: list or None :
|
---|---|
Returns : | msk: np.ndarray :
|
Notes
When using surface-based searchlights, a use case of this function is to get the voxels that were associated with the searchlights in a subset of all nodes on a cortical surface.
For a dataset return only portion with features which were selected
Parameters : | ds: Dataset :
keys: list or None :
|
---|---|
Returns : | Dataset :
|
Notes
The rationale of this function is that voxel selection can be run first (without using a mask for a dataset), then the dataset can be reduced to contain only voxels that were selected by voxel selection
Return a NIfTI image with the voxels included in any mask
Parameters : | keys: list or None :
|
---|---|
Returns : | msk: nibabel.Nifti1Image :
|
Notes
When using surface-based searchlights, a use case of this function is to get the voxels that were associated with the searchlights in a subset of all nodes on a cortical surface.
Return list of voxels that are in one or more masks
Returns : | idxs: list of int :
|
---|
Return a list of tuples with mask indices and/or aux information.
Parameters : | src: int or str :
*labels: str or None :
|
---|---|
Returns : | tuples: list of tuple :
|
DEPRECATED: use .get_tuple_list instead
Parameters : | *labels: str or None :
|
---|
Returns voxel indices at least once selected
Parameters : | keys: list or None :
|
---|---|
Returns : | voxel_indices: list of tuple :
|
Notes
When using surface-based searchlights, a use case of this function is to get the voxels that were associated with the searchlights in a subset of all nodes on a cortical surface.
Check whether another instance has the same spatial layout
Parameters : | other: VolumeMaskDictionary :
|
---|---|
Returns : | same: boolean :
|
Add masks from another instance
Parameters : | other: VolumeMaskDictionary :
|
---|
Return meta information such as number of node indices
Returns : | meta: dict or False :
|
---|
Geometric information of (the centers of) each mask.
In the case of surface-searchlights this should be a surface used as the center for searchlights.
Find the voxel nearest to a mask center
Parameters : | src: int :
|
---|---|
Returns : | target: int :
|
Find the voxel nearest to a mask center
Parameters : | target: int :
fallback_euclidean_distance: bool (default: False) :
|
---|---|
Returns : | src: int :
|
Find the indices of masks that map to a linear voxel index
Parameters : | nbr: int :
|
---|---|
Returns : | srcs: list of int :
|
Volume geometry information.
Computes the x,y,z coordinates of one or more mask centers
Parameters : | ss: list of int or None :
|
---|
Compute the x,y,z coordinates of one or more voxels
Parameters : | ts: list of int or None :
|
---|---|
Returns : | xyz: numpy.ndarray :
|