labs.spatial_models.discrete_domain

Module: labs.spatial_models.discrete_domain

Inheritance diagram for 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: 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 corresponding 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: 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 represents 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

unused 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 create 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 represents 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

unused 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 create 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, unused 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