class_docstr: 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)
class_docstr_tok: ["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",")"]
docstr: 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"
docstr_tok: ["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","''"]
code: def calibrate(
      self,
      nperms=DEF_NPERMS,
      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"
      """
      # Permutation indices
      if self.nsamples == 1:
          n, p = (
              self.data.shape[self.axis],
              self.data.shape[1 - self.axis],
          )
          max_nperms = 2**n
      elif self.nsamples == 2:
          n1, p = (
              self.data1.shape[self.axis],
              self.data1.shape[1 - self.axis],
          )
          n2 = self.data2.shape[self.axis]
          max_nperms = comb(n1 + n2, n1, exact=1)
          data = np.concatenate((self.data1, self.data2), self.axis)
          if self.vardata1 is not None:
              vardata = np.concatenate(
                  (self.vardata1, self.vardata2), self.axis
              )
      if nperms is None or nperms >= max_nperms:
          magic_numbers = np.arange(max_nperms)
      else:
          # magic_numbers = np.random.randint(max_nperms,size=nperms)
          # np.random.randint does not handle longint!
          # So we use the following hack instead:
          magic_numbers = np.random.uniform(max_nperms, size=nperms)
      # Initialize cluster_results
      cluster_results = []
      if clusters is not None:
          for thresh, diam in clusters:
              if diam is None:
                  if self.XYZ is None:
                      labels = extract_clusters_from_graph(
                          self.Tvalues, self.G, thresh
                      )
                  else:
                      labels = extract_clusters_from_thresh(
                          self.Tvalues, self.XYZ, thresh
                      )
              else:
                  labels = extract_clusters_from_diam(
                      self.Tvalues, self.XYZ, thresh, diam
                  )
              results = {
                  "thresh": thresh,
                  "diam": diam,
                  "labels": labels,
              }
              size_values, Fisher_values = compute_cluster_stats(
                  self.Tvalues,
                  labels,
                  self.random_Tvalues,
                  cluster_stats,
              )
              nclust = labels.max() + 1
              results["expected_voxels_per_thresh"] = 0.0
              results["expected_number_of_clusters"] = 0.0
              if self.XYZ is not None:
                  results["peak_XYZ"] = peak_XYZ(
                      self.XYZ, self.Tvalues, labels, np.arange(nclust)
                  )
              if "size" in cluster_stats:
                  results["size_values"] = size_values
                  results["perm_size_values"] = []
                  results["perm_maxsize_values"] = np.zeros(
                      len(magic_numbers), int
                  )
              if "Fisher" in cluster_stats:
                  results["Fisher_values"] = Fisher_values
                  results["perm_Fisher_values"] = []
                  results["perm_maxFisher_values"] = np.zeros(
                      len(magic_numbers), float
                  )
              cluster_results.append(results)
      # Initialize region_results
      region_results = []
      if regions is not None:
          for labels in regions:
              label_values = sorted_values(labels)
              nregions = len(label_values)
              results = {"label_values": label_values}
              if self.XYZ is not None:
                  results["peak_XYZ"] = peak_XYZ(
                      self.XYZ, self.Tvalues, labels, label_values
                  )
              if "Fisher" in region_stats:
                  results["Fisher_values"] = compute_region_stat(
                      self.Tvalues,
                      labels,
                      label_values,
                      self.random_Tvalues,
                  )
                  results["perm_Fisher_values"] = np.zeros(
                      (nregions, len(magic_numbers)), float
                  )
                  results["Fisher_p_values"] = np.zeros(nregions, float)
                  results["Fisher_Corr_p_values"] = np.zeros(
                      nregions, float
                  )
              region_results.append(results)
      # Permutation test
      p_values = np.zeros(p, float)
      Corr_p_values = np.zeros(p, float)
      nmagic = len(magic_numbers)
      perm_maxT_values = np.zeros(nmagic, float)
      for j in range(nmagic):
          m = magic_numbers[j]
          if verbose:
              print("Permutation", j + 1, "out of", nmagic)
          # T values under permutation
          if self.nsamples == 1:
              rand_sign = (
                  np.random.randint(2, size=n) * 2 - 1
              ).reshape(n, 1)
              rand_data = rand_sign * self.data
              if self.vardata is None:
                  rand_vardata = None
              else:
                  rand_vardata = rand_sign * self.vardata
  
              perm_Tvalues = onesample_stat(
                  rand_data,
                  rand_vardata,
                  self.stat_id,
                  self.base,
                  self.axis,
                  None,
                  self.niter,
              ).squeeze()
          elif self.nsamples == 2:
              rand_perm = np.random.permutation(np.arange(n1 + n2))
              rand_data1 = data[rand_perm[:n1]]
              rand_data2 = data[rand_perm[n1:]]
              if self.vardata1 is None:
                  rand_vardata1 = None
                  rand_vardata2 = None
              else:
                  rand_vardata1 = vardata[rand_perm[:n1]]
                  rand_vardata2 = vardata[rand_perm[n1:]]
  
              perm_Tvalues = np.squeeze(
                  twosample_stat(
                      rand_data1,
                      rand_vardata1,
                      rand_data2,
                      rand_vardata2,
                      self.stat_id,
                      self.axis,
                      np.array([m]),
                      self.niter,
                  )
              )
  
          # update p values
          p_values += perm_Tvalues >= self.Tvalues
          Corr_p_values += max(perm_Tvalues) >= self.Tvalues
          perm_maxT_values[j] = max(perm_Tvalues)
          # Update cluster_results
          if clusters is not None:
              for i in range(len(clusters)):
                  thresh, diam = clusters[i]
                  if diam is None:
                      if self.XYZ is None:
                          perm_labels = extract_clusters_from_graph(
                              perm_Tvalues, self.G, thresh
                          )
                      else:
                          perm_labels = extract_clusters_from_thresh(
                              perm_Tvalues, self.XYZ, thresh
                          )
                  else:
                      perm_labels = extract_clusters_from_diam(
                          perm_Tvalues, self.XYZ, thresh, diam
                      )
                  (
                      perm_size_values,
                      perm_Fisher_values,
                  ) = compute_cluster_stats(
                      perm_Tvalues,
                      perm_labels,
                      self.random_Tvalues,
                      cluster_stats,
                  )
                  perm_nclust = labels.max() + 1
                  cluster_results[i][
                      "expected_voxels_per_thresh"
                  ] += perm_size_values.sum() / float(nclust)
                  cluster_results[i][
                      "expected_number_of_clusters"
                  ] += nclust
                  if "size" in cluster_stats:
                      cluster_results[i]["perm_size_values"][
                          :0
                      ] = perm_size_values
                      cluster_results[i]["perm_maxsize_values"][
                          j
                      ] = max(perm_size_values)
                  if "Fisher" in cluster_stats:
                      cluster_results[i]["perm_Fisher_values"][
                          :0
                      ] = perm_Fisher_values
                      cluster_results[i]["perm_maxFisher_values"][
                          j
                      ] = max(perm_Fisher_values)
          # Update region_results
          if regions is not None:
              for i in range(len(regions)):
                  labels = regions[i]
                  label_values = region_results[i]["label_values"]
                  nregions = len(label_values)
                  if "Fisher" in region_stats:
                      perm_Fisher_values = compute_region_stat(
                          perm_Tvalues,
                          labels,
                          label_values,
                          self.random_Tvalues,
                      )
                      region_results[i]["perm_Fisher_values"][
                          :, j
                      ] = perm_Fisher_values
      # Compute p-values for clusters summary statistics
      if clusters is not None:
          for i in range(len(clusters)):
              if "size" in cluster_stats:
                  cluster_results[i]["perm_size_values"] = np.array(
                      cluster_results[i]["perm_size_values"]
                  )
                  cluster_results[i]["perm_size_values"].sort()
                  cluster_results[i]["perm_maxsize_values"].sort()
                  cluster_results[i][
                      "size_p_values"
                  ] = 1 - np.searchsorted(
                      cluster_results[i]["perm_size_values"],
                      cluster_results[i]["size_values"],
                  ) / float(
                      cluster_results[i]["expected_number_of_clusters"]
                  )
                  cluster_results[i][
                      "size_Corr_p_values"
                  ] = 1 - np.searchsorted(
                      cluster_results[i]["perm_maxsize_values"],
                      cluster_results[i]["size_values"],
                  ) / float(
                      nmagic
                  )
              if "Fisher" in cluster_stats:
                  cluster_results[i]["perm_Fisher_values"] = np.array(
                      cluster_results[i]["perm_Fisher_values"]
                  )
                  cluster_results[i]["perm_Fisher_values"].sort()
                  cluster_results[i]["perm_maxFisher_values"].sort()
                  cluster_results[i][
                      "Fisher_p_values"
                  ] = 1 - np.searchsorted(
                      cluster_results[i]["perm_Fisher_values"],
                      cluster_results[i]["Fisher_values"],
                  ) / float(
                      cluster_results[i]["expected_number_of_clusters"]
                  )
                  cluster_results[i][
                      "Fisher_Corr_p_values"
                  ] = 1 - np.searchsorted(
                      cluster_results[i]["perm_maxFisher_values"],
                      cluster_results[i]["Fisher_values"],
                  ) / float(
                      nmagic
                  )
              cluster_results[i]["expected_voxels_per_thresh"] /= float(
                  nmagic
              )
              cluster_results[i][
                  "expected_number_of_clusters"
              ] /= float(nmagic)
      # Compute p-values for regions summary statistics
      if regions is not None:
          for i in range(len(regions)):
              if "Fisher" in region_stats:
                  sorted_perm_Fisher_values = np.sort(
                      region_results[i]["perm_Fisher_values"], axis=1
                  )
                  label_values = region_results[i]["label_values"]
                  nregions = len(label_values)
                  # Compute uncorrected p-values
                  for j in range(nregions):
                      region_results[i]["Fisher_p_values"][
                          j
                      ] = 1 - np.searchsorted(
                          sorted_perm_Fisher_values[j],
                          region_results[i]["Fisher_values"][j],
                      ) / float(
                          nmagic
                      )
                  # Compute corrected p-values
                  perm_Fisher_p_values = np.zeros(
                      (nregions, nmagic), float
                  )
                  for j in range(nregions):
                      I = np.argsort(
                          region_results[i]["perm_Fisher_values"][j]
                      )
                      perm_Fisher_p_values[j][I] = 1 - np.arange(
                          1, nmagic + 1
                      ) / float(nmagic)
                  perm_min_Fisher_p_values = np.sort(
                      perm_Fisher_p_values.min(axis=0)
                  )
                  region_results[i][
                      "Fisher_Corr_p_values"
                  ] = 1 - np.searchsorted(
                      -perm_min_Fisher_p_values,
                      -region_results[i]["Fisher_p_values"],
                  ) / float(
                      nmagic
                  )
      voxel_results = {
          "p_values": p_values / float(nmagic),
          "Corr_p_values": Corr_p_values / float(nmagic),
          "perm_maxT_values": perm_maxT_values,
      }
      return voxel_results, cluster_results, region_results
  
imports: import numpy
  import warnings
  from nipy.algorithms.graph import wgraph_from_3d_grid
  from nipy.algorithms.graph.field import Field, field_from_graph_and_data
  from ..utils import zscore
  from .onesample import stat
  from .onesample import stat_mfx
  from .twosample import stat
  from .twosample import stat_mfx
label_desc: Use image node_id 1 for calling the permutation_test obj's underlying member method code with example usage: obj.calibrate(nperms, clusters, cluster_stats, regions, region_stats, verbose) and returns: voxel_results,  cluster_results,  region_results