README.Rmd

---
title: "An R interface to the Enrichr database"
author: "Wajid Jawaid"
email: "wj241@alumni.cam.ac.uk"
date: "`r Sys.Date()`"
bibliography: ./vignettes/enrichr.bib
output:
  github_document:
    html_preview: false
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "./tools/README-"
)
```

[![CRAN_Status_Badge](https://www.r-pkg.org/badges/version/enrichR)](https://cran.r-project.org/package=enrichR)
[![Project Status: Active - The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
[![CRAN mirror downloads](https://cranlogs.r-pkg.org/badges/enrichR)](https://cran.r-project.org/package=enrichR/)

# Installation

**enrichR** can be installed from Github or from CRAN.

## Github

```{r, echo = TRUE, eval = FALSE}
library(devtools)
install_github("wjawaid/enrichR")
```

## CRAN

The package can be downloaded from CRAN using:

```{r, echo = TRUE, eval = FALSE}
install.packages("enrichR")
```

# Usage example

**enrichR** provides an interface to the Enrichr database [@kuleshov_enrichr:_2016] hosted at https://maayanlab.cloud/Enrichr/.  

By default human genes are selected otherwise select your organism of choice. (This functionality was contributed by Alexander Blume)

## Initialising connection to Enrichr website

```{r, echo = TRUE, eval = TRUE}
library(enrichR)

listEnrichrSites()

setEnrichrSite("Enrichr") # Human genes
```

## Select gene-set libraries

List all available databases from Enrichr.

```{r, echo = TRUE, eval = TRUE}
dbs <- listEnrichrDbs()
```

```{r, echo = TRUE, eval = FALSE}
head(dbs)
```

```{r, echo = FALSE, results='asis'}
knitr::kable(head(dbs[c(1:6),-4]))
```

Select the 2023 GO databases.

```{r, echo = TRUE, eval = TRUE}
dbs <- c("GO_Molecular_Function_2023", "GO_Cellular_Component_2023",
         "GO_Biological_Process_2023")
```

## Perform analysis

### Without background

Query with `enrichr()` using example genes available from the package.

```{r, echo = TRUE, eval = TRUE}
# Load example input genes
data(input)
length(input)
head(input)

enriched <- enrichr(input, dbs)
```

Now view the `"GO_Biological_Process_2023"` results from the `enriched` object.

```{r, echo = TRUE, eval = FALSE}
head(enriched[["GO_Biological_Process_2023"]])
```

```{r, echo = FALSE, results = 'asis'}
x <- head(enriched[["GO_Biological_Process_2023"]])
x[,1] <- gsub(":", "&#58;", x[,1])
knitr::kable(x)
```

### With background

You can now add background genes when using `enrichr()`.

```{r, echo = TRUE, eval = TRUE}
# Load example background
data(background)
length(background)
head(background)

enriched2 <- enrichr(input, dbs, background = background)
```

Now view the `"GO_Biological_Process_2023"` results from the `enriched2` object.

```{r, echo = TRUE, eval = FALSE}
head(enriched2[["GO_Biological_Process_2023"]])
```

```{r, echo = FALSE, results = 'asis'}
x <- head(enriched2[["GO_Biological_Process_2023"]])
x[,1] <- gsub(":", "&#58;", x[,1])
knitr::kable(x)
```

By default, the results table from analysis with a background does not have the 'Overlap' column.
We can calculate the annotated genes in each term from GMT files and
replace the 'Rank' column with 'Overlap' by setting `include_overlap = TRUE`.

```{r, echo = TRUE, eval = TRUE}
enriched3 <- enrichr(input, dbs, background = background, include_overlap = TRUE)
```

Now view the `"GO_Biological_Process_2023"` results from the `enriched3` object.

```{r, echo = TRUE, eval = FALSE}
head(enriched3[["GO_Biological_Process_2023"]])
```

```{r, echo = FALSE, results = 'asis'}
x <- head(enriched3[["GO_Biological_Process_2023"]])
x[,1] <- gsub(":", "&#58;", x[,1])
knitr::kable(x)
```

## Visualise results

Plot the `"GO_Biological_Process_2023"` results. (Plotting function contributed by I-Hsuan Lin)

```{r, echo = TRUE, eval = TRUE, fig.width = 8, fig.height = 5, fig.align = "center", dpi = 100}
plotEnrich(enriched[["GO_Biological_Process_2023"]], showTerms = 20, numChar = 40, 
	   y = "Count", orderBy = "P.value")
```

## Export results

Export Enrichr results as text or Excel files. By default (i.e. `outFile = "txt"`), 
the results from all the selected databases are saved into individual text files. 
When using `outFile = "excel"`, the results are saved into worksheets in a single Excel 2007 (XLSX) file. 
(Print function contributed by I-Hsuan Lin and Kai Hu)

```{r, echo = TRUE, eval = FALSE}
# To text files
printEnrich(enriched)

# To Excel
printEnrich(enriched, outFile = "excel")
```

## Using `enrichR` behind a proxy

If your computer is behind an HTTP or HTTPS proxy,
you can set the RCurl Proxy options explicitly using `RCurlOptions` and
enrichR will use the provided settings to connect to the Enrichr database via `httr::use_proxy()`.

For example:

```{r, echo = TRUE, eval = FALSE}
options(RCurlOptions = list(proxy = 'http://ip_or_url',
                            proxyusername = 'myuser',
                            proxypassword = 'mypwd',
                            proxyport = 'port_num',
                            proxyauth = 'basic'))
```

# References