---
title: "SpaTalk Visualization Guide"
author: 
  - name: "Zaoqu Liu"
    email: "liuzaoqu@163.com"
    affiliation: "Maintainer"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 3
    fig_caption: true
vignette: >
  %\VignetteIndexEntry{SpaTalk 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,
  out.width = "100%",
  dpi = 100
)
```

## Introduction

SpaTalk provides a comprehensive suite of visualization functions for exploring spatial transcriptomics data and cell-cell communication results. This vignette demonstrates the key plotting functions with real examples.

## Setup

```{r load}
library(SpaTalk)
library(ggplot2)

# Load demo data
load(system.file("extdata", "starmap_data.rda", package = "SpaTalk"))
load(system.file("extdata", "starmap_meta.rda", package = "SpaTalk"))
data(lrpairs)
data(pathways)

# Create SpaTalk object
st_meta <- data.frame(
  cell = starmap_meta$cell,
  x = starmap_meta$x,
  y = starmap_meta$y
)

obj <- createSpaTalk(
  st_data = starmap_data,
  st_meta = st_meta,
  species = "Mouse",
  if_st_is_sc = TRUE,
  spot_max_cell = 1,
  celltype = starmap_meta$celltype
)

obj <- find_lr_path(obj, lrpairs, pathways, if_doParallel = FALSE)

# Show available cell types
cat("Available cell types:", paste(unique(starmap_meta$celltype), collapse = ", "), "\n")
```

## Spatial Cell Type Visualization

### plot_st_celltype_all

Display all cell types in a single spatial plot. This is one of the most commonly used visualizations.

```{r celltype_all, fig.cap="All cell types in spatial context"}
plot_st_celltype_all(
  object = obj,
  size = 1.2
)
```

### plot_st_celltype

Visualize specific cell type distributions in spatial coordinates.

```{r celltype, fig.cap="Spatial distribution of eL6 cells"}
plot_st_celltype(
  object = obj,
  celltype = "eL6",
  size = 1.5
)
```

### plot_st_celltype_density

Kernel density estimation of cell type spatial distributions.

```{r celltype_density, fig.cap="Cell type density map for eL6"}
plot_st_celltype_density(
  object = obj,
  celltype = "eL6",
  type = "contour"
)
```

## Gene Expression Visualization

### plot_st_gene

Visualize gene expression patterns in spatial coordinates.

```{r gene, fig.cap="Spatial gene expression"}
# Get available genes
genes <- rownames(obj@data$rawdata)
cat("Total genes:", length(genes), "\n")

# Plot first available gene
plot_st_gene(
  object = obj,
  gene = genes[1],
  size = 1.5
)
```

## Advanced Visualizations (After CCI Analysis)

The following visualizations require running `dec_cci()` or `dec_cci_all()` first:

```{r cci_analysis}
# Run CCI analysis for demonstration
obj <- dec_cci(
  object = obj,
  celltype_sender = "eL6",
  celltype_receiver = "PVALB",
  if_doParallel = FALSE
)

# Check results
if(nrow(obj@lrpair) > 0) {
  cat("Found", nrow(obj@lrpair), "significant LR pairs\n")
  print(head(obj@lrpair[, c("ligand", "receptor", "lr_co_ratio", "score")]))
}
```

### plot_ccdist

Distribution of distances between interacting cell types.

```{r ccdist, fig.cap="Cell-cell distance distribution between eL6 and PVALB"}
plot_ccdist(
  object = obj,
  celltype_sender = "eL6",
  celltype_receiver = "PVALB"
)
```

### plot_lrpair

Spatial visualization of specific ligand-receptor pair interactions (if significant pairs found).

```{r lrpair, fig.cap="Spatial LR pair visualization"}
if(nrow(obj@lrpair) > 0) {
  lr <- obj@lrpair[1, ]
  plot_lrpair(
    object = obj,
    ligand = lr$ligand,
    receptor = lr$receptor,
    celltype_sender = "eL6",
    celltype_receiver = "PVALB",
    size = 1.2
  )
} else {
  cat("No significant LR pairs found for visualization\n")
}
```

## Customization Tips

### Custom Themes

SpaTalk uses ggplot2 for all visualizations. You can easily customize:

```{r custom, fig.cap="Customized plot with different theme"}
p <- plot_st_celltype_all(obj, size = 1)

p + 
  theme_minimal() +
  theme(
    legend.position = "bottom",
    plot.title = element_text(hjust = 0.5, size = 14, face = "bold")
  ) +
  labs(title = "STARmap Cell Type Distribution")
```

## Summary of Visualization Functions

| Function | Description | Input Required |
|----------|-------------|----------------|
| `plot_st_celltype` | Single cell type spatial | SpaTalk object |
| `plot_st_celltype_all` | All cell types spatial | SpaTalk object |
| `plot_st_celltype_percent` | Pie chart per spot | Deconvolved object |
| `plot_st_celltype_density` | Density heatmap | SpaTalk object |
| `plot_st_gene` | Gene expression spatial | SpaTalk object |
| `plot_st_pie` | Pie chart composition | Deconvolved object |
| `plot_cci_lrpairs` | CCI chord diagram | After dec_cci |
| `plot_lrpair` | LR pair spatial | After dec_cci |
| `plot_lrpair_vln` | LR violin plot | After dec_cci |
| `plot_lr_path` | LR-pathway network | After dec_cci |
| `plot_path2gene` | Pathway heatmap | After dec_cci |
| `plot_st_cor_heatmap` | Correlation heatmap | SpaTalk object |
| `plot_ccdist` | Distance distribution | SpaTalk object |

## Session Info

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