safe {safe}R Documentation

Significance Analysis of Function and Expression

Description

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.

Usage

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, ...)

Arguments

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

Details

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.

Value

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

Author(s)

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

References

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.

See Also

{safeplot, getCmatrix, getPImatrix.}

Examples

## 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")
}

[Package safe version 2.2.0 Index]