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='')[source]¶ Bases:
objectDescriptor 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='')[source]¶ 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)
-
set_feature(fid, data, override=True)[source]¶ 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)[source]¶ Bases:
objecttemporary class to handle meshes
-
__init__(coord, triangles)[source]¶ 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
-
NDGridDomain¶
-
class
nipy.labs.spatial_models.discrete_domain.NDGridDomain(dim, ijk, shape, affine, local_volume, topology, referential='')[source]¶ Bases:
nipy.labs.spatial_models.discrete_domain.StructuredDomainParticular 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='')[source]¶ 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)|
-
to_image(path=None, data=None)[source]¶ 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
-
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='')[source]¶ 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
-
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
StructuredDomain¶
-
class
nipy.labs.spatial_models.discrete_domain.StructuredDomain(dim, coord, local_volume, topology, did='', referential='')[source]¶ Bases:
nipy.labs.spatial_models.discrete_domain.DiscreteDomainBesides DiscreteDomain attributed, StructuredDomain has a topology, which allows many operations (morphology etc.)
-
__init__(dim, coord, local_volume, topology, did='', referential='')[source]¶ 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
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
-
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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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