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

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

## Overview

fastCNV provides comprehensive visualization tools for CNV analysis results. This vignette covers:

1. **CNV Heatmaps** - Genome-wide CNV profiles
2. **Phylogenetic Trees** - Clonal evolution visualization
3. **Chromosome Arm Plots** - Arm-level CNV summary
4. **Spatial CNV Maps** - CNV patterns in tissue context

## CNV Heatmaps

### Example CNV Heatmap

```{r heatmap-example, echo=FALSE, eval=TRUE, out.width="100%", fig.cap="CNV heatmap showing chromosomal alterations. Rows represent cells, columns represent genomic windows. Blue = deletion, Red = amplification."}
knitr::include_graphics("figures/cnv_heatmap.png")
```

### Basic Heatmap

The `plotCNVResults()` function generates publication-ready heatmaps:

```{r basic-heatmap}
library(fastCNV)

# Generate CNV heatmap
plotCNVResults(
  seuratObj = result,
  referenceVar = "cell_type",
  tumorLabel = "Tumor"
)
```

### Customizing Heatmaps

#### Split by Cell Type

```{r split-heatmap}
plotCNVResults(
  seuratObj = result,
  referenceVar = "cell_type",
  tumorLabel = "Tumor",
  splitPlotOnVar = "cell_subtype"  # Split rows by subtype
)
```

#### Split by CNV Clusters

```{r cluster-heatmap}
plotCNVResults(
  seuratObj = result,
  referenceVar = "cell_type",
  tumorLabel = "Tumor",
  splitPlotOnVar = "cnv_clusters"  # Group by CNV clusters
)
```

#### Custom Color Scheme

The heatmap uses a diverging color scale:
- **Blue**: Deletions (negative CNV scores)
- **White**: Neutral (no alteration)
- **Red**: Amplifications (positive CNV scores)

```{r color-scheme}
# The default color scheme is optimized for CNV visualization
# Colors are scaled to the data range with balanced mapping
```

### Heatmap Components

A typical CNV heatmap includes:

```
┌─────────────────────────────────────────────────────────────┐
│                    Chromosome Labels (1-22, X)              │
├─────────────────────────────────────────────────────────────┤
│  Row      │                                                 │
│  Anno-    │          CNV Score Matrix                       │
│  tations  │          (cells × genomic windows)              │
│           │                                                 │
│  - Cell   │  Blue = Deletion                                │
│    type   │  White = Neutral                                │
│  - Clone  │  Red = Amplification                            │
│           │                                                 │
├─────────────────────────────────────────────────────────────┤
│                    Color Legend                             │
└─────────────────────────────────────────────────────────────┘
```

## Phylogenetic Trees

### Example Dendrogram

```{r dendrogram-example, echo=FALSE, eval=TRUE, out.width="80%", fig.align="center", fig.cap="Hierarchical clustering dendrogram based on CNV profiles, showing the relationship between different clones."}
knitr::include_graphics("figures/cnv_dendrogram.png")
```

### Building CNV Trees

CNV profiles can be used to reconstruct clonal phylogenies:

```{r build-tree}
# Build phylogenetic tree from CNV clusters
tree <- CNVTree(
  seuratObj = result,
  referenceVar = "cell_type",
  tumorLabel = "Tumor",
  cnv_thresh = 0.15
)
```

### Visualizing Trees

```{r plot-tree}
# Plot the phylogenetic tree
plotCNVTree(
  tree = tree,
  seuratObj = result,
  referenceVar = "cell_type",
  tumorLabel = "Tumor"
)
```

### Annotated Trees

Add CNV event annotations to tree branches:

```{r annotate-tree}
# Annotate tree with CNV events
annotated_tree <- annotateCNVTree(
  tree = tree,
  seuratObj = result,
  cnv_thresh = 0.15
)

# Plot with annotations
plotCNVTree(
  tree = annotated_tree,
  seuratObj = result,
  referenceVar = "cell_type",
  tumorLabel = "Tumor",
  show_annotations = TRUE
)
```

### Tree Interpretation

```
                    ┌─── Clone A (chr7+, chr10-)
            ┌───────┤
            │       └─── Clone B (chr7+, chr10-, chr19+)
    ────────┤
            │       ┌─── Clone C (chr1q+)
            └───────┤
                    └─── Clone D (chr1q+, chr8-)
    
    Legend:
    + = Amplification
    - = Deletion
```

## Chromosome Arm-Level Analysis

### Example: CNV Fraction per Chromosome Arm

```{r arm-example, echo=FALSE, eval=TRUE, out.width="90%", fig.align="center", fig.cap="Bar plot showing mean CNV scores per chromosome arm for different clones."}
knitr::include_graphics("figures/cnv_arm_barplot.png")
```

### Computing Arm-Level CNVs

```{r arm-cnv}
# Calculate CNV fraction per chromosome arm
result <- CNVPerChromosomeArm(
  seuratObj = result,
  referenceVar = "cell_type",
  tumorLabel = "Tumor"
)

# View arm-level data
head(result$cnv_per_arm)
```

### Visualizing Arm-Level CNVs

```{r arm-plot}
library(ggplot2)

# Extract arm-level data
arm_data <- result$cnv_per_arm

# Create bar plot
ggplot(arm_data, aes(x = arm, y = cnv_fraction, fill = cnv_type)) +
  geom_bar(stat = "identity") +
  facet_wrap(~cluster, ncol = 1) +
  theme_minimal() +
  theme(axis.text.x = element_text(angle = 45, hjust = 1)) +
  labs(
    title = "CNV Fraction per Chromosome Arm",
    x = "Chromosome Arm",
    y = "Fraction of Cells with CNV"
  )
```

## Spatial CNV Visualization

### Visium Data

```{r spatial-plot}
library(Seurat)

# Plot CNV clusters on tissue
SpatialDimPlot(
  result,
  group.by = "cnv_clusters",
  pt.size.factor = 1.6
)
```

### Visium HD Data

```{r hd-plot}
# For Visium HD, use the specialized function
plotCNVResultsHD(
  seuratObj = result,
  referenceVar = "region",
  tumorLabel = "Tumor"
)
```

### Combining Spatial and CNV Information

```{r combined-spatial}
# Create a multi-panel figure
library(patchwork)

# Panel 1: Cell type annotation
p1 <- SpatialDimPlot(result, group.by = "cell_type")

# Panel 2: CNV clusters
p2 <- SpatialDimPlot(result, group.by = "cnv_clusters")

# Panel 3: CNV score for specific chromosome
p3 <- SpatialFeaturePlot(result, features = "chr7_cnv_score")

# Combine
p1 | p2 | p3
```

## Custom Visualizations

### Extracting CNV Data

```{r extract-data}
# Get raw CNV scores matrix
cnv_scores <- as.matrix(result@assays$CNVScores@data)

# Get trimmed (thresholded) scores
cnv_trimmed <- as.matrix(result@assays$CNVScoresTrimmed@data)

# Get window annotations
window_info <- result@assays$CNVScores@meta.features
```

### Creating Custom Plots

```{r custom-plots}
library(ggplot2)
library(tidyr)

# Example: Plot CNV profile for a single cell
cell_profile <- cnv_scores[, "cell_1"]
window_positions <- 1:length(cell_profile)

ggplot(data.frame(pos = window_positions, cnv = cell_profile)) +

  geom_line(aes(x = pos, y = cnv), color = "steelblue") +
  geom_hline(yintercept = 0, linetype = "dashed", color = "gray50") +
  theme_minimal() +
  labs(
    title = "CNV Profile: Cell 1",
    x = "Genomic Position (window)",
    y = "CNV Score"
  )
```

### Comparing Clusters

```{r cluster-comparison}
# Compare average CNV profiles between clusters
library(dplyr)

# Calculate mean CNV per cluster
cluster_means <- result@meta.data %>%
  group_by(cnv_clusters) %>%
  summarise(
    mean_cnv_fraction = mean(cnv_fraction),
    n_cells = n()
  )

# Plot
ggplot(cluster_means, aes(x = cnv_clusters, y = mean_cnv_fraction, fill = cnv_clusters)) +
  geom_bar(stat = "identity") +
  theme_minimal() +
  labs(
    title = "Mean CNV Fraction by Cluster",
    x = "CNV Cluster",
    y = "Mean CNV Fraction"
  )
```

## Publication-Ready Figures

### High-Resolution Export

```{r export-figures}
# Save heatmap as PDF
pdf("cnv_heatmap.pdf", width = 12, height = 8)
plotCNVResults(
  seuratObj = result,
  referenceVar = "cell_type",
  tumorLabel = "Tumor"
)
dev.off()

# Save tree as PDF
pdf("cnv_tree.pdf", width = 8, height = 6)
plotCNVTree(
  tree = tree,
  seuratObj = result,
  referenceVar = "cell_type",
  tumorLabel = "Tumor"
)
dev.off()
```

### Figure Panel Assembly

```{r panel-assembly}
library(patchwork)
library(ggplot2)

# Create individual panels
p_umap <- DimPlot(result, group.by = "cnv_clusters")
p_spatial <- SpatialDimPlot(result, group.by = "cnv_clusters")

# Assemble figure
figure <- (p_umap | p_spatial) / 
          plot_spacer() +
          plot_layout(heights = c(2, 1))

# Save
ggsave("figure_panel.pdf", figure, width = 14, height = 10)
```

## Color Palettes

### Default Palettes

fastCNV uses carefully selected color palettes:

```{r palettes}
# CNV score colors (diverging)
# Blue (-) → White (0) → Red (+)

# Cluster colors (qualitative)
# Uses paletteer for distinct, colorblind-friendly colors
library(paletteer)
cluster_colors <- paletteer_d("ggsci::default_nejm")
```

### Custom Palettes

```{r custom-palette}
# Define custom cluster colors
custom_colors <- c(
  "Clone_A" = "#E64B35",
  "Clone_B" = "#4DBBD5",
  "Clone_C" = "#00A087",
  "Clone_D" = "#3C5488"
)

# Apply to plot
DimPlot(result, group.by = "cnv_clusters", cols = custom_colors)
```

## Tips and Best Practices

### 1. Heatmap Ordering

- Order cells by cluster, then by similarity within cluster
- Use dendrograms to show hierarchical relationships

### 2. Color Scaling

- Center the color scale at zero
- Use symmetric limits for amplifications and deletions

### 3. Resolution Selection

- For overview: show all chromosomes
- For detail: focus on specific regions of interest

### 4. Figure Legends

- Always include color scale bar
- Label chromosome boundaries clearly
- Annotate key CNV events

## Session Info

```{r session-info, eval=TRUE}
sessionInfo()
```