---
title: "2.A: Enrichr & rbioapi"
author: "Moosa Rezwani"
description: >
 Connect to Enrichr in R with rbioapi package. 
date: "`r Sys.Date()`"
output:
  rmarkdown::html_vignette:
    toc: true
    anchor_sections: true
    number_sections: true
    self_contained: true
    dev: png
    encoding: 'UTF-8'

vignette: >
  %\VignetteIndexEntry{2.A: Enrichr & rbioapi}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r message=FALSE, include=FALSE, results="hide", setup, echo=FALSE}
knitr::opts_chunk$set(
  echo = TRUE,
  eval = TRUE,
  message = FALSE,
  warning = FALSE,
  collapse = TRUE,
  tidy = FALSE,
  cache = FALSE,
  dev = "png",
  comment = "#>"
)
library(rbioapi)
rba_options(timeout = 30, skip_error = TRUE)
```


# Introduction {#introduction}

[Enrichr](https://maayanlab.cloud/Enrichr/) is a popular gene-set enrichment analysis tool developed in the Ma'ayan Lab.

------------------------------------------------------------------------

# Gene set library concept in Enrichr {#gene-set-library-concept-in-enrichr}

Directly quoting from Enrichr's help page:

> A *gene set library* is a set of related gene sets or enrichment terms [...] These libraries have been constructed from many sources such as published studies and major biological and biomedical online databases. Others have been created for and only available through Enrichr.
>
> (source: <https://maayanlab.cloud/Enrichr/help#background>)

To get a list of the available libraries in Enrichr, use:

```{r enrichr_libs}
enrichr_libs <- rba_enrichr_libs()
```

In the returned data frame, you can find the names of available Enrichr libraries in "libraryName" column. As you will see in the following sections, you can use these names to request an enrichment analysis based on the selected library or libraries.

```{r enrichr_libs_df, echo=FALSE}
if (is.data.frame(enrichr_libs)) {
  DT::datatable(
    data = enrichr_libs,
    options = list(
      scrollX = TRUE, 
      paging = TRUE,
      fixedHeader = TRUE,
      keys = TRUE,
      pageLength = 10
    )
  )
} else {
  print("Vignette building failed. It is probably because the web service was down during the building.")
}
```

------------------------------------------------------------------------

# Enrichment analysis using Enrichr {#enrichment-analysis-using-enrichr}

To perform enrichment analysis on your gene-set with Enrichr using rbioapi, you can take two approaches. We will begin with the simple one. But first, we create a vector of genes' NCBI IDs to use as the input example in this article.

```{r input_genes, eval=TRUE}
# Create a vector with our genes' NCBI IDs
genes <- c(
  "p53", "BRCA1", "cdk2", "Q99835", "CDC42","CDK1","KIF23","PLK1",
  "RAC2","RACGAP1","RHOA","RHOB", "PHF14", "RBM3", "MSL1"
)
```

## Approach 1: Using the one-step Wrapper function {#approach-1-using-the-wrapper-function}

The only required input for this function is to simply supply your gene-set as a character vector. Optionally you can also select one or more libraries. Please see `rba_enrichr()` function's manual for more details on the arguments.

```{r approach_1_all, eval=FALSE}
# Request the enrichment analysis
results_all <- rba_enrichr(gene_list = genes)
```

Note that the default value for the argument `gene_set_library` in the rba_enrichr function is "all". This means that if you call the function as above, all of the Enrichr libraries will be used for the enrichment analysis of your uploaded gene list. In this case, you will have a named list, where each of its elements is a dataframe containing your genes' analysis results using that Enrichr library.

Alternatively, you can use the `gene_set_library` argument to specify the library (or libraries) to use. Here we demonstrate using "MSigDB_Hallmark_2020" library:
```{r waiting1, echo=FALSE}
#wait 3 seconds to prevent rate limiting
Sys.sleep(3)
```

```{r approach_1_select, eval=TRUE}
# Request the enrichment analysis by a specific library
results_msig_hallmark <- rba_enrichr(
  gene_list = genes,
  gene_set_library = "MSigDB_Hallmark_2020",
  progress_bar = FALSE # to avoid printing issues in the vignette
)
```

```{r approach_1_select_df, echo=FALSE}
if (is.data.frame(results_msig_hallmark)) {
  DT::datatable(
    data = results_msig_hallmark,
    options = list(
      scrollX = TRUE, 
      paging = TRUE,
      fixedHeader = TRUE,
      keys = TRUE,
      pageLength = 10
    )
  )
} else {
  print("Vignette building failed. It is probably because the web service was down during the building.")
}
```

When supplying the `gene_set_library` argument, rbioapi assumes you are entering a regex pattern. You can disable this by setting `regex_library_name` to `FALSE`. However, this feature is useful if you need -for example- partial matches in the library names. Suppose you want to perform the enrichment analysis on every library available in Enrichr that contains the name "MSig". You can do the following:

```{r waiting2, echo=FALSE}
#wait 3 seconds to prevent rate limiting
Sys.sleep(3)
```

```{r approach_1_regex, eval=TRUE}
# Request the enrichment analysis
results_msig <- rba_enrichr(
  gene_list = genes,
  gene_set_library = "msig",
  regex_library_name = TRUE,
  progress_bar = FALSE # to avoid printing issues in the vignette
)

# You can drop `regex_library_name = TRUE`, as it is TRUE by default.
```

Note that when only one Enrichr library is selected, a data frame with enrichment analysis result will be returned.

```{r approach_1_single, eval=is.data.frame(results_msig_hallmark)}
str(results_msig_hallmark)
```

But when multiple libraries have been selected, the function's output will be a list where each element is a data frame corresponding to one of the selected libraries.

```{r approach_1_multi, eval=is.list(results_msig)&&is.data.frame(results_msig[[1]])}
str(results_msig, 1)
```

## Approach 2: Going step-by-step {#approach-2-going-step-by-step}

`rba_enrichr()` is a wrapper function. It internally executes a sequence of functions necessary to run your analysis. Alternatively, you could go step by step. We demonstrate these steps in this section.

First, you need to retrieve the list of available Enrichr libraries. This step is optional. You can skip it if you already know the name of your desired libraries or if you want to run the analysis over every available library.

```{r approach_2_libs, eval=FALSE}
# Get a list of available Enrichr libraries
libs <- rba_enrichr_libs(store_in_options = TRUE)
```

Now, you need to upload your genes list to Enrichr. By this, an identifier will be assigned to your submitted list, which is needed for the next step.

```{r waiting3, echo=FALSE}
#wait 3 seconds to prevent rate limiting
Sys.sleep(3)
```

```{r approach_2_add_list, eval=TRUE}
# Submit your gene-set to enrichr
list_id <- rba_enrichr_add_list(gene_list = genes)
```

From the returned response, we need the numeric ID in the "userListId" element.

```{r approach_2_str_list, eval=utils::hasName(list_id, "userListId")}
str(list_id)
```

Finally, we are ready to submit the enrichment analysis request to Enrichr. Same as explained above for the wrapper function `rba_enrichr()`, we can supply the "gene_set_library" argument in different ways. Here we will only select the "Table_Mining_of_CRISPR_Studies" library:
```{r waiting4, echo=FALSE}
#wait 3 seconds to prevent rate limiting
Sys.sleep(3)
```

```{r approach_2_enrichr_request, eval=utils::hasName(list_id, "userListId")}
# Request the analysis
results_crispr <- rba_enrichr_enrich(
  user_list_id = list_id$userListId,
  gene_set_library = "Table_Mining_of_CRISPR_Studies"
)
```

```{r approach_2_enrichr_results, eval=TRUE, echo=FALSE}
if (exists("results_crispr") && is.data.frame(results_crispr)) {
  DT::datatable(
    data = results_crispr,
    options = list(
      scrollX = TRUE, 
      paging = TRUE,
      fixedHeader = TRUE,
      keys = TRUE,
      pageLength = 10
    )
  )
} else {
  print("Vignette building failed. It is probably because the web service was down during the building.")
}
```

------------------------------------------------------------------------

# Working with Other Species {#other-species}

Enrichr also provides libraries for model organisms. The following functions have an `organism` argument that allows you to perform the analysis on species other than humans:

1.  `rba_enrichr()`

2.  `rba_enrichr_enrich()`

3.  `rba_enrichr_gene_map()`

4.  `rba_enrichr_libs()`

The available options for the organism argument are human", (H. sapiens & M. musculus), fly" (D. melanogaster), "yeast" (S. cerevisiae), "worm" (C. elegans), and "fish" (D. rerio).

------------------------------------------------------------------------

# Providing background gene list {#background-gene-list}

For human and mouse, Enrichr also support the use of background gene list. The background gene list will be used to compute the results statistics.

If using the one-step wrapper `rba_enrichr()` ([Approach 1](#approach-1-using-the-wrapper-function)), Everything is handled under the hood; simply supply your background gene with the `background_genes` parameter.

```{r background_gene_list_approach1, eval=FALSE}
# Assume we have the background genes in the variable my_background_genes
results_msig <- rba_enrichr(
  gene_list = genes,
  background_genes = my_background_genes,
  regex_library_name = TRUE
)
```


If you choose to follow the step-by-step approach, please note that Enrichr relies on an API back-end called [speedrichr](https://github.com/MaayanLab/speedrichr) to handle analysis with a background gene list. Therefore, when performing an analysis with background gene list, you must explicitly upload the target gene list to speedrichr. . Later steps will automatically interact with speedrichr as long as the relevant parameters for the background genes are specified.

```{r background_gene_list_approach2, eval=FALSE}

# Assume we have the background genes in the variable my_background_genes

# Create a vector with our genes' NCBI IDs
genes <- c(
  "p53", "BRCA1", "cdk2", "Q99835", "CDC42","CDK1","KIF23","PLK1",
  "RAC2","RACGAP1","RHOA","RHOB", "PHF14", "RBM3", "MSL1"
)

# Step 1: Upload the target gene list to speedrichr
# Note: Ensure `speedrichr = TRUE` is specified. Otherwise, it will not be 
#       possible to use the background gene list later.
list_id_spdr <- rba_enrichr_add_list(
  gene_list = genes,
  speedrichr = TRUE
)

# Step 2: Upload the background gene list
# Assume we have the background genes in the variable my_background_genes
background_id <- rba_enrichr_add_background(background_genes = my_background_genes)

# Step 3: Submit the enrichment analysis and retrieve the results
go_results <- rba_enrichr_enrich(
  user_list_id = list_id_spdr$userListId,
  background_id = background_id$backgroundid,
  gene_set_library = "GO"
)

```

------------------------------------------------------------------------

# See also in Functions' manuals {#see-also-in-functions-manuals}

Some rbioapi Enrichr functions were not covered in this vignette, be sure to check their manuals:

-   `rba_enrichr_gene_map()`

-   `rba_enrichr_view_list()`

------------------------------------------------------------------------

# How to Cite? {#citations}

To cite Enrichr (Please see <https://maayanlab.cloud/Enrichr/help#terms>):

-   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>

-   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>

-   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

To cite rbioapi:

-   Moosa Rezwani, Ali Akbar Pourfathollah, Farshid Noorbakhsh, rbioapi: user-friendly R interface to biologic web services' API, Bioinformatics, Volume 38, Issue 10, 15 May 2022, Pages 2952--2953, <https://doi.org/10.1093/bioinformatics/btac172>

------------------------------------------------------------------------

# Over-representation analysis Using Other Services {#other-services}

Other services supported by rbioapi also provide Over-representation analysis tools. Please see the vignette article [Do with rbioapi: Over-Representation (Enrichment) Analysis in R](rbioapi_do_enrich.html) ([link to the documentation site](https://rbioapi.moosa-r.com/articles/rbioapi_do_enrich.html)) for an in-depth review.

------------------------------------------------------------------------

# Links {#links}

-   [This article in rbioapi documentation site](https://rbioapi.moosa-r.com/articles/rbioapi_enrichr.html "https://rbioapi.moosa-r.com/articles/rbioapi_enrichr.html")

-   [Functions references in rbioapi documentation site](https://rbioapi.moosa-r.com/reference/index.html#section-enrichr-rba-enrichr- "rbioapi reference")

-   [rbioapi vignette index](rbioapi.html "rbioapi: User-Friendly R Interface to Biologic Web Services' API")

------------------------------------------------------------------------

# Session info {#session-info}

```{r sessionInfo, echo=FALSE}
sessionInfo()
```
