---
title: "Seurat Integration"
author: "Zaoqu Liu"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Seurat Integration}
  %\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,
  eval = FALSE
)
```

## Introduction

CytoSPACER provides seamless integration with the Seurat ecosystem, supporting both Seurat v4 and v5. This vignette demonstrates how to use CytoSPACER with Seurat objects for spatial transcriptomics analysis.

## Prerequisites

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

## Workflow Overview

The Seurat integration workflow consists of:

1. **Load Seurat objects** - scRNA-seq reference and spatial data
2. **Run CytoSPACER** - Direct analysis from Seurat objects
3. **Add results** - Integrate results back into Seurat object
4. **Visualize** - Use Seurat's spatial plotting functions

## Loading Data

### From Seurat Objects

```{r load-seurat}
# Load pre-processed Seurat objects
sc_seurat <- readRDS("path/to/scRNA_seurat.rds")
st_seurat <- readRDS("path/to/visium_seurat.rds")

# Check the objects
sc_seurat
st_seurat
```
 
### From 10x Visium Output

```{r load-visium}
# Load Visium data directly
visium_data <- read_visium_data(
  path = "path/to/spaceranger/output",
  use_seurat = TRUE
)

# Or load with Seurat
st_seurat <- Seurat::Load10X_Spatial("path/to/spaceranger/output")
```

## Running CytoSPACER with Seurat

### Direct Analysis

The `run_cytospace_seurat()` function handles data extraction automatically:

```{r run-seurat}
# Run CytoSPACER directly from Seurat objects
results <- run_cytospace_seurat(
  sc_seurat = sc_seurat,
  st_seurat = st_seurat,
  cell_type_col = "celltype",  # Column in metadata with cell type labels
  sc_assay = "RNA",            # Assay to use from scRNA-seq
  st_assay = "Spatial",        # Assay to use from spatial data
  mean_cells_per_spot = 5,
  distance_metric = "pearson",
  seed = 42
)
```

### Using Idents

If cell types are stored as Idents:

```{r run-idents}
# Set cell type identities
Idents(sc_seurat) <- sc_seurat$celltype

# Run without specifying cell_type_col (uses Idents)
results <- run_cytospace_seurat(
  sc_seurat = sc_seurat,
  st_seurat = st_seurat,
  cell_type_col = NULL  # Will use Idents(sc_seurat)
)
```

## Adding Results to Seurat

### Basic Integration

```{r add-results}
# Add CytoSPACER results to spatial Seurat object
st_seurat <- add_cytospace_to_seurat(st_seurat, results)

# Check new metadata columns
head(st_seurat@meta.data)
```

The function adds:

- `n_cells_cytospace`: Number of cells assigned to each spot
- `dominant_celltype_cytospace`: Most abundant cell type per spot
- `frac_*`: Fractional abundance for each cell type

### Visualizing with Seurat

```{r seurat-viz}
# Spatial plot of dominant cell type
SpatialDimPlot(st_seurat, group.by = "dominant_celltype_cytospace")

# Spatial plot of cell counts
SpatialFeaturePlot(st_seurat, features = "n_cells_cytospace")

# Cell type fractions
SpatialFeaturePlot(st_seurat, features = c("frac_Tumor", "frac_Immune"))
```

## Data Extraction Utilities

### Extract scRNA-seq Data

```{r extract-sc}
# Extract data for external analysis
sc_data <- extract_seurat_data(
  seurat_obj = sc_seurat,
  assay = "RNA",
  cell_type_col = "celltype"
)

# Returns list with expression matrix and cell types
names(sc_data)
dim(sc_data$expression)
head(sc_data$cell_types)
```

### Extract Spatial Data

```{r extract-st}
# Extract spatial data
st_data <- extract_spatial_data(
  seurat_obj = st_seurat,
  assay = "Spatial",
  image_name = NULL  # Uses first image if NULL
)

# Returns list with expression and coordinates
names(st_data)
dim(st_data$expression)
head(st_data$coordinates)
```

### Save to Files

```{r save-extracted}
# Save scRNA-seq data to files
extract_seurat_data(
  seurat_obj = sc_seurat,
  assay = "RNA",
  cell_type_col = "celltype",
  output_dir = "cytospace_input/",
  prefix = "scRNA_",
  sparse = FALSE
)

# Save spatial data to files
extract_spatial_data(
  seurat_obj = st_seurat,
  assay = "Spatial",
  output_dir = "cytospace_input/",
  prefix = "ST_"
)
```

## Complete Workflow Example

```{r complete-workflow}
library(CytoSPACER)
library(Seurat)

# 1. Load data
sc_seurat <- readRDS("scRNA_processed.rds")
st_seurat <- Load10X_Spatial("visium_output/")

# 2. Preprocess spatial data if needed
st_seurat <- SCTransform(st_seurat, assay = "Spatial", verbose = FALSE)

# 3. Run CytoSPACER
results <- run_cytospace_seurat(
  sc_seurat = sc_seurat,
  st_seurat = st_seurat,
  cell_type_col = "celltype",
  mean_cells_per_spot = 5,
  distance_metric = "pearson",
  n_workers = 4,
  seed = 42
)

# 4. Add results to Seurat object
st_seurat <- add_cytospace_to_seurat(st_seurat, results)

# 5. Visualize
p1 <- SpatialDimPlot(st_seurat, group.by = "dominant_celltype_cytospace")
p2 <- SpatialFeaturePlot(st_seurat, features = "n_cells_cytospace")

# 6. Save results
write_cytospace_results(results, output_dir = "cytospace_output/")
saveRDS(st_seurat, "st_seurat_with_cytospace.rds")
```

## Working with Seurat v5

CytoSPACER automatically detects Seurat version and handles the differences:

```{r seurat-v5}
# Seurat v5 uses layers instead of slots
# CytoSPACER handles this automatically

# Check Seurat version
packageVersion("Seurat")

# The same code works for both v4 and v5
results <- run_cytospace_seurat(
  sc_seurat = sc_seurat,
  st_seurat = st_seurat,
  cell_type_col = "celltype"
)
```

## Tips and Best Practices

### 1. Cell Type Annotation Quality

Ensure your scRNA-seq reference has high-quality cell type annotations:

```{r check-annotations}
# Check cell type distribution
table(sc_seurat$celltype)

# Visualize reference
DimPlot(sc_seurat, group.by = "celltype", label = TRUE)
```

### 2. Gene Overlap

Check gene overlap between scRNA-seq and spatial data:

```{r check-genes}
sc_genes <- rownames(sc_seurat)
st_genes <- rownames(st_seurat)
common_genes <- intersect(sc_genes, st_genes)

cat("scRNA-seq genes:", length(sc_genes), "\n")
cat("Spatial genes:", length(st_genes), "\n")
cat("Common genes:", length(common_genes), "\n")
```

### 3. Memory Management

For large datasets, consider subsetting:

```{r memory-tips}
# Subsample scRNA-seq reference
sc_subset <- subset(sc_seurat, downsample = 5000)

# Run with subset
results <- run_cytospace_seurat(
  sc_seurat = sc_subset,
  st_seurat = st_seurat,
  cell_type_col = "celltype"
)
```

## Troubleshooting

### Common Issues

**1. Missing cell type column:**
```{r troubleshoot-1}
# Check available metadata columns
colnames(sc_seurat@meta.data)

# Ensure cell_type_col exists
if (!"celltype" %in% colnames(sc_seurat@meta.data)) {
  stop("Cell type column not found!")
}
```

**2. No spatial image:**
```{r troubleshoot-2}
# Check available images
names(st_seurat@images)

# Specify image name if multiple exist
results <- run_cytospace_seurat(
  sc_seurat = sc_seurat,
  st_seurat = st_seurat,
  cell_type_col = "celltype",
  image_name = "slice1"
)
```

**3. Assay not found:**
```{r troubleshoot-3}
# Check available assays
Assays(sc_seurat)
Assays(st_seurat)

# Specify correct assay names
results <- run_cytospace_seurat(
  sc_seurat = sc_seurat,
  st_seurat = st_seurat,
  cell_type_col = "celltype",
  sc_assay = "RNA",
  st_assay = "Spatial"
)
```

## Session Info

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