safe {safe} | R Documentation |
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.
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, ...)
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 |
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.
The function returns an object of class SAFE
. See help for SAFE-class
for more details.
William T. Barry: bill.barry@duke.edu
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 {bf 21}(9) 1943–1949.
See also the vignette included with this package.
{safeplot
, getCmatrix
,
getPImatrix
.}
## 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") }