---
title: "Visualization Guide for scaper"
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 = 7,
  fig.height = 5,
  warning = FALSE,
  message = FALSE
)
```

## Introduction

This guide demonstrates visualization techniques for cytokine activity data generated by **scaper**.

## Basic Heatmap

```{r heatmap_example, eval=FALSE}
library(scaper)
library(Seurat)
library(pheatmap)

# Compute cytokine activities
data(pbmc_small)
result <- scapeForSeurat(pbmc_small, database = "cytosig", 
                         cytokine = "all", normalize = TRUE)

# Extract activity matrix
activity <- as.matrix(GetAssayData(result, assay = "scape", slot = "data"))

# Create heatmap
pheatmap(
  activity,
  fontsize_row = 6,
  fontsize_col = 4,
  cluster_rows = TRUE,
  cluster_cols = TRUE,
  color = colorRampPalette(c("blue", "white", "red"))(100),
  main = "Cytokine Activity Heatmap"
)
```

## Seurat Integration

```{r seurat_viz, eval=FALSE}
# Add activities to metadata
top_cytokines <- c("IL6", "IFNG", "IL4", "TNFA")
for (cyt in top_cytokines) {
  result <- AddMetaData(result, 
                        metadata = activity[cyt, ],
                        col.name = paste0(cyt, "_activity"))
}

# Violin plots
VlnPlot(result, features = paste0(top_cytokines, "_activity"), ncol = 2)

# Feature plots (requires UMAP/tSNE)
FeaturePlot(result, features = paste0(top_cytokines[1:2], "_activity"))
```

## Distribution Analysis

```{r distribution, eval=FALSE}
# Boxplot of activity scores
selected_cyts <- c("IL6", "IFNG", "IL4", "TNFA")
boxplot(t(activity[selected_cyts, ]),
        col = rainbow(length(selected_cyts)),
        main = "Cytokine Activity Distributions",
        ylab = "Activity Score",
        las = 2)
abline(h = c(0.3, 0.7), col = "gray", lty = 2)
```

## Correlation Analysis

```{r correlation, eval=FALSE}
# Cytokine-cytokine correlation
cor_matrix <- cor(t(activity))

pheatmap(
  cor_matrix,
  color = colorRampPalette(c("blue", "white", "red"))(100),
  breaks = seq(-1, 1, length.out = 101),
  main = "Cytokine Activity Correlations"
)
```

## Best Practices

**DO:**
- Use diverging color schemes for activity scores
- Cluster to reveal patterns
- Annotate with cell types
- Show scale bars

**DON'T:**
- Over-plot (sample if >1000 cells)
- Use rainbow colors for continuous data
- Ignore outliers without justification

## Session Information

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

---

**Author**: Zaoqu Liu  
**GitHub**: [Zaoqu-Liu/scaper](https://github.com/Zaoqu-Liu/scaper)