Multivariate Pattern Analysis in Python

# 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, 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.

  Attributes

  `meta` | Return meta information such as number of node indices
  `source` | Geometric information of (the centers of) each mask.
  `volgeom` | Volume geometry information.

  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`(() -> list of D’s (key, value) pairs, …) |
  `iteritems`(() -> an iterator over the (key, …) |
  `iterkeys`(() -> an iterator over the keys of D) |
  `itervalues`(…) |
  `keys`(() -> list of D’s 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`(() -> list of D’s 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

  > 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 surface-searchlights 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.

  Attributes

  `meta` | Return meta information such as number of node indices
  `source` | Geometric information of (the centers of) each mask.
  `volgeom` | Volume geometry information.

  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`(() -> list of D’s (key, value) pairs, …) |
  `iteritems`(() -> an iterator over the (key, …) |
  `iterkeys`(() -> an iterator over the keys of D) |
  `itervalues`(…) |
  `keys`(() -> list of D’s 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`(() -> list of D’s 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`(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 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.

  `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

    > Three-dimensional array with True for voxels that are included in one or more masks, and False elsewhere

    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.

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

  `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 sub-voxel 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 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.

  `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 old-style instances loaded with h5load

  `source`

    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.

  `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 source-argument 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