safe                  package:safe                  R Documentation

_S_i_g_n_i_f_i_c_a_n_c_e _A_n_a_l_y_s_i_s _o_f _F_u_n_c_t_i_o_n _a_n_d _E_x_p_r_e_s_s_i_o_n

_D_e_s_c_r_i_p_t_i_o_n:

     Performs a significance analysis of function and expression (SAFE)
     for a given gene expression experiment and a given set of
     functional categories. SAFE is a two-stage permutation-based
     method that can be applied to a 2-sample, multi-class, simple
     linear regression, and other linear models. Other experimental
     designs can also be accommodated through user-defined functions.

_U_s_a_g_e:

     safe(X.mat, y.vec, C.mat = NULL, platform = NULL, annotate = NULL, Pi.mat = NULL, 
          local = "default", global = "Wilcoxon", args.local = NULL, 
          args.global = list(one.sided = FALSE), error = "none", alpha = NA, 
          method = "permutation", min.size = 2, max.size = Inf, ...)

_A_r_g_u_m_e_n_t_s:

   X.mat: A matrix or data.frame of expression data; each row
          corresponds to a gene and each column to a sample. Data can
          also be given as the Bioconductor class 'ExpressionSet'. Data
          should be properly normalized and may not contain missing
          values.

   y.vec: a numeric, integer or character vector of length
          'ncol(X.mat)' containing the response of interest. If 'X.mat'
          is an 'ExpressionSet', 'y.vec' can also be the name or column
          number of a covariate in the 'phenoData' slot. For examples
          of the acceptable forms 'y.vec' can take, see the vignette. 

   C.mat: A matrix or data.frame containing the gene category
          assignments. Each column represents a category and should be
          named accordingly. For each column, values of 1 ('TRUE') and
          0 ('FALSE') indicate whether the genes in the corresponding
          rows of 'X.mat' are contained in the category. This can also
          be a list containing a sparse  matrix and dimnames as created
          by 'getCmatrix'

platform: If 'C.mat' is unspecified, a character string of a
          Bioconductor annotation package can be used to build gene
          categories. See vignette for details and examples.

annotate: If 'C.mat' is unspecified, a character string to specify the
          type of gene categories to build from annotation packages.
          "GO.MF", "GO.BP", "GO.CC", and "GO.ALL" (default)  specify
          one or all Gene Ontologies. "KEGG" specifies pathways, and
          "PFAM" homologous families from the respective sources.

  Pi.mat: Either a matrix or data.frame containing the permutations, or
          an integer. See 'getPImatrix' for the acceptable form of a
          matrix or data.frame. If 'Pi.mat' is an integer, then 'safe'
          will automatically generate as many random permutations of
          'X.mat'. 

   local: Specifies the gene-specific statistic from the following
          options: "t.Student", "t.Welch" and "t.SAM" for 2-sample
          designs, "f.ANOVA" for 1-way ANOVAs, "t.LM" for simple linear
          regressions, and "z.COXPH" for a Cox proportional hazards
          survival model.  "default" will choose between "t.Student"
          and "f.ANOVA", based on the form of 'y.vec'. User-defined
          local statistics can also be used; details are provided in
          the vignette. 

  global: Specifies the global statistic for a gene categories. By
          default, the Wilcoxon rank sum ("Wilcoxon") is used. Else, a
          Fisher's Exact test statistic ("Fisher") based on the
          hypergeometric dist'n, a chi-squared type Pearson's test
          ("Pearson") or t-test of average difference ("AveDiff") is
          available. User-defined global statistics can also be
          implemented. 

args.local: An optional list to be passed to user-defined local
          statistics that require additional arguments. By default
          'args.local = NULL'.  

args.global: An optional list to be passed to global statistics that
          require additional arguments. For two-sided local statistics,
          'args.global' = list(one.sided=F) allows bi-directional
          differential expression to be considered. 

   error: Specifies the method for computing error rate estimates.
          "FDR.YB" computes the Yekutieli-Benjamini FDR estimate,
          "FWER.WY" computes the Westfall-Young FWER estimate. A
          Bonferroni, ("FWER.Bonf"), Holm's step-up ("FWER.Holm"), and
          Benjamini-Hochberg step down ("FDR.BH") adjustment can also
          be specified. By default ("none") no error rates are
          computed. 

   alpha: Allows the user to define the criterion for significance. By
          default, alpha will be 0.05 for nominal p-values ('error' =
          "none" ), and 0.1 otherwise. 

  method: Type of hypothesis test can be specified as "permutation",
          "bootstrap.t", and  "bootstrap.q". See vignette for details

min.size: Optional minimum category size to be considered. 

max.size: Optional maximum category size to be considered. 

     ...: Allows arguments from version 1.0 to be ignored 

_D_e_t_a_i_l_s:

     'safe' utilizes a general framework for testing differential
     expression across gene categories that allows it to be used in
     various experimental designs. Through structured resampling of the
     data, 'safe' accounts for the unknown correlation among genes, and
     enables proper estimation of error rates when testing multiple
     categories.  'safe' also provides statistics and empirical
     p-values for the gene-specific  differential expression.

_V_a_l_u_e:

     The function returns an object of class 'SAFE'. See help for
     'SAFE-class' for more details.

_A_u_t_h_o_r(_s):

     William T. Barry: bill.barry@duke.edu

_R_e_f_e_r_e_n_c_e_s:

     W. T. Barry, A. B. Nobel and F.A. Wright, 2005, _Significance
     Analysis of functional categories in gene expression studies: a
     structured permutation approach_, _Bioinformatics_ *21*(9)
     1943-1949. 

     See also the vignette included with this package.

_S_e_e _A_l_s_o:

     'safeplot', 'getCmatrix',  'getPImatrix'.

_E_x_a_m_p_l_e_s:

     ## Simulate a dataset with 1000 genes and 20 arrays in a 2-sample design.
     ## The top 100 genes will be differentially expressed at varying levels

     g.alt <- 100
     g.null <- 900
     n <- 20

     data<-matrix(rnorm(n*(g.alt+g.null)),g.alt+g.null,n)
     data[1:g.alt,1:(n/2)] <- data[1:g.alt,1:(n/2)] + 
                              seq(2,2/g.alt,length=g.alt)
     dimnames(data) <- list(c(paste("Alt",1:g.alt),
                              paste("Null",1:g.null)),
                            paste("Array",1:n))

     ## A treatment vector 
     trt <- rep(c("Trt","Ctr"),each=n/2)

     ## 2 alt. categories and 18 null categories of size 50

     C.matrix <- kronecker(diag(20),rep(1,50))
     dimnames(C.matrix) <- list(dimnames(data)[[1]],
         c(paste("TrueCat",1:2),paste("NullCat",1:18)))
     dim(C.matrix)

     results <- safe(data,trt,C.matrix,Pi.mat = 100)
     results

     ## SAFE-plot made for the first category
     if (interactive()) { 
     safeplot(results,"TrueCat 1")
     }

