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[source]¶ Bases:
objectThis 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__($self, /, *args, **kwargs)¶ Initialize self. See help(type(self)) for accurate signature.
-
calibrate(nperms=10000, clusters=None, cluster_stats=['size', 'Fisher'], regions=None, region_stats=['Fisher'], verbose=False)[source]¶ Calibrate cluster and region summary statistics using permutation test
- Parameters
nperms : int, optional
Number of random permutations generated. Exhaustive permutations are used only if nperms=None, or exceeds total number of possible permutations
clusters : list [(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_stats : list [stat1,…], optional
List of cluster summary statistics id (either ‘size’ or ‘Fisher’)
regions : list [Labels1,Labels2,…]
List of region labels arrays, of size (p,) where p is the number of voxels
region_stats : list [stat1,…], optional
List of cluster summary statistics id (only ‘Fisher’ supported for now)
verbose : boolean, optional
“Chatterbox” mode switch
- Returns
voxel_results : dict
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_results : list [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”
-
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)[source]¶ Bases:
nipy.labs.group.permutation_test.permutation_testClass 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)[source]¶ 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
nperms : int, optional
Number of random permutations generated. Exhaustive permutations are used only if nperms=None, or exceeds total number of possible permutations
clusters : list [(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_stats : list [stat1,…], optional
List of cluster summary statistics id (either ‘size’ or ‘Fisher’)
regions : list [Labels1,Labels2,…]
List of region labels arrays, of size (p,) where p is the number of voxels
region_stats : list [stat1,…], optional
List of cluster summary statistics id (only ‘Fisher’ supported for now)
verbose : boolean, optional
“Chatterbox” mode switch
- Returns
voxel_results : dict
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_results : list [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)[source]¶ Bases:
nipy.labs.group.permutation_test.permutation_testClass 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)[source]¶ 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
nperms : int, optional
Number of random permutations generated. Exhaustive permutations are used only if nperms=None, or exceeds total number of possible permutations
clusters : list [(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_stats : list [stat1,…], optional
List of cluster summary statistics id (either ‘size’ or ‘Fisher’)
regions : list [Labels1,Labels2,…]
List of region labels arrays, of size (p,) where p is the number of voxels
region_stats : list [stat1,…], optional
List of cluster summary statistics id (only ‘Fisher’ supported for now)
verbose : boolean, optional
“Chatterbox” mode switch
- Returns
voxel_results : dict
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_results : list [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)[source]¶ Bases:
nipy.labs.group.permutation_test.permutation_testClass 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)[source]¶ 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
nperms : int, optional
Number of random permutations generated. Exhaustive permutations are used only if nperms=None, or exceeds total number of possible permutations
clusters : list [(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_stats : list [stat1,…], optional
List of cluster summary statistics id (either ‘size’ or ‘Fisher’)
regions : list [Labels1,Labels2,…]
List of region labels arrays, of size (p,) where p is the number of voxels
region_stats : list [stat1,…], optional
List of cluster summary statistics id (only ‘Fisher’ supported for now)
verbose : boolean, optional
“Chatterbox” mode switch
- Returns
voxel_results : dict
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_results : list [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'])[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ Wrapper for os_stat and os_stat_mfx
-
nipy.labs.group.permutation_test.peak_XYZ(XYZ, Tvalues, labels, label_values)[source]¶ Returns (3, n_labels) array of maximum T values coordinates for each label value