---
title: "Visualize Results"
vignette: >
  %\VignetteIndexEntry{Visualize Results}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  chunk_output_type: console
---

```{r, include=FALSE, messages=FALSE, warnings=FALSE}
knitr::opts_chunk$set(comment="", fig.align="center", fig.width=8.75, cache=FALSE)
library(tidyverse)
devtools::load_all(".")
```

### Example Data
The example data includes a pre-computed differential expression dataframe from limma. From the differential expression dataframe, we order genes descending so upregulated genes are near the top, then extract the gene symbol column as a vector. 

```{r}
data(limma)

signature <- limma %>% 
             dplyr::arrange(desc(t)) %>% 
             magrittr::use_series(symbol)

head(signature)
```

```{r}
genesets <- msigdb_gsets("Homo sapiens", "C2", "CP:REACTOME", clean=TRUE)

hyp_obj <- hypeR(signature, genesets, test="kstest", fdr=0.01)
```

To visualize the results, just pass the `hyp` object to any downstream functions.

# Dots Plot

One can visualize the top enriched genesets using `hyp_dots()` which returns a horizontal dots plot. Each dot is a geneset, where the color represents the significance and the size signifies the geneset size.

```{r, fig.height=5}
hyp_dots(hyp_obj)
```

# Enrichment Map

One can visualize the top enriched genesets using `hyp_emap()` which will return an enrichment map. Each node represents a geneset, where the shade of red indicates the normalized significance of enrichment. Hover over the node to view the raw value. Edges represent geneset similarity, calculated by either jaccard or overlap similarity metrics.

```{r, fig.height=7}
hyp_emap(hyp_obj, similarity_cutoff=0.70)
```

# Hiearchy Map

When dealing with hundreds of genesets, it's often useful to understand the relationships between them. This allows researchers to summarize many enriched pathways as more general biological processes. To do this, we rely on curated relationships defined between them.

### Relational Genesets

For example, [Reactome](https://reactome.org/) conveniently defines their genesets in a [hiearchy of pathways](https://reactome.org/PathwayBrowser/). This data can be formatted into a relational genesets object called `rgsets`. 

```{r}
genesets <- hyperdb_rgsets("REACTOME", version="70.0")
```

Relational genesets have three data atrributes including gsets, nodes, and edges. The `genesets` attribute includes the geneset information for the leaf nodes of the hiearchy, the `nodes` attribute describes all nodes in the hierarchy, including internal nodes, and the `edges` attribute describes the edges in the hiearchy.

```{r}
print(genesets)
```

Passing relational genesets works natively with `hypeR()`.

```{r}
hyp_obj <- hypeR(signature, genesets, test="kstest", fdr=0.01)
```

One can visualize the top enriched genesets using `hyp_hmap()` which will return a hierarchy map. Each node represents a geneset, where the shade of the gold border indicates the normalized significance of enrichment. Hover over the leaf nodes to view the raw value. Double click internal nodes to cluster their first degree connections. Edges represent a directed relationship between genesets in the hiearchy. Note: This function only works when the `hyp` object was initialized with an `rgsets` object.

```{r, fig.height=7}
hyp_hmap(hyp_obj, top=30)
```
