labs.spatial_models.hroi

Module: labs.spatial_models.hroi

Inheritance diagram for nipy.labs.spatial_models.hroi:

Inheritance diagram of nipy.labs.spatial_models.hroi

This module contains the specification of ‘hierarchical ROI’ object, Which is used in spatial models of the library such as structural analysis

The connection with other classes is not completely satisfactory at the moment: there should be some intermediate classes between ‘Fields’ and ‘hroi’

Author : Bertrand Thirion, 2009-2011
Virgile Fritsch <virgile.fritsch@inria.fr>

Class

HierarchicalROI

class nipy.labs.spatial_models.hroi.HierarchicalROI(domain, label, parents, id=None)

Bases: nipy.labs.spatial_models.mroi.SubDomains

Class that handles hierarchical ROIs

Parameters:

k : int

Number of ROI in the SubDomains object

label : array of shape (domain.size), dtype=np.int

An array use to define which voxel belongs to which ROI. The label values greater than -1 correspond to subregions labelling. The labels are recomputed so as to be consecutive integers. The labels should not be accessed outside this class. One has to use the API mapping methods instead.

features : dict {str: list of object, length=self.k}

Describe the voxels features, grouped by ROI

roi_features : dict {str: array-like, shape=(self.k, roi_feature_dim)

Describe the ROI features. A special feature, id, is read-only and is used to give an unique identifier for region, which is persistent through the MROI objects manipulations. On should access the different ROI’s features using ids.

parents : np.ndarray, shape(self.k)

self.parents[i] is the index of the parent of the i-th ROI.

TODO: have the parents as a list of id rather than a list of indices.

__init__(domain, label, parents, id=None)

Building the HierarchicalROI

copy()

Returns a copy of self.

self.domain is not copied.

get_leaves_id()

Return the ids of the leaves.

get_parents()

Return the parent of each node in the hierarchy

The parents are represented by their position in the nodes flat list.

TODO: The purpose of this class API is not to rely on this order, so we should have self.parents as a list of ids instead of a list of positions

get_size(id=None, ignore_children=True)

Get ROI size (counted in terms of voxels)

Parameters:

id: any hashable type, optional

Id of the ROI from which we want to get the size. Can be None (default) if we want all ROIs’s sizes.

ignore_children: bool, optional

Specify if the size of the node should include (ignore_children = False) or not the one of its children (ignore_children = True).

Returns:

size: int

if an id is provided,

or list of int

if no id provided (default)

get_volume(id=None, ignore_children=True)

Get ROI volume

Parameters:

id: any hashable type, optional

Id of the ROI from which we want to get the volume. Can be None (default) if we want all ROIs’s volumes.

ignore_children : bool, optional

Specify if the volume of the node should include (ignore_children = False) or not the one of its children (ignore_children = True).

Returns:

volume : float

if an id is provided,

or list of float

if no id provided (default)

make_forest()

Output an nipy forest structure to represent the ROI hierarchy.

make_graph()

Output an nipy graph structure to represent the ROI hierarchy.

merge_ascending(id_list, pull_features=None)

Remove the non-valid ROIs by including them in their parents when it exists.

Parameters:

id_list: list of id (any hashable type)

The id of the ROI to be merged into their parents. Nodes that are their own parent are unmodified.

pull_features: list of str

List of the ROI features that will be pooled from the children when they are merged into their parents. Otherwise, the receiving parent would keep its own ROI feature.

merge_descending(pull_features=None)

Remove the items with only one son by including them in their son

Parameters:

methods indicates the way possible features are dealt with

(not implemented yet)

Notes

Caveat: if roi_features have been defined, they will be removed

reduce_to_leaves()

Create a new set of rois which are only the leaves of self.

Modification of the structure is done in place. One way therefore want to work on a copy a of a given HROI oject.

representative_feature(fid, method='mean', id=None, ignore_children=True, assess_quality=True)

Compute a ROI representative of a given feature.

Parameters:

fid: str,

Feature id

method: str,

Method used to compute a representative. Chosen among ‘mean’ (default), ‘max’, ‘median’, ‘min’, ‘weighted mean’.

id: any hashable type

Id of the ROI from which we want to extract a representative feature. Can be None (default) if we want to get all ROIs’s representatives.

ignore_children: bool,

Specify if the volume of the node should include (ignore_children = False) or not the one of its children (ignore_children = True).

assess_quality: bool

If True, a new roi feature is created, which represent the quality of the feature representative (the number of non-nan value for the feature over the ROI size). Default is False.

select_roi(id_list)

Returns an instance of HROI with only the subset of chosen ROIs.

The hierarchy is set accordingly.

Parameters:

id_list: list of id (any hashable type)

The id of the ROI to be kept in the structure.

Functions

nipy.labs.spatial_models.hroi.HROI_as_discrete_domain_blobs(domain, data, threshold=-inf, smin=0, criterion='size')

Instantiate an HierarchicalROI as the blob decomposition of data in a certain domain.

Parameters:

domain : discrete_domain.StructuredDomain instance,

Definition of the spatial context.

data : array of shape (domain.size)

The corresponding data field.

threshold : float, optional

Thresholding level.

criterion : string, optional

To be chosen among ‘size’ or ‘volume’.

smin: float, optional

A threshold on the criterion.

Returns:

nroi: HierachicalROI instance with a signal feature.

nipy.labs.spatial_models.hroi.HROI_from_watershed(domain, data, threshold=-inf)

Instantiate an HierarchicalROI as the watershed of a certain dataset

Parameters:

domain: discrete_domain.StructuredDomain instance

Definition of the spatial context.

data: array of shape (domain.size)

The corresponding data field.

threshold: float, optional

Thresholding level.

Returns:

nroi : HierarchichalROI instance

The HierachicalROI instance with a seed feature.

nipy.labs.spatial_models.hroi.hroi_agglomeration(input_hroi, criterion='size', smin=0)

Performs an agglomeration then a selection of regions so that a certain size or volume criterion is satisfied.

Parameters:

input_hroi: HierarchicalROI instance

The input hROI

criterion: str, optional

To be chosen among ‘size’ or ‘volume’

smin: float, optional

The applied criterion

Returns:

output_hroi: HierarchicalROI instance

nipy.labs.spatial_models.hroi.make_hroi_from_subdomain(sub_domain, parents)

Instantiate an HROi from a SubDomain instance and parents