mvpa2.misc.surfing.volgeom.VolGeom

Inheritance diagram of 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.