labs.spatial_models.hroi¶
Module: labs.spatial_models.hroi¶
Inheritance diagram for 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’
- AuthorBertrand Thirion, 2009-2011
Virgile Fritsch <virgile.fritsch@inria.fr>
Class¶
HierarchicalROI¶
-
class
nipy.labs.spatial_models.hroi.HierarchicalROI(domain, label, parents, id=None)[source]¶ Bases:
nipy.labs.spatial_models.mroi.SubDomainsClass 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.
-
get_volume(id=None, ignore_children=True)[source]¶ 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)
-
get_size(id=None, ignore_children=True)[source]¶ 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)
-
select_roi(id_list)[source]¶ 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.
-
merge_ascending(id_list, pull_features=None)[source]¶ 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)[source]¶ 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
-
get_parents()[source]¶ 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
-
reduce_to_leaves()[source]¶ 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)[source]¶ 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.
-
feature_to_voxel_map(fid, roi=False, method='mean')¶ Convert a feature to a flat voxel-mapping array.
- Parameters
fid: str
Identifier of the feature to be mapped.
roi: bool, optional
If True, compute the map from a ROI feature.
method: str, optional
Representative feature computation method if fid is a feature and roi is True.
- Returns
res: array-like, shape=(domain.size, feature_dim)
A flat array, giving the correspondence between voxels and the feature.
-
get_coord(id=None)¶ Get coordinates of ROI’s voxels
- Parameters
id: any hashable type
Id of the ROI from which we want the voxels’ coordinates. Can be None (default) if we want all ROIs’s voxels coordinates.
- Returns
coords: array-like, shape=(roi_size, domain_dimension)
- if an id is provided,
or list of arrays of shape(roi_size, domain_dimension)
if no id provided (default)
-
get_feature(fid, id=None)¶ Return a voxel-wise feature, grouped by ROI.
- Parameters
fid: str,
Feature to be returned
id: any hashable type
Id of the ROI from which we want to get the feature. Can be None (default) if we want all ROIs’s features.
- Returns
feature: array-like, shape=(roi_size, feature_dim)
- if an id is provided,
or list of arrays, shape=(roi_size, feature_dim)
if no id provided (default)
-
get_id()¶ Return ROI’s id list.
Users must access ROIs with the use of the identifiers of this list and the methods that give access to their properties/features.
-
get_local_volume(id=None)¶ Get volume of ROI’s voxels
- Parameters
id: any hashable type
Id of the ROI from which we want the voxels’ volumes. Can be None (default) if we want all ROIs’s voxels volumes.
- Returns
loc_volume: array-like, shape=(roi_size, ),
- if an id is provided,
or list of arrays of shape(roi_size, )
if no id provided (default)
-
get_roi_feature(fid, id=None)¶
-
integrate(fid=None, id=None)¶ Integrate certain feature on each ROI and return the k results
- Parameters
fid : str
Feature identifier. By default, the 1 function is integrated, yielding ROI volumes.
id: any hashable type
The ROI on which we want to integrate. Can be None if we want the results for every region.
- Returns
lsum = array of shape (self.k, self.feature[fid].shape[1]),
The results
-
plot_feature(fid, ax=None)¶ Boxplot the distribution of features within ROIs. Note that this assumes 1-d features.
- Parameters
fid: string
the feature identifier
ax: axis handle, optional
-
recompute_labels()¶ Redefine labels so that they are consecutive integers.
Labels are used as a map to associate voxels to a given ROI. It is an inner object that should not be accessed outside this class. The number of nodes is updated appropriately.
Notes
This method must be called everytime the MROI structure is modified.
-
remove_feature(fid)¶ Remove a certain feature
- Parameters
fid: str
Feature id
- Returns
f : object
The removed feature.
-
remove_roi_feature(fid)¶ Remove a certain ROI feature.
The id ROI feature cannot be removed.
- Returns
f : object
The removed Roi feature.
-
select_id(id, roi=True)¶ Convert a ROI id into an index to be used to index features safely.
- Parameters
id : any hashable type, must be in self.get_id()
The id of the region one wants to access.
roi : bool
If True (default), return the ROI index in the ROI list. If False, return the indices of the voxels of the ROI with the given id. That way, internal access to self.label can be made.
- Returns
index : int or np.array of shape (roi.size, )
Either the position of the ROI in the ROI list (if roi == True), or the positions of the voxels of the ROI with id id with respect to the self.label array.
-
set_feature(fid, data, id=None, override=False)¶ Append or modify a feature
- Parameters
fid : str
feature identifier
data: list or array
The feature data. Can be a list of self.k arrays of shape(self.size[k], p) or array of shape(self.size[k])
id: any hashable type, optional
Id of the ROI from which we want to set the feature. Can be None (default) if we want to set all ROIs’s features.
override: bool, optional
Allow feature overriding
Note that we cannot create a feature having the same name than
a ROI feature.
-
set_roi_feature(fid, data, id=None, override=False)¶ Append or modify a ROI feature
- Parameters
fid: str,
feature identifier
data: list of self.k features or a single feature
The ROI feature data
id: any hashable type
Id of the ROI of which we want to set the ROI feature. Can be None (default) if we want to set all ROIs’s ROI features.
override: bool, optional,
Allow feature overriding
Note that we cannot create a ROI feature having the same name than
a feature.
Note that the `id` feature cannot be modified as an internal
component.
-
to_image(fid=None, roi=False, method='mean', descrip=None)¶ Generates a label image that represents self.
- Parameters
fid: str,
Feature to be represented. If None, a binary image of the MROI domain will be we created.
roi: bool,
Whether or not to write the desired feature as a ROI one. (i.e. a ROI feature corresponding to fid will be looked upon, and if not found, a representative feature will be computed from the fid feature).
method: str,
If a feature is written as a ROI feature, this keyword tweaks the way the representative feature is computed.
descrip: str,
Description of the image, to be written in its header.
- Returns
nim : nibabel nifti image
Nifti image corresponding to the ROI feature to be written.
Notes
Requires that self.dom is an ddom.NDGridDomain
Functions¶
-
nipy.labs.spatial_models.hroi.HROI_as_discrete_domain_blobs(domain, data, threshold=-inf, smin=0, criterion='size')[source]¶ 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)[source]¶ 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 :
HierarchichalROIinstanceThe HierachicalROI instance with a
seedfeature.
-
nipy.labs.spatial_models.hroi.hroi_agglomeration(input_hroi, criterion='size', smin=0)[source]¶ 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