mvpa2.misc.surfing.volume_mask_dict.VolumeMaskDictionary¶

class
mvpa2.misc.surfing.volume_mask_dict.
VolumeMaskDictionary
(vg, source, meta=None, src2nbr=None, src2aux=None)¶ 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, n1] 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 regionsofinterest 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_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_voxel_indices
([keys])Returns voxel indices at least once selected is_same_layout
(other)Check whether another instance has the same spatial layout 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 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_datasetlike or str :
data structure that contains volume geometry information.
source: Surface.surf or numpy.ndarray or None :
structure that contains the geometric information of (the centers of) each mask. In the case of surfacesearchlights this should be a surface used as the center for searchlights.
meta: dict or None :
Optional meta data stored with this instance (such as searchlight radius and volumetric information). A use case is storing an instance and loading it later, and then checking whether the meta information is correct when it used to run a searchlight analysis.
src2nbr: dict or None :
In a typical use case it contains a mapping from node center indices to lists of voxel indices.
src2aux: dict or None :
In a typical use case it can contain auxiliary information such as distance of each voxel to each center.
Methods
add
(src, nbrs[, aux])Add a volume mask 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_voxel_indices
([keys])Returns voxel indices at least once selected is_same_layout
(other)Check whether another instance has the same spatial layout 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 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
(src, nbrs, aux=None)¶ Add a volume mask
Parameters: src: int or str :
index or name of volume mask. src should not be already present in this dictionary
nbrs: list of int :
linear voxel indices of the voxels in the mask
aux: dict or None :
auxiliary properties associated with (the voxels in) the volume mask. If the current dictionary instance alraedy has stored auxiliary properties for other masks, then the set of keys in the current mask should be the same as for other masks. In addition, the length of each value in aux should be either the number of elements in nbrs or one.

aux_get
(*args, **kwargs)¶ DEPRECATED: use .get_aux instead

aux_keys
()¶ Names of auxiliary labels
Returns: keys: list of str :
Names of auxiliary labels that are supported by get_aux

get
(src)¶ Return the linear voxel indices of a mask
Parameters: src: int :
index of mask
Returns: idxs: list of int :
linear voxel indices indexed by src

get_aux
(src, label)¶ Auxiliary information of a mask
Parameters: src: int :
index of mask
label: str :
label of auxiliary information
Returns: vals: list :
auxiliary information labelled label for mask src

get_dataset_feature_mask
(ds, keys=None)¶ For a dataset return a mask of features that were selected at least once
Parameters: ds: Dataset :
A dataset with field .fa.voxel_indices
keys: list or None :
Indices of center ids for which the associated masks must be used. If None, all keys are used.
Returns: mask: np.ndarray (boolean) :
binary mask with ds.nfeatures values, with True for features that were selected at least once once since the initalization of this class. That is, for a voxel (feature) with feature index i it holds that mask[I] is True iff there is at least one key k so that i in self.get(k).
Notes
When using surfacebased 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.

get_mask
(keys=None)¶ Return a mask for voxels that are included in one or more masks
Parameters: keys: list or None :
Indices of center ids for which the associated masks must be used. If None, all keys are used.
Returns: msk: np.ndarray :
Threedimensional array with True for voxels that are included in one or more masks, and False elsewhere
Notes
When using surfacebased 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.

get_minimal_dataset
(ds, keys=None)¶ For a dataset return only portion with features which were selected
Parameters: ds: Dataset :
A dataset with field .fa.voxel_indices
keys: list or None :
Indices of center ids for which the associated masks must be used. If None, all keys are used.
Returns: Dataset :
A dataset containing features that were selected at least once
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

get_nifti_image_mask
(keys=None)¶ Return a NIfTI image with the voxels included in any mask
Parameters: keys: list or None :
Indices of center ids for which the associated masks must be used. If None, all keys are used.
Returns: msk: nibabel.Nifti1Image :
Nifti image where voxels have the value 1 for voxels that are included in one or more masks, and 0 elsewhere
Notes
When using surfacebased 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.

get_targets
()¶ Return list of voxels that are in one or more masks
Returns: idxs: list of int :
Linear indices of voxels in one or more masks

get_tuple_list
(src, *labels)¶ Return a list of tuples with mask indices and/or aux information.
Parameters: src: int or str :
index of mask
*labels: str or None :
List of labels to return. None refers to the voxel indices of the mask.
Returns: tuples: list of tuple :
N tuples each with len(labels) values, where N is the number of voxels in the mask indexed by src

get_tuple_list_dict
(*args, **kwargs)¶ DEPRECATED: use .get_tuple_list instead
 Return a dictionary of mapping that maps each mask index
 to tuples with mask indices and/or auxiliary information.
Parameters: *labels: str or None :
List of labels to return. None refers to the voxel indices of the mask.
 tuple_dict: dict
a mapping so that get_tuple_list(s, labels)==get_tuple_list_dict(labels)[s]

get_voxel_indices
(keys=None)¶ Returns voxel indices at least once selected
Parameters: keys: list or None :
Indices of center ids for which the associated masks must be used. If None, all keys are used.
Returns: voxel_indices: list of tuple :
List of triples with subvoxel indices that were selected at least once since the initalization of this class. That is, a triple (i,j,k) referring to a voxel V is an element of voxel_indices iff there is at least one key k so that self.get(k) contains the linear index of voxel V.
Notes
When using surfacebased 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.

is_same_layout
(other)¶ Check whether another instance has the same spatial layout
Parameters: other: VolumeMaskDictionary :
the instance that is compared to the current instance
Returns: same: boolean :
True iff the other instance has the same volume geometry and source as the current instance

merge
(other)¶ Add masks from another instance
Parameters: other: VolumeMaskDictionary :
The instance from which masks are added to the current one. The keys in the current and other instance should be disjoint, and auxiliary properties (if present) should have the same labels.

meta
¶ Return meta information such as number of node indices
Returns: meta: dict or False :
dictionary with meta information, or False if no such information is present. The latter case is to be compatible with oldstyle instances loaded with h5load

source
¶ Geometric information of (the centers of) each mask.
In the case of surfacesearchlights this should be a surface used as the center for searchlights.

source2nearest_target
(source)¶ Find the voxel nearest to a mask center
Parameters: src: int :
mask index
Returns: target: int :
linear index of the voxel that is contained in the mask associated with src and nearest (Euclidean distance) to src.

target2nearest_source
(target, fallback_euclidean_distance=False)¶ Find the voxel nearest to a mask center
Parameters: target: int :
linear index of a voxel
fallback_euclidean_distance: bool (default: False) :
Whether to use a euclidean distance metric if target is not in any of the masks in this instance
Returns: src: int :
key index for the mask that contains target and is nearest to target. If target is not contained in any mask, then None is returned if fallback_euclidean_distance is False, and the index of the source nearest to target using a Euclidean distance metric is returned if fallback_euclidean_distance is True

target2sources
(nbr)¶ Find the indices of masks that map to a linear voxel index
Parameters: nbr: int :
Linear voxel index
Returns: srcs: list of int :
Indices i for which get(i) contains nbr

volgeom
¶ Volume geometry information.

xyz_source
(ss=None)¶ Computes the x,y,z coordinates of one or more mask centers
Parameters: ss: list of int or None :
list of mask center indices for which coordinates should be computed. If ss is None, then coordinates for all masks that are mapped are computed. If is required that when the current instance was initialized, the sourceargument was either a surf.Surface or a numpy.ndarray.

xyz_target
(ts=None)¶ Compute the x,y,z coordinates of one or more voxels
Parameters: ts: list of int or None :
list of voxels for which coordinates should be computed. If ts is None, then coordinates for all voxels that are mapped are computed
Returns: xyz: numpy.ndarray :
Array with size len(ts) x 3 with x,y,z coordinates
