This vignette provides an introduction to goSorensen package, which was built to determine equivalence between features lists. The method is based on the Sorensen–Dice index and the joint frequencies of GO term enrichment. Starting from an introduction of the asociated technique and a description of the data used, this vignette explain how to: i) perform the equivalence test from contingency tables of joint enrichment or directly from features lists (either using a normal asymptotic or a bootstrap approximation), ii) collect specific fields of the test results like the p-value, the upper limit of the confidence interval or standard errors and iii) Another statistics related to the Sorensen-Dice dissimilarity
goSorensen 1.2.0
library(goSorensen)The goal of goSorensen is to implement the equivalence test introduced in Flores, P., Salicrú, M., Sánchez-Pla, A. and Ocaña, J.(2022) “An equivalence test between features lists, based on the Sorensen - Dice index and the joint frequencies of GO node enrichment”, BMC Bioinformatics, 2022 23:207.
Given two gene lists, \(L_1\) and \(L_2\), (the data) and a given set of n Gene Ontology (GO) terms (the frame of reference for biological information in these lists), the test is devoted to answer the following question (quite informally stated for the moment): The dissimilarity between the biological information in both lists, is it negligible? To measure the dissimilarity we use the Sorensen-Dice index:
\[ \hat d_{12} = d(L_1,L_2) = \frac{2n_{11}}{2n_{11} + n_{10} + n_{01}} \]
where \(n_{11}\) corresponds to the number of GO terms (among the n GO terms under consideration) which are enriched in both gene lists, \(n_{10}\) corresponds to the GO terms enriched in \(L_1\) but not in \(L_2\) and \(n_{01}\) the reverse, those enriched in \(L_2\) but not in \(L_1\). For notation completeness, \(n_{00}\) would correspond to those GO terms not enriched in both lists; it is not considered by the Sorensen-Dice index but would be necessary in some computations. Obviously, \(n = n_{11} + n_{10} + n_{01} + n_{00}\).
More precisely, the above problem can be restated as follows: Given a negligibility threshold \(d_0\) for the Sorensen-Dice values, to decide negligibility corresponds to rejecting the null hypothesis \(H_0: d \ge d_0\) in favor of the alternative \(H_1: d < d_0\), where \(d\) stands for the “true” value of the Sorensen-Dice dissimilarity (\(L_1\) and \(L_2\) are samples, and the own process of declaring enrichment of a GO term is random, so \(\hat d = d(L_1,L_2)\) is an estimate of \(d\)). Then, a bit more precise statement of the problem is “The dissimilarity between the biological information in two gene lists, is it negligible up to a degree \(d_0\)?” Where this information is expressed by means of the Sorensen-Dice dissimilarity measured on the degree of coincidence and non-coincidence in GO terms enrichment among a given set of GO terms.
For the moment, the reference set of GO terms can be only all those GO terms in a given level of one GO ontology, either BP, CC or MF.
goSorensen package has to be installed with a working R version (>=4.2.0). Installation could take a few minutes on a regular desktop or laptop. Package can be installed from Bioconductor or devtools package, then it needs to be loaded using library(goSorensen)
To install from Bioconductor (recommended):
## Only if BiocManager is not previosly installed:
install.packages("BiocManager")
## otherwise, directly:
BiocManager::install("goSorensen")To install from Github
devtools::install_github("pablof1988/goSorensen", build_vignettes = TRUE)The dataset used in this vignette, allOncoGeneLists, is based on the gene lists compiled at http://www.bushmanlab.org/links/genelists, a comprehensive set of gene lists related to cancer. The package goSorensen loads this dataset by means of data(allOncoGeneLists):
data("allOncoGeneLists")It is a “list” object of length 7. Each one of its elements is a “character” with the gene identifiers of a gene list related to cancer.
Function equivTestSorensen performs the equivalence test. One possibility is to build first the mutual enrichment contingency table by means of the function buildEnrichTable and then to perform the equivalence test:
data("humanEntrezIDs")
length(allOncoGeneLists)## [1] 7sapply(allOncoGeneLists, length)## atlas cangenes cis miscellaneous sanger
## 991 189 613 187 450
## Vogelstein waldman
## 419 426# First 20 gene identifiers of gene lists Vogelstein and sanger:
allOncoGeneLists[["Vogelstein"]][1:20]## [1] "10006" "25" "27" "23305" "91" "4299" "3899" "27125"
## [9] "207" "238" "139285" "324" "367" "23092" "23365" "8289"
## [17] "57492" "196528" "405" "79058"allOncoGeneLists[["sanger"]][1:20]## [1] "25" "27" "2181" "57082" "10962" "51517" "27125" "10142"
## [9] "207" "208" "217" "238" "57714" "324" "23365" "399"
## [17] "8289" "405" "79058" "171023"# Build the enrichment contingency table between gene lists Vogelstein and
# sanger for the MF ontology at GO level 5:
enrichTab <- buildEnrichTable(allOncoGeneLists[["Vogelstein"]],
allOncoGeneLists[["sanger"]],
geneUniverse = humanEntrezIDs, orgPackg = "org.Hs.eg.db",
onto = "MF", GOLevel = 5, listNames = c("Vogelstein", "sanger"))
enrichTab## Enriched in sanger
## Enriched in Vogelstein TRUE FALSE
## TRUE 27 7
## FALSE 2 2187# Equivalence test for an equivalence (or negligibility) limit 0.2857
testResult <- equivTestSorensen(enrichTab, d0 = 0.2857)
testResult##
## Normal asymptotic test for 2x2 contingency tables based on the
## Sorensen-Dice dissimilarity
##
## data: enrichTab
## (d - d0) / se = -2.9884, p-value = 0.001402
## alternative hypothesis: true equivalence limit d0 is less than 0.2857
## 95 percent confidence interval:
## 0.0000000 0.2214798
## sample estimates:
## Sorensen dissimilarity
## 0.1428571
## attr(,"se")
## standard error
## 0.04779919To perform the test directly from the gene lists (internally building the contingency table) is also possible:
equivTestSorensen(allOncoGeneLists[["Vogelstein"]], allOncoGeneLists[["sanger"]], d0 = 0.2857,
geneUniverse = humanEntrezIDs, orgPackg = "org.Hs.eg.db",
onto = "MF", GOLevel = 5, listNames = c("Vogelstein", "sanger"))##
## Normal asymptotic test for 2x2 contingency tables based on the
## Sorensen-Dice dissimilarity
##
## data: tab
## (d - d0) / se = -2.9884, p-value = 0.001402
## alternative hypothesis: true equivalence limit d0 is less than 0.2857
## 95 percent confidence interval:
## 0.0000000 0.2214798
## sample estimates:
## Sorensen dissimilarity
## 0.1428571
## attr(,"se")
## standard error
## 0.04779919To save computing time, the first option (building the contingency table separately, first) may be preferable: buildEnrichTable may take some time (many enrichment tests) and it would be advantageous to have the contingency table ready for further computations.
The above tests use a standard normal approximation to the sample distribution of the \((\hat d - d) / \widehat {se}\) statistic, where \(\widehat {se}\) stands for the standard error of the sample dissimilarity, \(\hat d\).
Alternatively, it is possible to estimate this distribution by means of bootstrap:
boot.testResult <- equivTestSorensen(enrichTab, d0 = 0.2857, boot = TRUE)
boot.testResult##
## Bootstrap test for 2x2 contingency tables based on the Sorensen-Dice
## dissimilarity (9997 effective bootstrap replicates of 10000)
##
## data: enrichTab
## (d - d0) / se = -2.9884, p-value = 0.0169
## alternative hypothesis: true equivalence limit d0 is less than 0.2857
## 95 percent confidence interval:
## 0.0000000 0.2438589
## sample estimates:
## Sorensen dissimilarity
## 0.1428571
## attr(,"se")
## standard error
## 0.04779919For low frequencies in the contingency table, bootstrap is a more conservative but preferable approach, with better type I error control.
To access specific fields of the test result:
getDissimilarity(testResult)## Sorensen dissimilarity
## 0.1428571
## attr(,"se")
## standard error
## 0.04779919getSE(testResult)## standard error
## 0.04779919getPvalue(testResult)## p-value
## 0.001402234getTable(testResult)## Enriched in sanger
## Enriched in Vogelstein TRUE FALSE
## TRUE 27 7
## FALSE 2 2187getUpper(testResult)## dUpper
## 0.2214798# In the bootstrap approach, only these differ:
getPvalue(boot.testResult)## p-value
## 0.01690338getUpper(boot.testResult)## dUpper
## 0.2438589# (Only available for bootstrap tests) efective number of bootstrap resamples:
getNboot(boot.testResult)## [1] 10000For objects of class list, all these functions (equivTestSorensen, dSorensen, seSorensen, duppSorensen) assume a list of character objects containing gene identifiers and all pairwise computations are performed. For example, to obtain the matrix of all pairwise Sorensen-Dice dissimilarities:
dSorensen(allOncoGeneLists, onto = "MF", GOLevel = 5,
geneUniverse = humanEntrezIDs, orgPackg = "org.Hs.eg.db")## atlas cangenes cis miscellaneous sanger Vogelstein
## atlas 0.0000000 1 0.7647059 0.4492754 0.4520548 0.4358974
## cangenes 1.0000000 0 1.0000000 1.0000000 1.0000000 1.0000000
## cis 0.7647059 1 0.0000000 0.6875000 0.6666667 0.7073171
## miscellaneous 0.4492754 1 0.6875000 0.0000000 0.4444444 0.4915254
## sanger 0.4520548 1 0.6666667 0.4444444 0.0000000 0.1428571
## Vogelstein 0.4358974 1 0.7073171 0.4915254 0.1428571 0.0000000
## waldman 0.3975904 1 0.7391304 0.2812500 0.4705882 0.4794521
## waldman
## atlas 0.3975904
## cangenes 1.0000000
## cis 0.7391304
## miscellaneous 0.2812500
## sanger 0.4705882
## Vogelstein 0.4794521
## waldman 0.0000000Similarly, the following code performs all pairwise tests:
allTests <- equivTestSorensen(allOncoGeneLists, d0 = 0.2857,
onto = "MF", GOLevel = 5,
geneUniverse = humanEntrezIDs,
orgPackg = "org.Hs.eg.db")
getPvalue(allTests)## cangenes.atlas.p-value cis.atlas.p-value
## NaN 0.999999999
## cis.cangenes.p-value miscellaneous.atlas.p-value
## NaN 0.987655731
## miscellaneous.cangenes.p-value miscellaneous.cis.p-value
## NaN 0.999894013
## sanger.atlas.p-value sanger.cangenes.p-value
## 0.990549965 NaN
## sanger.cis.p-value sanger.miscellaneous.p-value
## 0.999889111 0.973079331
## Vogelstein.atlas.p-value Vogelstein.cangenes.p-value
## 0.986530586 NaN
## Vogelstein.cis.p-value Vogelstein.miscellaneous.p-value
## 0.999996190 0.994763728
## Vogelstein.sanger.p-value waldman.atlas.p-value
## 0.001402234 0.959649373
## waldman.cangenes.p-value waldman.cis.p-value
## NaN 0.999999921
## waldman.miscellaneous.p-value waldman.sanger.p-value
## 0.472457677 0.993675934
## waldman.Vogelstein.p-value
## 0.996522105getDissimilarity(allTests, simplify = FALSE)## atlas cangenes cis miscellaneous sanger Vogelstein
## atlas 0.0000000 1 0.7647059 0.4492754 0.4520548 0.4358974
## cangenes 1.0000000 0 1.0000000 1.0000000 1.0000000 1.0000000
## cis 0.7647059 1 0.0000000 0.6875000 0.6666667 0.7073171
## miscellaneous 0.4492754 1 0.6875000 0.0000000 0.4444444 0.4915254
## sanger 0.4520548 1 0.6666667 0.4444444 0.0000000 0.1428571
## Vogelstein 0.4358974 1 0.7073171 0.4915254 0.1428571 0.0000000
## waldman 0.3975904 1 0.7391304 0.2812500 0.4705882 0.4794521
## waldman
## atlas 0.3975904
## cangenes 1.0000000
## cis 0.7391304
## miscellaneous 0.2812500
## sanger 0.4705882
## Vogelstein 0.4794521
## waldman 0.0000000Besides admitting objects of class table, character and list, functions equivTestSorensen, dSorensen, seSorensen and duppSorensen are also adequate for contingency tables represented as a plain matrix or a numeric:
enrichMat <- matrix(c(20, 1, 9, 2149), nrow = 2)
enrichMat## [,1] [,2]
## [1,] 20 9
## [2,] 1 2149dSorensen(enrichMat)## [1] 0.2enrichVec <- c(20, 1, 9, 2149)
equivTestSorensen(enrichVec)##
## Normal asymptotic test for 2x2 contingency tables based on the
## Sorensen-Dice dissimilarity
##
## data: enrichVec
## (d - d0) / se = -3.8784, p-value = 5.257e-05
## alternative hypothesis: true equivalence limit d0 is less than 0.4444444
## 95 percent confidence interval:
## 0.0000000 0.3036703
## sample estimates:
## Sorensen dissimilarity
## 0.2
## attr(,"se")
## standard error
## 0.06302709equivTestSorensen(enrichVec, boot = TRUE)##
## Bootstrap test for 2x2 contingency tables based on the Sorensen-Dice
## dissimilarity (10000 bootstrap replicates)
##
## data: enrichVec
## (d - d0) / se = -3.8784, p-value = 0.005499
## alternative hypothesis: true equivalence limit d0 is less than 0.4444444
## 95 percent confidence interval:
## 0.0000000 0.3323029
## sample estimates:
## Sorensen dissimilarity
## 0.2
## attr(,"se")
## standard error
## 0.06302709len3Vec <- c(20, 1, 9)
dSorensen(len3Vec)## [1] 0.2seSorensen(len3Vec)## [1] 0.06302709duppSorensen(len3Vec)## [1] 0.3036703# Error, bootstrapping requires the full (4 values) contingency table:
try(duppSorensen(len3Vec, boot = TRUE), TRUE)All software and respective versions used to produce this document are listed below.
sessionInfo()## R version 4.3.0 RC (2023-04-13 r84269 ucrt)
## Platform: x86_64-w64-mingw32/x64 (64-bit)
## Running under: Windows Server 2022 x64 (build 20348)
##
## Matrix products: default
##
##
## locale:
## [1] LC_COLLATE=C
## [2] LC_CTYPE=English_United States.utf8
## [3] LC_MONETARY=English_United States.utf8
## [4] LC_NUMERIC=C
## [5] LC_TIME=English_United States.utf8
##
## time zone: America/New_York
## tzcode source: internal
##
## attached base packages:
## [1] stats graphics grDevices utils datasets methods base
##
## other attached packages:
## [1] goSorensen_1.2.0 BiocStyle_2.28.0
##
## loaded via a namespace (and not attached):
## [1] DBI_1.1.3 bitops_1.0-7 gson_0.1.0
## [4] shadowtext_0.1.2 gridExtra_2.3 rlang_1.1.0
## [7] magrittr_2.0.3 DOSE_3.26.0 compiler_4.3.0
## [10] RSQLite_2.3.1 png_0.1-8 vctrs_0.6.2
## [13] reshape2_1.4.4 stringr_1.5.0 pkgconfig_2.0.3
## [16] crayon_1.5.2 fastmap_1.1.1 XVector_0.40.0
## [19] ggraph_2.1.0 utf8_1.2.3 HDO.db_0.99.1
## [22] rmarkdown_2.21 enrichplot_1.20.0 purrr_1.0.1
## [25] bit_4.0.5 xfun_0.39 zlibbioc_1.46.0
## [28] cachem_1.0.7 aplot_0.1.10 GenomeInfoDb_1.36.0
## [31] jsonlite_1.8.4 blob_1.2.4 BiocParallel_1.34.0
## [34] tweenr_2.0.2 parallel_4.3.0 R6_2.5.1
## [37] RColorBrewer_1.1-3 bslib_0.4.2 stringi_1.7.12
## [40] jquerylib_0.1.4 GOSemSim_2.26.0 Rcpp_1.0.10
## [43] bookdown_0.33 knitr_1.42 goProfiles_1.62.0
## [46] downloader_0.4 IRanges_2.34.0 Matrix_1.5-4
## [49] splines_4.3.0 igraph_1.4.2 tidyselect_1.2.0
## [52] qvalue_2.32.0 yaml_2.3.7 viridis_0.6.2
## [55] codetools_0.2-19 lattice_0.21-8 tibble_3.2.1
## [58] plyr_1.8.8 treeio_1.24.0 Biobase_2.60.0
## [61] withr_2.5.0 KEGGREST_1.40.0 evaluate_0.20
## [64] CompQuadForm_1.4.3 gridGraphics_0.5-1 scatterpie_0.1.9
## [67] polyclip_1.10-4 Biostrings_2.68.0 ggtree_3.8.0
## [70] pillar_1.9.0 BiocManager_1.30.20 stats4_4.3.0
## [73] clusterProfiler_4.8.0 ggfun_0.0.9 generics_0.1.3
## [76] RCurl_1.98-1.12 S4Vectors_0.38.0 ggplot2_3.4.2
## [79] tidytree_0.4.2 munsell_0.5.0 scales_1.2.1
## [82] glue_1.6.2 lazyeval_0.2.2 tools_4.3.0
## [85] data.table_1.14.8 fgsea_1.26.0 graphlayouts_0.8.4
## [88] fastmatch_1.1-3 tidygraph_1.2.3 cowplot_1.1.1
## [91] grid_4.3.0 ape_5.7-1 tidyr_1.3.0
## [94] AnnotationDbi_1.62.0 colorspace_2.1-0 nlme_3.1-162
## [97] patchwork_1.1.2 GenomeInfoDbData_1.2.10 ggforce_0.4.1
## [100] cli_3.6.1 fansi_1.0.4 viridisLite_0.4.1
## [103] dplyr_1.1.2 gtable_0.3.3 yulab.utils_0.0.6
## [106] sass_0.4.5 digest_0.6.31 BiocGenerics_0.46.0
## [109] ggplotify_0.1.0 ggrepel_0.9.3 org.Hs.eg.db_3.17.0
## [112] farver_2.1.1 memoise_2.0.1 htmltools_0.5.5
## [115] lifecycle_1.0.3 httr_1.4.5 GO.db_3.17.0
## [118] bit64_4.0.5 MASS_7.3-59Flores, P., Salicrú, M., Sánchez-Pla, A. et al. An equivalence test between features lists, based on the Sorensen–Dice index and the joint frequencies of GO term enrichment. BMC Bioinformatics 23, 207 (2022). https://doi.org/10.1186/s12859-022-04739-2