twilight.filtering         package:twilight         R Documentation

_A _f_u_n_c_t_i_o_n _f_o_r _p_e_r_m_u_t_a_t_i_o_n _f_i_l_t_e_r_i_n_g

_D_e_s_c_r_i_p_t_i_o_n:

     The function call invokes the filtering for permutations of class
     labels that produce a set of complete null scores. Depending on
     the test setting, the algorithm iteratively generates valid
     permutations of the class labels and computes scores. These are
     transformed to pooled p-values and each set of permutation
     p-values is tested for uniformity. Permutations with acceptable
     uniform p-value distributions are kept. The search stops if either
     the number 'num.perm' of wanted permutations is reached or if the
     number of possible unique(!) permutations is smaller than
     'num.perm'. The default values are similar to function
     'twilight.pval' but please note the details below.

_U_s_a_g_e:

     twilight.filtering(xin, yin, method = "fc", paired = FALSE, s0 = 0, verbose = TRUE, num.perm = 1000, num.take = 50)

_A_r_g_u_m_e_n_t_s:

     xin: Either an expression set ('exprSet') or a data matrix with
          rows corresponding to features and columns corresponding to
          samples. 

     yin: A numerical vector containing class labels. The higher label
          denotes the case, the lower label the control samples to test
          case vs. control. For correlation scores, 'yin' can be any
          numerical vector of length equal to the number of samples. 

  method: Character string: '"fc"' for fold change equivalent test
          (that is log ratio test), '"t"' for t-test, and '"z"' for
          Z-test. With '"pearson"' or '"spearman"', the test statistic
          is either Pearson's correlation coefficient or Spearman's
          rank correlation coefficient.

  paired: Logical value. Depends on whether the samples are paired.
          Ignored if 'method="pearson"' or 'method="spearman"'.

      s0: Fudge factor for variance correction in the Z-test. Takes
          effect only if 'method="z"'. If 's0=0': The fudge factor is
          set to the median of the pooled standard deviations.

 verbose: Logical value for message printing. 

num.perm: Number of permutations. Within 'twilight.pval', 'num.perm' is
          set to 'B'. 

num.take: Number of permutations kept in each step of the iterative
          filtering. Within 'twilight.pval', 'num.take' is set to the
          minimum of 50 and 'ceiling(num.perm/20)'. 

_D_e_t_a_i_l_s:

     See vignette.

_V_a_l_u_e:

     Returns a list with two elements: Matrix 'yperm' with permuted
     input labels 'yin' as rows, and a numerical value 'test' giving
     the p-value of a goodness-of-fit chi2 test to evaluate whether the
     distribution of Hamming distances of the filtered permutations to
     the original labeling is still random. Please note that 'yperm' is
     already translated into binary labels for two-sample testing or to
     ranks if Spearman's correlation was chosen. The resulting
     permutation matrix can be directly passed into function
     'twilight.pval'. Please note that the first row of 'yperm' always
     contains the original input 'yin' to be consistent with the other
     permutation functions in package 'twilight'.

_A_u_t_h_o_r(_s):

     Stefanie Scheid <URL: http://www.molgen.mpg.de/~scheid>

_R_e_f_e_r_e_n_c_e_s:

     to come

_S_e_e _A_l_s_o:

     'twilight.pval'

_E_x_a_m_p_l_e_s:

     ### Leukemia data set of Golub et al. (1999).
     library(golubEsets)
     data(golubTrain)

     ### Variance-stabilizing normalization of Huber et al. (2002).
     library(vsn)
     golubNorm <- vsn(exprs(golubTrain))

     ### A binary vector of class labels.
     id <- as.numeric(golubTrain$ALL.AML)

     ### Do an unpaired t-test.
     ### Let's have a quick example with 50 filtered permutations only.
     ### With num.take=10, we only need 5 iteration steps.
     a <- twilight.filtering(golubNorm,id,method="t",num.perm=50,num.take=10)
     dim(a$yperm)

     ### Let's see if the filtered permutations really produce uniform p-value distributions.
     ### The first row is the original labeling, so we try the second permutation.
     a$yperm <- a$yperm[-1,]
     b <- twilight.pval(golubNorm,a$yperm[1,],method="t",yperm=a$yperm)
     hist(b$result$pvalue)

