Multivariate Pattern Analysis in Python

# mvpa2.misc.surfing.volgeom.VolGeom

class `mvpa2.misc.surfing.volgeom.``VolGeom`(shape, affine, mask=None)

  Defines a mapping between sub and linear indices and world coordinate in volumatric fmri datasets

  Attributes

  `affine` | Returns the affine transformation matrix.
  `linear_mask` | Returns the mask as a vector
  `mask` | Returns the mask.
  `nvoxels` | Returns the number of voxels.

  `nvoxels_mask`

  Returns: |

  `shape` | Returns the shape.

  Methods

  `apply_affine3`(mat, v) | Applies an affine transformation matrix.
  `as_pickable`() | Returns a pickable instance.
  `contains_ijk`(ijk[, apply_mask]) | Returns whether a set of sub voxel indices are contained within this instance.
  `contains_lin`(lin[, apply_mask]) | Returns whether a set of linear voxel indices are contained within this instance.
  `get_empty_array`([nt]) | Returns an empty array with size according to the volume
  `get_empty_nifti_image`([nt]) | Returns an empty nifti image with size according to the volume
  `get_masked_array`([nt, dilate]) | Provides a masked numpy array
  `get_masked_nifti_image`([nt, dilate]) | Provides a masked nifti image
  `ijk2lin`(ijk) | Converts sub to linear voxel indices.
  `ijk2triples`(ijk) | Converts sub indices to a list of triples
  `ijk2xyz`(ijk) | Maps sub voxel indices to world coordinates.
  `lin2ijk`(lin) | Converts sub to linear voxel indices.
  `lin2xyz`(lin) | Maps linear voxel indices to world coordinates.
  `same_geometry`(other) | Compares this geometry with another instance
  `same_mask`(other) | Compares the mask with another instance
  `same_shape`(other) | Compares the shape of the spatial dimensions with another instance
  `triples2ijk`(tuples) | Converts triples to sub indices
  `xyz2ijk`(xyz) | Maps world coordinates to sub voxel indices.
  `xyz2lin`(xyz) | Maps world coordinates to linear voxel indices.

  Parameters:

  shape: tuple

  > Number of values in each dimension. Typically the first three dimensions are spatial and the remaining ones temporal. Only the first three dimensions are stored

  affine: numpy.ndarray

  > 4x4 affine transformation array that maps voxel to world coordinates.

  mask: numpy.ndarray (default: None)

  > voxel mask that indicates which voxels are included. Values of zero in mask mean that a voxel is not included. If mask is None, then all voxels are included.

  Attributes

  `affine` | Returns the affine transformation matrix.
  `linear_mask` | Returns the mask as a vector
  `mask` | Returns the mask.
  `nvoxels` | Returns the number of voxels.

  `nvoxels_mask`

  Returns: |

  `shape` | Returns the shape.

  Methods

  `apply_affine3`(mat, v) | Applies an affine transformation matrix.
  `as_pickable`() | Returns a pickable instance.
  `contains_ijk`(ijk[, apply_mask]) | Returns whether a set of sub voxel indices are contained within this instance.
  `contains_lin`(lin[, apply_mask]) | Returns whether a set of linear voxel indices are contained within this instance.
  `get_empty_array`([nt]) | Returns an empty array with size according to the volume
  `get_empty_nifti_image`([nt]) | Returns an empty nifti image with size according to the volume
  `get_masked_array`([nt, dilate]) | Provides a masked numpy array
  `get_masked_nifti_image`([nt, dilate]) | Provides a masked nifti image
  `ijk2lin`(ijk) | Converts sub to linear voxel indices.
  `ijk2triples`(ijk) | Converts sub indices to a list of triples
  `ijk2xyz`(ijk) | Maps sub voxel indices to world coordinates.
  `lin2ijk`(lin) | Converts sub to linear voxel indices.
  `lin2xyz`(lin) | Maps linear voxel indices to world coordinates.
  `same_geometry`(other) | Compares this geometry with another instance
  `same_mask`(other) | Compares the mask with another instance
  `same_shape`(other) | Compares the shape of the spatial dimensions with another instance
  `triples2ijk`(tuples) | Converts triples to sub indices
  `xyz2ijk`(xyz) | Maps world coordinates to sub voxel indices.
  `xyz2lin`(xyz) | Maps world coordinates to linear voxel indices.

  `affine`

    Returns the affine transformation matrix.

    Returns:

    affine : numpy.ndarray

    > 4x4 array that maps voxel to world coordinates.

  `apply_affine3`(mat, v)

    Applies an affine transformation matrix.

    Parameters:

    mat : numpy.ndarray (float)

    > Matrix with size at least 3x4

    v : numpy.ndarray (float)

    > Px3 values to which transformation is applied

    Returns:

    w : numpy.ndarray(float)

    > Px3 transformed values

  `as_pickable`()

    Returns a pickable instance.

    Returns:

    dict

    > A dictionary that contains all information from this instance (and can be saved using pickle).

  `contains_ijk`(ijk, apply_mask=True)

    Returns whether a set of sub voxel indices are contained within this instance.

    Parameters:

    ijk : numpy.ndarray

    > Px3 array with sub voxel indices

    Returns:

    numpy.ndarray (boolean)

    > P boolean values indicating which voxels are within the volume.

  `contains_lin`(lin, apply_mask=True)

    Returns whether a set of linear voxel indices are contained within this instance.

    Parameters:

    lin : numpy.ndarray

    > Px1 array with linear voxel indices.

    Returns:

    numpy.ndarray (boolean)

    > P boolean values indicating which voxels are within the volume.

  `get_empty_array`(nt=None)

    Returns an empty array with size according to the volume

    Parameters:

    nt: int or None

    > Number of timepoints (or samples). Each feature has the same value (1 if in the mask, 0 otherwise) for each sample. If nt is None, then the output is 3D; otherwise it is 4D with ‘nt’ values in the last dimension.

    Returns:

    arr: numpy.ndarray

    > An array with value zero everywhere.

  `get_empty_nifti_image`(nt=None)

    Returns an empty nifti image with size according to the volume

    Parameters:

    nt: int or None

    > Number of timepoints (or samples). Each feature has the same value (1 if in the mask, 0 otherwise) for each sample. If nt is None, then the output is 3D; otherwise it is 4D with ‘nt’ values in the last dimension.

    Returns:

    arr: nibabel.Nifti1Image

    > A Nifti image with value zero everywhere.

  `get_masked_array`(nt=None, dilate=None)

    Provides a masked numpy array

    Parameters:

    nt: int or None

    > Number of timepoints (or samples). Each feature has the same value (1 if in the mask, 0 otherwise) for each sample. If nt is None, then the output is 3D; otherwise it is 4D with ‘nt’ values in the last dimension.

    dilate: callable or int or None

    > Speficiation of mask dilation. If a callable, it should be a a neighborhood function (like Sphere(..)) that can map a single voxel coordinate (represented as a triple of indices) to a list of voxel coordinates that define the neighboorhood of that coordinate. For example, Sphere(3) can be used to dilate the original mask by 3 voxels. If an int, then it uses Sphere(dilate) to dilate the mask. If set to None the mask is not dilated.

    Returns:

    msk: numpy.ndarray

    > an array with values 1. for values inside the mask and values of 0 elsewhere. If the instance has no mask, then all values are 1.

  `get_masked_nifti_image`(nt=None, dilate=None)

    Provides a masked nifti image

    Parameters:

    nt: int or None

    > Number of timepoints (or samples). Each feature has the same value (1 if in the mask, 0 otherwise) for each sample. If nt is None, then the output is 3D; otherwise it is 4D with ‘nt’ values in the last dimension.

    dilate: callable or int or None

    > If a callable, it should be a a neighborhood function (like Sphere(..)) that can map a single voxel coordinate (represented as a triple of indices) to a list of voxel coordinates that define the neighboorhood of that coordinate. For example, Sphere(3) can be used to dilate the original mask by 3 voxels. If an int, then it uses Sphere(dilate) to dilate the mask. If set to None the mask is not dilated.

    Returns:

    msk: Nifti1image

    > a nifti image with values 1. for values inside the mask and values of 0 elsewhere. If the instance has no mask, then all values are 1.

  `ijk2lin`(ijk)

    Converts sub to linear voxel indices.

    Parameters:

    ijk: numpy.ndarray

    > Px3 array with sub voxel indices.

    Returns:

    lin: Px1 array with linear voxel indices.

    > If ijk[i,:] is outside the volume, then lin[i]==self.nvoxels.

  `ijk2triples`(ijk)

    Converts sub indices to a list of triples

    Parameters:

    ijk: np.ndarray (Px3)

    > sub indices

    Returns:

    triples: list with P triples

    > the indices from ijk, so that triples[i][j]==ijk[i,j]

  `ijk2xyz`(ijk)

    Maps sub voxel indices to world coordinates.

    Parameters:

    ijk: numpy.ndarray (int)

    > Px3 array with sub voxel indices.

    Returns:

    xyz : numpy.ndarray (float)

    > Px3 array with world coordinates. If ijk[i,:] is outside the volume, then xyz[i,:] is NaN.

  `lin2ijk`(lin)

    Converts sub to linear voxel indices.

    Parameters: | Px1 array with linear voxel indices.

    Returns:

    ijk: numpy.ndarray

    > Px3 array with sub voxel indices. If lin[i] is outside the volume, then ijk[i,:]==self.shape.

  `lin2xyz`(lin)

    Maps linear voxel indices to world coordinates.

    Parameters:

    ijk: numpy.ndarray (int)

    > Px3 array with linear voxel indices.

    Returns:

    xyz : np.ndarray (float)

    > Px1 array with world coordinates. If lin[i] is outside the volume, then xyz[i,:] is NaN.

  `linear_mask`

    Returns the mask as a vector

    Returns:

    mask: np.ndarray (vector with P values)

    > boolean vector indicating which voxels are included. If no mask is associated with this instance then mask is None.

  `mask`

    Returns the mask.

    Returns:

    mask: np.ndarray

    > boolean vector indicating which voxels are included. If no mask is associated with this instance then mask is None.

  `nvoxels`

    Returns the number of voxels.

    Returns:

    nv: int

    > Number of spatial points (i.e. number of voxels)

  `nvoxels_mask`

    Returns:

    nv: int

    > Number of voxels that survive the mask

  `same_geometry`(other)

    Compares this geometry with another instance

    Parameters:

    other: VolGeom

    > instance to which the current instance is compared

    Returns:

    same: boolean

    > True iff it has the same geometry. It does not compare whether the mask is the same

  `same_mask`(other)

    Compares the mask with another instance

    Parameters:

    other: VolGeom

    > instance to which the current instance is compared

    Returns:

    same: boolean

    > True iff it has effectively the same mask

  `same_shape`(other)

    Compares the shape of the spatial dimensions with another instance

    Parameters:

    other: VolGeom

    > instance to which the current instance is compared

    Returns:

    same: boolean

    > True iff it has the same shape in the first three dimensions

  `shape`

    Returns the shape.

    Returns:

    sh: tuple of int

    > Number of values in each dimension

  `triples2ijk`(tuples)

    Converts triples to sub indices

    Parameters: | triples: list with P triples

    Returns:

    ijk: np.ndarray(Px3)

    > an array from triples, so that ijk[i,j]==triples[i][j]

  `xyz2ijk`(xyz)

    Maps world coordinates to sub voxel indices.

    Parameters:

    xyz : numpy.ndarray (float)

    > Px3 array with world coordinates.

    Returns:

    ijk: numpy.ndarray (int)

    > Px3 array with sub voxel indices. If xyz[i,:] is outside the volume, then ijk[i,:]==self.shape

  `xyz2lin`(xyz)

    Maps world coordinates to linear voxel indices.

    Parameters:

    xyz : numpy.ndarray (float)

    > Px3 array with world coordinates

    Returns:

    ijk: numpy.ndarray (int)

    > Px1 array with linear indices. If xyz[i,:] is outside the volume, then lin[i]==self.nvoxels.