labs.group.permutation_test

Module: labs.group.permutation_test

Inheritance diagram for nipy.labs.group.permutation_test:

One and two sample permutation tests.

Classes

permutation_test

class nipy.labs.group.permutation_test.permutation_test

Bases: object

This generic permutation test class contains the calibration method which is common to the derived classes permutation_test_onesample and permutation_test_twosample (as well as other common methods)

__init__(*args, **kwargs)

calibrate(nperms=10000, clusters=None, cluster_stats=['size', 'Fisher'], regions=None, region_stats=['Fisher'], verbose=False)

Calibrate cluster and region summary statistics using permutation test

Parameters:

npermsint, optional

Number of random permutations generated. Exhaustive permutations are used only if nperms=None, or exceeds total number of possible permutations

clusterslist [(thresh1,diam1),(thresh2,diam2),…], optional

List of cluster extraction pairs: (thresh,diam). thresh provides T values threshold, diam is the maximum cluster diameter, in voxels. Using *diam*==None yields classical suprathreshold clusters.

cluster_statslist [stat1,…], optional

List of cluster summary statistics id (either ‘size’ or ‘Fisher’)

regionslist [Labels1,Labels2,…]

List of region labels arrays, of size (p,) where p is the number of voxels

region_statslist [stat1,…], optional

List of cluster summary statistics id (only ‘Fisher’ supported for now)

verboseboolean, optional

“Chatterbox” mode switch

Returns:

voxel_resultsdict

A dictionary containing the following keys: p_values (p,) Uncorrected p-values.``Corr_p_values`` (p,) Corrected p-values, computed by the Tmax procedure. perm_maxT_values (nperms) values of the maximum statistic under permutation.

cluster_resultslist [results1,results2,…]

List of permutation test results for each cluster extraction pair. These are dictionaries with the following keys “thresh”, “diam”, “labels”, “expected_voxels_per_cluster”, “expected_number_of_clusters”, and “peak_XYZ” if XYZ field is nonempty and for each summary statistic id “S”: “size_values”, “size_p_values”, “S_Corr_p_values”, “perm_size_values”, “perm_maxsize_values”

region_results :list [results1,results2,…]

List of permutation test results for each region labels arrays. These are dictionaries with the following keys: “label_values”, “peak_XYZ” (if XYZ field nonempty) and for each summary statistic id “S”: “size_values”, “size_p_values”, “perm_size_values”, “perm_maxsize_values”

height_threshold(pval)

Return the uniform height threshold matching a given permutation-based P-value.

pvalue(Tvalues=None)

Return uncorrected voxel-level pseudo p-values.

zscore(Tvalues=None)

Return z score corresponding to the uncorrected voxel-level pseudo p-value.

permutation_test_onesample

class nipy.labs.group.permutation_test.permutation_test_onesample(data, XYZ, axis=0, vardata=None, stat_id='student', base=0.0, niter=5, ndraws=100000)

Bases: permutation_test

Class derived from the generic permutation_test class. Inherits the calibrate method

__init__(data, XYZ, axis=0, vardata=None, stat_id='student', base=0.0, niter=5, ndraws=100000)

Initialize permutation_test_onesample instance, compute statistic values in each voxel and under permutation In: data data array

XYZ voxels coordinates

axis <int> Subject axis in data

vardata variance (same shape as data)

optional (if None, mfx statistics cannot be used)

stat_id <char> choice of test statistic

(see onesample.stats for a list of possible stats)

base <float> mean signal under H0 niter <int> number of iterations of EM algorithm ndraws <int> Number of generated random t values

Out:

self.Tvalues voxelwise test statistic values self.random_Tvalues sorted statistic values in random voxels and under random

sign permutation

calibrate(nperms=10000, clusters=None, cluster_stats=['size', 'Fisher'], regions=None, region_stats=['Fisher'], verbose=False)

Calibrate cluster and region summary statistics using permutation test

Parameters:

npermsint, optional

Number of random permutations generated. Exhaustive permutations are used only if nperms=None, or exceeds total number of possible permutations

clusterslist [(thresh1,diam1),(thresh2,diam2),…], optional

List of cluster extraction pairs: (thresh,diam). thresh provides T values threshold, diam is the maximum cluster diameter, in voxels. Using *diam*==None yields classical suprathreshold clusters.

cluster_statslist [stat1,…], optional

List of cluster summary statistics id (either ‘size’ or ‘Fisher’)

regionslist [Labels1,Labels2,…]

List of region labels arrays, of size (p,) where p is the number of voxels

region_statslist [stat1,…], optional

List of cluster summary statistics id (only ‘Fisher’ supported for now)

verboseboolean, optional

“Chatterbox” mode switch

Returns:

voxel_resultsdict

A dictionary containing the following keys: p_values (p,) Uncorrected p-values.``Corr_p_values`` (p,) Corrected p-values, computed by the Tmax procedure. perm_maxT_values (nperms) values of the maximum statistic under permutation.

cluster_resultslist [results1,results2,…]

List of permutation test results for each cluster extraction pair. These are dictionaries with the following keys “thresh”, “diam”, “labels”, “expected_voxels_per_cluster”, “expected_number_of_clusters”, and “peak_XYZ” if XYZ field is nonempty and for each summary statistic id “S”: “size_values”, “size_p_values”, “S_Corr_p_values”, “perm_size_values”, “perm_maxsize_values”

region_results :list [results1,results2,…]

List of permutation test results for each region labels arrays. These are dictionaries with the following keys: “label_values”, “peak_XYZ” (if XYZ field nonempty) and for each summary statistic id “S”: “size_values”, “size_p_values”, “perm_size_values”, “perm_maxsize_values”

height_threshold(pval)

Return the uniform height threshold matching a given permutation-based P-value.

pvalue(Tvalues=None)

Return uncorrected voxel-level pseudo p-values.

zscore(Tvalues=None)

Return z score corresponding to the uncorrected voxel-level pseudo p-value.

permutation_test_onesample_graph

class nipy.labs.group.permutation_test.permutation_test_onesample_graph(data, G, axis=0, vardata=None, stat_id='student', base=0.0, niter=5, ndraws=100000)

Bases: permutation_test

Class derived from the generic permutation_test class. Inherits the calibrate method

__init__(data, G, axis=0, vardata=None, stat_id='student', base=0.0, niter=5, ndraws=100000)

Initialize permutation_test_onesample instance, compute statistic values in each voxel and under permutation In: data data array

G weighted graph (each vertex corresponds to a voxel) axis <int> Subject axis in data vardata variance (same shape as data)

optional (if None, mfx statistics cannot be used)

stat_id <char> choice of test statistic

(see onesample.stats for a list of possible stats)

base <float> mean signal under H0 niter <int> number of iterations of EM algorithm ndraws <int> Number of generated random t values

Out:

self.Tvalues voxelwise test statistic values self.random_Tvalues sorted statistic values in random voxels and under random

sign permutation

calibrate(nperms=10000, clusters=None, cluster_stats=['size', 'Fisher'], regions=None, region_stats=['Fisher'], verbose=False)

Calibrate cluster and region summary statistics using permutation test

Parameters:

npermsint, optional

Number of random permutations generated. Exhaustive permutations are used only if nperms=None, or exceeds total number of possible permutations

clusterslist [(thresh1,diam1),(thresh2,diam2),…], optional

List of cluster extraction pairs: (thresh,diam). thresh provides T values threshold, diam is the maximum cluster diameter, in voxels. Using *diam*==None yields classical suprathreshold clusters.

cluster_statslist [stat1,…], optional

List of cluster summary statistics id (either ‘size’ or ‘Fisher’)

regionslist [Labels1,Labels2,…]

List of region labels arrays, of size (p,) where p is the number of voxels

region_statslist [stat1,…], optional

List of cluster summary statistics id (only ‘Fisher’ supported for now)

verboseboolean, optional

“Chatterbox” mode switch

Returns:

voxel_resultsdict

A dictionary containing the following keys: p_values (p,) Uncorrected p-values.``Corr_p_values`` (p,) Corrected p-values, computed by the Tmax procedure. perm_maxT_values (nperms) values of the maximum statistic under permutation.

cluster_resultslist [results1,results2,…]

List of permutation test results for each cluster extraction pair. These are dictionaries with the following keys “thresh”, “diam”, “labels”, “expected_voxels_per_cluster”, “expected_number_of_clusters”, and “peak_XYZ” if XYZ field is nonempty and for each summary statistic id “S”: “size_values”, “size_p_values”, “S_Corr_p_values”, “perm_size_values”, “perm_maxsize_values”

region_results :list [results1,results2,…]

List of permutation test results for each region labels arrays. These are dictionaries with the following keys: “label_values”, “peak_XYZ” (if XYZ field nonempty) and for each summary statistic id “S”: “size_values”, “size_p_values”, “perm_size_values”, “perm_maxsize_values”

height_threshold(pval)

Return the uniform height threshold matching a given permutation-based P-value.

pvalue(Tvalues=None)

Return uncorrected voxel-level pseudo p-values.

zscore(Tvalues=None)

Return z score corresponding to the uncorrected voxel-level pseudo p-value.

permutation_test_twosample

class nipy.labs.group.permutation_test.permutation_test_twosample(data1, data2, XYZ, axis=0, vardata1=None, vardata2=None, stat_id='student', niter=5, ndraws=100000)

Bases: permutation_test

Class derived from the generic permutation_test class. Inherits the calibrate method

__init__(data1, data2, XYZ, axis=0, vardata1=None, vardata2=None, stat_id='student', niter=5, ndraws=100000)

Initialize permutation_test_twosample instance, compute statistic values in each voxel and under permutation In: data1, data2 data arrays

XYZ voxels coordinates

axis <int> Subject axis in data

vardata1, vardata2 variance (same shape as data)

optional (if None, mfx statistics cannot be used)

stat_id <char> choice of test statistic

(see onesample.stats for a list of possible stats)

niter <int> number of iterations of EM algorithm ndraws <int> Number of generated random t values

Out:

self.Tvalues voxelwise test statistic values self.random_Tvalues sorted statistic values in random voxels and under random

sign permutation

calibrate(nperms=10000, clusters=None, cluster_stats=['size', 'Fisher'], regions=None, region_stats=['Fisher'], verbose=False)

Calibrate cluster and region summary statistics using permutation test

Parameters:

npermsint, optional

Number of random permutations generated. Exhaustive permutations are used only if nperms=None, or exceeds total number of possible permutations

clusterslist [(thresh1,diam1),(thresh2,diam2),…], optional

List of cluster extraction pairs: (thresh,diam). thresh provides T values threshold, diam is the maximum cluster diameter, in voxels. Using *diam*==None yields classical suprathreshold clusters.

cluster_statslist [stat1,…], optional

List of cluster summary statistics id (either ‘size’ or ‘Fisher’)

regionslist [Labels1,Labels2,…]

List of region labels arrays, of size (p,) where p is the number of voxels

region_statslist [stat1,…], optional

List of cluster summary statistics id (only ‘Fisher’ supported for now)

verboseboolean, optional

“Chatterbox” mode switch

Returns:

voxel_resultsdict

A dictionary containing the following keys: p_values (p,) Uncorrected p-values.``Corr_p_values`` (p,) Corrected p-values, computed by the Tmax procedure. perm_maxT_values (nperms) values of the maximum statistic under permutation.

cluster_resultslist [results1,results2,…]

List of permutation test results for each cluster extraction pair. These are dictionaries with the following keys “thresh”, “diam”, “labels”, “expected_voxels_per_cluster”, “expected_number_of_clusters”, and “peak_XYZ” if XYZ field is nonempty and for each summary statistic id “S”: “size_values”, “size_p_values”, “S_Corr_p_values”, “perm_size_values”, “perm_maxsize_values”

region_results :list [results1,results2,…]

List of permutation test results for each region labels arrays. These are dictionaries with the following keys: “label_values”, “peak_XYZ” (if XYZ field nonempty) and for each summary statistic id “S”: “size_values”, “size_p_values”, “perm_size_values”, “perm_maxsize_values”

height_threshold(pval)

Return the uniform height threshold matching a given permutation-based P-value.

pvalue(Tvalues=None)

Return uncorrected voxel-level pseudo p-values.

zscore(Tvalues=None)

Return z score corresponding to the uncorrected voxel-level pseudo p-value.

Functions

nipy.labs.group.permutation_test.compute_cluster_stats(Tvalues, labels, random_Tvalues, cluster_stats=['size', 'Fisher'])

size_values, Fisher_values = compute_cluster_stats(Tvalues, labels, random_Tvalues, cluster_stats=[“size”,”Fisher”]) Compute summary statistics in each cluster In: see permutation_test_onesample class docstring Out: size_values Array of size nclust, or None if “size” not in cluster_stats

Fisher_values Array of size nclust, or None if “Fisher” not in cluster_stats

nipy.labs.group.permutation_test.compute_region_stat(Tvalues, labels, label_values, random_Tvalues)

Fisher_values = compute_region_stat(Tvalues, labels, label_values, random_Tvalues) Compute summary statistics in each cluster In: see permutation_test_onesample class docstring Out: Fisher_values Array of size nregions

nipy.labs.group.permutation_test.extract_clusters_from_diam(T, XYZ, th, diam, k=18)

Extract clusters from a statistical map under diameter constraint and above given threshold In: T (p) statistical map

XYZ (3,p) voxels coordinates th <float> minimum threshold diam <int> maximal diameter (in voxels) k <int> the number of neighbours considered. (6,18 or 26)

Out: labels (p) cluster labels

Comment by alexis-roche, September 15th 2012: this function was originally developed by Merlin Keller in an attempt to generalize classical cluster-level analysis by subdividing clusters in blobs with limited diameter (at least, this is my understanding). This piece of code seems to have remained very experimental and its usefulness in real-world neuroimaging image studies is still to be demonstrated.

nipy.labs.group.permutation_test.extract_clusters_from_graph(T, G, th)

This returns a label vector of same size as T, defining connected components for subgraph of weighted graph G containing vertices s.t. T >= th

nipy.labs.group.permutation_test.extract_clusters_from_thresh(T, XYZ, th, k=18)

Extract clusters from statistical map above specified threshold In: T (p) statistical map

XYZ (3,p) voxels coordinates th <float> threshold k <int> the number of neighbours considered. (6,18 or 26)

Out: labels (p) cluster labels

nipy.labs.group.permutation_test.max_dist(XYZ, I, J)

Maximum distance between two set of points In: XYZ (3,p) voxels coordinates

I (q) index of points J (r) index of points

Out: d <float>

nipy.labs.group.permutation_test.onesample_stat(Y, V, stat_id, base=0.0, axis=0, Magics=None, niter=5)

Wrapper for os_stat and os_stat_mfx

nipy.labs.group.permutation_test.peak_XYZ(XYZ, Tvalues, labels, label_values)

Returns (3, n_labels) array of maximum T values coordinates for each label value

nipy.labs.group.permutation_test.sorted_values(a)

Extract list of distinct sortedvalues from an array

nipy.labs.group.permutation_test.twosample_stat(Y1, V1, Y2, V2, stat_id, axis=0, Magics=None, niter=5)

Wrapper for ts_stat and ts_stat_mfx