neurospin.spatial_models.bayesian_structural_analysis

Module: neurospin.spatial_models.bayesian_structural_analysis

The main routine of this package that aims at performing the extraction of ROIs from multisubject dataset using the localization and activation strength of extracted regions. This has been puclished in Thirion et al. High level group analysis of FMRI data based on Dirichlet process mixture models, IPMI 2007

Author : Bertrand Thirion, 2006-2009

Functions

nipy.neurospin.spatial_models.bayesian_structural_analysis.bsa_dpmm(Fbeta, bf, gf0, sub, gfc, coord, dmax, thq, ths, g0, verbose=0)

Estimation of the population level model of activation density using dpmm and inference

Parameters:

Fbeta nipy.neurospin.graph.field.Field instance :

an describing the spatial relationships in the dataset. nbnodes = Fbeta.V

bf list of nipy.neurospin.spatial_models.hroi.Nroi instances :

representing individual ROIs let nr be the number of terminal regions across subjects

gf0, array of shape (nr) :

the mixture-based prior probability that the terminal regions are true positives

sub, array of shape (nr) :

the subject index associated with the terminal regions

gfc, array of shape (nr, coord.shape[1]) :

the coordinates of the of the terminal regions

dmax float>0: :

expected cluster std in the common space in units of coord

thq = 0.5 (float in the [0,1] interval) :

p-value of the prevalence test

ths=0, float in the rannge [0,nsubj] :

null hypothesis on region prevalence that is rejected during inference

g0 = 1.0 (float): constant value of the uniform density :

over the (compact) volume of interest

verbose=0, verbosity mode :

Returns:

crmap: array of shape (nnodes): :

the resulting group-level labelling of the space

LR: a instance of sbf.Landmark_regions that describes the ROIs found :

in inter-subject inference If no such thing can be defined LR is set to None

bf: List of nipy.neurospin.spatial_models.hroi.Nroi instances :

representing individual ROIs

p: array of shape (nnodes): :

likelihood of the data under H1 over some sampling grid

nipy.neurospin.spatial_models.bayesian_structural_analysis.bsa_dpmm2(Fbeta, bf, gf0, sub, gfc, coord, dmax, thq, ths, g0, verbose)

Estimation of the population level model of activation density using dpmm and inference

Parameters:

Fbeta nipy.neurospin.graph.field.Field instance :

an describing the spatial relationships in the dataset. nbnodes = Fbeta.V

bf list of nipy.neurospin.spatial_models.hroi.Nroi instances :

representing individual ROIs let nr be the number of terminal regions across subjects

gf0, array of shape (nr) :

the mixture-based prior probability that the terminal regions are true positives

sub, array of shape (nr) :

the subject index associated with the terminal regions

gfc, array of shape (nr, coord.shape[1]) :

the coordinates of the of the terminal regions

dmax float>0: :

expected cluster std in the common space in units of coord

thq = 0.5 (float in the [0,1] interval) :

p-value of the prevalence test

ths=0, float in the rannge [0,nsubj] :

null hypothesis on region prevalence that is rejected during inference

g0 = 1.0 (float): constant value of the uniform density :

over the (compact) volume of interest

verbose=0, verbosity mode :

Returns:

crmap: array of shape (nnodes): :

the resulting group-level labelling of the space

LR: a instance of sbf.Landmark_regions that describes the ROIs found :

in inter-subject inference If no such thing can be defined LR is set to None

bf: List of nipy.neurospin.spatial_models.hroi.Nroi instances :

representing individual ROIs

Coclust: array of shape (nr,nr): :

co-labelling matrix that gives for each pair of cross_subject regions how likely they are in the same class according to the model

compute_BSA_dev(Fbeta, lbeta, coord, dmax, xyz, affine=array([[ 1., 0., 0., 0.],

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

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

[ 0., 0., 0., 1.]]), shape=None, thq=0.90000000000000002, smin=5, ths=0, theta=3.0, g0=1.0, bdensity=0, verbose=0)

Compute the Bayesian Structural Activation paterns

Parameters:

Fbeta : nipy.neurospin.graph.field.Field instance

an describing the spatial relationships in the dataset. nbnodes = Fbeta.V

lbeta: an array of shape (nbnodes, subjects): :

the multi-subject statistical maps

coord array of shape (nnodes,3): :

spatial coordinates of the nodes

xyz array of shape (nnodes,3): :

the grid coordinates of the field

affine=np.eye(4), array of shape(4,4) :

coordinate-defining affine transformation

shape=None, tuple of length 3 defining the size of the grid :

implicit to the discrete ROI definition

thq = 0.5 (float): posterior significance threshold should be in [0,1] :

smin = 5 (int): minimal size of the regions to validate them :

theta = 3.0 (float): first level threshold :

g0 = 1.0 (float): constant values of the uniform density :

over the (compact) volume of interest

bdensity=0 if bdensity=1, the variable p in ouput :

contains the likelihood of the data under H1 on the set of input nodes

verbose=0 : verbosity mode

compute_BSA_ipmi(Fbeta, lbeta, coord, dmax, xyz, affine=array([[ 1., 0., 0., 0.],

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

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

[ 0., 0., 0., 1.]]), shape=None, thq=0.5, smin=5, ths=0, theta=3.0, g0=1.0, bdensity=0, verbose=0)

Compute the Bayesian Structural Activation patterns with approach described in IPMI‘07 paper

Parameters:

Fbeta : nipy.neurospin.graph.field.Field instance

an describing the spatial relationships in the dataset. nbnodes = Fbeta.V

lbeta: an array of shape (nbnodes, subjects): :

the multi-subject statistical maps

coord array of shape (nnodes,3): :

spatial coordinates of the nodes

xyz array of shape (nnodes,3): :

the grid coordinates of the field

affine=np.eye(4), array of shape(4,4) :

coordinate-defining affine transformation

shape=None, tuple of length 3 defining the size of the grid :

implicit to the discrete ROI definition

thq = 0.5 (float): posterior significance threshold should be in [0,1] :

smin = 5 (int): minimal size of the regions to validate them :

theta = 3.0 (float): first level threshold :

g0 = 1.0 (float): constant values of the uniform density :

over the (compact) volume of interest

bdensity=0 if bdensity=1, the variable p in ouput :

contains the likelihood of the data under H1 on the set of input nodes

verbose=0 : verbosity mode

compute_BSA_loo(Fbeta, lbeta, coord, dmax, xyz, affine=array([[ 1., 0., 0., 0.],

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

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

[ 0., 0., 0., 1.]]), shape=None, thq=0.5, smin=5, ths=0, theta=3.0, g0=1.0, verbose=0)

Compute the Bayesian Structural Activation paterns - with statistical validation

Parameters:

Fbeta : nipy.neurospin.graph.field.Field instance

an describing the spatial relationships in the dataset. nbnodes = Fbeta.V

lbeta: an array of shape (nbnodes, subjects): :

the multi-subject statistical maps

coord array of shape (nnodes,3): :

spatial coordinates of the nodes

dmax float>0: :

expected cluster std in the common space in units of coord

xyz array of shape (nnodes,3): :

the grid coordinates of the field

affine=np.eye(4), array of shape(4,4) :

coordinate-defining affine transformation

shape=None, tuple of length 3 defining the size of the grid :

implicit to the discrete ROI definition

thq = 0.5 (float): :

posterior significance threshold should be in the [0,1] interval

smin = 5 (int): minimal size of the regions to validate them :

theta = 3.0 (float): first level threshold :

g0 = 1.0 (float): constant values of the uniform density :

over the (compact) volume of interest

verbose=0: verbosity mode :

compute_BSA_simple(Fbeta, lbeta, coord, dmax, xyz, affine=array([[ 1., 0., 0., 0.],

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

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

[ 0., 0., 0., 1.]]), shape=None, thq=0.5, smin=5, ths=0, theta=3.0, g0=1.0, verbose=0)

Compute the Bayesian Structural Activation paterns - simplified version

Parameters:

Fbeta : nipy.neurospin.graph.field.Field instance

an describing the spatial relationships in the dataset. nbnodes = Fbeta.V

lbeta: an array of shape (nbnodes, subjects): :

the multi-subject statistical maps

coord array of shape (nnodes,3): :

spatial coordinates of the nodes

dmax float>0: :

expected cluster std in the common space in units of coord

xyz array of shape (nnodes,3): :

the grid coordinates of the field

affine=np.eye(4), array of shape(4,4) :

coordinate-defining affine transformation

shape=None, tuple of length 3 defining the size of the grid :

implicit to the discrete ROI definition

thq = 0.5 (float): :

posterior significance threshold should be in the [0,1] interval

smin = 5 (int): minimal size of the regions to validate them :

theta = 3.0 (float): first level threshold :

g0 = 1.0 (float): constant values of the uniform density :

over the (compact) volume of interest

verbose=0: verbosity mode :

compute_BSA_simple_quick(Fbeta, lbeta, coord, dmax, xyz, affine=array([[ 1., 0., 0., 0.],

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

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

[ 0., 0., 0., 1.]]), shape=None, thq=0.5, smin=5, ths=0, theta=3.0, g0=1.0, verbose=0)

Idem compute_BSA_simple, but this one does not estimate the full density (on small datasets, it can be much faster)

Parameters:

Fbeta : nipy.neurospin.graph.field.Field instance

an describing the spatial relationships in the dataset. nbnodes = Fbeta.V

lbeta: an array of shape (nbnodes, subjects): :

the multi-subject statistical maps

coord array of shape (nnodes,3): :

spatial coordinates of the nodes

dmax float>0: :

expected cluster std in the common space in units of coord

xyz array of shape (nnodes,3): :

the grid coordinates of the field

affine=np.eye(4), array of shape(4,4) :

coordinate-defining affine transformation

shape=None, tuple of length 3 defining the size of the grid :

implicit to the discrete ROI definition

thq = 0.5 (float): :

posterior significance threshold should be in the [0,1] interval

smin = 5 (int): minimal size of the regions to validate them :

theta = 3.0 (float): first level threshold :

g0 = 1.0 (float): constant values of the uniform density :

over the (compact) volume of interest

verbose=0: verbosity mode :

compute_individual_regions(Fbeta, lbeta, coord, dmax, xyz, affine=array([[ 1., 0., 0., 0.],

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

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

[ 0., 0., 0., 1.]]), shape=None, smin=5, theta=3.0, verbose=0, reshuffle=0)

Compute the Bayesian Structural Activation paterns - with statistical validation

Parameters:

Fbeta : nipy.neurospin.graph.field.Field instance

an describing the spatial relationships in the dataset. nbnodes = Fbeta.V

lbeta: an array of shape (nbnodes, subjects): :

the multi-subject statistical maps

coord array of shape (nnodes,3): :

spatial coordinates of the nodes

dmax float>0: :

expected cluster std in the common space in units of coord

xyz array of shape (nnodes,3): :

the grid coordinates of the field

affine=np.eye(4), array of shape(4,4) :

coordinate-defining affine transformation

shape=None, tuple of length 3 defining the size of the grid :

implicit to the discrete ROI definition

smin = 5 (int): minimal size of the regions to validate them :

theta = 3.0 (float): first level threshold :

verbose=0: verbosity mode :

reshuffle=0: if nonzero, reshuffle the positions; this affects bf and gfc :

Returns:

bf list of nipy.neurospin.spatial_models.hroi.Nroi instances :

representing individual ROIs let nr be the number of terminal regions across subjects

gf0, array of shape (nr) :

the mixture-based prior probability that the terminal regions are true positives

sub, array of shape (nr) :

the subject index associated with the terminal regions

gfc, array of shape (nr, coord.shape[1]) :

the coordinates of the of the terminal regions

nipy.neurospin.spatial_models.bayesian_structural_analysis.infer_LR(bf, thq=0.94999999999999996, ths=0, verbose=0)

Given a list of hierarchical ROIs, and an associated labelling, this creates an Amer structure wuch groups ROIs with the same label.

Parameters:

bf : list of nipy.neurospin.spatial_models.hroi.Nroi instances

it is assumd that each list corresponds to one subject each NROI is assumed to have the roi_features ‘position’, ‘label’ and ‘posterior_proba’ defined

thq=0.95,ths=0 defines the condition (c): :

(c) A label should be present in ths subjects with a probability>thq in order to be valid

nipy.neurospin.spatial_models.bayesian_structural_analysis.make_crmap(AF, coord, verbose=0)

crmap = make_crmap(AF,coord) Compute the spatial map associated with the AF i.e. the confidence interfval for the position of the different landmarks

Parameters:

- AF the list of group-level landmarks regions :

- coord: array of shape(nvox,3): the position of the reference points :