---
title: "SpaTalk for Different Spatial Transcriptomics Platforms"
author: 
  - name: "Zaoqu Liu"
    email: "liuzaoqu@163.com"
    affiliation: "Maintainer"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 3
vignette: >
  %\VignetteIndexEntry{SpaTalk for Different Spatial Transcriptomics Platforms}
  %\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
)
```

## Overview

Spatial transcriptomics technologies can be broadly categorized into two types:

| Category | Resolution | Examples | SpaTalk Setting |
|----------|-----------|----------|-----------------|
| **Spot-based** | Multi-cellular | 10x Visium, Slide-seq, ST | `if_st_is_sc = FALSE` |
| **Single-cell** | Cellular | STARmap, MERFISH, seqFISH+, Xenium | `if_st_is_sc = TRUE` |

This vignette provides platform-specific guidance for using SpaTalk.

## Single-Cell Resolution Platforms

### STARmap Example (Built-in Data)

STARmap provides single-cell resolution with targeted gene panels. Let's demonstrate with the built-in STARmap data:

```{r starmap}
library(SpaTalk)

# Load built-in STARmap demo data
load(system.file("extdata", "starmap_data.rda", package = "SpaTalk"))
load(system.file("extdata", "starmap_meta.rda", package = "SpaTalk"))

# Check data dimensions
cat("Genes:", nrow(starmap_data), "\n")
cat("Cells:", ncol(starmap_data), "\n")
cat("Cell types:", length(unique(starmap_meta$celltype)), "\n")
```

```{r starmap_create}
# Create SpaTalk object - NO deconvolution needed
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,       # Single-cell resolution
  spot_max_cell = 1,        # One cell per "spot"
  celltype = starmap_meta$celltype  # Direct annotation
)

obj
```

```{r starmap_viz, fig.cap="STARmap single-cell spatial distribution"}
plot_st_celltype_all(obj, size = 1.2)
```

### Other Single-Cell Platforms

For **MERFISH**, **Xenium**, **seqFISH+**, etc., use the same workflow:

```{r sc_workflow, eval=FALSE}
# Generic single-cell resolution workflow
obj <- createSpaTalk(
  st_data = your_counts,        # Gene x Cell matrix
  st_meta = your_coords,        # data.frame with cell, x, y
  species = "Human",            # or "Mouse"
  if_st_is_sc = TRUE,           # Single-cell resolution
  spot_max_cell = 1,
  celltype = your_annotations   # Cell type labels
)

# No deconvolution needed - proceed directly to CCI
data(lrpairs)
data(pathways)
obj <- find_lr_path(obj, lrpairs, pathways)
obj <- dec_cci_all(obj)
```

## Spot-Based Platforms

### 10x Visium Workflow

Visium captures ~1-10 cells per 55μm diameter spot with whole-transcriptome coverage.

```{r visium, eval=FALSE}
library(SpaTalk)
library(Seurat)

# Load Visium data using Seurat
visium <- Load10X_Spatial(
  data.dir = "path/to/spaceranger/output/",
  filename = "filtered_feature_bc_matrix.h5"
)

# Quality control
visium <- subset(visium, 
  nFeature_Spatial > 200 & 
  nFeature_Spatial < 10000 &
  percent.mt < 20
)

# Extract for SpaTalk
st_data <- GetAssayData(visium, slot = "counts")
coords <- GetTissueCoordinates(visium)
st_meta <- data.frame(
  spot = rownames(coords),
  x = coords$imagerow,
  y = coords$imagecol
)

# Create SpaTalk object (spot-based)
obj <- createSpaTalk(
  st_data = st_data,
  st_meta = st_meta,
  species = "Human",
  if_st_is_sc = FALSE,      # Spot-based
  spot_max_cell = 8         # Visium: ~1-10 cells/spot
)

# Deconvolution with scRNA-seq reference (REQUIRED for spot-based)
obj <- dec_celltype(
  object = obj,
  sc_data = sc_reference,
  sc_celltype = sc_annotations
)
```

### Slide-seq / Slide-seqV2

Slide-seq uses 10μm beads, typically capturing 1-10 cells per bead.

```{r slideseq, eval=FALSE}
# Slide-seq workflow
obj <- createSpaTalk(
  st_data = slideseq_counts,
  st_meta = data.frame(
    spot = colnames(slideseq_counts),
    x = bead_coordinates$x,
    y = bead_coordinates$y
  ),
  species = "Mouse",
  if_st_is_sc = FALSE,
  spot_max_cell = 5  # Slide-seq: smaller spots
)

# Deconvolution required
obj <- dec_celltype(obj, sc_data, sc_celltype)
```

## Workflow Comparison

### Single-cell Workflow (STARmap, MERFISH, Xenium)

```{r workflow_sc}
# Complete single-cell workflow demonstration
library(SpaTalk)

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

# 2. Create object with cell types
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
)

# 3. NO deconvolution needed

# 4. Filter LR paths
data(lrpairs)
data(pathways)
obj <- find_lr_path(obj, lrpairs, pathways, if_doParallel = FALSE)

# 5. Infer CCIs
obj <- dec_cci(obj, "eL6", "PVALB", if_doParallel = FALSE)

cat("Single-cell workflow completed!\n")
cat("LR pairs found:", nrow(obj@lrpair), "\n")
```

### Spot-based Workflow (Visium, Slide-seq)

```{r workflow_spot, eval=FALSE}
# Spot-based workflow (requires scRNA-seq reference)

# 1. Create object (spot-based)
obj <- createSpaTalk(st_data, st_meta, "Human", 
                     if_st_is_sc = FALSE, spot_max_cell = 10)

# 2. Deconvolution (REQUIRED)
obj <- dec_celltype(obj, sc_data, sc_celltype)

# 3. Filter LR paths
obj <- find_lr_path(obj, lrpairs, pathways)

# 4. Infer CCIs
obj <- dec_cci_all(obj)
```

## Parameter Guidelines by Platform

| Platform | `spot_max_cell` | Deconvolution | Notes |
|----------|-----------------|---------------|-------|
| 10x Visium | 5-10 | Required | 55μm spots |
| Slide-seq | 3-8 | Required | 10μm beads |
| Slide-seqV2 | 3-8 | Required | Improved capture |
| Original ST | 15-30 | Required | 100μm spots |
| STARmap | 1 | Not needed | Single-cell |
| MERFISH | 1 | Not needed | Single-cell |
| Xenium | 1 | Not needed | Single-cell |
| seqFISH+ | 1 | Not needed | Single-cell |
| CosMx | 1 | Not needed | Single-cell |

## Best Practices

### For Spot-based Data

1. **Reference selection**: Use tissue-matched scRNA-seq
2. **Deconvolution validation**: Check proportions against known biology
3. **Spatial coherence**: Verify cell types cluster appropriately

### For Single-cell Data

1. **Cell type annotation**: Use robust clustering methods
2. **Quality control**: Filter low-quality cells
3. **Gene coverage**: Consider gene panel limitations

## Session Info

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