neurospin.spatial_models.roi

Module: neurospin.spatial_models.roi

Inheritance diagram for nipy.neurospin.spatial_models.roi:

Classes

DiscreteROI

DiscreteROI(id='roi', affine=array([[ 1., 0., 0., 0.],

[ 0., 1., 0., 0.],

[ 0., 0., 1., 0.],

[ 0., 0., 0., 1.]]), shape=None)

Bases: object

Temporary ROI class for nipy Ultimately, it should be merged with the nipy class

ROI definition requires an identifier an affine transform and a shape that can be used to

translate grid coordinates to position and to generate images from the DiscreteROI structure

The ROI can be derived from a image

roi.features is a dictionary of informations on the ROI elements. It is assumed that the ROI is sampled on a discrete grid, so that each feature is in fact a (voxel,feature_dimension) array

Methods

check_header
from_binary_image
from_labelled_image
from_position
from_position_and_image
get_feature
make_image
plot_feature
representative_feature
set_feature
set_feature_from_image
set_feature_from_masked_data

DiscreteROI.check_header(image_path)

checks that the image is in the header of self

Parameters:

image_path: (string) the path of an image (nifti) :

Returns:

True if the affine and shape of the given nifti file correpond :

to the ROI’s. :

DiscreteROI.from_binary_image(image_path)

Take all the <>0 sites of the image as the ROI

Parameters:

image_path: string :

the path of an image

DiscreteROI.from_labelled_image(image_path, label)

Define the ROI as the set of voxels of the image that have the pre-defined label

Parameters:

image_path: ndarray :

a label (discrete valued) image

label: int :

the desired label

DiscreteROI.from_position(position, radius)

A ball in the grid requires that the grid and header are defined

DiscreteROI.from_position_and_image(image_path, position)

Define the ROI as the set of voxels of the image that is closest to the provided position

Parameters:

image_path: string, :

the path of a label (discrete valued) image

position: array of shape (3,) :

x, y, z position in the world space

Notes

everything could be performed in the image space

DiscreteROI.get_feature(fid)

return the feature corrsponding to fid, if it exists

DiscreteROI.make_image(image_path=None)

write a binary nifty image where the nonzero values are the ROI mask

Parameters:

image_path: string, optional :

the desired image name

DiscreteROI.plot_feature(fid)

boxplot the feature within the ROI

DiscreteROI.representative_feature(fid, method='mean')

Compute a statistical representative of the within-ROI feature

DiscreteROI.set_feature(fid, data)

Given an array of data that is assumed to comprise the ROI, get the subset of values that correponds to voxel-based data in the ROI

Parameters:

fid: string :

feature identifier, e.g. data (array of shape (self.VolumeExtent))

Returns:

ldata: ndarray of shape (roi.nbvox, dim) :

the ROI-based feature

Notes

this function creates a reduced feature array corresponding to the ROI item.

DiscreteROI.set_feature_from_image(fid, image_path)

extract some roi-related information from an image

Parameters:

fid: string :

feature id

image: string :

image path

DiscreteROI.set_feature_from_masked_data(fid, data, mask)

idem set_feature but the input data is thought to be masked

MultiROI

class nipy.neurospin.spatial_models.roi.MultiROI(id='multiple_roi', k=0)

Bases: object

This class describes multiple ROIs that are not ‘discretized’, i.e. sampled on a discrete grid there are only 3 main members: self.id: an identifier self.k the number of ROIs under consideration self.roi_features : a dictionary of roi properties

fixme : currently lacks an __add__ method, and a method to be transformed to a multiple_discrete_roi

Methods

append_roi
as_multiple_balls
check_features
clean
complete_roi_feature
plot_roi_feature
to_multiple_roi

__init__(id='roi', header=None)

Parameters:

id=”multiple_roi” string, roi identifier :

k=1, int, number of rois that are included in the structure :

append_roi(roi)

as_multiple_balls(position, radius)

self.as_multiple_balls(position, radius) Given a set of positions and radii, defines one roi at each (position/radius) couple

Parameters:

position: array of shape (k,3): the set of positions :

radius: array of shape (k): the set of radii :

check_features()

check that self.roi_features have the coorect size i.e. f.shape[0]=self.k for f in self.roi_features

clean(valid)

remove the regions for which valid==0

Parameters:valid: (boolean) array of shape self.k :

complete_roi_feature(fid, values)

completes roi_feature corresponding to fid by appending the values

plot_roi_feature(fid)

boxplot the feature within the ROI Note that this assumes a 1-d feature

Parameters:fid the feature identifier :

to_multiple_roi(shape, affine)

Note can work only if radius/position features have been defined

MultipleROI

MultipleROI(id='multiple_roi', k=0, affine=array([[ 1., 0., 0., 0.],

[ 0., 1., 0., 0.],

[ 0., 0., 1., 0.],

[ 0., 0., 0., 1.]]), shape=None, xyz=None)

Bases: object

This is a class to deal with multiple discrete ROIs defined in a given space (mroi.affine, mroi.shape) provide the necessary referential information so that the mroi is basically defined as a multiple sets of 3D coordinates finally, there is two associated feature dictionaries:

roi_features: list of roi-level features

it is assumed that each feature is an (roi,feature_dim) array, i.e. each roi is assumed homogeneous wrt the feature

discrete_features is a dictionary of informations sampled

on the discrete membre of the rois (voxels or vertices) each feature os thus a list of self.k arrays of shape (roi_size, feature_dimension)

fixme : - can create an ROI with k =0 ? Deal with taht case properly - merge append_balls and as_multiple_balls

Methods

append_balls
append_discrete_ROI
as_multiple_balls
check_consistency
check_features
check_header
clean
complete_roi_feature
compute_discrete_position
discrete_to_roi_features
feature_argmax
from_labelled_image
get_roi_feature
get_size
make_image
plot_discrete_feature
plot_roi_feature
remove_roi_feature
set_discrete_feature
set_discrete_feature_from_image
set_discrete_feature_from_index
set_roi_feature
set_roi_feature_from_image
set_xyz

MultipleROI.append_balls(position, radius)

idem self.as_multiple_balls, but the ROIs are added fixme : should be removed from the class as soon as __add__ is implemented

MultipleROI.append_discrete_ROI(droi)

complete self with a discrete roi only the features that have a common ideas between self and droi are kept

MultipleROI.as_multiple_balls(position, radius)

self.as_multiple_balls(position, radius) Given a set of positions and radii, defines one roi at each (position/radius) couple

Parameters:

position: array of shape (k,3): the set of positions :

radius: array of shape (k): the set of radii :

MultipleROI.check_consistency()

Check the consistency of the input values: affine should be a (4,4) array

all values of xyz should be in the range [0,d1]*[0,d2]*[0,d3] where self.shape = (d1,d2,d3), if shape is defined

MultipleROI.check_features()

check that self.roi_features have the coorect size i.e. f.shape[0]=self.k for f in self.roi_features and that self.discrete features have the correct size i.e. for f in self.roi_features: f is a list of length self.k f[i] is an array with dimensions consistent with xyz

Note: features that are not found consistent are removed

MultipleROI.check_header(image_path)

checks that the image is in the header of self

Parameters:image_path: (string) the path of an image :

MultipleROI.clean(valid)

remove the regions for which valid==0

Parameters:valid: (boolean) array of shape self.k :

MultipleROI.complete_roi_feature(fid, values)

completes roi_feature corresponding to fid by appending the values

MultipleROI.compute_discrete_position()

Create a ‘position’ feature based on self.affine and self.indexes, which is simply an affine transform from self.xyz to the space of self

fixme : if a position is already available it does not need to be computed

the computed position is returned

MultipleROI.discrete_to_roi_features(fid, method='average')

Compute an ROI-level feature given the discrete features

Parameters:

fid(string) the discrete feature under consideration :

method=’average’ the assessment method :

Returns:

ldata: array of shape [self.k,fdim ] :

the computed roi-level feature

MultipleROI.feature_argmax(fid)

Returns for each roi the index of the discrete element that is the within-ROI for the fid feature this makes sense only if the corresponding feature has dimension 1

MultipleROI.from_labelled_image(image_path, labels=None, add=True)

All the voxels of the image that have non-zero-value self.k becomes the number of values of the (discrete) image

Parameters:

image_path: string :

path of a label (discrete valued) image

labels=None : array of shape (nlabels)

the set of image labels that shall be used as ROI definitions By default, all the image labels are used

MultipleROI.get_roi_feature(fid)

return sthe searched feature

MultipleROI.get_size()

return the number of voxels per ROI in one array

MultipleROI.make_image(path=None)

write a int image where the nonzero values are the ROIs

Parameters:

path: string, optional :

the desired image path

Returns:

brifti image instance :

MultipleROI.plot_discrete_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 :

MultipleROI.plot_roi_feature(fid)

boxplot the feature within the ROI Note that this assumes a 1-d feature

Parameters:

fid string, :

the feature identifier

MultipleROI.remove_roi_feature(fid)

removes the specified feature

MultipleROI.set_discrete_feature(fid, data)

Parameters:

fid (string): feature identifier :

data: list of self.k arrays with shape(nk,p),with p>0 :

nk = self.xyz[k].shape[0] (number of elements in ROI k) this function simply stores data

MultipleROI.set_discrete_feature_from_image(fid, image_path=None, image=None)

extract some discrete information from an image

Parameters:

fid: string, feature id :

image_path, string, optional :

input image path

image, brfiti image path, :

input image

Note that either image_path or image has to be provided :

MultipleROI.set_discrete_feature_from_index(fid, data)

Assuming that self.discrete_feature[‘index’] exists this extracts the values from data corresponding to the index and sets these are self.discrete_feature[fid]

Parameters:

fid (string): feature id :

data: array of shape(nbitem,k) where nbitem is supposed :

to be greater than any value in self.discrete_feature[‘index’]

MultipleROI.set_roi_feature(fid, data)

this function simply stores data

Parameters:

fid (string): feature identifier, e.g. :

data: array of shape(self.k,p),with p>0 :

MultipleROI.set_roi_feature_from_image(fid, image_path, method='average')

extract some roi-related information from an image

Parameters:

fid: feature id :

image_path(string): path of the feature-defining image :

method=’average’ (string) : take the roi feature as

the average feature over the ROI

MultipleROI.set_xyz(xyz)

set manually the values of xyz xyz is a list of arrays that contains the coordinates of all ROIs voxels

ROI

class nipy.neurospin.spatial_models.roi.ROI(id='roi')

Bases: object

Generic ROI class

Merely a container: an abstract ROI

Methods

as_ball

__init__(id='roi')

Parameters:

id: string :

roi identifier

as_ball(position, radius)

A ball in the grid requires that the grid and header are defined