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

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

## Introduction

CytoSPACER provides comprehensive visualization functions built on `ggplot2`. This vignette showcases the various plotting options available for exploring and presenting your results.

## Setup

```{r load-packages}
library(CytoSPACER)
library(ggplot2)
```

## Generate Example Data

First, let's create a simulated dataset:

```{r simulate-data}
set.seed(123)

# Parameters
n_genes <- 100
n_cells <- 500
n_spots <- 50

# Create scRNA-seq data
sc_data <- matrix(rpois(n_genes * n_cells, lambda = 5), nrow = n_genes, ncol = n_cells)
rownames(sc_data) <- paste0("Gene", seq_len(n_genes))
colnames(sc_data) <- paste0("Cell", seq_len(n_cells))

# Define cell types
cell_types <- rep(c("TypeA", "TypeB", "TypeC", "TypeD", "TypeE"), each = 100)
names(cell_types) <- colnames(sc_data)

# Add cell type-specific expression
for (i in 1:5) {
  marker_genes <- ((i-1)*20 + 1):(i*20)
  type_cells <- which(cell_types == unique(cell_types)[i])
  sc_data[marker_genes, type_cells] <- sc_data[marker_genes, type_cells] + 20
}

# Create ST data
st_data <- matrix(rpois(n_genes * n_spots, lambda = 50), nrow = n_genes, ncol = n_spots)
rownames(st_data) <- paste0("Gene", seq_len(n_genes))
colnames(st_data) <- paste0("Spot", seq_len(n_spots))

# Create spatial coordinates (grid pattern)
coordinates <- data.frame(
  row = rep(1:10, each = 5),
  col = rep(1:5, times = 10),
  row.names = colnames(st_data)
)

# Create cell type fractions
unique_types <- unique(cell_types)
n_types <- length(unique_types)
cell_type_fractions <- as.data.frame(matrix(
  1/n_types, nrow = n_spots, ncol = n_types,
  dimnames = list(colnames(st_data), unique_types)
))

# Run CytoSPACER
results <- run_cytospace(
  sc_data = sc_data,
  cell_types = cell_types,
  st_data = st_data,
  coordinates = coordinates,
  cell_type_fractions = cell_type_fractions,
  mean_cells_per_spot = 5,
  seed = 42,
  verbose = FALSE
)
```

## Basic Spatial Plots

### Cell Type Distribution

The primary visualization shows the spatial distribution of assigned cell types:

```{r plot-basic}
plot_cytospace(results, type = "cell_types")
```

### Customizing Point Size and Transparency

```{r plot-custom-points}
plot_cytospace(
  results, 
  type = "cell_types",
  point_size = 2.5,
  alpha = 0.7
)
```

### Adding Jitter

For dense regions where points overlap, add jitter:

```{r plot-jitter}
plot_cytospace(
  results, 
  type = "cell_types",
  jitter = 0.3,
  point_size = 2
)
```

### Custom Colors

```{r plot-custom-colors}
my_colors <- c(
  "TypeA" = "#E41A1C",
  "TypeB" = "#377EB8", 
  "TypeC" = "#4DAF4A",
  "TypeD" = "#984EA3",
  "TypeE" = "#FF7F00"
)

plot_cytospace(
  results, 
  type = "cell_types",
  colors = my_colors,
  point_size = 2.5
)
```

### Custom Title

```{r plot-custom-title}
plot_cytospace(
  results, 
  type = "cell_types",
  title = "Spatial Distribution of Cell Types",
  point_size = 2
)
```

## Cell Type Composition Plots

### Global Composition

```{r plot-composition-global}
plot_composition(results, type = "global")
```

### With Custom Colors

```{r plot-composition-colors}
plot_composition(results, type = "global", colors = my_colors)
```

## Advanced Visualizations

### Combining with ggplot2

Since all plots are ggplot2 objects, you can easily customize them:

```{r plot-ggplot-custom}
p <- plot_cytospace(results, type = "cell_types", colors = my_colors)

# Add custom theme
p + 
  theme_minimal() +
  theme(
    legend.position = "bottom",
    legend.title = element_text(face = "bold"),
    plot.title = element_text(hjust = 0.5, size = 16, face = "bold")
  ) +
  guides(color = guide_legend(nrow = 1, override.aes = list(size = 4)))
```

### Faceted by Cell Type

```{r plot-faceted, fig.width=10, fig.height=6}
# Get the assigned locations data
locs <- results$assigned_locations
locs$Y_plot <- -locs$col

# Create faceted plot
ggplot(locs, aes(x = row, y = Y_plot)) +
  geom_point(aes(color = CellType), size = 1.5, alpha = 0.8) +
  facet_wrap(~ CellType, ncol = 3) +
  scale_color_manual(values = my_colors) +
  coord_equal() +
  theme_minimal() +
  theme(
    axis.text = element_blank(),
    axis.title = element_blank(),
    axis.ticks = element_blank(),
    panel.grid = element_blank(),
    strip.text = element_text(face = "bold", size = 11),
    legend.position = "none"
  ) +
  labs(title = "Cell Type Distribution by Type")
```

## Saving Plots

```{r save-plots, eval=FALSE}
# Save individual plot
p <- plot_cytospace(results, type = "cell_types", colors = my_colors)

# Using CytoSPACER function
save_cytospace_plot(
  plot = p,
  output_dir = "figures/",
  prefix = "spatial_",
  formats = c("png", "pdf"),
  width = 10,
  height = 8,
  dpi = 300
)

# Using ggplot2 directly
ggsave("figures/cell_types.png", p, width = 10, height = 8, dpi = 300)
```

## Color Palettes

CytoSPACER includes a built-in color palette optimized for distinguishing cell types:

```{r show-palette, fig.width=8, fig.height=2}
# Default CytoSPACER colors (first 10)
default_colors <- c(
  "#222222", "#F3C300", "#875692", "#F38400", "#A1CAF1",
  "#BE0032", "#C2B280", "#848482", "#008856", "#E68FAC"
)

# Display palette
barplot(rep(1, 10), col = default_colors, border = NA, axes = FALSE,
        main = "CytoSPACER Default Color Palette", names.arg = 1:10)
```

## Session Info

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