labs.datasets.volumes.volume_grid

Module: labs.datasets.volumes.volume_grid

Inheritance diagram for nipy.labs.datasets.volumes.volume_grid:

Inheritance diagram of nipy.labs.datasets.volumes.volume_grid

The volume grid class.

This class represents data lying on a (non rigid, non regular) grid embedded in a 3D world represented as a 3+D array.

VolumeGrid

class nipy.labs.datasets.volumes.volume_grid.VolumeGrid(data, transform, metadata=None, interpolation='continuous')

Bases: nipy.labs.datasets.volumes.volume_data.VolumeData

A class representing data stored in a 3+D array embedded in a 3D world.

This object has data stored in an array-like multidimensional indexable objects, with the 3 first dimensions corresponding to spatial axis and defining a 3D grid that may be non-regular or non-rigid.

The object knows how the data is mapped to a 3D “real-world space”, and how it can change real-world coordinate system. The transform mapping it to world is arbitrary, and thus the grid can be warped: in the world space, the grid may not be regular or orthogonal.

Notes

The data is stored in an undefined way: prescalings might need to be applied to it before using it, or the data might be loaded on demand. The best practice to access the data is not to access the _data attribute, but to use the get_data method.

If the transform associated with the image has no inverse mapping, data corresponding to a given world space position cannot be calulated. If it has no forward mapping, it is impossible to resample another dataset on the same support.

Attributes

world_space: string World space the data is embedded in. For instance mni152.
metadata: dictionnary Optional, user-defined, dictionnary used to carry around extra information about the data as it goes through transformations. The consistency of this information is not maintained as the data is modified.
_data: Private pointer to the data.
__init__(data, transform, metadata=None, interpolation='continuous')

The base image containing data.

Parameters:

data: ndarray

n dimensional array giving the embedded data, with the 3 first dimensions being spatial.

transform: nipy transform object

The transformation from voxel to world.

metadata : dictionnary, optional

Dictionnary of user-specified information to store with the image.

interpolation : ‘continuous’ or ‘nearest’, optional

Interpolation type used when calculating values in different word spaces.

as_volume_img(affine=None, shape=None, interpolation=None, copy=True)

Resample the image to be an image with the data points lying on a regular grid with an affine mapping to the word space (a nipy VolumeImg).

Parameters:

affine: 4x4 or 3x3 ndarray, optional

Affine of the new voxel grid or transform object pointing to the new voxel coordinate grid. If a 3x3 ndarray is given, it is considered to be the rotation part of the affine, and the best possible bounding box is calculated, in this case, the shape argument is not used. If None is given, a default affine is provided by the image.

shape: (n_x, n_y, n_z), tuple of integers, optional

The shape of the grid used for sampling, if None is given, a default affine is provided by the image.

interpolation : None, ‘continuous’ or ‘nearest’, optional

Interpolation type used when calculating values in different word spaces. If None, the image’s interpolation logic is used.

Returns:

resampled_image : nipy VolumeImg

New nipy VolumeImg with the data sampled on the grid defined by the affine and shape.

Notes

The coordinate system of the image is not changed: the returned image points to the same world space.

get_transform()

Returns the transform object associated with the volumetric structure which is a general description of the mapping from the values to the world space.

Returns:transform : nipy.datasets.Transform object
get_world_coords()

Return the data points coordinates in the world space.

Returns:

x: ndarray

x coordinates of the data points in world space

y: ndarray

y coordinates of the data points in world space

z: ndarray

z coordinates of the data points in world space

like_from_data(data)

Returns an volumetric data structure with the same relationship between data and world space, and same metadata, but different data.

Parameters:data: ndarray
values_in_world(x, y, z, interpolation=None)

Return the values of the data at the world-space positions given by x, y, z

Parameters:

x : number or ndarray

x positions in world space, in other words milimeters

y : number or ndarray

y positions in world space, in other words milimeters. The shape of y should match the shape of x

z : number or ndarray

z positions in world space, in other words milimeters. The shape of z should match the shape of x

interpolation : None, ‘continuous’ or ‘nearest’, optional

Interpolation type used when calculating values in different word spaces. If None, the image’s interpolation logic is used.

Returns:

values : number or ndarray

Data values interpolated at the given world position. This is a number or an ndarray, depending on the shape of the input coordinate.