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

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.

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.