algorithms.group.parcel_analysis¶
Module: algorithms.group.parcel_analysis
¶
Inheritance diagram for nipy.algorithms.group.parcel_analysis
:
Parcelbased group analysis of multisubject image data.
Routines implementing Bayesian inference on grouplevel effects assumed to be constant within given brain parcels. The model accounts for both estimation errors and localization uncertainty in reference space of firstlevel 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 parcelbased analysis.
Given a sequence of independent images registered to a common space (for instance, a set of contrast images from a firstlevel fMRI analysis), perform a secondlevel 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 parcelwise parameter vectors. The algorithm computes the Bayesian posterior probability of beta in each parcel using an expectation propagation scheme.
Parameters: con_imgs: sequence of nipylike images
Images input to the group analysis.
parcel_img: nipylike 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: nipylike image, optional
Binary mask to restrict analysis. By default, analysis is carried out on all parcels with nonzero value.
vcon_imgs: sequece of nipylike images, optional
Firstlevel variance estimates corresponding to con_imgs. This is useful if the input images are “noisy”. By default, firstlevel variances are assumed to be zero.
design_matrix: array, optional
If None, a onesample 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 parcelwise 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 parcelbased 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 firstlevel 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 voxelwise tstatistic map. This map is different from what you would get from an SPMstyle mass univariate analysis because the method accounts for both spatial uncertainty in reference space and possibly errors on firstlevel inputs (if variance images are provided).
Returns: tmap_img: nipy image
tstatistic 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 parcelbased analysis.
Given a sequence of independent images registered to a common space (for instance, a set of contrast images from a firstlevel fMRI analysis), perform a secondlevel 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 parcelwise 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 nipylike images
Images input to the group analysis.
parcel_img: nipylike image
Label image where each label codes for a parcel.
msk_img: nipylike image, optional
Binary mask to restrict analysis. By default, analysis is carried out on all parcels with nonzero value.
vcon_imgs: sequece of nipylike images, optional
Firstlevel variance estimates corresponding to con_imgs. This is useful if the input images are “noisy”. By default, firstlevel variances are assumed to be zero.
design_matrix: array, optional
If None, a onesample 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 parcelwise 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.