neurospin.spatial_models.parcellation

Module: neurospin.spatial_models.parcellation

Inheritance diagram for nipy.neurospin.spatial_models.parcellation:

Generic Parcellation class: Contains all the items that define a multi-subject parcellation

Author : Bertrand Thirion, 2005-2008

TODO : add a method ‘global field’, i.e. non-subject-specific info

Parcellation

class nipy.neurospin.spatial_models.parcellation.Parcellation(k, ijk, label, group_labels=None, referential=None, subjects=[])

Bases: object

This is the basic Parcellation class: It is defined discretely , i.e. the parcellation is an explicit function on the set of voxels (or equivalently a labelling) we explictly handle the case of multiple subjects, where the labelling varies with the subjects

k is the number of parcels/classes ijk: array of shape(nbvoxels,anatomical_dimension)

that represents the grid of voxels to be parcelled (the same for all subjects) typically anatomical_dimension=3

referential rerpresents the image referential,

resoltuion, position and size this is expressed as an affine (4,4) transformation matrix

label (nbvox, subjects) array: nbvox is the number of voxels

within the binary mask if the voxel is not labelled in a given subject, then the label is -1 thus the label has integer values in [-1,k-1]

group_labels is a labelling of the template subjects=none is a list of ids of the subjects

by default, is is set as range(self.nb_subj)

Methods

PRFX
add_subjects
average_feature
boxplot_feature
check
copy
empty_parcels
get_feature
isfield
make_feature
make_feature_from_info
population
remove_feature
set_feature
set_group_labels
set_info
set_labels
set_subjects
var_feature_intra
variance_inter
variance_intra

__init__(k, ijk, label, group_labels=None, referential=None, subjects=[])

Constructor

PRFX(fid, zstat=1, DMtx=None)

Compute the Random effects of the feature on the parcels across subjects

Parameters:

fid : str

feature identifier; it is assumed that the feature is 1-dimensional

zstat : int

indicator variable for the output variate. If ztsat==0, the basic student statistic is returned. If zstat==1, the student stat is converted to a normal(z) variate

DMtx : None

design matrix for the model. So far, it is assumed that DMtx = np.ones(self.nb_subj)

Returns:

RFX: array with shape (self.k,fdim) :

the parcel-based RFX.

add_subjects(label, nsubj_id)

self.add_subjects(label,subj_id) Add some subjects to the structure Not implemented yet.

average_feature(Feature, subj=-1)

compute parcel-based fetaure bu averaging voxel-based quantities

Parameters:

Feature is a list of length self.nb_subj, :

so that for each s in 0..self.nb_subj-1, that Feature[s] is an (nvox,fdim)-shaped array where nvox is the number of voxels in subject s with label >-1

subj = -1: subject in which this is performed :

if subj==-1, this is in all subjects, and it is checked that the fid is not defined yet if subj>-1, this is in one particular subject, and Feature merely is an array, not a list

Returns:

PF: array of shape (self.nb_subj,self.k,fdim) if subj==-1 :

or (self.k,fdim) containing the parcel-based features.

boxplot_feature(pid, fids)

self.show_feature(pid,fids) This function makes a boxplot of the feature distribution in a given parcel across subjects

Parameters:

pid = parcel identifier an integer within the [0..self.K] range :

fids = list of features of inetegers :

check()

Some sanity check on the arguments of the class

copy()

Pa = self.copy() copy method

empty_parcels()

q = self.empty_parcels() returns the ids of all parcels that are empty

get_feature(fid)

Get feature to the feature list of the structure

Parameters:

fid, string, the feature id :

Returns:

feature: array of shape(self.nb_subj,self.k,fdim), :

where fdim is the feature dimension

isfield(fid)

tests whether fid is known as a field

make_feature(data, fid, subj=-1, method='average')

Compute and Add a feature to the feature list of the structure

Parameters:

data: a list of arrays of shape(nbvoxels,fdim), :

where fdim is the feature dimension Note: if subj>-1, then data is simply an array of shape (nbvoxels,fdim)

fid, string, the feature id :

subj = -1: subject in which this is performed :

if subject==-1, this is in all subjects, and it is checked that the fid is not defined yet otherwise, this is in one particular subject, and the feature may be overriden

method = ‘average’, the way to compute the feature :

make_feature_from_info(fid)

population()

pop = self.population() the population of parcellation is the number of voxels included in each parcel this function simply returns an array of shape (number of parcels, number of subjects) that contains the parcel population

remove_feature(fid)

Remove feature from the feature list of the structure

Parameters:fid, string, the feature id :

set_feature(feature, fid)

self.set_feature(feature,fid): Add a feature to the feature list of the structure

Parameters:

feature: array of shape(self.nb_subj,self.k,fdim), :

where fdim is the feature dimension

fid, string, the feature id :

set_group_labels(glabels)

self.reset_group_labels(glabels) reset the group labels

set_info(data, fid)

self.set_info(data,fid): Add some non-subject specific feature information defined on a voxel-by voxel basis

Parameters:

feature: an array of shape(self.nbvox,dim), :

where dim is the info dimension

fid : an identifier of the information

set_labels(label)

resets the label array of the class

Parameters:label = array of shape(self.k,self.nb_subj) :

set_subjects(subjects)

self.reset_subjects(subjects) reset the list of subjects name

Parameters:subjects = a list of subjects id with length self.nb_subj :

var_feature_intra(Feature)

compute the feature variance in each subject and each parcel

variance_inter(fid)

Compute the variance of the feature at each parcel across subjects

Parameters:

fid, string, the feature identifier :

Returns:

HI, array of shape (self.k) (?) :

the inter-subject variance

variance_intra(data, bweight=0)

Vintra = self.variance_intra(fid) Compute the variance of the feature at each parcel within each subject

Parameters:

data is the data on which the variance is estimated: :

this is a list of arrays

bweight=0: flag for the relative weighting of the parcels :

if bweight = 1, the variance of each parcels is weighted by its size else, all parcels are equally weighted

Returns:

VA : array of shape (self.k) of the variance