buildEnrichTable: Creates a 2x2 enrichment contingency table from two gene...

In pablof1988/goSorensen: Statistical inference based on the Sorensen-Dice dissimilarity and the Gene Ontology (GO)

Creates a 2x2 enrichment contingency table from two gene lists, or all pairwise contingency tables for a "list" of gene lists.

Description

Creates a 2x2 enrichment contingency table from two gene lists, or all pairwise contingency tables for a "list" of gene lists.

Usage

buildEnrichTable(x, ...)

## Default S3 method:
buildEnrichTable(
  x,
  y,
  listNames = c("gene.list1", "gene.list2"),
  check.table = TRUE,
  geneUniverse,
  orgPackg,
  onto,
  GOLevel,
  storeEnrichedIn = TRUE,
  pAdjustMeth = "BH",
  pvalCutoff = 0.01,
  qvalCutoff = 0.05,
  parallel = FALSE,
  nOfCores = 1,
  ...
)

## S3 method for class 'character'
buildEnrichTable(
  x,
  y,
  listNames = c("gene.list1", "gene.list2"),
  check.table = TRUE,
  geneUniverse,
  orgPackg,
  onto,
  GOLevel,
  storeEnrichedIn = TRUE,
  pAdjustMeth = "BH",
  pvalCutoff = 0.01,
  qvalCutoff = 0.05,
  parallel = FALSE,
  nOfCores = min(detectCores() - 1),
  ...
)

## S3 method for class 'list'
buildEnrichTable(
  x,
  check.table = TRUE,
  geneUniverse,
  orgPackg,
  onto,
  GOLevel,
  storeEnrichedIn = TRUE,
  pAdjustMeth = "BH",
  pvalCutoff = 0.01,
  qvalCutoff = 0.05,
  parallel = FALSE,
  nOfCores = min(detectCores() - 1, length(x) - 1),
  ...
)

Arguments

x	either an object of class "character" (or coerzable to "character") representing a vector of gene identifiers (e.g., ENTREZ) or an object of class "list". In this second case, each element of the list must be a "character" vector of gene identifiers (e.g., ENTREZ). Then, all pairwise contingency tables between these gene lists are built.
...	Additional parameters for internal use (not used for the moment)
y	an object of class "character" (or coerzable to "character") representing a vector of gene identifiers (e.g., ENTREZ).
listNames	a character(2) with the gene lists names originating the cross-tabulated enrichment frequencies. Only in the "character" or default interface.
check.table	Logical The resulting table must be checked. Defaults to TRUE.
geneUniverse	character vector containing the universe of genes from where gene lists have been extracted. This vector must be obtained from the annotation package declared in orgPackg. For more details, refer to vignette goSorensen_Introduction.
orgPackg	A string with the name of the genomic annotation package corresponding to a specific species to be analyzed, which must be previously installed and activated. For more details, refer to vignette goSorensen_Introduction.
onto	string describing the ontology. Either "BP", "MF" or "CC".
GOLevel	An integer, the GO ontology level.
storeEnrichedIn	logical, the matrix of enriched (GO terms) x (gene lists) TRUE/FALSE values, must be stored in the result? See the details section
pAdjustMeth	string describing the adjust method, either "BH", "BY" or "Bonf", defaults to 'BH'.
pvalCutoff	adjusted pvalue cutoff on enrichment tests to report
qvalCutoff	qvalue cutoff on enrichment tests to report as significant. Tests must pass i) pvalueCutoff on unadjusted pvalues, ii) pvalueCutoff on adjusted pvalues and iii) qvalueCutoff on qvalues to be reported
parallel	Logical. Defaults to FALSE but put it at TRUE for parallel computation.
nOfCores	Number of cores for parallel computations. Only in "list" interface.

Details

If the argument storeEnrichedIn is TRUE (the default value), the result of buildEnrichTable includes an additional attribute enriched with a matrix of TRUE/FALSE values. Each of its rows indicates if a given GO term is enriched or not in each one of the gene lists (columns). To save space, only GO terms enriched in almost one of the gene lists are included in this matrix.

Also to avoid redundancies and to save space, the result of buildEnrichTable.list (an object of class "tableList", which is itself an aggregate of 2x2 contingency tables of class "table") has the attribute enriched but its table members do not have this attribute.

The default value of argument parallel ís "FALSE" and you may consider the trade of between the time spent in initializing parallelization and the possible time gain when parallelizing. It is difficult to establish a general guideline, but parallelizing is only worthwhile when analyzing many gene lists, on the order of 30 or more, although it depends on each computer and each application.

Value

in the "character" interface, an object of class "table". It represents a 2x2 contingency table, the cross-tabulation of the enriched GO terms in two gene lists: "Number of enriched GO terms in list 1 (TRUE, FALSE)" x "Number of enriched Go terms in list 2 (TRUE, FALSE)". In the "list" interface, the result is an object of class "tableList" with all pairwise tables. Class "tableList" corresponds to objects representing all mutual enrichment contingency tables generated in a pairwise fashion: Given gene lists (i.e. "character" vectors of gene identifiers) l1, l2, ..., lk, an object of class "tableList" is a list of lists of contingency tables t(i,j) generated from each pair of gene lists i and j, with the following structure:

$l2

$l2$l1$t(2,1)

$l3

$l3$l1$t(3,1), $l3$l2$t(3,2)

...

$lk

$lk$l1$t(k,1), $lk$l2$t(k,2), ..., $lk$l(k-1)t(K,k-1)

Methods (by class)

• buildEnrichTable(default): S3 default method

• buildEnrichTable(character): S3 method for class "character"

• buildEnrichTable(list): S3 method for class "list"

Examples

# Obtaining ENTREZ identifiers for the gene universe of humans:
library(org.Hs.eg.db)
humanEntrezIDs <- keys(org.Hs.eg.db, keytype = "ENTREZID")

# Gene lists to be explored for enrichment:
data(allOncoGeneLists)
?allOncoGeneLists

# Table of joint GO term enrichment between gene lists Vogelstein and sanger,
# for ontology MF at GO level 6.
vog.VS.sang <- buildEnrichTable(allOncoGeneLists[["Vogelstein"]],
                                allOncoGeneLists[["sanger"]],
                                geneUniverse = humanEntrezIDs, orgPackg = "org.Hs.eg.db",
                                onto = "MF", GOLevel = 6, listNames = c("Vogelstein", "sanger"))
vog.VS.sang
attr(vog.VS.sang, "enriched")

# All tables of mutual enrichment:
all.tabs <- buildEnrichTable(allOncoGeneLists,
                             geneUniverse = humanEntrezIDs, orgPackg = "org.Hs.eg.db",
                             onto = "MF", GOLevel = 6)
attr(all.tabs, "enriched")
all.tabs$waldman
all.tabs$waldman$atlas
attr(all.tabs$waldman$atlas, "enriched")

pablof1988/goSorensen documentation built on Dec. 15, 2024, 12:01 p.m.