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.