---
title: "Visualization Guide"
author: "Zaoqu Liu"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 3
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 = 6,
  dpi = 150,
  eval = FALSE
)
```

## Introduction

This vignette demonstrates how to visualize clustering results from **recall** 
and compare them with standard Seurat clustering.

## Setup

```{r load-packages}
library(Seurat)
library(recall)
library(ggplot2)
library(patchwork)

set.seed(123)
```

## Data Preparation

```{r load-data}
# Load your Seurat object
# seurat_obj <- readRDS("your_data.rds")

# Standard preprocessing
seurat_obj <- NormalizeData(seurat_obj)
seurat_obj <- FindVariableFeatures(seurat_obj, nfeatures = 2000)
seurat_obj <- ScaleData(seurat_obj)
seurat_obj <- RunPCA(seurat_obj)
seurat_obj <- FindNeighbors(seurat_obj, dims = 1:10)
seurat_obj <- RunUMAP(seurat_obj, dims = 1:10)
```

## Comparing Clustering Methods

### Standard vs Calibrated Clustering

```{r run-clustering}
# Standard Seurat clustering
seurat_standard <- FindClusters(seurat_obj, resolution = 0.8)

# recall calibrated clustering
seurat_recall <- FindClustersRecall(seurat_obj, resolution_start = 0.8)
```

### Side-by-Side UMAP Comparison

```{r umap-comparison, fig.width=12, fig.height=5}
p1 <- DimPlot(seurat_standard, reduction = "umap", label = TRUE, pt.size = 0.5) +
  ggtitle(paste0("Standard Seurat (", length(unique(Idents(seurat_standard))), " clusters)")) +
  theme(legend.position = "none")

p2 <- DimPlot(seurat_recall, reduction = "umap", label = TRUE, pt.size = 0.5) +
  ggtitle(paste0("recall Calibrated (", length(unique(Idents(seurat_recall))), " clusters)")) +
  theme(legend.position = "none")

p1 + p2
```

## Cluster Quality Assessment

### Cluster Size Distribution

```{r cluster-sizes, fig.width=10, fig.height=4}
# Extract cluster information
standard_clusters <- table(Idents(seurat_standard))
recall_clusters <- table(Idents(seurat_recall))

# Create data frames
df_standard <- data.frame(
  Cluster = names(standard_clusters),
  Count = as.numeric(standard_clusters),
  Method = "Standard"
)

df_recall <- data.frame(
  Cluster = names(recall_clusters),
  Count = as.numeric(recall_clusters),
  Method = "recall"
)

df_combined <- rbind(df_standard, df_recall)

# Plot
ggplot(df_combined, aes(x = reorder(Cluster, -Count), y = Count, fill = Method)) +
  geom_bar(stat = "identity", position = "dodge") +
  facet_wrap(~Method, scales = "free_x") +
  labs(x = "Cluster", y = "Number of Cells", title = "Cluster Size Distribution") +
  theme_minimal() +
  theme(axis.text.x = element_text(angle = 45, hjust = 1))
```

### Marker Gene Heatmap

```{r marker-heatmap, fig.width=10, fig.height=8}
# Find markers for recall clusters
recall_markers <- FindAllMarkers(
  seurat_recall, 
  only.pos = TRUE, 
  min.pct = 0.25, 
  logfc.threshold = 0.25
)

# Select top 5 markers per cluster
top_markers <- recall_markers %>%
  dplyr::group_by(cluster) %>%
  dplyr::top_n(n = 5, wt = avg_log2FC)

# Create heatmap
DoHeatmap(seurat_recall, features = top_markers$gene) +
  scale_fill_gradientn(colors = c("blue", "white", "red")) +
  ggtitle("Top Marker Genes per Cluster (recall)")
```

## Feature Visualization

### Expression Patterns

```{r feature-plots, fig.width=12, fig.height=8}
# Define marker genes for your cell types
markers <- c("CD3D", "CD14", "MS4A1", "CD8A", "FCGR3A", "NKG7")

# Feature plots
FeaturePlot(seurat_recall, features = markers, ncol = 3)
```

### Violin Plots

```{r violin-plots, fig.width=12, fig.height=6}
VlnPlot(seurat_recall, features = c("CD3D", "CD14", "MS4A1"), ncol = 3)
```

## Resolution Analysis

### Multi-Resolution Comparison

```{r resolution-sweep, fig.width=15, fig.height=5}
resolutions <- c(0.4, 0.8, 1.2)
plots <- list()

for (res in resolutions) {
  seurat_temp <- FindClustersRecall(seurat_obj, resolution_start = res)
  n_clusters <- length(unique(Idents(seurat_temp)))
  
  plots[[as.character(res)]] <- DimPlot(seurat_temp, label = TRUE, pt.size = 0.3) +
    ggtitle(paste0("Resolution: ", res, " (", n_clusters, " clusters)")) +
    theme(legend.position = "none")
}

wrap_plots(plots, ncol = 3)
```

## Publication-Ready Figures

### Custom Theme

```{r custom-theme}
theme_publication <- function() {
  theme_minimal() +
    theme(
      plot.title = element_text(size = 14, face = "bold", hjust = 0.5),
      axis.title = element_text(size = 12),
      axis.text = element_text(size = 10),
      legend.title = element_text(size = 11),
      legend.text = element_text(size = 10),
      panel.grid.minor = element_blank(),
      panel.border = element_rect(color = "black", fill = NA, linewidth = 0.5)
    )
}
```

## Exporting Figures

```{r export-figures, eval=FALSE}
# Save high-resolution figures
ggsave(
  "recall_clustering_results.pdf",
  width = 14, height = 10,
  device = cairo_pdf
)

ggsave(
  "recall_clustering_results.png",
  width = 14, height = 10, dpi = 300
)
```

## Session Info

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