---
title: "Plotting Functions and Options"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Plotting Functions and Options}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  echo = TRUE,
  message = FALSE,
  warning = FALSE,
  fig.cap = "",
  tidy = TRUE,
  global.device = TRUE
)
options(timeout = 300)
```

In addition to the numerous plotting options available in the original [Domino](https://github.com/Elisseeff-Lab/domino), dominoSignal has added more functionality and new methods to improve visualization and interpretation of analysis results. Here, we will go over the different plotting functions available, as well as different options that can be utilized, and options for customization.

## Setup and Data Load
```{r setup, eval = TRUE}
set.seed(42)
library(dominoSignal)
library(patchwork)
```

In this tutorial, we will use the domino object we built on the [Getting Started](https://fertiglab.github.io/dominoSignal/articles/dominoSignal) page. If you have not yet built a domino object, you can do so by following the instructions on the [Getting Started](https://fertiglab.github.io/dominoSignal/articles/dominoSignal) page.

<details><summary>Instructions to load data</summary>

```{r load data}
# BiocFileCache helps with managing files across sessions
bfc <- BiocFileCache::BiocFileCache(ask = FALSE)
data_url <- "https://zenodo.org/records/10951634/files/pbmc_domino_built.rds"
tmp_path <- BiocFileCache::bfcrpath(bfc, data_url)
dom <- readRDS(tmp_path)
```
</details>

## Heatmaps

### Correlations between receptors and transcription factors

`cor_heatmap()` can be used to show the correlations calculated between receptors and transcription factors.

```{r corheatmap}
cor_heatmap(dom, title = "PBMC R-TF Correlations", column_names_gp = grid::gpar(fontsize = 8))
```

In addition to displaying the scores for the correlations, this function can also be used to identify correlations above a certain value (using the `bool` and `bool_thresh` arguments) or to identify the combinations of receptors and transcription factors (TFs) that are connected (with argument `mark_connections`).

```{r corheatmap-options, fig.show="hold", out.width = "50%"}
cor_heatmap(dom, bool = TRUE, bool_thresh = 0.25)
cor_heatmap(dom, bool = FALSE, mark_connections = TRUE)
```

If only a subset of receptors or transcription factors are of interest, a vector of either (or both) can be passed to the function.

```{r corheatmap-subset}
receptors <- c("CSF1R", "CSF3R", "CCR7", "FCER2")
tfs <- c("PAX5", "JUNB", "FOXJ3", "FOSB")
cor_heatmap(dom, feats = tfs, recs = receptors)
```

The heatmap functions in dominoSignal are based on `ComplexHeatmap::Heatmap()` and will also accept additional arguments meant for that function. For example, while an argument for clustering rows or columns of the heatmap is not explicitly stated, they can still be passed to `ComplexHeatmap::Heatmap()` through `cor_heatmap()`.

```{r corheatmap-ComplexHeatmap-args}
cor_heatmap(
    dom,
    cluster_rows = FALSE, cluster_columns = FALSE,
    column_title = "Heatmap Without Clustering", column_names_gp = grid::gpar(fontsize = 4)
)
```

### Heatmap of Transcription Factor Activation Scores

`feat_heatmap()` is used to show the transcription factor activation for features in the signaling network. 

```{r featheatmap}
feat_heatmap(dom, use_raster = FALSE, row_names_gp = grid::gpar(fontsize = 4))
```

It functions similarly to `cor_heatmap()`, with arguments to select a specific vector of features, to use a boolean view with a threshold, and to pass other arguments to `ComplexHeatmap::Heatmap()`. Specific to this function though are arguments for setting the range of values to be visualized and one to choose to normalize the scores to the max value.

```{r featheatmap-options, fig.show="hold", out.width = "50%"}
feat_heatmap(dom,
    min_thresh = 0.1, max_thresh = 0.6,
    norm = TRUE, bool = FALSE, use_raster = FALSE
)
feat_heatmap(dom, bool = TRUE, use_raster = FALSE)
```

### Heatmap of Incoming Signaling for a Cluster

`incoming_signaling_heatmap()` can be used to visualize the cluster average expression of the ligands capable of activating the TFs enriched in the cluster. For example, to view the incoming signaling of the CD8  T cells:

```{r incoming}
incoming_signaling_heatmap(dom, "CD8_T_cell")
```

We can also select for specific clusters of interest that are signaling to the CD8 T cells. If we are only interested in viewing the monocyte signaling:

```{r incoming-subset}
incoming_signaling_heatmap(dom, "CD8_T_cell", clusts = c("CD14_monocyte", "CD16_monocyte"))
```

As with our other heatmap functions, options are available for a minimum threshold, maximum threshold, whether to scale the values after thresholding, whether to normalize the matrix, and the ability to pass further arguments to `ComplexHeatmap::Heatmap()`.

### Heatmap of Signaling Between Clusters

`signaling_heatmap()` makes a heatmap showing the signaling strength of ligands from each cluster to receptors of each cluster based on averaged expression.

```{r signaling}
signaling_heatmap(dom)
```

As with other functions, specific clusters can be selected, thresholds can be set, and normalization methods can be selected as well.

```{r signaling-norm, fig.show="hold", out.width = "50%"}
signaling_heatmap(dom, scale = "sqrt")
signaling_heatmap(dom, normalize = "rec_norm")
```

## Network Plots

### Network showing L - R - TF signaling between clusters

`gene_network()` makes a network plot to display signaling in selected clusters such that ligands, receptors and features associated with those clusters are displayed as nodes with edges as linkages. To look at signaling to the CD16 Monocytes from the CD14 Monocytes:

```{r genenetwork}
gene_network(dom, clust = "CD16_monocyte", OutgoingSignalingClust = "CD14_monocyte")
```

Options to modify this plot include adjusting scaling for the ligands and different layouts (some of which are more legible than others).

```{r genenetwork-options}
gene_network(dom,
    clust = "CD16_monocyte", OutgoingSignalingClust = "CD14_monocyte",
    lig_scale = 25, layout = "sphere"
)
```

Additionally, colors can be given for select genes (for example, to highlight a specific signaling path).

```{r genenetwork-cols}
gene_network(dom,
    clust = "CD16_monocyte", OutgoingSignalingClust = "CD14_monocyte",
    cols = c("CD1D" = "violet", "LILRB2" = "violet", "FOSB" = "violet"), lig_scale = 10
)
```

### Network Showing Interaction Strength Across Data

`signaling_network()` can be used to create a network plot such that nodes are clusters and the edges indicate signaling from one cluster to another.

```{r signalingnet}
signaling_network(dom)
```

In addition to changes such as scaling, thresholds, or layouts, this plot can be modified by selecting incoming or outgoing clusters (or both!). An example to view signaling from the CD14 Monocytes to other clusters:

```{r signalingnet-clusts}
signaling_network(dom,
    showOutgoingSignalingClusts = "CD14_monocyte", scale = "none",
    norm = "none", layout = "fr", scale_by = "none", edge_weight = 2, vert_scale = 10
)
```

## Other Types of Plots

### Chord Diagrams Connecting Ligands and Receptors
A new addition to dominoSignal, `circos_ligand_receptor()` creates a chord plot showing ligands that can activate a specific receptor, displaying mean cluster expression of the ligand with the width of the chord.

```{r circos, fig.asp = 0.6, out.width = "90%"}
circos_ligand_receptor(dom, receptor = "CD74")
```

This function can be given cluster colors to match other plots you may make with your data. In addition, the plot can be adjusted by changing the threshold of ligand expression required for a linkage to be visualized or selecting clusters of interest.

```{r circos-opt, fig.asp = 0.6, out.width = "90%"}
cols <- c(
    "red", "orange", "green", "blue", "pink", "purple",
    "slategrey", "firebrick", "hotpink"
)
names(cols) <- dom_clusters(dom, labels = FALSE)
circos_ligand_receptor(dom, receptor = "CD74", cell_colors = cols)
```

### Scatter Plot to Visualize Correlation

`cor_scatter()` can be used to plot each cell based on activation of the selected TF and expression of the receptor. This produces a scatter plot as well as a line of best fit to look at receptor - TF correlation.

```{r corscatter}
cor_scatter(dom, "FOSB", "CD74")
```

Do keep in mind that there is an argument for `remove_rec_dropout` that should match the parameter that was used when the domino object was built. In this case, we did not use that build parameter, so we will leave the value in this argument as its default value of FALSE.

## Continued Development

Since dominoSignal is a package still being developed, there are new functions and features that will be implemented in future versions. In the meantime, to view an example analysis, see our [Getting Started](https://fertiglab.github.io/dominoSignal/articles/dominoSignal) page, or see our [domino object structure](https://fertiglab.github.io/dominoSignal/articles/domino_object_vignette) page to get familiar with the object structure. Additionally, if you find any bugs, have further questions, or want to share an idea, please let us know [here](https://github.com/FertigLab/dominoSignal/issues).

<details><summary>Vignette Build Information</summary>
Date last built and session information:
```{r}
Sys.Date()
sessionInfo()
```
</details>