labs.spatial_models.discrete_domain

Module: labs.spatial_models.discrete_domain

Inheritance diagram for nipy.labs.spatial_models.discrete_domain:

This module define 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

Methods

connected_components
copy	Generic (shallow and deep) copying operations.
get_coord
get_feature
get_volume
integrate
mask
representative_feature
set_feature

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

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

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 :

fid : string, 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

Methods

area
topology

__init__(coord, triangles)

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()

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

Methods

connected_components
copy	Generic (shallow and deep) copying operations.
get_coord
get_feature
get_volume
integrate
make_feature_from_image
mask
representative_feature
set_feature
to_image

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

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

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 :

fid : string, 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.)

Methods

connected_components
copy	Generic (shallow and deep) copying operations.
get_coord
get_feature
get_volume
integrate
mask
representative_feature
set_feature

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

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 :

fid : string, 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_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_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.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 :

mask : 3d 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 :

mask : nd 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