From a0866ad35945e518b4744f4cb7c6e2026007c221 Mon Sep 17 00:00:00 2001 From: Moosa Rezwani Date: Thu, 26 Dec 2024 01:57:47 +0100 Subject: [PATCH] Update Enrichr functions - Implement the option to provide background gene list (Add rba_enrichr_add_background and rewrite other functions accordingly) - Revise function manuals --- NAMESPACE | 1 + R/enrichr.R | 489 +++++++++++++++++++++++------- R/internal_functions.R | 8 +- man/rba_enrichr.Rd | 39 ++- man/rba_enrichr_add_background.Rd | 84 +++++ man/rba_enrichr_add_list.Rd | 47 ++- man/rba_enrichr_enrich.Rd | 43 ++- man/rba_enrichr_gene_map.Rd | 9 +- man/rba_enrichr_libs.Rd | 35 ++- man/rba_enrichr_view_list.Rd | 20 +- 10 files changed, 593 insertions(+), 182 deletions(-) create mode 100644 man/rba_enrichr_add_background.Rd diff --git a/NAMESPACE b/NAMESPACE index 9e23246a..e0221645 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -2,6 +2,7 @@ export(rba_connection_test) export(rba_enrichr) +export(rba_enrichr_add_background) export(rba_enrichr_add_list) export(rba_enrichr_enrich) export(rba_enrichr_gene_map) diff --git a/R/enrichr.R b/R/enrichr.R index fbb0ef1f..9e5af23d 100644 --- a/R/enrichr.R +++ b/R/enrichr.R @@ -1,28 +1,30 @@ #' Retrieve a List of available libraries from Enrichr #' -#' This function will retrieve a list of available libraries in Enrichr with -#' their statistics. And by default, will save those names as a global option -#' ("rba_enrichr_libs") to be available for other Enrichr functions that -#' internally require the names of Enrichr libraries. -#' -#' You should call this function once per R session with the argument -#' 'store_in_options = TRUE' before using \code{\link{rba_enrichr_enrich}} -#' or \code{\link{rba_enrichr}}. -#' \cr Nevertheless, rbioapi will do this for you in the background at the -#' first time you call any function which requires this. -#' \cr Note that using \code{\link{rba_enrichr}} is a more convenient way to -#' automatically perform this and other required function calls to enrich -#' your input gene-set. +#' This function retrieves a list of libraries available in Enrichr along with +#' their associated statistics. Each library represents a collection of gene sets +#' that can be used for enrichment analysis. +#' +#' By default, this function will save the library names as a global option +#' ("rba_enrichr_libs") for other Enrichr functions that internally require +#' the names of Enrichr libraries. You should call this function once per +#' R session with the argument 'store_in_options = TRUE' before +#' using \code{\link{rba_enrichr_enrich}} or \code{\link{rba_enrichr}}. +#' However, if you do not explicitly call it, rbioapi will automatically +#' execute this function in the background the when it is needed. +#' +#' Please note that \code{\link{rba_enrichr}} provides a one-step and +#' more convenient way to automatically handle this and other required +#' function calls needed to perform gene set enrichment analysis with Enrichr. #' #' @section Corresponding API Resources: #' "GET https://maayanlab.cloud/Enrichr/datasetStatistics" #' -#' @param store_in_options logical: (default = TRUE) Should a list of available -#' Enrichr libraries be saved as a global option? #' @param organism (default = "human") Which model organism version of Enrichr #' to use? Available options are: "human", (H. sapiens & M. musculus), #' "fly" (D. melanogaster), "yeast" (S. cerevisiae), "worm" (C. elegans) #' and "fish" (D. rerio). +#' @param store_in_options logical: (default = TRUE) Should a list of available +#' Enrichr libraries be saved as a global option? #' @param ... rbioapi option(s). See \code{\link{rba_options}}'s #' arguments manual for more information on available options. #' @@ -59,8 +61,8 @@ #' @family "Enrichr" #' @seealso \code{\link{rba_enrichr}} #' @export -rba_enrichr_libs <- function(store_in_options = FALSE, - organism = "human", +rba_enrichr_libs <- function(organism = "human", + store_in_options = TRUE, ...){ ## Load Global Options .rba_ext_args(...) @@ -92,34 +94,51 @@ rba_enrichr_libs <- function(store_in_options = FALSE, ## Save Library Names as Global Options if (isTRUE(store_in_options) && utils::hasName(final_output, "libraryName")) { - options(rba_enrichr_libs = final_output[["libraryName"]]) + + enrichr_libs <- getOption("rba_enrichr_libs", default = list()) + enrichr_libs[[organism]] <- final_output[["libraryName"]] + options("rba_enrichr_libs" = enrichr_libs) + } return(final_output) } #' Upload Your Gene-List to Enrichr #' -#' Prior to perform enrichment, Enrichr requires you to upload your gene-list -#' and retrieve a 'user list ID'. +#' This function uploads your gene list to Enrichr and retrieves a unique +#' 'user list ID' required for performing enrichment analysis. #' -#' Note that using \code{\link{rba_enrichr}} is a more convenient way to -#' automatically perform this and other required function calls to -#' perform enrichment analysis on your input gene-set. +#' Enrichr uses separate APIs for analysis with or without a background gene +#' list. Set `speedrichr = TRUE` if this gene list will be used with a +#' background gene list; otherwise, set it to FALSE. Gene lists submitted with +#' `speedrichr = TRUE` can only be analyzed with a background set, and those +#' submitted with `speedrichr = FALSE` can only be analyzed without one. +#' Currently, background-based enrichment is supported only for human +#' libraries. +#' +#' Please note that \code{\link{rba_enrichr}} provides a one-step and +#' more convenient way to automatically handle this and other required +#' function calls needed to perform gene set enrichment analysis with Enrichr. #' #' @section Corresponding API Resources: #' "POST https://maayanlab.cloud/Enrichr/addList" +#' \cr "POST https://maayanlab.cloud/speedrichr/api/addList" #' -#' @param gene_list A vector with Entrez gene symbols. -#' @param description (optional) A name or description to be associated with your +#' @param gene_list A character vector with Entrez gene symbols of test genes. +#' @param description (optional) A description to be associated with your #' uploaded gene-set to Enrichr servers. #' @param organism (default = "human") Which model organism version of Enrichr #' to use? Available options are: "human", (H. sapiens & M. musculus), #' "fly" (D. melanogaster), "yeast" (S. cerevisiae), "worm" (C. elegans) #' and "fish" (D. rerio). +#' @param speedrichr logical (default = FALSE) Set to TRUE if you will use this +#' gene list with a background list; otherwise, set to FALSE. Only available +#' for human libraries. Refer to the details section for more information. #' @param ... rbioapi option(s). See \code{\link{rba_options}}'s #' arguments manual for more information on available options. #' -#' @return A list with two unique IDs for your uploaded gene sets. +#' @return A list with the unique IDs for your uploaded gene list. `userListId` +#' is the ID required for later steps. #' #' @references \itemize{ #' \item Chen, E.Y., Tan, C.M., Kou, Y. et al. Enrichr: interactive and @@ -146,7 +165,13 @@ rba_enrichr_libs <- function(store_in_options = FALSE, #' @examples #' \donttest{ #' rba_enrichr_add_list(gene_list = c("TP53", "TNF", "EGFR"), -#' description = "tumoral genes") +#' description = "tumoral genes", +#' speedrichr = FALSE) +#' } +#' \donttest{ +#' rba_enrichr_add_list(gene_list = c("RAG1", "RAG2", "DNTT", "LIG4", "ARTEMIS"), +#' description = "TCR rearrangment", +#' speedrichr = TRUE) #' } #' #' @family "Enrichr" @@ -155,6 +180,7 @@ rba_enrichr_libs <- function(store_in_options = FALSE, rba_enrichr_add_list <- function(gene_list, description = NULL, organism = "human", + speedrichr = FALSE, ...){ ## Load Global Options .rba_ext_args(...) @@ -166,13 +192,28 @@ rba_enrichr_add_list <- function(gene_list, list(arg = "organism", class = "character", no_null = TRUE, - val = c("human", "fly", "yeast", "worm", "fish")) - )) + val = c("human", "fly", "yeast", "worm", "fish")), + list(arg = "speedrichr", + class = "logical", + no_null = TRUE)), + cond = list(list(quote((isTRUE(speedrichr)) && organism != "human"), + "Using speedrichr (to provide background gene list later) is only availbale for `human`."))) .msg("Uploading %s gene symbols to Enrichr %s.", length(gene_list), organism) ## Build POST API Request's URL + input_path <- paste0( + .rba_stg( + "enrichr", "pth", ifelse(speedrichr, "speedrichr", organism)), + "addList" + ) + + # Description is mandatory for speedrichr + if (isTRUE(speedrichr) && is.null(description)) { + description = "Submitted to speedrichr" + } + call_body <- .rba_query(init = list("format" = "text", "list" = paste(unique(gene_list), collapse = "\n")), @@ -180,11 +221,11 @@ rba_enrichr_add_list <- function(gene_list, !is.null(description), description)) + ## Build Function-Specific Call input_call <- .rba_httr(httr = "post", url = .rba_stg("enrichr", "url"), - path = paste0(.rba_stg("enrichr", "pth", organism), - "addList"), + path = input_path, body = call_body, accept = "application/json", parser = "json->list_simp", @@ -197,22 +238,25 @@ rba_enrichr_add_list <- function(gene_list, #' View an Uploaded Gene List #' -#' Retrieve a list of uploaded genes under a 'user list ID'. +#' Retrieve the list of uploaded genes with a given 'user list ID'. #' #' @section Corresponding API Resources: #' "GET https://maayanlab.cloud/Enrichr/view" # -#' @param user_list_id a user_list_id returned to you after uploading a gene +#' @param user_list_id a user list ID returned after uploading a gene #' list using \code{\link{rba_enrichr_add_list}} #' @param organism (default = "human") Which model organism version of Enrichr #' to use? Available options are: "human", (H. sapiens & M. musculus), #' "fly" (D. melanogaster), "yeast" (S. cerevisiae), "worm" (C. elegans) #' and "fish" (D. rerio). +#' @param speedrichr logical (default = FALSE) Did you upload your gene list +#' to speedrichr API? (i.e. did you intend to use this gene list along with +#' a background gene list?) #' @param ... rbioapi option(s). See \code{\link{rba_options}}'s #' arguments manual for more information on available options. #' -#' @return A list containing the genes and description available under the -#' supplied user_list_id +#' @return A list containing the genes and description associated to the +#' supplied user_list_id. #' #' @references \itemize{ #' \item Chen, E.Y., Tan, C.M., Kou, Y. et al. Enrichr: interactive and @@ -245,18 +289,24 @@ rba_enrichr_add_list <- function(gene_list, #' @export rba_enrichr_view_list <- function(user_list_id, organism = "human", + speedrichr = FALSE, ...){ ## Load Global Options .rba_ext_args(...) ## Check User-input Arguments .rba_args(cons = list(list(arg = "user_list_id", - class = c("numeric", "integer"), + class = c("numeric"), len = 1), list(arg = "organism", class = "character", no_null = TRUE, - val = c("human", "fly", "yeast", "worm", "fish")) - )) + val = c("human", "fly", "yeast", "worm", "fish")), + list(arg = "speedrichr", + class = "logical", + no_null = TRUE)), + cond = list(list(quote((isTRUE(speedrichr)) && organism != "human"), + "Using speedrichr (to provide background gene list later) is only availbale for `human`.")) + ) .msg("Retrieving the gene list under the ID %s from Enrichr %s.", user_list_id, organism) @@ -280,6 +330,95 @@ rba_enrichr_view_list <- function(user_list_id, return(final_output) } +#' Upload Background Gene-List to Enrichr +#' +#' In addition to the main gene list, you can also submit a background gene +#' list to Enrichr. This gene list can be used later to compute the +#' statistics of the enrichment analysis. +#' +#' Please note that \code{\link{rba_enrichr}} provides a one-step and +#' more convenient way to automatically handle this and other required +#' function calls needed to perform gene set enrichment analysis with Enrichr. +#' +#' @section Corresponding API Resources: +#' "POST https://maayanlab.cloud/speedrichr/api/addbackground" +#' +#' @param background_genes A character vector of Entrez gene symbols of the +#' background genes. +#' @param ... rbioapi option(s). See \code{\link{rba_options}}'s +#' arguments manual for more information on available options. +#' +#' @return A list with the unique IDs for your uploaded background gene list. +#' +#' @references \itemize{ +#' \item Chen, E.Y., Tan, C.M., Kou, Y. et al. Enrichr: interactive and +#' collaborative HTML5 gene list enrichment analysis tool. Bioinformatics +#' 14, 128 (2013). https://doi.org/10.1186/1471-2105-14-128 +#' \item Maxim V. Kuleshov, Matthew R. Jones, Andrew D. Rouillard, Nicolas +#' F. Fernandez, Qiaonan Duan, Zichen Wang, Simon Koplev, Sherry L. Jenkins, +#' Kathleen M. Jagodnik, Alexander Lachmann, Michael G. McDermott, +#' Caroline D. Monteiro, Gregory W. Gundersen, Avi Ma’ayan, Enrichr: a +#' comprehensive gene set enrichment analysis web server 2016 update, +#' Nucleic Acids Research, Volume 44, Issue W1, 8 July 2016, Pages W90–W97, +#' https://doi.org/10.1093/nar/gkw377 +#' \item Xie, Z., Bailey, A., Kuleshov, M. V., Clarke, D. J. B., +#' Evangelista, J. E., Jenkins, S. L., Lachmann, A., Wojciechowicz, M. L., +#' Kropiwnicki, E., Jagodnik, K. M., Jeon, M., & Ma’ayan, A. (2021). Gene +#' set knowledge discovery with Enrichr. Current Protocols, 1, e90. +#' doi: 10.1002/cpz1.90 +#' \item \href{https://maayanlab.cloud/Enrichr/help#api}{Enrichr API +#' Documentation} +#' \item \href{https://maayanlab.cloud/Enrichr/help#terms}{Citations note +#' on Enrichr website} +#' } +#' +#' @examples +#' \donttest{ +#' my_background_genes <- c( +#' "NSUN3", "POLRMT", "NLRX1", "SFXN5", "ZC3H12C", "SLC25A39", "ARSG", +#' "DEFB29", "PCMTD2", "ACAA1A", "LRRC1", "2810432D09RIK", "SEPHS2", +#' "SAC3D1", "TMLHE", "LOC623451", "TSR2", "PLEKHA7", "GYS2", "ARHGEF12", +#' "HIBCH", "LYRM2", "ZBTB44", "ENTPD5", "RAB11FIP2", "LIPT1", +#' "INTU", "ANXA13", "KLF12", "SAT2", "GAL3ST2", "VAMP8", "FKBPL", +#' "AQP11", "TRAP1", "PMPCB", "TM7SF3", "RBM39", "BRI3", "KDR", "ZFP748", +#' "NAP1L1", "DHRS1", "LRRC56", "WDR20A", "STXBP2", "KLF1", "UFC1", +#' "CCDC16", "9230114K14RIK", "RWDD3", "2610528K11RIK") +#' +#' rba_enrichr_add_background(background_genes = my_background_genes) +#' } +#' +#' @family "Enrichr" +#' @seealso \code{\link{rba_enrichr}} +#' @export +rba_enrichr_add_background <- function(background_genes, + ...){ + ## Load Global Options + .rba_ext_args(...) + ## Check User-input Arguments + .rba_args(cons = list(list(arg = "background_genes", + class = "character"))) + + .msg("Uploading %s background gene symbols to Enrichr.", + length(background_genes)) + + ## Build POST API Request's URL + call_body <- list(background = paste(background_genes, collapse = "\n")) + + ## Build Function-Specific Call + input_call <- .rba_httr(httr = "post", + url = .rba_stg("enrichr", "url"), + path = paste0(.rba_stg("enrichr", "pth", "speedrichr"), + "addbackground"), + body = call_body, + accept = "application/json", + parser = "json->list_simp", + save_to = .rba_file("enrichr_add_background.json")) + + ## Call API + final_output <- .rba_skeleton(input_call) + return(final_output) +} + #' Internal function for rba_enrichr_enrich #' #' This is an internal helper function which will retrieve the enrichment @@ -290,6 +429,7 @@ rba_enrichr_view_list <- function(user_list_id, #' #' @section Corresponding API Resources: #' "GET https://maayanlab.cloud/Enrichr/enrich" +#' \cr "POST https://maayanlab.cloud/speedrichr/api/backgroundenrich" #' #' @param user_list_id An ID returned to you after uploading a gene #' list using \code{\link{rba_enrichr_add_list}} @@ -330,6 +470,7 @@ rba_enrichr_view_list <- function(user_list_id, #' #' @noRd .rba_enrichr_enrich_internal <- function(user_list_id, + background_id = NULL, gene_set_library, save_name, organism = "human", @@ -337,42 +478,105 @@ rba_enrichr_view_list <- function(user_list_id, ...){ ## Load Global Options .rba_ext_args(...) + ## Build GET API Request's query - call_query <- list("userListId" = user_list_id, - "backgroundType" = gene_set_library) + if (is.null(background_id)) { + httr_verb <- "get" + httr_accept <- "text/tab-separated-values" + call_query <- list("userListId" = user_list_id, + "backgroundType" = gene_set_library) + call_body = NULL - ## Build Function-Specific Call - parser_input <- function(x) { - httr::content(x, - as = "text", - type = "text/tab-separated-values", - encoding = "UTF-8") + path_input <- paste0(.rba_stg("enrichr", "pth", organism), + "export") + + parser_input <- function(httr_response) { + parsed_response <- httr::content(httr_response, + as = "text", + type = "text/tab-separated-values", + encoding = "UTF-8") + try(utils::read.delim(textConnection(parsed_response), + sep = "\t", header = TRUE, + stringsAsFactors = FALSE), + silent = !get("diagnostics")) + } + + } else { + httr_verb <- "post" + httr_accept <- "application/json" + call_query <- NULL + call_body <- list("userListId" = user_list_id, + "backgroundid" = background_id, + "backgroundType" = gene_set_library) + + path_input <- paste0(.rba_stg("enrichr", "pth", "speedrichr"), + "backgroundenrich") + + parser_input <- function(httr_response) { + parsed_response <- gsub("Infinity", "\"Inf\"", httr::content(httr_response, + as = "text", + encoding = "UTF-8")) + # parsed_response <- gsub("NaN", "\"NaN\"", parsed_response) + parsed_response <- jsonlite::fromJSON(parsed_response)[[1]] + + parsed_response <- lapply(parsed_response, function(response_row) { + names(response_row) <- c("Rank", "Term", + "P.value", "Odds.Ratio", + "Combined.Score", "Genes", + "Adjusted.P.value", + "Old.P.value", "Old.adjusted.P.value") + response_row$Overlapping.genes <- paste0( + response_row$Overlapping.genes, + collapse = ";") + + return(response_row) + }) + + if (length(parsed_response) == 0) { + parsed_response <- data.frame( + Rank = integer(), + Term = character(), + P.value = numeric(), + Odds.Ratio = numeric(), + Combined.Score = numeric(), + Genes = character(), + Adjusted.P.value = numeric(), + Old.P.value = numeric(), + Old.adjusted.P.value = numeric() + ) + } else { + parsed_response <- do.call(rbind, lapply(parsed_response, function(response_row) + {as.data.frame(response_row, stringsAsFactors = FALSE)} + ) + ) + numeric_cols <- c("Rank", "P.value", "Odds.Ratio", "Combined.Score", + "Adjusted.P.value", "Old.P.value", "Old.adjusted.P.value") + parsed_response[numeric_cols] <- lapply(parsed_response[numeric_cols], as.numeric) + } + return(parsed_response) + } } - input_call <- .rba_httr(httr = "get", + input_call <- .rba_httr(httr = httr_verb, .rba_stg("enrichr", "url"), - path = paste0(.rba_stg("enrichr", "pth", organism), - "export"), + path = path_input, query = call_query, - httr::accept("text/tab-separated-values"), + body = call_body, + httr::accept(httr_accept), parser = parser_input, save_to = .rba_file(save_name)) ## Call API Sys.sleep(sleep_time) - final_output_raw <- .rba_skeleton(input_call) - final_output <- try(utils::read.delim(textConnection(final_output_raw), - sep = "\t", header = TRUE, - stringsAsFactors = FALSE), - silent = !get("diagnostics")) + final_output <- .rba_skeleton(input_call) if (is.data.frame(final_output)) { return(final_output) } else { - error_message <- paste0("Error: Couldn't parse the server response for the requested Enrichr analysis.", - "Please try again. If the problem persists, kindly report the issue to us.", - "The server's raw response is:", - as.character(final_output_raw), + error_message <- paste0("Error: Couldn't parse the server response for the requested Enrichr analysis. ", + "Please try again. If the problem persists, kindly report the issue to us. ", + "The server's raw response was: ", + as.character(final_output), collapse = "\n") if (isTRUE(get("skip_error"))) { return(error_message) @@ -385,35 +589,47 @@ rba_enrichr_view_list <- function(user_list_id, #' Get Enrichr Enrichment Results #' -#' This function which will retrieve the enrichment results of your -#' supplied gene-list id against one or multiple Enrichr libraries. +#' This function retrieves enrichment analysis results for your supplied +#' `user_list_id` against one or multiple Enrichr libraries. +#' +#' If `background_id` is supplied, this function will interact with the +#' speedrichr API. In this case, `user_list_id` must have been obtained +#' from a \code{\link{rba_enrichr_add_list}} call with the `speedrichr` +#' parameter set to `TRUE`. Additionally, this feature is only available +#' for "human" organism. #' -#' Note that using \code{\link{rba_enrichr}} is a more convenient way to -#' automatically perform this and other required function calls to -#' perform enrichment analysis on your input gene-set. +#' Please note that \code{\link{rba_enrichr}} provides a one-step and +#' more convenient way to automatically handle this and other required +#' function calls needed to perform gene set enrichment analysis with Enrichr. #' #' @section Corresponding API Resources: #' "GET https://maayanlab.cloud/Enrichr/enrich" +#' \cr "POST https://maayanlab.cloud/speedrichr/api/backgroundenrich" #' -#' @param user_list_id An ID returned to you after uploading a gene -#' list using \code{\link{rba_enrichr_add_list}} +#' @param user_list_id An ID returned after uploading a gene list +#' using \code{\link{rba_enrichr_add_list}}, with the `speedrichr` set to +#' TRUE or FALSE depending on whether you intend to analyze this gene list +#' with or without a background gene list, respectively. +#' @param background_id An ID returned after uploading a background gene +#' list using \code{\link{rba_enrichr_add_background}} #' @param gene_set_library One of the: #' \enumerate{ #' \item "all" to select all of the available Enrichr gene-set libraries. -#' \item A gene-set library name existed in the results -#' retrieved via \code{\link{rba_enrichr_libs}} +#' \item A gene-set library name. You can retrieve the available options +#' for a given species using \code{\link{rba_enrichr_libs}}. #' \item If regex_library_name = TRUE, A partially-matching name a regex #' pattern that correspond to one or more of Enrichr library names. #' } #' @param regex_library_name logical: if TRUE (default) the supplied -#' gene_set_library will be regarded as a regex or partially matching name. if -#' FALSE, gene_set_library will be considered exact match. +#' gene_set_library will be considered as a regex pattern. +#' If FALSE, gene_set_library will be considered as an exact match. #' @param organism (default = "human") Which model organism version of Enrichr #' to use? Available options are: "human", (H. sapiens & M. musculus), #' "fly" (D. melanogaster), "yeast" (S. cerevisiae), "worm" (C. elegans) -#' and "fish" (D. rerio). -#' @param progress_bar logical: In case of selecting multiple Enrichr -#' libraries, should a progress bar be displayed? +#' and "fish" (D. rerio). If `background_id` is provided, the only available +#' option is "human". +#' @param progress_bar logical: (default = TRUE) if multiple Enrichr libraries +#' are selected, should a progress bar be displayed? #' @param ... rbioapi option(s). See \code{\link{rba_options}}'s #' arguments manual for more information on available options. #' @@ -464,31 +680,25 @@ rba_enrichr_enrich <- function(user_list_id, gene_set_library = "all", regex_library_name = TRUE, organism = "human", + background_id = NULL, progress_bar = TRUE, ...){ ## Load Global Options .rba_ext_args(...) ## get a list of available libraries - if (is.null(getOption("rba_enrichr_libs"))) { + if (is.null(getOption("rba_enrichr_libs")[[organism]])) { .msg("Calling rba_enrichr_libs() to get the names of available Enrichr %s libraries.", organism) - enrichr_libs <- rba_enrichr_libs(store_in_options = TRUE) + enrichr_libs <- rba_enrichr_libs(organism = organism, + store_in_options = TRUE) if (utils::hasName(enrichr_libs, "libraryName")) { enrichr_libs <- enrichr_libs[["libraryName"]] } - } else { - enrichr_libs <- getOption("rba_enrichr_libs") - } - if (length(enrichr_libs) <= 1) { - no_lib_msg <- "Error: Couldn't fetch available Enrichr libraries. Please manually run `rba_enrichr_libs(store_in_options = TRUE)`." - if (isTRUE(get("skip_error"))) { - return(no_lib_msg) - } else { - stop(no_lib_msg, call. = get("diagnostics")) - } + } else { + enrichr_libs <- getOption("rba_enrichr_libs")[[organism]] } ## handle different gene_set_library input situations @@ -506,11 +716,11 @@ rba_enrichr_enrich <- function(user_list_id, ignore.case = TRUE, value = TRUE, perl = TRUE) #check the results of regex if (length(gene_set_library) == 0) { + no_lib_error <- "Error: No Enrichr libraries matched your regex pattern." if (isTRUE(get("skip_error"))) { - return("Your regex pattern did not match any Enrichr library name.") + return(no_lib_error) } else { - stop("Your regex pattern did not match any Enrichr library name.", - call. = get("diagnostics")) + stop(no_lib_error, call. = get("diagnostics")) } } else if (length(gene_set_library) == 1) { run_mode <- "single" @@ -518,7 +728,8 @@ rba_enrichr_enrich <- function(user_list_id, run_mode <- "multiple" } } - } #end of if length(gene_set_library) > 1 + } # end of if length(gene_set_library) > 1 + ## Check User-input Arguments .rba_args(cons = list(list(arg = "user_list_id", class = c("numeric", "integer"), @@ -531,13 +742,19 @@ rba_enrichr_enrich <- function(user_list_id, list(arg = "organism", class = "character", no_null = TRUE, - val = c("human", "fly", "yeast", "worm", "fish")) - )) + val = c("human", "fly", "yeast", "worm", "fish")), + list(arg = "background_id", + class = "character", + len = 1)), + cond = list(list(quote((!is.null(background_id)) && organism != "human"), + "Providing background gene set is only availbale for `human`."))) + ## call Enrichr API if (run_mode == "single") { .msg("Performing enrichment analysis on gene-list %s against Enrichr %s library: %s.", user_list_id, organism, gene_set_library) final_output <- .rba_enrichr_enrich_internal(user_list_id = user_list_id, + background_id = background_id, gene_set_library = gene_set_library, save_name = sprintf("enrichr_%s_%s.json", user_list_id, @@ -562,6 +779,7 @@ rba_enrichr_enrich <- function(user_list_id, final_output <- lapply(gene_set_library, function(x){ lib_enrich_res <- .rba_enrichr_enrich_internal(user_list_id = user_list_id, + background_id = background_id, gene_set_library = x, save_name = sprintf("enrichr_%s_%s.json", user_list_id, @@ -590,7 +808,7 @@ rba_enrichr_enrich <- function(user_list_id, #' "GET https://maayanlab.cloud/Enrichr/genemap" #' #' @param gene character: An Entrez gene symbol. -#' @param catagorize logical: Should the category informations be included? +#' @param categorize logical: Should the category information be included? #' @param organism (default = "human") Which model organism version of Enrichr #' to use? Available options are: "human", (H. sapiens & M. musculus), #' "fly" (D. melanogaster), "yeast" (S. cerevisiae), "worm" (C. elegans) @@ -598,7 +816,7 @@ rba_enrichr_enrich <- function(user_list_id, #' @param ... rbioapi option(s). See \code{\link{rba_options}}'s #' arguments manual for more information on available options. #' -#' @return a list containing the search results of your supplied gene. +#' @return A nested list containing the search results of your supplied gene. #' #' @references \itemize{ #' \item Chen, E.Y., Tan, C.M., Kou, Y. et al. Enrichr: interactive and @@ -627,13 +845,13 @@ rba_enrichr_enrich <- function(user_list_id, #' rba_enrichr_gene_map(gene = "p53") #' } #' \donttest{ -#' rba_enrichr_gene_map(gene = "p53", catagorize = TRUE) +#' rba_enrichr_gene_map(gene = "p53", categorize = TRUE) #' } #' #' @family "Enrichr" #' @export rba_enrichr_gene_map <- function(gene, - catagorize = FALSE, + categorize = FALSE, organism = "human", ...){ ## Load Global Options @@ -642,7 +860,7 @@ rba_enrichr_gene_map <- function(gene, .rba_args(cons = list(list(arg = "gene", class = "character", len = 1), - list(arg = "catagorize", + list(arg = "categorize", class = "logical"), list(arg = "organism", class = "character", @@ -656,7 +874,7 @@ rba_enrichr_gene_map <- function(gene, call_query <- .rba_query(init = list("gene" = gene, "json" = "true"), list("setup", - isTRUE(catagorize), + isTRUE(categorize), "true")) ## Build Function-Specific Call input_call <- .rba_httr(httr = "get", @@ -665,7 +883,7 @@ rba_enrichr_gene_map <- function(gene, "genemap"), query = call_query, accept = "application/json", - parser = "json->list_simp", + parser = "json->list_simp_flt_df", save_to = .rba_file("enrichr_gene_map.json")) ## Call API @@ -675,26 +893,33 @@ rba_enrichr_gene_map <- function(gene, #' A One-step Wrapper for Gene-list Enrichment Using Enrichr #' -#' This function is an easy-to-use wrapper for the multiple function calls -#' necessary to perform enrichment analysis on a given gene-list using Enrichr. -#' see details section for more information. +#' This function provides a convenient one-step wrapper for performing +#' enrichment analysis on a given gene list using Enrichr. It simplifies the +#' process by internally calling the necessary functions in the correct order. +#' See the details section for more information. #' #' This function will call other rba_enrichr_*** functions with the following #' order: #' \enumerate{ -#' \item (If neccessary) Call \code{\link{rba_enrichr_libs}} to obtain a list -#' of available libraries in Enrichr. +#' \item (If necessary) Call \code{\link{rba_enrichr_libs}} to obtain a list +#' of available libraries in Enrichr for the given organism. #' \item Call \code{\link{rba_enrichr_add_list}} to upload your gene-list #' and obtain a 'user list ID'. +#' \item (If necessary) Call \code{\link{rba_enrichr_add_background}} to +#' upload your background gene-list and obtain a 'background list ID'. #' \item Call \code{\link{rba_enrichr_enrich}} to perform enrichment analysis #' on the gene-list against one or multiple Enrichr libraries #' } #' @section Corresponding API Resources: #' "GET https://maayanlab.cloud/Enrichr/datasetStatistics" #' \cr "POST https://maayanlab.cloud/Enrichr/addList" +#' \cr "POST https://maayanlab.cloud/speedrichr/api/addList" +#' \cr "POST https://maayanlab.cloud/speedrichr/api/addbackground" #' \cr "GET https://maayanlab.cloud/Enrichr/enrich" +#' \cr "POST https://maayanlab.cloud/speedrichr/api/backgroundenrich" #' #' @inheritParams rba_enrichr_add_list +#' @inheritParams rba_enrichr_add_background #' @inheritParams rba_enrichr_enrich #' #' @return A list containing data frames of the enrichment results of your @@ -744,7 +969,8 @@ rba_enrichr <- function(gene_list, gene_set_library = "all", regex_library_name = TRUE, organism = "human", - progress_bar = FALSE, + background_genes = NULL, + progress_bar = TRUE, ...) { ## Load Global Options .rba_ext_args(...) @@ -760,17 +986,27 @@ rba_enrichr <- function(gene_list, list(arg = "organism", class = "character", no_null = TRUE, - val = c("human", "fly", "yeast", "worm", "fish")) - )) + val = c("human", "fly", "yeast", "worm", "fish")), + list(arg = "background_genes", + class = "character")), + cond = list(list(quote((!is.null(background_genes)) && organism != "human"), + "Providing background gene set is only availbale for `human`."), + list(quote(!is.null(background_genes) && (!all(gene_list %in% background_genes))), + "Some of the gene_list elements are not present in background_genes")) + ) + .msg("--Step 1/3:") - enrichr_libs <- rba_enrichr_libs(store_in_options = TRUE) + enrichr_libs <- rba_enrichr_libs(organism = organism, + store_in_options = TRUE) if (utils::hasName(enrichr_libs, "libraryName")) { enrichr_libs <- enrichr_libs[["libraryName"]] } - if (exists("enrichr_libs") && length(enrichr_libs) <= 1) { # Halt at step 1 - no_lib_msg <- paste0("Error: Couldn't fetch available Enrichr libraries. Please manually run `rba_enrichr_libs(store_in_options = TRUE)`.", + step_1_success <- exists("enrichr_libs") && length(enrichr_libs) > 1 + + if (!step_1_success) { # Halt at step 1 + no_lib_msg <- paste0("Error: Couldn't fetch available Enrichr libraries. Please manually run `rba_enrichr_libs(store_in_options = TRUE)`. ", "If the problem persists, kindly report this issue to us. The error message was: ", try(enrichr_libs), collapse = "\n") @@ -787,22 +1023,43 @@ rba_enrichr <- function(gene_list, Sys.sleep(2) list_id <- rba_enrichr_add_list(gene_list = gene_list, description = description, + organism = organism, + speedrichr = !is.null(background_genes), ...) - if (exists("list_id") && utils::hasName(list_id, "userListId")) { # proceed to step 3 + step_2_success <- exists("list_id") && utils::hasName(list_id, "userListId") + + if (!is.null(background_genes)) { + background_id <- rba_enrichr_add_background(background_genes = background_genes) + + step_2_success <- step_2_success && exists("background_id") && utils::hasName(background_id, "backgroundid") + if (step_2_success) { + background_id <- background_id$backgroundid + } + + } else { + background_id <- NULL + } + + if (step_2_success) { # proceed to step 3 .msg("--Step 3/3:") Sys.sleep(2) enriched <- rba_enrichr_enrich(user_list_id = list_id$userListId, gene_set_library = gene_set_library, regex_library_name = regex_library_name, + background_id = background_id, + organism = organism, progress_bar = progress_bar, ...) - if (exists("enriched") && (is.list(enriched) || is.data.frame(enriched))) { # Finish step 3 + + step_3_success <- exists("enriched") && (is.list(enriched) || is.data.frame(enriched)) + + if (step_3_success) { # Finish step 3 return(enriched) } else { # Halt at step 3 - no_enriched_msg <- paste0("Error: Couldn't retrieve the submitted Enrichr analysis request.", - "Please retry or manually run the required steps as demonstrated in the `Enrichr & rbioapi` vignette article, section `Approach 2: Going step-by-step`", - "If the problem persists, kindly report this issue to us. The error message was: ", + no_enriched_msg <- paste0("Error: Couldn't retrieve the submitted Enrichr analysis request. ", + "Please retry or manually run the required steps as demonstrated in the `Enrichr & rbioapi` vignette article, section `Approach 2: Going step-by-step`. ", + "If the problem persists, kindly report this issue to us. The error message was:", try(enriched), collapse = "\n") if (isTRUE(get("skip_error"))) { @@ -813,8 +1070,8 @@ rba_enrichr <- function(gene_list, } } } else { # Halt at step 2 - no_list_msg <- paste0("Error: Couldn't upload your genes list to Enrichr.", - "Please retry or manually run the required steps as demonstrated in the `Enrichr & rbioapi` vignette article, section `Approach 2: Going step-by-step`", + no_list_msg <- paste0("Error: Couldn't upload your genes list to Enrichr. ", + "Please retry or manually run the required steps as demonstrated in the `Enrichr & rbioapi` vignette article, section `Approach 2: Going step-by-step`. ", "If the problem persists, kindly report this issue to us. The error message was: ", try(list_id), collapse = "\n") diff --git a/R/internal_functions.R b/R/internal_functions.R index 35d506e0..187b5f7e 100644 --- a/R/internal_functions.R +++ b/R/internal_functions.R @@ -31,13 +31,15 @@ "fly", "yeast", "worm", - "fish")), + "fish", + "speedrichr")), human = "Enrichr/", fly = "FlyEnrichr/", yeast = "YeastEnrichr/", worm = "WormEnrichr/", - fish = "FishEnrichr/"), - ptn = "^(https?://)?(www\\.)?maayanlab\\.cloud/.*Enrichr/", + fish = "FishEnrichr/", + speedrichr = "speedrichr/api/"), + ptn = "^(https?://)?(www\\.)?maayanlab\\.cloud/(.*Enrichr|speedrichr)/", err_ptn = "^$" ), ensembl = switch( diff --git a/man/rba_enrichr.Rd b/man/rba_enrichr.Rd index 2910a9df..60300079 100644 --- a/man/rba_enrichr.Rd +++ b/man/rba_enrichr.Rd @@ -10,36 +10,40 @@ rba_enrichr( gene_set_library = "all", regex_library_name = TRUE, organism = "human", - progress_bar = FALSE, + background_genes = NULL, + progress_bar = TRUE, ... ) } \arguments{ -\item{gene_list}{A vector with Entrez gene symbols.} +\item{gene_list}{A character vector with Entrez gene symbols of test genes.} -\item{description}{(optional) A name or description to be associated with your +\item{description}{(optional) A description to be associated with your uploaded gene-set to Enrichr servers.} \item{gene_set_library}{One of the: \enumerate{ \item "all" to select all of the available Enrichr gene-set libraries. -\item A gene-set library name existed in the results -retrieved via \code{\link{rba_enrichr_libs}} +\item A gene-set library name. You can retrieve the available options +for a given species using \code{\link{rba_enrichr_libs}}. \item If regex_library_name = TRUE, A partially-matching name a regex pattern that correspond to one or more of Enrichr library names. }} \item{regex_library_name}{logical: if TRUE (default) the supplied -gene_set_library will be regarded as a regex or partially matching name. if -FALSE, gene_set_library will be considered exact match.} +gene_set_library will be considered as a regex pattern. +If FALSE, gene_set_library will be considered as an exact match.} \item{organism}{(default = "human") Which model organism version of Enrichr to use? Available options are: "human", (H. sapiens & M. musculus), "fly" (D. melanogaster), "yeast" (S. cerevisiae), "worm" (C. elegans) and "fish" (D. rerio).} -\item{progress_bar}{logical: In case of selecting multiple Enrichr -libraries, should a progress bar be displayed?} +\item{background_genes}{A character vector of Entrez gene symbols of the +background genes.} + +\item{progress_bar}{logical: (default = TRUE) if multiple Enrichr libraries +are selected, should a progress bar be displayed?} \item{...}{rbioapi option(s). See \code{\link{rba_options}}'s arguments manual for more information on available options.} @@ -49,18 +53,21 @@ A list containing data frames of the enrichment results of your supplied gene-list against the selected Enrichr libraries. } \description{ -This function is an easy-to-use wrapper for the multiple function calls - necessary to perform enrichment analysis on a given gene-list using Enrichr. - see details section for more information. +This function provides a convenient one-step wrapper for performing + enrichment analysis on a given gene list using Enrichr. It simplifies the + process by internally calling the necessary functions in the correct order. + See the details section for more information. } \details{ This function will call other rba_enrichr_*** functions with the following order: \enumerate{ - \item (If neccessary) Call \code{\link{rba_enrichr_libs}} to obtain a list - of available libraries in Enrichr. + \item (If necessary) Call \code{\link{rba_enrichr_libs}} to obtain a list + of available libraries in Enrichr for the given organism. \item Call \code{\link{rba_enrichr_add_list}} to upload your gene-list and obtain a 'user list ID'. + \item (If necessary) Call \code{\link{rba_enrichr_add_background}} to + upload your background gene-list and obtain a 'background list ID'. \item Call \code{\link{rba_enrichr_enrich}} to perform enrichment analysis on the gene-list against one or multiple Enrichr libraries } @@ -69,7 +76,10 @@ This function will call other rba_enrichr_*** functions with the following "GET https://maayanlab.cloud/Enrichr/datasetStatistics" \cr "POST https://maayanlab.cloud/Enrichr/addList" + \cr "POST https://maayanlab.cloud/speedrichr/api/addList" + \cr "POST https://maayanlab.cloud/speedrichr/api/addbackground" \cr "GET https://maayanlab.cloud/Enrichr/enrich" + \cr "POST https://maayanlab.cloud/speedrichr/api/backgroundenrich" } \examples{ @@ -113,6 +123,7 @@ rba_enrichr(gene_list = c("TP53", "TNF", "EGFR"), } \seealso{ Other "Enrichr": +\code{\link{rba_enrichr_add_background}()}, \code{\link{rba_enrichr_add_list}()}, \code{\link{rba_enrichr_enrich}()}, \code{\link{rba_enrichr_gene_map}()}, diff --git a/man/rba_enrichr_add_background.Rd b/man/rba_enrichr_add_background.Rd new file mode 100644 index 00000000..47bbe0bf --- /dev/null +++ b/man/rba_enrichr_add_background.Rd @@ -0,0 +1,84 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/enrichr.R +\name{rba_enrichr_add_background} +\alias{rba_enrichr_add_background} +\title{Upload Background Gene-List to Enrichr} +\usage{ +rba_enrichr_add_background(background_genes, ...) +} +\arguments{ +\item{background_genes}{A character vector of Entrez gene symbols of the +background genes.} + +\item{...}{rbioapi option(s). See \code{\link{rba_options}}'s +arguments manual for more information on available options.} +} +\value{ +A list with the unique IDs for your uploaded background gene list. +} +\description{ +In addition to the main gene list, you can also submit a background gene + list to Enrichr. This gene list can be used later to compute the + statistics of the enrichment analysis. +} +\details{ +Please note that \code{\link{rba_enrichr}} provides a one-step and + more convenient way to automatically handle this and other required + function calls needed to perform gene set enrichment analysis with Enrichr. +} +\section{Corresponding API Resources}{ + + "POST https://maayanlab.cloud/speedrichr/api/addbackground" +} + +\examples{ +\donttest{ +my_background_genes <- c( +"NSUN3", "POLRMT", "NLRX1", "SFXN5", "ZC3H12C", "SLC25A39", "ARSG", +"DEFB29", "PCMTD2", "ACAA1A", "LRRC1", "2810432D09RIK", "SEPHS2", +"SAC3D1", "TMLHE", "LOC623451", "TSR2", "PLEKHA7", "GYS2", "ARHGEF12", +"HIBCH", "LYRM2", "ZBTB44", "ENTPD5", "RAB11FIP2", "LIPT1", +"INTU", "ANXA13", "KLF12", "SAT2", "GAL3ST2", "VAMP8", "FKBPL", +"AQP11", "TRAP1", "PMPCB", "TM7SF3", "RBM39", "BRI3", "KDR", "ZFP748", +"NAP1L1", "DHRS1", "LRRC56", "WDR20A", "STXBP2", "KLF1", "UFC1", +"CCDC16", "9230114K14RIK", "RWDD3", "2610528K11RIK") + +rba_enrichr_add_background(background_genes = my_background_genes) +} + +} +\references{ +\itemize{ + \item Chen, E.Y., Tan, C.M., Kou, Y. et al. Enrichr: interactive and + collaborative HTML5 gene list enrichment analysis tool. Bioinformatics + 14, 128 (2013). https://doi.org/10.1186/1471-2105-14-128 + \item Maxim V. Kuleshov, Matthew R. Jones, Andrew D. Rouillard, Nicolas + F. Fernandez, Qiaonan Duan, Zichen Wang, Simon Koplev, Sherry L. Jenkins, + Kathleen M. Jagodnik, Alexander Lachmann, Michael G. McDermott, + Caroline D. Monteiro, Gregory W. Gundersen, Avi Ma’ayan, Enrichr: a + comprehensive gene set enrichment analysis web server 2016 update, + Nucleic Acids Research, Volume 44, Issue W1, 8 July 2016, Pages W90–W97, + https://doi.org/10.1093/nar/gkw377 + \item Xie, Z., Bailey, A., Kuleshov, M. V., Clarke, D. J. B., + Evangelista, J. E., Jenkins, S. L., Lachmann, A., Wojciechowicz, M. L., + Kropiwnicki, E., Jagodnik, K. M., Jeon, M., & Ma’ayan, A. (2021). Gene + set knowledge discovery with Enrichr. Current Protocols, 1, e90. + doi: 10.1002/cpz1.90 + \item \href{https://maayanlab.cloud/Enrichr/help#api}{Enrichr API + Documentation} + \item \href{https://maayanlab.cloud/Enrichr/help#terms}{Citations note + on Enrichr website} + } +} +\seealso{ +\code{\link{rba_enrichr}} + +Other "Enrichr": +\code{\link{rba_enrichr}()}, +\code{\link{rba_enrichr_add_list}()}, +\code{\link{rba_enrichr_enrich}()}, +\code{\link{rba_enrichr_gene_map}()}, +\code{\link{rba_enrichr_libs}()}, +\code{\link{rba_enrichr_view_list}()} +} +\concept{"Enrichr"} diff --git a/man/rba_enrichr_add_list.Rd b/man/rba_enrichr_add_list.Rd index f9c84469..ad483898 100644 --- a/man/rba_enrichr_add_list.Rd +++ b/man/rba_enrichr_add_list.Rd @@ -4,12 +4,18 @@ \alias{rba_enrichr_add_list} \title{Upload Your Gene-List to Enrichr} \usage{ -rba_enrichr_add_list(gene_list, description = NULL, organism = "human", ...) +rba_enrichr_add_list( + gene_list, + description = NULL, + organism = "human", + speedrichr = FALSE, + ... +) } \arguments{ -\item{gene_list}{A vector with Entrez gene symbols.} +\item{gene_list}{A character vector with Entrez gene symbols of test genes.} -\item{description}{(optional) A name or description to be associated with your +\item{description}{(optional) A description to be associated with your uploaded gene-set to Enrichr servers.} \item{organism}{(default = "human") Which model organism version of Enrichr @@ -17,30 +23,50 @@ to use? Available options are: "human", (H. sapiens & M. musculus), "fly" (D. melanogaster), "yeast" (S. cerevisiae), "worm" (C. elegans) and "fish" (D. rerio).} +\item{speedrichr}{logical (default = FALSE) Set to TRUE if you will use this +gene list with a background list; otherwise, set to FALSE. Only available +for human libraries. Refer to the details section for more information.} + \item{...}{rbioapi option(s). See \code{\link{rba_options}}'s arguments manual for more information on available options.} } \value{ -A list with two unique IDs for your uploaded gene sets. +A list with the unique IDs for your uploaded gene list. `userListId` + is the ID required for later steps. } \description{ -Prior to perform enrichment, Enrichr requires you to upload your gene-list - and retrieve a 'user list ID'. +This function uploads your gene list to Enrichr and retrieves a unique + 'user list ID' required for performing enrichment analysis. } \details{ -Note that using \code{\link{rba_enrichr}} is a more convenient way to - automatically perform this and other required function calls to - perform enrichment analysis on your input gene-set. +Enrichr uses separate APIs for analysis with or without a background gene + list. Set `speedrichr = TRUE` if this gene list will be used with a + background gene list; otherwise, set it to FALSE. Gene lists submitted with + `speedrichr = TRUE` can only be analyzed with a background set, and those + submitted with `speedrichr = FALSE` can only be analyzed without one. + Currently, background-based enrichment is supported only for human + libraries. + +Please note that \code{\link{rba_enrichr}} provides a one-step and + more convenient way to automatically handle this and other required + function calls needed to perform gene set enrichment analysis with Enrichr. } \section{Corresponding API Resources}{ "POST https://maayanlab.cloud/Enrichr/addList" + \cr "POST https://maayanlab.cloud/speedrichr/api/addList" } \examples{ \donttest{ rba_enrichr_add_list(gene_list = c("TP53", "TNF", "EGFR"), - description = "tumoral genes") + description = "tumoral genes", + speedrichr = FALSE) +} +\donttest{ +rba_enrichr_add_list(gene_list = c("RAG1", "RAG2", "DNTT", "LIG4", "ARTEMIS"), + description = "TCR rearrangment", + speedrichr = TRUE) } } @@ -72,6 +98,7 @@ rba_enrichr_add_list(gene_list = c("TP53", "TNF", "EGFR"), Other "Enrichr": \code{\link{rba_enrichr}()}, +\code{\link{rba_enrichr_add_background}()}, \code{\link{rba_enrichr_enrich}()}, \code{\link{rba_enrichr_gene_map}()}, \code{\link{rba_enrichr_libs}()}, diff --git a/man/rba_enrichr_enrich.Rd b/man/rba_enrichr_enrich.Rd index eed7679e..5ed8310a 100644 --- a/man/rba_enrichr_enrich.Rd +++ b/man/rba_enrichr_enrich.Rd @@ -9,34 +9,41 @@ rba_enrichr_enrich( gene_set_library = "all", regex_library_name = TRUE, organism = "human", + background_id = NULL, progress_bar = TRUE, ... ) } \arguments{ -\item{user_list_id}{An ID returned to you after uploading a gene -list using \code{\link{rba_enrichr_add_list}}} +\item{user_list_id}{An ID returned after uploading a gene list +using \code{\link{rba_enrichr_add_list}}, with the `speedrichr` set to +TRUE or FALSE depending on whether you intend to analyze this gene list +with or without a background gene list, respectively.} \item{gene_set_library}{One of the: \enumerate{ \item "all" to select all of the available Enrichr gene-set libraries. -\item A gene-set library name existed in the results -retrieved via \code{\link{rba_enrichr_libs}} +\item A gene-set library name. You can retrieve the available options +for a given species using \code{\link{rba_enrichr_libs}}. \item If regex_library_name = TRUE, A partially-matching name a regex pattern that correspond to one or more of Enrichr library names. }} \item{regex_library_name}{logical: if TRUE (default) the supplied -gene_set_library will be regarded as a regex or partially matching name. if -FALSE, gene_set_library will be considered exact match.} +gene_set_library will be considered as a regex pattern. +If FALSE, gene_set_library will be considered as an exact match.} \item{organism}{(default = "human") Which model organism version of Enrichr to use? Available options are: "human", (H. sapiens & M. musculus), "fly" (D. melanogaster), "yeast" (S. cerevisiae), "worm" (C. elegans) -and "fish" (D. rerio).} +and "fish" (D. rerio). If `background_id` is provided, the only available +option is "human".} -\item{progress_bar}{logical: In case of selecting multiple Enrichr -libraries, should a progress bar be displayed?} +\item{background_id}{An ID returned after uploading a background gene +list using \code{\link{rba_enrichr_add_background}}} + +\item{progress_bar}{logical: (default = TRUE) if multiple Enrichr libraries +are selected, should a progress bar be displayed?} \item{...}{rbioapi option(s). See \code{\link{rba_options}}'s arguments manual for more information on available options.} @@ -46,17 +53,24 @@ A list containing data frames of the enrichment results of your supplied gene-list against the selected Enrichr libraries. } \description{ -This function which will retrieve the enrichment results of your - supplied gene-list id against one or multiple Enrichr libraries. +This function retrieves enrichment analysis results for your supplied + `user_list_id` against one or multiple Enrichr libraries. } \details{ -Note that using \code{\link{rba_enrichr}} is a more convenient way to - automatically perform this and other required function calls to - perform enrichment analysis on your input gene-set. +If `background_id` is supplied, this function will interact with the + speedrichr API. In this case, `user_list_id` must have been obtained + from a \code{\link{rba_enrichr_add_list}} call with the `speedrichr` + parameter set to `TRUE`. Additionally, this feature is only available + for "human" organism. + +Please note that \code{\link{rba_enrichr}} provides a one-step and + more convenient way to automatically handle this and other required + function calls needed to perform gene set enrichment analysis with Enrichr. } \section{Corresponding API Resources}{ "GET https://maayanlab.cloud/Enrichr/enrich" + \cr "POST https://maayanlab.cloud/speedrichr/api/backgroundenrich" } \examples{ @@ -103,6 +117,7 @@ rba_enrichr_enrich(user_list_id = "11111", Other "Enrichr": \code{\link{rba_enrichr}()}, +\code{\link{rba_enrichr_add_background}()}, \code{\link{rba_enrichr_add_list}()}, \code{\link{rba_enrichr_gene_map}()}, \code{\link{rba_enrichr_libs}()}, diff --git a/man/rba_enrichr_gene_map.Rd b/man/rba_enrichr_gene_map.Rd index d0080195..9c5af306 100644 --- a/man/rba_enrichr_gene_map.Rd +++ b/man/rba_enrichr_gene_map.Rd @@ -4,12 +4,12 @@ \alias{rba_enrichr_gene_map} \title{Find Enrichr Terms That Contain a Given Gene} \usage{ -rba_enrichr_gene_map(gene, catagorize = FALSE, organism = "human", ...) +rba_enrichr_gene_map(gene, categorize = FALSE, organism = "human", ...) } \arguments{ \item{gene}{character: An Entrez gene symbol.} -\item{catagorize}{logical: Should the category informations be included?} +\item{categorize}{logical: Should the category information be included?} \item{organism}{(default = "human") Which model organism version of Enrichr to use? Available options are: "human", (H. sapiens & M. musculus), @@ -20,7 +20,7 @@ and "fish" (D. rerio).} arguments manual for more information on available options.} } \value{ -a list containing the search results of your supplied gene. +A nested list containing the search results of your supplied gene. } \description{ This function will search the gene and retrieve a list of Enrichr @@ -36,7 +36,7 @@ This function will search the gene and retrieve a list of Enrichr rba_enrichr_gene_map(gene = "p53") } \donttest{ -rba_enrichr_gene_map(gene = "p53", catagorize = TRUE) +rba_enrichr_gene_map(gene = "p53", categorize = TRUE) } } @@ -66,6 +66,7 @@ rba_enrichr_gene_map(gene = "p53", catagorize = TRUE) \seealso{ Other "Enrichr": \code{\link{rba_enrichr}()}, +\code{\link{rba_enrichr_add_background}()}, \code{\link{rba_enrichr_add_list}()}, \code{\link{rba_enrichr_enrich}()}, \code{\link{rba_enrichr_libs}()}, diff --git a/man/rba_enrichr_libs.Rd b/man/rba_enrichr_libs.Rd index 760b795b..6a8ffd06 100644 --- a/man/rba_enrichr_libs.Rd +++ b/man/rba_enrichr_libs.Rd @@ -4,17 +4,17 @@ \alias{rba_enrichr_libs} \title{Retrieve a List of available libraries from Enrichr} \usage{ -rba_enrichr_libs(store_in_options = FALSE, organism = "human", ...) +rba_enrichr_libs(organism = "human", store_in_options = TRUE, ...) } \arguments{ -\item{store_in_options}{logical: (default = TRUE) Should a list of available -Enrichr libraries be saved as a global option?} - \item{organism}{(default = "human") Which model organism version of Enrichr to use? Available options are: "human", (H. sapiens & M. musculus), "fly" (D. melanogaster), "yeast" (S. cerevisiae), "worm" (C. elegans) and "fish" (D. rerio).} +\item{store_in_options}{logical: (default = TRUE) Should a list of available +Enrichr libraries be saved as a global option?} + \item{...}{rbioapi option(s). See \code{\link{rba_options}}'s arguments manual for more information on available options.} } @@ -23,20 +23,22 @@ A data frame with the names of available library in Enrichr and their statistics. } \description{ -This function will retrieve a list of available libraries in Enrichr with - their statistics. And by default, will save those names as a global option - ("rba_enrichr_libs") to be available for other Enrichr functions that - internally require the names of Enrichr libraries. +This function retrieves a list of libraries available in Enrichr along with + their associated statistics. Each library represents a collection of gene sets + that can be used for enrichment analysis. } \details{ -You should call this function once per R session with the argument - 'store_in_options = TRUE' before using \code{\link{rba_enrichr_enrich}} - or \code{\link{rba_enrichr}}. - \cr Nevertheless, rbioapi will do this for you in the background at the - first time you call any function which requires this. - \cr Note that using \code{\link{rba_enrichr}} is a more convenient way to - automatically perform this and other required function calls to enrich - your input gene-set. +By default, this function will save the library names as a global option + ("rba_enrichr_libs") for other Enrichr functions that internally require + the names of Enrichr libraries. You should call this function once per + R session with the argument 'store_in_options = TRUE' before + using \code{\link{rba_enrichr_enrich}} or \code{\link{rba_enrichr}}. + However, if you do not explicitly call it, rbioapi will automatically + execute this function in the background the when it is needed. + +Please note that \code{\link{rba_enrichr}} provides a one-step and + more convenient way to automatically handle this and other required + function calls needed to perform gene set enrichment analysis with Enrichr. } \section{Corresponding API Resources}{ @@ -77,6 +79,7 @@ rba_enrichr_libs() Other "Enrichr": \code{\link{rba_enrichr}()}, +\code{\link{rba_enrichr_add_background}()}, \code{\link{rba_enrichr_add_list}()}, \code{\link{rba_enrichr_enrich}()}, \code{\link{rba_enrichr_gene_map}()}, diff --git a/man/rba_enrichr_view_list.Rd b/man/rba_enrichr_view_list.Rd index ed0aeff5..a8803aae 100644 --- a/man/rba_enrichr_view_list.Rd +++ b/man/rba_enrichr_view_list.Rd @@ -4,10 +4,15 @@ \alias{rba_enrichr_view_list} \title{View an Uploaded Gene List} \usage{ -rba_enrichr_view_list(user_list_id, organism = "human", ...) +rba_enrichr_view_list( + user_list_id, + organism = "human", + speedrichr = FALSE, + ... +) } \arguments{ -\item{user_list_id}{a user_list_id returned to you after uploading a gene +\item{user_list_id}{a user list ID returned after uploading a gene list using \code{\link{rba_enrichr_add_list}}} \item{organism}{(default = "human") Which model organism version of Enrichr @@ -15,15 +20,19 @@ to use? Available options are: "human", (H. sapiens & M. musculus), "fly" (D. melanogaster), "yeast" (S. cerevisiae), "worm" (C. elegans) and "fish" (D. rerio).} +\item{speedrichr}{logical (default = FALSE) Did you upload your gene list +to speedrichr API? (i.e. did you intend to use this gene list along with +a background gene list?)} + \item{...}{rbioapi option(s). See \code{\link{rba_options}}'s arguments manual for more information on available options.} } \value{ -A list containing the genes and description available under the - supplied user_list_id +A list containing the genes and description associated to the + supplied user_list_id. } \description{ -Retrieve a list of uploaded genes under a 'user list ID'. +Retrieve the list of uploaded genes with a given 'user list ID'. } \section{Corresponding API Resources}{ @@ -62,6 +71,7 @@ rba_enrichr_view_list(user_list_id = 11111) \seealso{ Other "Enrichr": \code{\link{rba_enrichr}()}, +\code{\link{rba_enrichr_add_background}()}, \code{\link{rba_enrichr_add_list}()}, \code{\link{rba_enrichr_enrich}()}, \code{\link{rba_enrichr_gene_map}()},