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

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

## Introduction

iTALK provides three visualization functions for exploring cell-cell communication:

| Function | Type | Best For |
|----------|------|----------|
| `LRPlot()` | Circos plot | Detailed L-R pair visualization |
| `NetView()` | Network graph | Overall communication topology |
| `TimePlot()` | Time series | Dynamic changes across conditions |

This vignette demonstrates customization options for each visualization.

## Setup

```{r load}
library(iTALK)
library(dplyr)

# Create example L-R pairs data
set.seed(42)
lr_data <- data.frame(
  ligand = c("TGFB1", "VEGFA", "IL6", "CCL2", "CXCL12", "TNF", "IL1B", "PDGFA"),
  receptor = c("TGFBR1", "KDR", "IL6R", "CCR2", "CXCR4", "TNFRSF1A", "IL1R1", "PDGFRA"),
  cell_from = c("Macrophage", "Fibroblast", "T_cell", "Monocyte", "Stromal", "Macrophage", "Dendritic", "Fibroblast"),
  cell_to = c("Fibroblast", "Endothelial", "B_cell", "T_cell", "T_cell", "Neutrophil", "T_cell", "Smooth_muscle"),
  cell_from_mean_exprs = c(45, 32, 28, 55, 40, 38, 25, 42),
  cell_to_mean_exprs = c(38, 45, 22, 35, 48, 30, 42, 35),
  comm_type = c("growth_factor", "growth_factor", "cytokine", "chemokine", "chemokine", "cytokine", "cytokine", "growth_factor"),
  stringsAsFactors = FALSE
)

# Define cell colors
cell_colors <- c(
  "T_cell" = "#E41A1C",
  "Macrophage" = "#377EB8",
  "Fibroblast" = "#4DAF4A",
  "B_cell" = "#984EA3",
  "Monocyte" = "#FF7F00",
  "Stromal" = "#A65628",
  "Endothelial" = "#F781BF",
  "Dendritic" = "#999999",
  "Neutrophil" = "#66C2A5",
  "Smooth_muscle" = "#FC8D62"
)

cat("Example data preview:\n")
print(lr_data)
```

## LRPlot: Circos Visualization

### Basic Circos Plot

The `LRPlot()` function creates a circular visualization where arrows represent ligand-receptor interactions between cell types.

```{r lrplot_basic, fig.cap="Basic circos plot showing ligand-receptor interactions between cell types"}
LRPlot(
  data = lr_data,
  datatype = "mean count",
  cell_col = cell_colors,
  transparency = 0.5,
  link.arr.lwd = 2,
  link.arr.type = "triangle"
)
```

### Understanding the Circos Plot

The circos plot encodes multiple dimensions:

- **Outer ring**: Cell types (colored sectors)
- **Inner ring**: Gene names (ligands and receptors)
- **Arrows**: Communication direction (ligand → receptor)
- **Arrow width**: Expression level of ligand
- **Arrow head width**: Expression level of receptor

### Customized Circos Plot

```{r lrplot_custom, fig.cap="Customized circos plot with adjusted arrow properties"}
# Custom arrow properties based on expression
LRPlot(
  data = lr_data,
  datatype = "mean count",
  cell_col = cell_colors,
  transparency = 0.3,
  link.arr.type = "big.arrow",
  track.height_1 = circlize::uh(3, "mm"),
  track.height_2 = circlize::uh(15, "mm"),
  text.vjust = "0.5cm"
)
```

## NetView: Network Visualization

### Basic Network Plot

The `NetView()` function creates a network graph showing overall communication patterns between cell types.

```{r netview_basic, fig.cap="Network view of cell-cell communication"}
g <- NetView(
  data = lr_data,
  col = cell_colors,
  vertex.size = 30,
  vertex.label.cex = 0.8,
  edge.max.width = 8,
  edge.curved = 0.2,
  arrow.width = 1.5,
  margin = 0.2
)
```

### Understanding the Network

- **Nodes**: Cell types (size can represent number of interactions)
- **Edges**: Communication channels between cells
- **Edge width**: Number of L-R pairs
- **Edge color**: Source cell type color
- **Arrows**: Direction of communication

### Customized Network with Labels

```{r netview_custom, fig.cap="Network plot with edge labels showing interaction counts"}
g <- NetView(
  data = lr_data,
  col = cell_colors,
  vertex.size = 35,
  vertex.label.cex = 0.9,
  vertex.label.color = "white",
  edge.max.width = 10,
  edge.curved = 0.3,
  arrow.width = 2,
  edge.label.cex = 0.7,
  edge.label.color = "darkgray",
  label = TRUE,
  margin = 0.15
)
```

## DEG Data Visualization

For differential expression results, the visualization changes to show up/down regulation:

```{r deg_data}
# Create DEG-style data
lr_deg <- data.frame(
  ligand = c("TGFB1", "IL6", "CCL2", "TNF"),
  receptor = c("TGFBR1", "IL6R", "CCR2", "TNFRSF1A"),
  cell_from = c("Macrophage", "T_cell", "Monocyte", "Macrophage"),
  cell_to = c("Fibroblast", "B_cell", "T_cell", "Neutrophil"),
  cell_from_logFC = c(2.5, -1.8, 1.2, 3.0),
  cell_to_logFC = c(1.8, 2.1, -0.8, 1.5),
  comm_type = c("growth_factor", "cytokine", "chemokine", "cytokine"),
  stringsAsFactors = FALSE
)
```

```{r lrplot_deg, fig.cap="Circos plot for DEG data showing up/down regulation"}
LRPlot(
  data = lr_deg,
  datatype = "DEG",
  cell_col = cell_colors,
  transparency = 0.4
)
```

**Arrow color coding for DEG:**

| Ligand | Receptor | Arrow Color |
|--------|----------|-------------|
| ↑ Up | ↑ Up | Red (#d73027) |
| ↑ Up | ↓ Down | Yellow (#dfc27d) |
| ↓ Down | ↑ Up | Purple (#9933ff) |
| ↓ Down | ↓ Down | Cyan (#00ccff) |

## Color Recommendations

### Scientific Color Palettes

```{r palettes, fig.height=3, fig.width=8}
# Display recommended palettes
par(mfrow = c(1, 3), mar = c(1, 1, 2, 1))

# Option 1: Set1 from RColorBrewer
pal1 <- c("#E41A1C", "#377EB8", "#4DAF4A", "#984EA3", "#FF7F00", "#A65628")
barplot(rep(1, 6), col = pal1, border = NA, main = "Set1 Palette", axes = FALSE)

# Option 2: Paired
pal2 <- c("#A6CEE3", "#1F78B4", "#B2DF8A", "#33A02C", "#FB9A99", "#E31A1C")
barplot(rep(1, 6), col = pal2, border = NA, main = "Paired Palette", axes = FALSE)

# Option 3: Dark2
pal3 <- c("#1B9E77", "#D95F02", "#7570B3", "#E7298A", "#66A61E", "#E6AB02")
barplot(rep(1, 6), col = pal3, border = NA, main = "Dark2 Palette", axes = FALSE)
```

## Publication-Ready Export

```{r export, eval=FALSE}
# PDF export for vector graphics
pdf("communication_circos.pdf", width = 10, height = 10)
LRPlot(lr_data, datatype = "mean count", cell_col = cell_colors)
dev.off()

# PNG export for high-resolution raster
png("communication_network.png", width = 3000, height = 3000, res = 300)
NetView(lr_data, col = cell_colors, vertex.size = 30)
dev.off()
```

## Tips and Best Practices

1. **Limit pairs for clarity**: Show top 20-30 pairs in LRPlot for readability
2. **Consistent colors**: Use the same cell colors across all plots
3. **Meaningful order**: Sort data by expression/significance before plotting
4. **Vector formats**: Use PDF for publication-quality figures
5. **Color blindness**: Consider colorblind-friendly palettes

## Session Info

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