--- title: "An introduction to package goSorensen" author: - name: Jordi Ocaña email: jocana@ub.edu affiliation: Department of Genetics, Microbiology and Statistics, Statistics Section, University of Barcelona - name: Pablo Flores email: p_flores@espoch.edu.ec affiliation: Escuela Superior Politécnica de Chimborazo (ESPOCH), Facultad de Ciencias, Carrera de Estadística. package: goSorensen abstract: > 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 output: BiocStyle::html_document: toc_float: true vignette: > %\VignetteIndexEntry{An introduction to equivalence test between feature lists using goSorensen.} %\VignetteEngine{knitr::rmarkdown} %%\VignetteKeywords{Annotation, GO, GeneSetEnrichment, Software, Microarray, Pathways, GeneExpression, MultipleComparison} %\VignetteEncoding{UTF-8} --- ```{r style, echo = FALSE, results = 'asis'} BiocStyle::markdown() ``` ```{r setup, include=FALSE} knitr::opts_chunk$set(dpi=25,fig.width=7) ``` ```{r env, message = FALSE, warning = FALSE, echo = TRUE} library(goSorensen) ``` # Introduction 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. # Installation 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): ```{r, eval=FALSE} ## Only if BiocManager is not previosly installed: install.packages("BiocManager") ## otherwise, directly: BiocManager::install("goSorensen") ``` To install from Github ```{r, eval=FALSE} devtools::install_github("pablof1988/goSorensen", build_vignettes = TRUE) ``` # Data. The dataset used in this vignette, `allOncoGeneLists`, is based on the gene lists compiled at , a comprehensive set of gene lists related to cancer. The package `goSorensen` loads this dataset by means of `data(allOncoGeneLists)`: ```{r} 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. # Performing the equivalence test ## From a previously built contingency table of join enrichment 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: ```{r} data("humanEntrezIDs") length(allOncoGeneLists) sapply(allOncoGeneLists, length) # First 20 gene identifiers of gene lists Vogelstein and sanger: allOncoGeneLists[["Vogelstein"]][1:20] allOncoGeneLists[["sanger"]][1:20] # 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 # Equivalence test for an equivalence (or negligibility) limit 0.2857 testResult <- equivTestSorensen(enrichTab, d0 = 0.2857) testResult ``` ## Directly from the gene lists. To perform the test directly from the gene lists (internally building the contingency table) is also possible: ```{r} equivTestSorensen(allOncoGeneLists[["Vogelstein"]], allOncoGeneLists[["sanger"]], d0 = 0.2857, geneUniverse = humanEntrezIDs, orgPackg = "org.Hs.eg.db", onto = "MF", GOLevel = 5, listNames = c("Vogelstein", "sanger")) ``` To 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$. ## Using a bootstrap aproximation. Alternatively, it is possible to estimate this distribution by means of bootstrap: ```{r} boot.testResult <- equivTestSorensen(enrichTab, d0 = 0.2857, boot = TRUE) boot.testResult ``` For low frequencies in the contingency table, bootstrap is a more conservative but preferable approach, with better type I error control. # Accessing to specific fields To access specific fields of the test result: ```{r} getDissimilarity(testResult) getSE(testResult) getPvalue(testResult) getTable(testResult) getUpper(testResult) # In the bootstrap approach, only these differ: getPvalue(boot.testResult) getUpper(boot.testResult) # (Only available for bootstrap tests) efective number of bootstrap resamples: getNboot(boot.testResult) ``` # Other statistics related to the Sorensen-Dice dissimilarity Sometimes, it would be interesting not to perform the full equivalence test but to compute other statistics related to the Sorensen-Dice dissimilarity: ```{r} # The dissimilarity: dSorensen(enrichTab) # Or from scratch, directly from both gene lists: dSorensen(allOncoGeneLists[["Vogelstein"]], allOncoGeneLists[["sanger"]], geneUniverse = humanEntrezIDs, orgPackg = "org.Hs.eg.db", onto = "MF", GOLevel = 5, listNames = c("Vogelstein", "sanger")) # The first option is faster, it avoids internally building the enrichment # contingency table # Its standard error: seSorensen(enrichTab) # or: seSorensen(allOncoGeneLists[["Vogelstein"]], allOncoGeneLists[["sanger"]], geneUniverse = humanEntrezIDs, orgPackg = "org.Hs.eg.db", onto = "MF", GOLevel = 5, listNames = c("Vogelstein", "sanger")) # Upper limit of the confidence interval for the true distance: duppSorensen(enrichTab) duppSorensen(enrichTab, conf.level = 0.90) duppSorensen(enrichTab, conf.level = 0.90, boot = TRUE) duppSorensen(allOncoGeneLists[["Vogelstein"]], allOncoGeneLists[["sanger"]], geneUniverse = humanEntrezIDs, orgPackg = "org.Hs.eg.db", onto = "MF", GOLevel = 5, listNames = c("Vogelstein", "sanger")) ``` # All pairwise tests (or other computations) For 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: ```{r} dSorensen(allOncoGeneLists, onto = "MF", GOLevel = 5, geneUniverse = humanEntrezIDs, orgPackg = "org.Hs.eg.db") ``` Similarly, the following code performs all pairwise tests: ```{r} allTests <- equivTestSorensen(allOncoGeneLists, d0 = 0.2857, onto = "MF", GOLevel = 5, geneUniverse = humanEntrezIDs, orgPackg = "org.Hs.eg.db") getPvalue(allTests) getDissimilarity(allTests, simplify = FALSE) ``` # Alternative representations of contingency tables of joint enrichment Besides 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`: ```{r} enrichMat <- matrix(c(20, 1, 9, 2149), nrow = 2) enrichMat dSorensen(enrichMat) enrichVec <- c(20, 1, 9, 2149) equivTestSorensen(enrichVec) equivTestSorensen(enrichVec, boot = TRUE) len3Vec <- c(20, 1, 9) dSorensen(len3Vec) seSorensen(len3Vec) duppSorensen(len3Vec) # Error, bootstrapping requires the full (4 values) contingency table: try(duppSorensen(len3Vec, boot = TRUE), TRUE) ``` # Session information {.unnumbered} All software and respective versions used to produce this document are listed below. ```{r sessionInfo} sessionInfo() ``` # References {.unnumbered} Flores, 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).