NIPY logo

Site Navigation

NIPY Community

Github repo

Table Of Contents

Previous topic

labs.mask

Next topic

labs.spatial_models.bsa_io

This Page

labs.spatial_models.bayesian_structural_analysis

Module: labs.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 published in: - Thirion et al. High level group analysis of FMRI data based on Dirichlet process mixture models, IPMI 2007 - Thirion et al. Accurate Definition of Brain Regions Position Through the Functional Landmark Approach, MICCAI 2010

Author : Bertrand Thirion, 2006-2011

Functions

nipy.labs.spatial_models.bayesian_structural_analysis.bsa_dpmm(bf, gf0, sub, gfc, dmax, thq, ths, verbose=0)

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

Parameters :

bf list of nipy.labs.spatial_models.hroi.HierarchicalROI 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

verbose=0, verbosity mode :

Returns :

crmap: array of shape (nnodes): :

the resulting group-level labelling of the space

LR: a instance of sbf.LandmarkRegions 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.labs.spatial_models.hroi.Nroi instances :

representing individual ROIs

p: array of shape (nnodes): :

likelihood of the data under H1 over some sampling grid

nipy.labs.spatial_models.bayesian_structural_analysis.bsa_dpmm2(bf, gf0, sub, gfc, dmax, thq, ths, verbose)

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

Parameters :

bf list of nipy.labs.spatial_models.hroi.HierarchicalROI 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 false 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

verbose=0, verbosity mode :

Returns :

crmap: array of shape (nnodes): :

the resulting group-level labelling of the space

LR: a instance of sbf.LandmarkRegions 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.labs.spatial_models.hroi.Nroi instances :

representing individual ROIs

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

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

nipy.labs.spatial_models.bayesian_structural_analysis.compute_BSA_loo(dom, lbeta, dmax, thq=0.5, smin=5, ths=0, theta=3.0, verbose=0)

Compute the Bayesian Structural Activation paterns - with statistical validation

Parameters :

dom: StructuredDomain instance, :

Description of the spatial context of the data

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

the multi-subject statistical maps

dmax float>0: :

expected cluster std in the common space in units of coord

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 :

method: string, optional, :

the method used to assess the prior significance of the regions

verbose=0: verbosity mode :

Returns :

mll : float

the average cross-validated log-likelihood across subjects

ml0 : float

the log-likelihood of the model under a global null hypothesis

nipy.labs.spatial_models.bayesian_structural_analysis.compute_BSA_quick(dom, lbeta, dmax, thq=0.5, smin=5, ths=0, theta=3.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 :

dom : StructuredDomain instance,

Description of the spatial context of the data

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

the multi-subject statistical maps

dmax float>0: :

expected cluster std in the common space in units of coord

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 :

method: string, optional, :

the method used to assess the prior significance of the regions

verbose=0: verbosity mode :

Returns :

crmap: array of shape (nnodes): :

the resulting group-level labelling of the space

LR: a instance of sbf.LandmarkRegions 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.labs.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

nipy.labs.spatial_models.bayesian_structural_analysis.compute_BSA_simple(dom, lbeta, dmax, thq=0.5, smin=5, ths=0, theta=3.0, method='prior', verbose=0)

Compute the Bayesian Structural Activation paterns simplified version

Parameters :

dom : StructuredDomain instance,

Description of the spatial context of the data

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

the multi-subject statistical maps

dmax float>0: :

expected cluster std in the common space in units of coord

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 :

method: string, optional, :

the method used to assess the prior significance of the regions

verbose=0: verbosity mode :

Returns :

crmap: array of shape (nnodes): :

the resulting group-level labelling of the space

LR: a instance of sbf.LandmarkRegions 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.labs.spatial_models.hroi.Nroi instances :

representing individual ROIs

p: array of shape (nnodes): :

likelihood of the data under H1 over some sampling grid

Notes

In that case, the DPMM is used to derive a spatial density of significant local maxima in the volume. Each terminal (leaf) region which is a posteriori significant enough is assigned to the nearest mode of this distribution

nipy.labs.spatial_models.bayesian_structural_analysis.compute_individual_regions(domain, lbeta, smin=5, theta=3.0, method='gauss_mixture', verbose=0, reshuffle=0, criterion='size', assign_val='weighted_mean')

Compute the individual regions that are real activation candidates

Parameters :

dom : StructuredDomain instance,

generic descriptor of the space domain

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

the multi-subject statistical maps

smin: int, optional :

minimal size of the regions to validate them

theta: float, optional :

first level threshold

method: string, optional, :

method that is used to provide priori significance can be ‘prior’, ‘gauss_mixture’, ‘gam_gauss’ or ‘emp_null’

verbose: verbosity mode, optional :

reshuffle: bool, otpional, :

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

criterion: string, optional, :

‘size’ or ‘volume’, thresholdding criterion

assign_val: string, optional, :

to be chosen in ‘weighted mean’, ‘mean’, ‘min’, ‘max’ heuristic to assigna blob-level signal

Returns :

bf list of nipy.labs.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 false 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.labs.spatial_models.bayesian_structural_analysis.dpmm(gfc, alpha, g0, g1, dof, prior_precision, gf1, sub, burnin, spatial_coords=None, nis=1000, co_clust=False, verbose=False)

Apply the dpmm analysis to compute clusters from regions coordinates

nipy.labs.spatial_models.bayesian_structural_analysis.signal_to_pproba(test, learn=None, method='prior', alpha=0.01, verbose=0)

Convert a set of z-values to posterior probabilities of not being active

Parameters :

test: array pf shape(n_samples), :

data that is assessed

learn: array pf shape(n_samples), optional :

data to learn a mixture model

method: string, optional, to be chosen within :

[‘gauss_mixture’, ‘emp_null’, ‘gam_gauss’, ‘prior’]

alpha: float in the [0,1], optional, :

parameter that yields the prior probability that a region is active should be chosen close to 0