# 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:
      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`

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:
      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)

  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:
      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)

  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:
      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'])

  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