---
title: "Quick Start Guide"
author: "Zaoqu Liu"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Quick Start Guide}
  %\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
)
```

## Introduction

**CytoSPACER** is an R implementation of CytoSPACE (Vahid et al., *Nature Biotechnology*, 2023), designed for high-resolution mapping of single-cell transcriptomes to spatial transcriptomics (ST) data. This vignette provides a quick introduction to get you started with the package.

## Installation

```{r install, eval = FALSE}
# From R-universe (recommended)
install.packages("CytoSPACER", repos = "https://zaoqu-liu.r-universe.dev")

# From GitHub
remotes::install_github("Zaoqu-Liu/CytoSPACER")
```

## Load the Package

```{r load}
library(CytoSPACER)
```

## Simulated Example

Let's create a simple simulated dataset to demonstrate the workflow:

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

# Simulate scRNA-seq data (100 genes x 500 cells)
n_genes <- 100
n_cells <- 500
n_spots <- 50

# Create expression matrix with some structure
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))

# Add cell type-specific expression patterns
cell_types <- rep(c("TypeA", "TypeB", "TypeC", "TypeD", "TypeE"), each = 100)
names(cell_types) <- colnames(sc_data)

# TypeA cells express genes 1-20 highly
sc_data[1:20, cell_types == "TypeA"] <- sc_data[1:20, cell_types == "TypeA"] + 20
# TypeB cells express genes 21-40 highly
sc_data[21:40, cell_types == "TypeB"] <- sc_data[21:40, cell_types == "TypeB"] + 20
# TypeC cells express genes 41-60 highly
sc_data[41:60, cell_types == "TypeC"] <- sc_data[41:60, cell_types == "TypeC"] + 20

# Simulate ST data (100 genes x 50 spots)
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)
)

# Display data dimensions
cat("scRNA-seq data:", nrow(sc_data), "genes x", ncol(sc_data), "cells\n")
cat("ST data:", nrow(st_data), "genes x", ncol(st_data), "spots\n")
cat("Cell types:", paste(unique(cell_types), collapse = ", "), "\n")
```

## Run CytoSPACER

Now let's run the main analysis. We'll provide pre-computed cell type fractions to skip the Seurat-dependent deconvolution step:
 
```{r run-cytospace}
# Create simple cell type fractions (for demonstration)
# In real analysis, these would be estimated from the data
unique_types <- unique(cell_types)
n_types <- length(unique_types)
cell_type_fractions <- matrix(
  1/n_types, 
  nrow = n_spots, 
  ncol = n_types,
  dimnames = list(colnames(st_data), unique_types)
)
cell_type_fractions <- as.data.frame(cell_type_fractions)

# Run CytoSPACER with default parameters
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,
  distance_metric = "pearson",
  sampling_method = "duplicates",
  seed = 42,
  verbose = TRUE
)
```

## Explore Results

The results object contains several components:

```{r results-structure}
# Check the structure
names(results)

# View assigned locations
head(results$assigned_locations)

# Cell type counts per spot
head(results$cell_type_by_spot)

# Fractional abundances
head(results$fractional_abundances)
```

## Visualization

CytoSPACER provides several visualization functions:

### Spatial Cell Type Distribution

```{r plot-cell-types, fig.width=8, fig.height=6}
# Plot cell type spatial distribution
plot_cytospace(results, type = "cell_types", point_size = 2)
```

### With Jitter for Dense Regions

```{r plot-jitter, fig.width=8, fig.height=6}
# Add jitter to separate overlapping points
plot_cytospace(results, type = "cell_types", jitter = 0.3, point_size = 2)
```

### Cell Type Composition

```{r plot-composition, fig.width=7, fig.height=5}
# Global cell type composition
plot_composition(results, type = "global")
```

## Summary Statistics

```{r summary}
# Total cells assigned
cat("Total cells assigned:", nrow(results$assigned_locations), "\n")

# Cells per cell type
table(results$assigned_locations$CellType)

# Average cells per spot
cat("Average cells per spot:", 
    mean(results$cell_type_by_spot$Total), "\n")

# Runtime
cat("Analysis runtime:", round(results$runtime, 2), "seconds\n")
```
 
## Save Results

```{r save, eval = FALSE}
# Save results to files
write_cytospace_results(results, output_dir = "cytospace_output/")
```

## Next Steps

- See the [Algorithm Principles](algorithm.html) vignette for detailed methodology
- See the [Visualization Gallery](visualization.html) for more plotting options
- See the [Seurat Integration](seurat-integration.html) for working with Seurat objects
- See the [Performance Optimization](performance.html) for large datasets

## Session Info

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