labs.spatial_models.mroi

Module: labs.spatial_models.mroi

Inheritance diagram for nipy.labs.spatial_models.mroi:

digraph inheritance3be2910832 { rankdir=LR; size="8.0, 12.0"; "spatial_models.mroi.SubDomains" [URL="#nipy.labs.spatial_models.mroi.SubDomains",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",target="_top",tooltip="This is a class to represent multiple ROI objects, where the"]; }

Class

SubDomains

class nipy.labs.spatial_models.mroi.SubDomains(domain, label, id=None)

Bases: object

This is a class to represent multiple ROI objects, where the reference to a given domain is explicit.

A mutliple ROI object is a set of ROI defined on a given domain, each having its own ‘region-level’ characteristics (ROI features).

Every voxel of the domain can have its own characteristics yet, defined at the ‘voxel-level’, but those features can only be accessed familywise (i.e. the values are grouped by ROI).

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.

__init__(domain, label, id=None)

Initialize subdomains instance

Parameters

domain: ROI instance

defines the spatial context of the SubDomains

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 select_id() mapping method instead.

id: array of shape (n_roi)

Define the ROI identifiers. Once an id has been associated to a ROI it becomes impossible to change it using the API. Hence, one should access ROI through their id to avoid hazardous manipulations.

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.

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.

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.

copy()

Returns a copy of self.

Note that self.domain is not copied.

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_size(id=None)

Get ROI size (counted in terms of voxels)

Parameters

id: any hashable type

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

Returns

size: int

if an id is provided,

or list of int

if no id provided (default)

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_volume(id=None)

Get ROI volume

Parameters

id: any hashable type

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

Returns

volume : float

if an id is provided,

or list of float

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)

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.

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

Compute a ROI representative of a given feature.

Parameters

fid : str

Feature id

method : str, optional

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

id : any hashable type, optional

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.

assess_quality: bool, optional

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.

Returns

summary_feature: np.ndarray, shape=(self.k, feature_dim)

Representative feature computed according to method.

remove_feature(fid)

Remove a certain feature

Parameters

fid: str

Feature id

Returns

f : object

The removed feature.

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.

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

get_roi_feature(fid, id=None)

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.

remove_roi_feature(fid)

Remove a certain ROI feature.

The id ROI feature cannot be removed.

Returns

f : object

The removed Roi feature.

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

select_roi(id_list)

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

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.mroi.subdomain_from_array(labels, affine=None, nn=0)

Return a SubDomain from an n-d int array

Parameters

label: np.array instance

A supposedly boolean array that yields the regions.

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: int,

Neighboring system considered. Unused at the moment.

Notes

Only labels > -1 are considered.

nipy.labs.spatial_models.mroi.subdomain_from_balls(domain, positions, radii)

Create discrete ROIs as a set of balls within a certain coordinate systems.

Parameters

domain: StructuredDomain instance,

the description of a discrete domain

positions: array of shape(k, dim):

the positions of the balls

radii: array of shape(k):

the sphere radii

nipy.labs.spatial_models.mroi.subdomain_from_image(mim, nn=18)

Return a SubDomain instance from the input mask image.

Parameters

mim: NiftiIImage instance, or string path toward such an image

supposedly a label image

nn: int, optional

Neighboring system considered from the image can be 6, 18 or 26.

Returns

The MultipleROI instance

Notes

Only labels > -1 are considered

nipy.labs.spatial_models.mroi.subdomain_from_position_and_image(nim, pos)

Keep the set of labels of the image corresponding to a certain index so that their position is closest to the prescribed one.

Parameters

mim: NiftiIImage instance, or string path toward such an image

supposedly a label image

pos: array of shape(3) or list of length 3,

the prescribed position