algorithms.group.parcel_analysis

Module: algorithms.group.parcel_analysis

Inheritance diagram for nipy.algorithms.group.parcel_analysis:

Parcel-based group analysis of multi-subject image data.

Routines implementing Bayesian inference on group-level effects assumed to be constant within given brain parcels. The model accounts for both estimation errors and localization uncertainty in reference space of first-level images.

See:

Keller, Merlin et al (2008). Dealing with Spatial Normalization Errors in fMRI Group Inference using Hierarchical Modeling. Statistica Sinica; 18(4).

Keller, Merlin et al (2009). Anatomically Informed Bayesian Model Selection for fMRI Group Data Analysis. In MICCAI’09, Lecture Notes in Computer Science; 5762:450–457.

Roche, Alexis (2012). OHBM’12 talk, slides at: https://sites.google.com/site/alexisroche/slides/Talk_Beijing12.pdf

ParcelAnalysis

class nipy.algorithms.group.parcel_analysis.ParcelAnalysis(con_imgs, parcel_img, parcel_info=None, msk_img=None, vcon_imgs=None, design_matrix=None, cvect=None, fwhm=8, smooth_method='default', res_path=None, write_smoothed_images=False)

Bases: object

__init__(con_imgs, parcel_img, parcel_info=None, msk_img=None, vcon_imgs=None, design_matrix=None, cvect=None, fwhm=8, smooth_method='default', res_path=None, write_smoothed_images=False)

Bayesian parcel-based analysis.

Given a sequence of independent images registered to a common space (for instance, a set of contrast images from a first-level fMRI analysis), perform a second-level analysis assuming constant effects throughout parcels defined from a given label image in reference space. Specifically, a model of the following form is assumed:

Y = X * beta + variability,

where Y denotes the input image sequence, X is a design matrix, and beta are parcel-wise parameter vectors. The algorithm computes the Bayesian posterior probability of beta in each parcel using an expectation propagation scheme.

Parameters:

con_imgs: sequence of nipy-like images

Images input to the group analysis.

parcel_img: nipy-like image

Label image where each label codes for a parcel.

parcel_info: sequence of arrays, optional

A sequence of two arrays with same length equal to the number of distinct parcels consistently with the parcel_img argument. The first array gives parcel names and the second, parcel values, i.e., corresponding intensities in the associated parcel image. By default, parcel values are taken as np.unique(parcel_img.get_fdata()) and parcel names are these values converted to strings.

msk_img: nipy-like image, optional

Binary mask to restrict analysis. By default, analysis is carried out on all parcels with nonzero value.

vcon_imgs: sequence of nipy-like images, optional

First-level variance estimates corresponding to con_imgs. This is useful if the input images are “noisy”. By default, first-level variances are assumed to be zero.

design_matrix: array, optional

If None, a one-sample analysis model is used. Otherwise, an array with shape (n, p) where n matches the number of input scans, and p is the number of regressors.

cvect: array, optional

Contrast vector of interest. The method makes an inference on the contrast defined as the dot product cvect’*beta, where beta are the unknown parcel-wise effects. If None, cvect is assumed to be np.array((1,)). However, the cvect argument is mandatory if design_matrix is provided.

fwhm: float, optional

A parameter that represents the localization uncertainty in reference space in terms of the full width at half maximum of an isotropic Gaussian kernel.

smooth_method: str, optional

One of ‘default’ and ‘spm’. Setting smooth_method=spm results in simply smoothing the input images using a Gaussian kernel, while the default method involves more complex smoothing in order to propagate spatial uncertainty into the inference process.

res_path: str, optional

An existing path to write output images. If None, no output is written.

write_smoothed_images: bool, optional

Specify whether smoothed images computed throughout the inference process are to be written on disk in res_path.

dump_results(path=None)

Save parcel analysis information in NPZ file.

parcel_maps(full_res=True)

Compute parcel-based posterior contrast means and positive contrast probabilities.

Parameters:

full_res: boolean

If True, the output images will be at the same resolution as the parcel image. Otherwise, resolution will match the first-level images.

Returns:

pmap_mu_img: nipy image

Image of posterior contrast means for each parcel.

pmap_prob_img: nipy image

Corresponding image of posterior probabilities of positive contrast.

t_map()

Compute voxel-wise t-statistic map. This map is different from what you would get from an SPM-style mass univariate analysis because the method accounts for both spatial uncertainty in reference space and possibly errors on first-level inputs (if variance images are provided).

Returns:

tmap_img: nipy image

t-statistic map.

nipy.algorithms.group.parcel_analysis.parcel_analysis(con_imgs, parcel_img, msk_img=None, vcon_imgs=None, design_matrix=None, cvect=None, fwhm=8, smooth_method='default', res_path=None)

Helper function for Bayesian parcel-based analysis.

Given a sequence of independent images registered to a common space (for instance, a set of contrast images from a first-level fMRI analysis), perform a second-level analysis assuming constant effects throughout parcels defined from a given label image in reference space. Specifically, a model of the following form is assumed:

Y = X * beta + variability,

where Y denotes the input image sequence, X is a design matrix, and beta are parcel-wise parameter vectors. The algorithm computes the Bayesian posterior probability of cvect’*beta, where cvect is a given contrast vector, in each parcel using an expectation propagation scheme.

Parameters:

con_imgs: sequence of nipy-like images

Images input to the group analysis.

parcel_img: nipy-like image

Label image where each label codes for a parcel.

msk_img: nipy-like image, optional

Binary mask to restrict analysis. By default, analysis is carried out on all parcels with nonzero value.

vcon_imgs: sequence of nipy-like images, optional

First-level variance estimates corresponding to con_imgs. This is useful if the input images are “noisy”. By default, first-level variances are assumed to be zero.

design_matrix: array, optional

If None, a one-sample analysis model is used. Otherwise, an array with shape (n, p) where n matches the number of input scans, and p is the number of regressors.

cvect: array, optional

Contrast vector of interest. The method makes an inference on the contrast defined as the dot product cvect’*beta, where beta are the unknown parcel-wise effects. If None, cvect is assumed to be np.array((1,)). However, the cvect argument is mandatory if design_matrix is provided.

fwhm: float, optional

A parameter that represents the localization uncertainty in reference space in terms of the full width at half maximum of an isotropic Gaussian kernel.

smooth_method: str, optional

One of ‘default’ and ‘spm’. Setting smooth_method=spm results in simply smoothing the input images using a Gaussian kernel, while the default method involves more complex smoothing in order to propagate spatial uncertainty into the inference process.

res_path: str, optional

An existing path to write output images. If None, no output is written.

Returns:

pmap_mu_img: nipy image

Image of posterior contrast means for each parcel.

pmap_prob_img: nipy image

Corresponding image of posterior probabilities of positive contrast.