labs.spatial_models.parcel_io

Module: labs.spatial_models.parcel_io

Utility functions for mutli-subjectParcellation: this basically uses nipy io lib to perform IO opermation in parcel definition processes

Functions

nipy.labs.spatial_models.parcel_io.fixed_parcellation(mask_image, betas, nbparcel, nn=6, method='ward', write_dir=None, mu=10.0, verbose=0, fullpath=None)

Fixed parcellation of a given dataset

Parameters

domain/mask_image

betas: list of paths to activation images from the subject

nbparcel, int : number fo desired parcels

nn=6: number of nearest neighbors to define the image topology

(6, 18 or 26)

method=’ward’: clustering method used, to be chosen among

‘ward’, ‘gkm’, ‘ward_and-gkm’ ‘ward’: Ward’s clustering algorithm ‘gkm’: Geodesic k-means algorithm, random initialization ‘gkm_and_ward’: idem, initialized by Ward’s clustering

write_di: string, topional, write directory.

If fullpath is None too, then no file output.

mu = 10., float: the relative weight of anatomical information

verbose=0: verbosity mode

fullpath=None, string,

path of the output image If write_dir and fullpath are None then no file output. If only fullpath is None then it is the write dir + a name depending on the method.

Notes

Ward’s method takes time (about 6 minutes for a 60K voxels dataset)

Geodesic k-means is ‘quick and dirty’

Ward’s + GKM is expensive but quite good

To reduce CPU time, rather use nn=6 (especially with Ward)

nipy.labs.spatial_models.parcel_io.mask_parcellation(mask_images, nb_parcel, threshold=0, output_image=None)

Performs the parcellation of a certain mask

Parameters

mask_images: string or Nifti1Image or list of strings/Nifti1Images,

paths of mask image(s) that define(s) the common space.

nb_parcel: int,

number of desired parcels

threshold: float, optional,

level of intersection of the masks

output_image: string, optional

path of the output image

Returns

wim: Nifti1Imagine instance, representing the resulting parcellation

nipy.labs.spatial_models.parcel_io.parcel_input(mask_images, learning_images, ths=0.5, fdim=None)

Instantiating a Parcel structure from a give set of input

Parameters

mask_images: string or Nifti1Image or list of strings/Nifti1Images,

paths of mask image(s) that define(s) the common space.

learning_images: (nb_subject-) list of (nb_feature-) list of strings,

paths of feature images used as input to the parcellation procedure

ths=.5: threshold to select the regions that are common across subjects.

if ths = .5, thethreshold is half the number of subjects

fdim: int, optional

if nb_feature (the dimension of the data) used in subsequent analyses if greater than fdim, a PCA is perfomed to reduce the information in the data Byd efault, no reduction is performed

Returns

domain : discrete_domain.DiscreteDomain instance

that stores the spatial information on the parcelled domain

feature: (nb_subect-) list of arrays of shape (domain.size, fdim)

feature information available to parcellate the data

nipy.labs.spatial_models.parcel_io.parcellation_based_analysis(Pa, test_images, test_id='one_sample', rfx_path=None, condition_id='', swd=None)

This function computes parcel averages and RFX at the parcel-level

Parameters

Pa: MultiSubjectParcellation instance

the description of the parcellation

test_images: (Pa.nb_subj-) list of paths

paths of images used in the inference procedure

test_id: string, optional,

if test_id==’one_sample’, the one_sample statstic is computed otherwise, the parcel-based signal averages are returned

rfx_path: string optional,

path of the resulting one-sample test image, if applicable

swd: string, optional

output directory used to compute output path if rfx_path is not given

condition_id: string, optional,

contrast/condition id used to compute output path

Returns

test_data: array of shape(Pa.nb_parcel, Pa.nb_subj)

the parcel-level signal average if test is not ‘one_sample’

prfx: array of shape(Pa.nb_parcel),

the one-sample t-value if test_id is ‘one_sample’

nipy.labs.spatial_models.parcel_io.write_parcellation_images(Pa, template_path=None, indiv_path=None, subject_id=None, swd=None)

Write images that describe the spatial structure of the parcellation

Parameters

Pa : MultiSubjectParcellation instance,

the description of the parcellation

template_path: string, optional,

path of the group-level parcellation image

indiv_path: list of strings, optional

paths of the individual parcellation images

subject_id: list of strings of length Pa.nb_subj

subject identifiers, used to infer the paths when not available

swd: string, optional

output directory used to infer the paths when these are not available