algorithms.graph.field

Module: algorithms.graph.field

Inheritance diagram for nipy.algorithms.graph.field:

Inheritance diagram of nipy.algorithms.graph.field

This module implements the Field class, which simply a WeightedGraph (see the graph.py) module, plus an arrray that yields (possibly multi-dimnesional) features associated with graph vertices. This allows some kinds of computations (all thoses relating to mathematical morphology, diffusion etc.)

Certain functions are provided to Instantiate Fields easily, given a WeightedGraph and feature data.

Author:Bertrand Thirion, 2006–2011

Class

Field

class nipy.algorithms.graph.field.Field(V, edges=None, weights=None, field=None)

Bases: nipy.algorithms.graph.graph.WeightedGraph

This is the basic field structure,
which contains the weighted graph structure plus an array of data (the ‘field’)
field is an array of size(n, p)
where n is the number of vertices of the graph and p is the field dimension
__init__(V, edges=None, weights=None, field=None)
Parameters:

V (int > 0) the number of vertices of the graph

edges=None: the edge array of the graph

weights=None: the asociated weights array

field=None: the field data itself

closing(nbiter=1)

Morphological closing of the field data. self.field is changed inplace

Parameters:nbiter=1 : the number of iterations required
constrained_voronoi(seed)

Voronoi parcellation of the field starting from the input seed

Parameters:seed: int array of shape(p), the input seeds
Returns:label: The resulting labelling of the data

Notes

FIXME: deal with graphs with several ccs

copy()

copy function

custom_watershed(refdim=0, th=-inf)

customized watershed analysis of the field. Note that bassins are found around each maximum (and not minimum as conventionally)

Parameters:

refdim: int, optional

th: float optional, threshold of the field

Returns:

idx: array of shape (nbassins)

indices of the vertices that are local maxima

label : array of shape (self.V)

labelling of the vertices according to their bassin

diffusion(nbiter=1)

diffusion of the field data in the weighted graph structure self.field is changed inplace

Parameters:nbiter: int, optional the number of iterations required

Notes

The process is run for all the dimensions of the field

dilation(nbiter=1, fast=True)

Morphological dilation of the field data, changed in place

Parameters:nbiter: int, optional, the number of iterations required

Notes

When data dtype is not float64, a slow version of the code is used

erosion(nbiter=1)

Morphological openeing of the field

Parameters:nbiter: int, optional, the number of iterations required
geodesic_kmeans(seeds=None, label=None, maxiter=100, eps=0.0001, verbose=0)

Geodesic k-means algorithm i.e. obtention of clusters that are topologically connected and minimally variable concerning the information of self.field

Parameters:

seeds: array of shape(p), optional,

initial indices of the seeds within the field if seeds==None the labels are used as initialization

labels: array of shape(self.V) initial labels, optional,

it is expected that labels take their values in a certain range (0..lmax) if Labels==None, this is not used if seeds==None and labels==None, an ewxception is raised

maxiter: int, optional,

maximal number of iterations

eps: float, optional,

increase of inertia at which convergence is declared

Returns:

seeds: array of shape (p), the final seeds

label : array of shape (self.V), the resulting field label

J: float, inertia value

get_field()
get_local_maxima(refdim=0, th=-inf)

Look for the local maxima of one dimension (refdim) of self.field

Parameters:

refdim (int) the field dimension over which the maxima are looked after

th = float, optional

threshold so that only values above th are considered

Returns:

idx: array of shape (nmax)

indices of the vertices that are local maxima

depth: array of shape (nmax)

topological depth of the local maxima : depth[idx[i]] = q means that idx[i] is a q-order maximum

highest_neighbor(refdim=0)

Computes the neighbor with highest field value along refdim

Parameters:

refdim: int, optional,

the dimension of the field under consideration

Returns:

hneighb: array of shape(self.V),

index of the neighbor with highest value

local_maxima(refdim=0, th=-inf)

Returns all the local maxima of a field

Parameters:

refdim (int) field dimension over which the maxima are looked after

th: float, optional

threshold so that only values above th are considered

Returns:

depth: array of shape (nmax)

a labelling of the vertices such that depth[v] = 0 if v is not a local maximum depth[v] = 1 if v is a first order maximum … depth[v] = q if v is a q-order maximum

opening(nbiter=1)

Morphological opening of the field data. self.field is changed inplace

Parameters:nbiter: int, optional, the number of iterations required
set_field(field)
subfield(valid)

Returns a subfield of self, with only vertices such that valid > 0

Parameters:

valid: array of shape (self.V),

nonzero for vertices to be retained

Returns:

F: Field instance,

the desired subfield of self

Notes

The vertices are renumbered as [1..p] where p = sum(valid>0) when sum(valid) == 0 then None is returned

threshold_bifurcations(refdim=0, th=-inf)

Analysis of the level sets of the field: Bifurcations are defined as changes in the topology in the level sets when the level (threshold) is varied This can been thought of as a kind of Morse analysis

Parameters:

th: float, optional,

threshold so that only values above th are considered

Returns:

idx: array of shape (nlsets)

indices of the vertices that are local maxima

height: array of shape (nlsets)

the depth of the local maxima depth[idx[i]] = q means that idx[i] is a q-order maximum Note that this is also the diameter of the basins associated with local maxima

parents: array of shape (nlsets)

the label of the maximum which dominates each local maximum i.e. it describes the hierarchy of the local maxima

label: array of shape (self.V)

a labelling of thevertices according to their bassin

ward(nbcluster)

Ward’s clustering of self

Parameters:

nbcluster: int,

the number of desired clusters

Returns:

label: array of shape (self.V)

the resulting field label

J (float): the resulting inertia

Functions

nipy.algorithms.graph.field.field_from_coo_matrix_and_data(x, data)

Instantiates a weighted graph from a (sparse) coo_matrix

Parameters:

x: (V, V) scipy.sparse.coo_matrix instance,

the input matrix

data: array of shape (V, dim),

the field data

Returns:

ifield: resulting Field instance

nipy.algorithms.graph.field.field_from_graph_and_data(g, data)

Instantiate a Fieldfrom a WeightedGraph plus some feature data Parameters ———- x: (V, V) scipy.sparse.coo_matrix instance,

the input matrix
data: array of shape (V, dim),
the field data
Returns:ifield: resulting field instance