# 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:
      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

  __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:
      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 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:
      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_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:
    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, 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