---
title: "Visualization Gallery"
author: "Zaoqu Liu"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 3
    fig_caption: true
vignette: >
  %\VignetteIndexEntry{Visualization Gallery}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 8,
  fig.height = 6,
  fig.align = "center",
  message = FALSE,
  warning = FALSE,
  dpi = 150
)
```

## Introduction

NOVA provides a comprehensive suite of visualization functions to explore and present cell-cell communication analysis results. This gallery demonstrates the various plotting capabilities with practical examples.

## Setup

```{r load_packages}
library(NOVA)
library(ggplot2)
```

### Creating Example Data

```{r create_data}
set.seed(123)

# Simulate expression matrix
n_genes <- 200
n_cells <- 500
gene_names <- paste0("Gene", 1:n_genes)
cell_names <- paste0("Cell", 1:n_cells)

expr <- matrix(0, nrow = n_genes, ncol = n_cells,
               dimnames = list(gene_names, cell_names))
expressed <- sample(length(expr), size = length(expr) * 0.25)
expr[expressed] <- abs(rnorm(length(expressed), mean = 3, sd = 1.5))
expr <- Matrix::Matrix(expr, sparse = TRUE)

# Create clusters
clusters <- sample(c("T_cells", "B_cells", "Macrophages", "Fibroblasts", "Dendritic"), 
                   n_cells, replace = TRUE, prob = c(0.25, 0.20, 0.25, 0.15, 0.15))
names(clusters) <- cell_names
annotation <- data.frame(cell = cell_names, cluster = clusters)

# Map genes to LR database
lr_db <- GetLRDatabase("lrc2p")
ligands <- unique(lr_db$ligand)[1:30]
receptors <- unique(lr_db$receptor)[1:30]
rownames(expr)[1:30] <- ligands
rownames(expr)[31:60] <- receptors
```

### Running Analysis

```{r run_analysis, eval=FALSE}
# Run NOVA analysis
result <- ExtractEdges(
  expression = expr,
  annotation = annotation,
  species = "human",
  database = "lrc2p",
  min_pct = 0.05
)

print(result)
```

## 1. Communication Heatmap

The heatmap displays the overall communication strength between cell types.

### Basic Heatmap

```{r heatmap_basic, eval=FALSE, fig.cap="Communication heatmap showing edge counts between cell types"}
# Count-based heatmap
ht <- PlotHeatmap(result, metric = "count", show_values = TRUE)
```

### Specificity-weighted Heatmap

```{r heatmap_spec, eval=FALSE, fig.cap="Specificity-weighted communication heatmap"}
# Specificity-based heatmap
ht_spec <- PlotHeatmap(result, metric = "specificity", show_values = TRUE)
```

## 2. Network Visualization

Network graphs provide an intuitive view of communication patterns.

### Circular Layout

```{r network_circle, eval=FALSE, fig.cap="Circular network layout showing cell-cell communication"}
PlotNetwork(result, 
            layout = "circle",
            metric = "count",
            title = "Cell-Cell Communication Network")
```

### Force-directed Layout

```{r network_fr, eval=FALSE, fig.cap="Force-directed network layout"}
PlotNetwork(result, 
            layout = "fr",  # Fruchterman-Reingold
            metric = "specificity",
            title = "Communication Network (FR Layout)")
```

### Kamada-Kawai Layout

```{r network_kk, eval=FALSE, fig.cap="Kamada-Kawai network layout"}
PlotNetwork(result, 
            layout = "kk",
            metric = "count",
            title = "Communication Network (KK Layout)")
```

## 3. Chord Diagram

Chord diagrams elegantly display the flow of communication between cell types.

```{r chord, eval=FALSE, fig.cap="Chord diagram of cell-cell communication"}
PlotChord(result, 
          metric = "count",
          transparency = 0.4,
          title = "Communication Flow")
```

### Specificity-based Chord

```{r chord_spec, eval=FALSE, fig.cap="Specificity-weighted chord diagram"}
PlotChord(result, 
          metric = "specificity",
          transparency = 0.5,
          title = "Specificity-weighted Communication")
```

## 4. Ligand-Receptor Pairs Visualization

Examine specific LR pairs between cluster pairs.

```{r lr_pairs, eval=FALSE, fig.cap="Top ligand-receptor pairs between T cells and Macrophages"}
# Get specific cluster pair interactions
PlotLRPairs(result, 
            sending = "T_cells", 
            target = "Macrophages",
            top_n = 15,
            rank_by = "specificity",
            title = "T cells → Macrophages LR Interactions")
```

```{r lr_pairs2, eval=FALSE, fig.cap="Top ligand-receptor pairs between Macrophages and Fibroblasts"}
PlotLRPairs(result, 
            sending = "Macrophages", 
            target = "Fibroblasts",
            top_n = 10,
            rank_by = "mean")
```

## 5. Color Palette

NOVA provides a custom color palette optimized for cell type visualization.

```{r palette, fig.cap="NOVA color palette"}
# Display color palette
colors <- nova_palette(20)
barplot(rep(1, 20), col = colors, border = NA, axes = FALSE,
        main = "NOVA Color Palette")
```

## 6. Custom Styling

### Custom Colors

```{r custom_colors, eval=FALSE, fig.cap="Network with custom colors"}
custom_cols <- c("T_cells" = "#E64B35", 
                 "B_cells" = "#4DBBD5", 
                 "Macrophages" = "#00A087",
                 "Fibroblasts" = "#3C5488",
                 "Dendritic" = "#F39B7F")

PlotNetwork(result, 
            layout = "circle",
            colors = custom_cols,
            title = "Network with Custom Colors")
```

## 7. Saving Plots

```{r save, eval=FALSE}
# Save heatmap to PDF
SavePlot(ht, "communication_heatmap.pdf", width = 10, height = 8)

# Save network to PNG
p <- PlotNetwork(result, layout = "circle")
SavePlot(p, "communication_network.png", width = 10, height = 8, dpi = 300)
```

## Summary Table

| Function | Description | Output Type |
|----------|-------------|-------------|
| `PlotHeatmap()` | Communication strength heatmap | ComplexHeatmap |
| `PlotNetwork()` | Network graph | ggplot2 |
| `PlotChord()` | Chord diagram | Base R |
| `PlotLRPairs()` | Bipartite LR visualization | ggplot2 |
| `PlotDiffHeatmap()` | Differential communication heatmap | ComplexHeatmap |
| `PlotVolcano()` | Volcano plot | ggplot2 |

## Session Info

```{r session}
sessionInfo()
```

## Author

**Zaoqu Liu**

- Email: liuzaoqu@163.com
- GitHub: [Zaoqu-Liu](https://github.com/Zaoqu-Liu)