---
title: "2.E: Reactome & rbioapi"
author: "Moosa Rezwani"
description: >
 Connect to Reactome 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.E: Reactome & 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}

Directly quoting from [Reactome](https://reactome.org/):

> REACTOME is an open-source, open access, manually curated and peer-reviewed pathway database. Our goal is to provide intuitive bioinformatics tools for the visualization, interpretation and analysis of pathway knowledge to support basic and clinical research, genome analysis, modeling, systems biology and education. Founded in 2003, the Reactome project is led by Lincoln Stein of [OICR](https://oicr.on.ca/), Peter D'Eustachio of [NYULMC](https://nyulangone.org/), Henning Hermjakob of [EMBL-EBI](https://www.ebi.ac.uk/), and Guanming Wu of [OHSU](https://www.ohsu.edu/).
>
> (source: <https://reactome.org/what-is-reactome>)

Reactome provides two RESTful API services: Reactome content services and Reactome analysis services. In rbioapi, the naming schema is that any function which belongs to analysis services starts with rba_reactome_analysis\* . Other rba_reactome\_\* functions without the 'analysis' infix correspond to content services API.

Before continuing reading this article, it is a good idea to read [Reactome Data Model](https://reactome.org/documentation/data-model) page.

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

# Reactome analysis services {#reactome-analysis-services}

This section mostly revolves around `rba_reactome_analysis()` function. So, naturally, we will start with that. As explained in the function's manual, you have considerable freedom in providing the main input for this function; You can supply an R object (as a data frame, matrix, or simple vector), a URL, or a local file path. Note that the type of analysis will be decided based on whether your input is 1-dimensional or 2-dimensional. This has been explained in detail in the manual of `rba_reactome_analysis()`, see that for more information.\
`rba_reactome_analysis()` is the API equivalent of Reactome's [analyse gene list](https://reactome.org/PathwayBrowser/#TOOL=AT) tool. You can see that the function's arguments correspond to what would you choose in the webpage's wizard.

```{r rba_reactome_analysis}
## 1 We create a simple vector with our genes
genes <- c(
  "p53", "BRCA1", "cdk2", "Q99835", "CDC42", "CDK1", "KIF23", "PLK1", "RAC2",
  "RACGAP1", "RHOA", "RHOB", "MSL1", "PHF21A", "INSR", "JADE2", "P2RX7",
  "CCDC101", "PPM1B", "ANAPC16", "CDH8", "HSPA1L", "CUL2", "ZNF302", "CUX1",
  "CYTH2", "SEC22C", "EIF4E3", "ROBO2", "CXXC1", "LINC01314", "ATP5F1"
)

## 2 We call reactome analysis with the default parameters
analyzed <- rba_reactome_analysis(
  input = genes,
  projection = TRUE,
  p_value = 0.01
)

## 3 As always, we use str() to inspect the resutls
str(analyzed, 1)

## 4 Note that in the summary element: (analyzed$summary)
### 4.a because we supplied a simple vector, the analysis type was: over-representation
### 4.b You need the token for other rba_reactome_analysis_* functions

## 5 Analsis results are in the pathways data frame:
```

```{r analysis_results, echo=FALSE}
if (utils::hasName(analyzed, "pathways") && is.data.frame(analyzed$pathways)) {
  DT::datatable(
    data = jsonlite::flatten(analyzed$pathways),
    options = list(
      scrollX = TRUE, 
      paging = TRUE,
      fixedHeader = TRUE,
      keys = TRUE,
      pageLength = 5
    )
  )
} else {
  print("Vignette building failed. It is probably because the web service was down during the building.")
}

```

As mentioned, some of `rba_reactome_analysis()`'s arguments correspond to the wizard of [analyse gene list](https://reactome.org/PathwayBrowser/#TOOL=AT) tool; Other arguments corresponds to the contents of "Filter your results" tab in the results page.

Having the analysis's token, you can retrieve the analysis results in many formats using `rba_reactome_analysis_pdf()` and `rba_reactome_analysis_download()`:

```{r rba_reactome_analysis_pdf/download, eval=FALSE}
# download a full pdf report
rba_reactome_analysis_pdf(
  token = analyzed$summary$token,
  species = 9606
)

# download the result in compressed json.gz format
rba_reactome_analysis_download(
  token = analyzed$summary$token,
  request = "results",
  save_to = "reactome_results.json"
)
```

Your token is only guaranteed to be stored for 7 days. After that, you can upload the JSON file you have downloaded using `rba_reactome_analysis_download` and get a token for that:

```{r rba_reactome_analysis_import, eval=FALSE}
re_uploaded <- rba_reactome_analysis_import(input = "reactome_results.json")
```

**Please Note:** 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.

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

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

-   `rba_reactome_analysis_mapping()`

-   `rba_reactome_analysis_species()`

-   `rba_reactome_analysis_token()`

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

# Reactome contents services {#reactome-contents-services}

rbioapi functions that correspond to Reactome content services are those starting with rba_reactome\_\* but without "\_analysis" infix. These functions cover what you can do with objects in Reactome knowledge-base. In simpler terms, most -but not all of them- correspond to what you can find in [Reactome Pathway Browser](https://reactome.org/PathwayBrowser/ "Reactome Pathway Browser") and [search results](https://reactome.org/content/query?q=apoptosis&species=Homo+sapiens "Search results for apoptosis"). (e.g. a [pathway](https://reactome.org/content/detail/R-HSA-109581 "Apoptosis Homo sapiens"), a [reaction](https://reactome.org/content/detail/R-HSA-202939 "Caspase-mediated cleavage of E-Cadherin"), a [physical Entity](https://reactome.org/content/detail/R-HSA-350870 "Caspase-3 [cytosol]"), etc.)

## Retrieve any object from Reactome knowledge-base {#retrieve-any-object-from-reactome-knowledge-base}

Using `rba_reactome_query()`, you can retrieve any object from Reactome knowledge-base. In simpler terms, what I mean by the object is roughly anything that Reactome associated an ID to it. This can range from a person's entry to proteins, reactions, pathways, species, and many more! You can explore [Reactome's data schema](https://reactome.org/content/schema/DatabaseObject "Graph Database :: Data Schema") to learn about Reactome knowledge-base objects and their organization. Here are some examples, note that you are not limited to only one ID per query. You can use a vector of inputs, the only limitation is that when you supply more than one ID, you cannot have `enhanced = TRUE`.

```{r rba_reactome_query_ex1}
## 1 query a pathway Entry
pathway <- rba_reactome_query(
  ids = "R-HSA-109581",
  enhanced = TRUE
)

## 2 As always we use str() to inspect the output's structure
str(pathway, 2)



## 3 You can compare it with the webpage of R-HSA-202939 entry:
# https://reactome.org/content/detail/R-HSA-202939
```

```{r rba_reactome_query_ex2}
## 1 query a protein Entry
protein <- rba_reactome_query(
  ids = 66247,
  enhanced = TRUE
)

## 2 As always we use str() to inspect the output's structure
str(protein, 1)



## 3 You can compare it with the webpage of R-HSA-202939 entry:
# https://reactome.org/content/detail/R-HSA-202939

```

## Find Cross-Reference IDs in Reactome {#find-cross-reference-ids-in-reactome}

As you can see in the second example usage of we used Reactome's dbID `66247` to query CD40 protein. How did we obtain that in the first place? You can use `rba_reactome_xref` to map any cross-reference (external) IDs to Reactome IDs.

```{r rba_reactome_xref}
## 1 We Supply HGNC ID to find what is the corresponding database ID in Reactome
xref_protein <- rba_reactome_xref("CD40")

## 2 As always use str() to inspect the output's structure
str(xref_protein, 1)
```

## Map Cross-Reference IDs to Reactome {#map-cross-reference-ids-to-reactome}

While we are at the cross-reference topic, here is another useful resource. Using `rba_reactome_mapping` you can find the Reactome pathways or reactions which include your external ID:

```{r xref_mapping}
## 1 Again, consider CD40 protein:
xref_mapping <- rba_reactome_mapping(
  id = "CD40",
  resource = "hgnc",
  map_to = "pathways"
)
```

```{r xref_mapping_df, echo=FALSE}
if (is.data.frame(xref_mapping)) {
  DT::datatable(
    data = xref_mapping,
    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.")
}
```

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

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

There are still more rbioapi f Reactome content functions that were not covered in this vignette. Here is a brief overview, see the functions' manual for detailed guides and examples.

## Retrieve Reactome Database information {#retrieve-reactome-database-information}

-   `rba_reactome_version()`: Return current Reactome version

-   `rba_reactome_diseases()`: Retrieve a list of disease annotated in Reactome.

-   `rba_reactome_species()`: Retrieve a list of species annotated in Reactome.

## General Mapping/Querying {#general-mapping-querying}

-   `rba_reactome_query()`

-   `rba_reactome_mapping()`

-   `rba_reactome_xref()`

## Things you can do with a Entities {#things-you-can-do-with-a-entities}

-   `reactome_complex_list()`: Get a list of complexes that have your molecule in them.

-   `rba_reactome_complex_subunits()`: Get the list of subunits in your complex

-   `rba_reactome_participant_of()`: Get a list of Reactome sets and complexes that your entity (event, molecule, reaction, pathway etc.) is a participant in them.

-   `rba_reactome_entity_other_forms()`

## Things you can do with Events {#things-you-can-do-with-events}

-   `rba_reactome_event_ancestors()`

-   `rba_reactome_participants()`

-   `rba_reactome_pathways_events()`

-   `rba_reactome_event_ancestors()`

-   `rba_reactome_orthology()`

-   `rba_reactome_event_hierarchy()`: Retrieve full event hierarchy of an species.

## Pathways {#pathways}

-   `rba_reactome_pathways_low()`

-   `rba_reactome_pathways_events()`

-   `rba_reactome_pathways_top()`

## Interactors {#interactors}

-   `rba_reactome_interactors_psicquic()`

-   `rba_reactome_interactors_static()`

## People {#peaple}

-   `rba_reactome_people_name()`

-   `rba_reactome_people_id()`

## Export diagrams and events {#export-diagrams-and-events}

-   `rba_reactome_exporter_diagram()`

-   `rba_reactome_exporter_overview()`

-   `rba_reactome_exporter_reaction()`

-   `rba_reactome_exporter_event()`

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

# How to Cite? {#citations}

To cite Reactome (Please see <https://reactome.org/cite>):

-   Marc Gillespie, Bijay Jassal, Ralf Stephan, Marija Milacic, Karen Rothfels, Andrea Senff-Ribeiro, Johannes Griss, Cristoffer Sevilla, Lisa Matthews, Chuqiao Gong, Chuan Deng, Thawfeek Varusai, Eliot Ragueneau, Yusra Haider, Bruce May, Veronica Shamovsky, Joel Weiser, Timothy Brunson, Nasim Sanati, Liam Beckman, Xiang Shao, Antonio Fabregat, Konstantinos Sidiropoulos, Julieth Murillo, Guilherme Viteri, Justin Cook, Solomon Shorser, Gary Bader, Emek Demir, Chris Sander, Robin Haw, Guanming Wu, Lincoln Stein, Henning Hermjakob, Peter D'Eustachio, The reactome pathway knowledgebase 2022, *Nucleic Acids Research*, 2021;, kab1028, <https://doi.org/10.1093/nar/gkab1028>
-   Griss J, Viteri G, Sidiropoulos K, Nguyen V, Fabregat A, Hermjakob H. ReactomeGSA - Efficient Multi-Omics Comparative Pathway Analysis. Mol Cell Proteomics. 2020 Sep 9. doi: 10.1074/mcp. [PubMed PMID: 32907876](https://pubmed.ncbi.nlm.nih.gov/32907876).
-   Fabregat A, Korninger F, Viteri G, Sidiropoulos K, Marin-Garcia P, Ping P, Wu G, Stein L, D'Eustachio P, Hermjakob H. Reactome graph database: Efficient access to complex pathway data. *PLoS Comput Biol.* 2018 Jan 29;14(1):e1005968. doi: 10.1371/journal.pcbi.1005968. eCollection 2018 Jan. [PubMed PMID: 29377902](https://pubmed.ncbi.nlm.nih.gov/29377902).
-   Fabregat A, Sidiropoulos K, Viteri G, Marin-Garcia P, Ping P, Stein L, D'Eustachio P, Hermjakob H. Reactome diagram viewer: data structures and strategies to boost performance. *Bioinformatics.* 2018 Apr 1;34(7):1208-1214. doi: 10.1093/bioinformatics/btx752. [PubMed PMID: 29186351](https://pubmed.ncbi.nlm.nih.gov/29186351).
-   Fabregat A, Sidiropoulos K, Viteri G, Forner O, Marin-Garcia P, Arnau V, D'Eustachio P, Stein L, Hermjakob H. Reactome pathway analysis: a high-performance in-memory approach. *BMC Bioinformatics.* 2017 Mar 2;18(1):142. doi: 10.1186/s12859-017-1559-2. [PubMed PMID: 28249561](https://pubmed.ncbi.nlm.nih.gov/28249561).
-   Wu G, Haw R. Functional Interaction Network Construction and Analysis for Disease Discovery. *Methods Mol Biol.* 2017;1558:235-253. doi: 10.1007/978-1-4939-6783-4_11. [PubMed PMID: 28150241](https://pubmed.ncbi.nlm.nih.gov/28150241). 

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>

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

# Links {#links}

-   [This article in rbioapi documentation site](https://rbioapi.moosa-r.com/articles/rbioapi_reactome.html "2.D: Reactome & rbioapi")

-   [Functions references in rbioapi documentation site](https://rbioapi.moosa-r.com/reference/index.html#section-reactome-analysis-services-rba-reactome- "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()
```
