---
title: "Quick Start Guide"
author: "Zaoqu Liu"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 2
    fig_width: 8
    fig_height: 6
vignette: >
  %\VignetteIndexEntry{Quick Start Guide}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 8,
  fig.height = 6,
  message = FALSE,
  warning = FALSE
)
```

## Overview

This guide demonstrates the essential COMMOTR workflow in **5 simple steps**:
1. Load ligand-receptor database
2. Infer spatial communication
3. Compute communication direction
4. Analyze cluster communication
5. Visualize results

## Installation

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

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

## Setup

```{r library, eval=FALSE}
library(COMMOTR)
library(Seurat)
library(Matrix)
library(ggplot2)
```

## Create Demo Data

For this tutorial, we create a simulated spatial dataset with known communication patterns:

```{r create_demo, eval=FALSE}
set.seed(42)

# Simulate 100 cells in two spatial clusters
n_cells <- 100
n_genes <- 50

# Create expression matrix
expr <- matrix(rpois(n_cells * n_genes, lambda = 5), 
               nrow = n_genes, ncol = n_cells)

# Gene names including ligand-receptor pairs
gene_names <- c("Tgfb1", "Tgfbr1", "Tgfbr2",  # TGFb pathway
                "Wnt5a", "Fzd1", "Lrp5",       # Wnt pathway
                "Fgf2", "Fgfr1",               # FGF pathway
                paste0("Gene", 1:(n_genes - 8)))
rownames(expr) <- gene_names
colnames(expr) <- paste0("Cell", 1:n_cells)

# Create spatial structure: left cluster (ligand-high), right cluster (receptor-high)
coords <- matrix(c(
  runif(50, 0, 45),   runif(50, 55, 100),  # x coordinates
  runif(100, 0, 100)                        # y coordinates
), ncol = 2)
rownames(coords) <- colnames(expr)
colnames(coords) <- c("x", "y")

# Add differential expression
expr["Tgfb1", 1:50] <- expr["Tgfb1", 1:50] + 15
expr["Tgfbr1", 51:100] <- expr["Tgfbr1", 51:100] + 15
expr["Tgfbr2", 51:100] <- expr["Tgfbr2", 51:100] + 15

# Create Seurat object
seurat_obj <- CreateSeuratObject(counts = expr, assay = "RNA")
seurat_obj <- SetAssayData(seurat_obj, layer = "data", 
                           new.data = log1p(as(expr, "dgCMatrix")))

# Add spatial coordinates
colnames(coords) <- c("spatial_1", "spatial_2")
seurat_obj[["spatial"]] <- CreateDimReducObject(
  embeddings = coords, key = "spatial_", assay = "RNA"
)

# Add cluster labels
seurat_obj$cluster <- factor(c(rep("Sender", 50), rep("Receiver", 50)))
```

## Step 1: Load LR Database

```{r load_lr, eval=FALSE}
# Create custom LR database for demo
df_lr <- data.frame(
  ligand = c("Tgfb1", "Wnt5a", "Fgf2"),
  receptor = c("Tgfbr1_Tgfbr2", "Fzd1_Lrp5", "Fgfr1"),
  pathway = c("TGFb", "WNT", "FGF"),
  stringsAsFactors = FALSE
)

# In real analysis, load from built-in databases:
df_lr <- ligand_receptor_database("CellChat", "mouse", "Secreted Signaling")
df_lr <- filter_lr_database(df_lr, seurat_obj, min_cell_pct = 0.05)
```

## Step 2: Infer Spatial Communication

```{r spatial_comm, eval=FALSE}
# Run spatial communication inference
seurat_obj <- spatial_communication(
  seurat_obj,
  df_ligrec = df_lr,
  database_name = "demo",
  spatial_coords = "spatial",
  dis_thr = 40,           # Distance threshold
  cot_eps_p = 0.1,        # Entropy regularization
  cot_rho = 10,           # Unbalanced penalty
  verbose = TRUE
)

# Access results
results <- get_communication_results(seurat_obj, "demo")
```

## Step 3: Communication Direction

```{r direction, eval=FALSE}
# Compute vector field for TGFb pathway
seurat_obj <- communication_direction(
  seurat_obj,
  database_name = "demo",
  pathway_name = "TGFb",
  spatial_coords = "spatial",
  k = 5
)
```

## Step 4: Cluster Communication

```{r cluster_comm, eval=FALSE}
# Analyze cluster-level communication with permutation test
seurat_obj <- cluster_communication(
  seurat_obj,
  database_name = "demo",
  clustering = "cluster",
  pathway_name = "TGFb",
  n_permutations = 100
)
```

## Step 5: Visualization

### Spatial Communication Plot

```{r plot_example, eval=TRUE, echo=FALSE, fig.height=5}
# Static example visualization
library(ggplot2)

set.seed(42)
n <- 100
example_df <- data.frame(
  x = c(runif(50, 0, 45), runif(50, 55, 100)),
  y = runif(n, 0, 100),
  cluster = factor(c(rep("Sender", 50), rep("Receiver", 50))),
  signal = c(rnorm(50, 3, 0.5), rnorm(50, 1, 0.3))
)

ggplot(example_df, aes(x = x, y = y)) +
  geom_point(aes(color = signal, shape = cluster), size = 3) +
  scale_color_viridis_c(option = "plasma", name = "Sender\nSignal") +
  labs(title = "Example: Sender Communication Signal",
       subtitle = "Higher in Sender cluster (left)",
       x = "Spatial X", y = "Spatial Y") +
  theme_minimal() +
  theme(legend.position = "right")
```

### Vector Field Visualization

```{r vector_example, eval=TRUE, echo=FALSE, fig.height=5}
# Example vector field
arrow_df <- example_df[example_df$signal > 2, ]
arrow_df$vx <- 4
arrow_df$vy <- runif(nrow(arrow_df), -1, 1)

ggplot() +
  geom_point(data = example_df, aes(x = x, y = y), color = "gray80", size = 2) +
  geom_segment(data = arrow_df,
               aes(x = x, y = y, xend = x + vx, yend = y + vy, color = signal),
               arrow = arrow(length = unit(0.12, "cm")), linewidth = 0.8) +
  scale_color_gradient(low = "#fee0d2", high = "#de2d26", name = "Signal") +
  labs(title = "Example: TGFb Communication Direction",
       subtitle = "Arrows show signal flow from senders to receivers",
       x = "Spatial X", y = "Spatial Y") +
  theme_minimal() +
  coord_fixed()
```

### Cluster Communication Heatmap

```{r heatmap_example, eval=TRUE, echo=FALSE, fig.height=4}
# Example heatmap
comm_df <- expand.grid(
  Sender = c("Sender", "Receiver"),
  Receiver = c("Sender", "Receiver")
)
comm_df$Communication <- c(1.2, 0.3, 2.8, 0.5)
comm_df$significant <- c(FALSE, FALSE, TRUE, FALSE)

ggplot(comm_df, aes(x = Receiver, y = Sender)) +
  geom_tile(aes(fill = Communication), color = "white", linewidth = 1) +
  geom_text(aes(label = ifelse(significant, paste0(round(Communication, 1), "*"), 
                               round(Communication, 1))), 
            color = "white", size = 5, fontface = "bold") +
  scale_fill_gradient(low = "#f7fbff", high = "#08519c", name = "Strength") +
  labs(title = "Cluster Communication Matrix",
       subtitle = "* indicates p < 0.05",
       x = "Receiver Cluster", y = "Sender Cluster") +
  theme_minimal() +
  coord_fixed()
```

## Summary

| Step | Function | Purpose |
|------|----------|---------|
| 1 | `ligand_receptor_database()` | Load LR pairs |
| 2 | `spatial_communication()` | Infer communication |
| 3 | `communication_direction()` | Compute vector fields |
| 4 | `cluster_communication()` | Cluster-level analysis |
| 5 | Visualization | Interpret results |

## Next Steps

- Read the [Algorithm Theory](algorithm_theory.html) vignette for mathematical details
- Explore the [Visualization Gallery](visualization.html) for more plot types
- Check the [Full Tutorial](COMMOTR_tutorial.html) for advanced analysis

---
*Developed by Zaoqu Liu | [GitHub](https://github.com/Zaoqu-Liu) | liuzaoqu@163.com*