# 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_data()) 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: sequece 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. 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: sequece 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. 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.