labs.spatial_models.discrete_domain

Module: labs.spatial_models.discrete_domain

Inheritance diagram for nipy.labs.spatial_models.discrete_domain:

Inheritance diagram of nipy.labs.spatial_models.discrete_domain

This module defines the StructuredDomain class, that represents a generic neuroimaging kind of domain This is meant to provide a unified API to deal with n-d imaged and meshes.

Author: Bertrand Thirion, 2010

Classes

DiscreteDomain

class nipy.labs.spatial_models.discrete_domain.DiscreteDomain(dim, coord, local_volume, id='', referential='')

Bases: object

Descriptor of a certain domain that consists of discrete elements that are characterized by a coordinate system and a topology: the coordinate system is specified through a coordinate array the topology encodes the neighboring system

__init__(dim, coord, local_volume, id='', referential='')

Initialize discrete domain instance

Parameters
dim: int

the (physical) dimension of the domain.

coord: array of shape(size, em_dim)

explicit coordinates of the domain sites.

local_volume: array of shape(size)

yields the volume associated with each site.

id: string, optional

domain identifier.

referential: string, optional

identifier of the referential of the coordinates system.

Notes

Caveat: em_dim may be greater than dim e.g. (meshes coordinate in 3D)

connected_components()

returns a labelling of the domain into connected components

copy()

Returns a copy of self

get_coord()

Returns self.coord

get_feature(fid)

Return self.features[fid]

get_volume()

Returns self.local_volume

integrate(fid)

Integrate certain feature over the domain and returns the result

Parameters
fidstring, feature identifier,

by default, the 1 function is integrataed, yielding domain volume

Returns
lsum = array of shape (self.feature[fid].shape[1]),

the result

mask(bmask, id='')

Returns an DiscreteDomain instance that has been further masked

representative_feature(fid, method)

Compute a statistical representative of the within-Foain feature

Parameters
fid: string, feature id
method: string, method used to compute a representative

to be chosen among ‘mean’, ‘max’, ‘median’, ‘min’

set_feature(fid, data, override=True)

Append a feature ‘fid’

Parameters
fid: string,

feature identifier

data: array of shape(self.size, p) or self.size

the feature data

MeshDomain

class nipy.labs.spatial_models.discrete_domain.MeshDomain(coord, triangles)

Bases: object

temporary class to handle meshes

__init__(coord, triangles)

Initialize mesh domain instance

Parameters
coord: array of shape (n_vertices, 3),

the node coordinates

triangles: array of shape(n_triables, 3),

indices of the nodes per triangle

area()

Return array of areas for each node

Returns
area: array of shape self.V,

area of each node

topology()

Returns a sparse matrix that represents the connectivity in self

NDGridDomain

class nipy.labs.spatial_models.discrete_domain.NDGridDomain(dim, ijk, shape, affine, local_volume, topology, referential='')

Bases: nipy.labs.spatial_models.discrete_domain.StructuredDomain

Particular instance of StructuredDomain, that receives 3 additional variables: affine: array of shape (dim+1, dim+1),

affine transform that maps points to a coordinate system

shape: dim-tuple,

shape of the domain

ijk: array of shape(size, dim), int

grid coordinates of the points

This is to allow easy conversion to images when dim==3, and for compatibility with previous classes

__init__(dim, ijk, shape, affine, local_volume, topology, referential='')

Initialize ndgrid domain instance

Parameters
dim: int,

the (physical) dimension of the domain

ijk: array of shape(size, dim), int

grid coordinates of the points

shape: dim-tuple,

shape of the domain

affine: array of shape (dim+1, dim+1),

affine transform that maps points to a coordinate system

local_volume: array of shape(size),

yields the volume associated with each site

topology: sparse binary coo_matrix of shape (size, size),

that yields the neighboring locations in the domain

referential: string, optional,

identifier of the referential of the coordinates system

Notes

FIXME: local_volume might be computed on-the-fly as |det(affine)|

connected_components()

returns a labelling of the domain into connected components

copy()

Returns a copy of self

get_coord()

Returns self.coord

get_feature(fid)

Return self.features[fid]

get_volume()

Returns self.local_volume

integrate(fid)

Integrate certain feature over the domain and returns the result

Parameters
fidstring, feature identifier,

by default, the 1 function is integrataed, yielding domain volume

Returns
lsum = array of shape (self.feature[fid].shape[1]),

the result

make_feature_from_image(path, fid='')

Extract the information from an image to make it a domain a feature

Parameters
path: string or Nifti1Image instance,

the image from which one wished to extract data

fid: string, optional

identifier of the resulting feature. if ‘’, the feature is not stored

Returns
the correponding set of values
mask(bmask)

Returns an instance of self that has been further masked

representative_feature(fid, method)

Compute a statistical representative of the within-Foain feature

Parameters
fid: string, feature id
method: string, method used to compute a representative

to be chosen among ‘mean’, ‘max’, ‘median’, ‘min’

set_feature(fid, data, override=True)

Append a feature ‘fid’

Parameters
fid: string,

feature identifier

data: array of shape(self.size, p) or self.size

the feature data

to_image(path=None, data=None)

Write itself as a binary image, and returns it

Parameters
path: string, path of the output image, if any
data: array of shape self.size,

data to put in the nonzer-region of the image

StructuredDomain

class nipy.labs.spatial_models.discrete_domain.StructuredDomain(dim, coord, local_volume, topology, did='', referential='')

Bases: nipy.labs.spatial_models.discrete_domain.DiscreteDomain

Besides DiscreteDomain attributed, StructuredDomain has a topology, which allows many operations (morphology etc.)

__init__(dim, coord, local_volume, topology, did='', referential='')

Initialize structured domain instance

Parameters
dim: int,

the (physical) dimension of the domain

coord: array of shape(size, em_dim),

explicit coordinates of the domain sites

local_volume: array of shape(size),

yields the volume associated with each site

topology: sparse binary coo_matrix of shape (size, size),

that yields the neighboring locations in the domain

did: string, optional,

domain identifier

referential: string, optional,

identifier of the referential of the coordinates system

connected_components()

returns a labelling of the domain into connected components

copy()

Returns a copy of self

get_coord()

Returns self.coord

get_feature(fid)

Return self.features[fid]

get_volume()

Returns self.local_volume

integrate(fid)

Integrate certain feature over the domain and returns the result

Parameters
fidstring, feature identifier,

by default, the 1 function is integrataed, yielding domain volume

Returns
lsum = array of shape (self.feature[fid].shape[1]),

the result

mask(bmask, did='')

Returns a StructuredDomain instance that has been further masked

representative_feature(fid, method)

Compute a statistical representative of the within-Foain feature

Parameters
fid: string, feature id
method: string, method used to compute a representative

to be chosen among ‘mean’, ‘max’, ‘median’, ‘min’

set_feature(fid, data, override=True)

Append a feature ‘fid’

Parameters
fid: string,

feature identifier

data: array of shape(self.size, p) or self.size

the feature data

Functions

nipy.labs.spatial_models.discrete_domain.array_affine_coord(mask, affine)

Compute coordinates from a boolean array and an affine transform

Parameters
mask: nd array,

input array, interpreted as a mask

affine: (n+1, n+1) matrix,

affine transform that maps the mask points to some embedding space

Returns
coords: array of shape(sum(mask>0), n),

the computed coordinates

nipy.labs.spatial_models.discrete_domain.domain_from_binary_array(mask, affine=None, nn=0)

Return a StructuredDomain from an n-d array

Parameters
mask: np.array instance

a supposedly boolean array that repesents the domain

affine: np.array, optional

affine transform that maps the array coordinates to some embedding space by default, this is np.eye(dim+1, dim+1)

nn: neighboring system considered

unsued at the moment

nipy.labs.spatial_models.discrete_domain.domain_from_image(mim, nn=18)

Return a StructuredDomain instance from the input mask image

Parameters
mim: NiftiIImage instance, or string path toward such an image

supposedly a mask (where is used to crate the DD)

nn: int, optional

neighboring system considered from the image can be 6, 18 or 26

Returns
The corresponding StructuredDomain instance
nipy.labs.spatial_models.discrete_domain.domain_from_mesh(mesh)

Instantiate a StructuredDomain from a gifti mesh

Parameters
mesh: nibabel gifti mesh instance, or path to such a mesh
nipy.labs.spatial_models.discrete_domain.grid_domain_from_binary_array(mask, affine=None, nn=0)

Return a NDGridDomain from an n-d array

Parameters
mask: np.array instance

a supposedly boolean array that repesents the domain

affine: np.array, optional

affine transform that maps the array coordinates to some embedding space by default, this is np.eye(dim+1, dim+1)

nn: neighboring system considered

unsued at the moment

nipy.labs.spatial_models.discrete_domain.grid_domain_from_image(mim, nn=18)

Return a NDGridDomain instance from the input mask image

Parameters
mim: NiftiIImage instance, or string path toward such an image

supposedly a mask (where is used to crate the DD)

nn: int, optional

neighboring system considered from the image can be 6, 18 or 26

Returns
The corresponding NDGridDomain instance
nipy.labs.spatial_models.discrete_domain.grid_domain_from_shape(shape, affine=None)

Return a NDGridDomain from an n-d array

Parameters
shape: tuple

the shape of a rectangular domain.

affine: np.array, optional

affine transform that maps the array coordinates to some embedding space. By default, this is np.eye(dim+1, dim+1)

nipy.labs.spatial_models.discrete_domain.idx_affine_coord(idx, affine)

Compute coordinates from a set of indexes and an affine transform

Parameters
idx:array of shape (n_samples, dim), type int

indexes of certain positions in a nd space

affine: (n+1, n+1) matrix,

affine transform that maps the mask points to some embedding space

Returns
coords: array of shape(sum(mask>0), n),

the computed coordinates

nipy.labs.spatial_models.discrete_domain.reduce_coo_matrix(mat, mask)

Reduce a supposedly coo_matrix to the vertices in the mask

Parameters
mat: sparse coo_matrix,

input matrix

mask: boolean array of shape mat.shape[0],

desired elements

nipy.labs.spatial_models.discrete_domain.smatrix_from_3d_array(mask, nn=18)

Create a sparse adjacency matrix from an array

Parameters
mask3d array,

input array, interpreted as a mask

nn: int, optional

3d neighboring system to be chosen within {6, 18, 26}

Returns
coo_mat: a sparse coo matrix,

adjacency of the neighboring system

nipy.labs.spatial_models.discrete_domain.smatrix_from_3d_idx(ijk, nn=18)

Create a sparse adjacency matrix from 3d index system

Parameters
idx:array of shape (n_samples, 3), type int

indexes of certain positions in a 3d space

nn: int, optional

3d neighboring system to be chosen within {6, 18, 26}

Returns
coo_mat: a sparse coo matrix,

adjacency of the neighboring system

nipy.labs.spatial_models.discrete_domain.smatrix_from_nd_array(mask, nn=0)

Create a sparse adjacency matrix from an arbitrary nd array

Parameters
masknd array,

input array, interpreted as a mask

nn: int, optional

nd neighboring system, unsused at the moment

Returns
coo_mat: a sparse coo matrix,

adjacency of the neighboring system

nipy.labs.spatial_models.discrete_domain.smatrix_from_nd_idx(idx, nn=0)

Create a sparse adjacency matrix from nd index system

Parameters
idx:array of shape (n_samples, dim), type int

indexes of certain positions in a nd space

nn: int, optional

nd neighboring system, unused at the moment

Returns
coo_mat: a sparse coo matrix,

adjacency of the neighboring system