twilight.pval            package:twilight            R Documentation

_C_o_m_p_u_t_e _p-_v_a_l_u_e_s _f_r_o_m _e_x_p_r_e_s_s_i_o_n _s_e_t_s

_D_e_s_c_r_i_p_t_i_o_n:

     A function to compute two-sample t, Z and fold change equivalent
     test statistics (paired or unpaired) and correlation coefficients.
     Based on permutations, expected test statistics as given in Tusher
     et al. (2001) and empirical p-values are computed. Additional
     output are q-values computed as given in Storey and Tibshirani
     (2003). The resulting object is of class 'twilight' and can be
     passed to functions 'twilight' or 'plot.twilight'.

_U_s_a_g_e:

     twilight.pval(xin, yin, method = "fc", paired = FALSE, B = 1000, yperm = NULL, balance = FALSE, quant.ci = 0.95, s0=NULL, verbose = TRUE, filtering = FALSE)

_A_r_g_u_m_e_n_t_s:

     xin: Either an expression set ('ExpressionSet') 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"'.

       B: Numerical value specifying the number of permutations. 

   yperm: Optional matrix containing in each row a permutation of the
          class labels in binary(!) format for two-sample testing. For
          computation of correlation scores, the rows of 'yperm' have
          to contain the appropriate values or ranks. Use this argument
          carefully! If 'yperm' is specified, no other permutation will
          be done. Please note that the first row of 'yperm' MUST be
          the input vector 'yin'. Otherwise, the p-value calculation
          will be incorrect.

 balance: Logical value. Depends on whether balanced or unbalanced
          permutations should be done. Ignored if 'method="pearson"' or
          'method="spearman"'.

quant.ci: Probability value for confidence lines. Lines are symmetric
          and denote the 'quant.ci'-quantile of maximal absolute
          differences between each permutatin and the expected scores. 

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

 verbose: Logical value for message printing. 

filtering: Logical value for filtering for permutations of class labels
          that produce a set of complete null scores. Invokes function
          'twilight.filtering'. If 'yperm' is specified, no filtering
          will be done. Note that the filtering is done on unbalanced
          permutations even if 'balance=TRUE'. 

_D_e_t_a_i_l_s:

     Please see vignette for detailed information.

_V_a_l_u_e:

     Returns a 'twilight' object consisting of a 'data.frame' named
     'result' with variables 

observed: Observed test statistics.

expected: Mean of order statistics of the permutation statistics.

candidate: Binary vector. '"1"' for observations exceeding the
          confidence lines.

  pvalue: Empirical p-values from two-sided hypothesis tests.

  qvalue: q-values computed as described in Storey and Tibshirani
          (2003).

   index: Index of the original ordering.

     Values are sorted by absolute 'observed' scores.

_N_o_t_e:

     Additional output consists of

       'ci.line'   Quantile corresponding to 'quant.ci', passed for plotting.
       'pi0'       Estimated prior probability.
       's0'        Estimated fudge factor if 'method="z"'.
       'call'      Character string of function arguments.
       'quant.ci'  Passes 'quant.ci' for plotting.

     The remaining slots are left free for function '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:

     Scheid S and Spang R (2004): A stochastic downhill search
     algorithm for estimating the local false discovery rate, _IEEE
     TCBB_ *1(3)*, 98-108.

     Scheid S and Spang R (2005): twilight; a Bioconductor package for
     estimating the local false discovery rate, _Bioinformatics_
     *21(12)*, 2921-2922. 

     Scheid S and Spang R (2006): Permutation filtering: A novel
     concept for significance analysis of large-scale genomic data, in:
     Apostolico A, Guerra C, Istrail S, Pevzner P, and Waterman M
     (Eds.): _Research in Computational Molecular Biology: 10th Annual
     International Conference, Proceedings of RECOMB 2006, Venice,
     Italy, April 2-5, 2006_. Lecture Notes in Computer Science vol.
     3909, Springer, Heidelberg, pp. 338-347.

     Storey JD and Tibshirani R (2003): Statistical significance for
     genomewide studies, _PNAS_ *100(16)*, 9440-9445.

     Tusher VG, Tibshirani R and Chu G (2001): Significance analysis of
     mircroarrays applied to the ionizing response, _PNAS_ *98(9)*,
     5116-5121.

_S_e_e _A_l_s_o:

     'twilight', 'plot.twilight', 'twilight.combi',
     'twilight.filtering', 'expval', 'twilight.teststat'

_E_x_a_m_p_l_e_s:

     ### twilight object created from Golub data set
     data(expval)
     print(expval)
     plot(expval)

