---
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 = 8,
  fig.height = 8,
  warning = FALSE,
  message = FALSE
)
```

## Introduction

**iTALK** (intercellular communication analysis toolkit) is an R package designed to characterize and visualize cell-cell communication from transcriptomic data. This vignette provides a quick introduction to the core functionality.

## Installation

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

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

## Load Package and Create Example Data

```{r load}
library(iTALK)
library(dplyr)

# Access database to get real ligand-receptor pairs
db <- iTALK:::database
cyto_db <- db[db$Classification == "cytokine", ]

# Get some real ligands and receptors from the database
ligands <- head(unique(cyto_db$Ligand.ApprovedSymbol), 10)
receptors <- head(unique(cyto_db$Receptor.ApprovedSymbol), 10)
genes <- unique(c(ligands, receptors))

cat("Using genes from database:\n")
cat("Ligands:", paste(ligands, collapse = ", "), "\n")
cat("Receptors:", paste(receptors, collapse = ", "), "\n\n")

# Create synthetic expression data
set.seed(42)
n_cells <- 200
cell_types <- c("T_cell", "B_cell", "Macrophage", "Dendritic", "NK_cell")

data <- data.frame(
  cell_type = sample(cell_types, n_cells, replace = TRUE)
)

# Add gene expression
for (gene in genes) {
  data[[gene]] <- rpois(n_cells, lambda = sample(5:25, 1))
}

cat("Data dimensions:", nrow(data), "cells x", ncol(data), "columns\n")
cat("Cell types:", paste(unique(data$cell_type), collapse = ", "), "\n")
head(data[, 1:6])
```

## Workflow 1: Highly Expressed Gene Analysis

### Step 1: Parse Expression Data

Identify the top expressed genes in each cell type:

```{r rawparse}
# Get top 50% highly expressed genes per cell type
highly_expr <- rawParse(data, top_genes = 50, stats = "mean")

cat("\nTop expressed genes found:", nrow(highly_expr), "\n")
cat("Cell types:", paste(unique(highly_expr$cell_type), collapse = ", "), "\n\n")
head(highly_expr)
```

### Step 2: Find Ligand-Receptor Pairs

```{r findlr}
# Find ligand-receptor pairs from cytokine category
lr_pairs <- FindLR(
  data_1 = highly_expr,
  datatype = "mean count",
  comm_type = "cytokine"
)

cat("Found", nrow(lr_pairs), "ligand-receptor pairs\n\n")
if (nrow(lr_pairs) > 0) {
  head(lr_pairs)
}
```

### Step 3: Visualize with Circos Plot

```{r viz_circos, fig.cap="Circos plot showing ligand-receptor interactions between cell types"}
# Define cell type colors
cell_col <- c(
  "T_cell" = "#E41A1C",
  "B_cell" = "#377EB8", 
  "Macrophage" = "#4DAF4A",
  "Dendritic" = "#984EA3",
  "NK_cell" = "#FF7F00"
)

# Create circos plot
if (nrow(lr_pairs) > 0) {
  # Take top pairs for cleaner visualization
  plot_data <- lr_pairs[1:min(20, nrow(lr_pairs)), ]
  
  LRPlot(
    data = plot_data,
    datatype = "mean count",
    cell_col = cell_col,
    transparency = 0.5,
    link.arr.type = "triangle"
  )
}
```

### Step 4: Visualize with Network Plot

```{r viz_network, fig.cap="Network visualization of cell-cell communication"}
if (nrow(lr_pairs) > 0) {
  g <- NetView(
    data = lr_pairs,
    col = cell_col,
    vertex.size = 30,
    edge.max.width = 8,
    edge.curved = 0.2,
    arrow.width = 1.5,
    margin = 0.2
  )
}
```

## Workflow 2: Multi-Category Analysis

You can analyze different communication types separately:

```{r multi_category}
# Communication categories in database
comm_types <- c("cytokine", "growth factor", "checkpoint", "other")

# Analyze each category
results_list <- list()
for (comm in comm_types) {
  lr <- FindLR(highly_expr, datatype = "mean count", comm_type = comm)
  if (nrow(lr) > 0) {
    results_list[[comm]] <- lr
    cat(comm, ":", nrow(lr), "pairs\n")
  }
}
```

## Workflow 3: Using the Ligand-Receptor Database

iTALK includes a curated database of ligand-receptor pairs:

```{r database}
# Access the built-in database
data(database)

cat("Database contains", nrow(database), "ligand-receptor pairs\n\n")
cat("Categories:", paste(unique(database$Classification), collapse = ", "), "\n\n")

# Preview
head(database[, c("Pair.Name", "Ligand.ApprovedSymbol", "Receptor.ApprovedSymbol", "Classification")])
```

## Summary

This quick start covered:

1. **Data preparation** - Expression matrix with cell type annotations
2. **Gene parsing** - Identifying highly expressed genes per cell type
3. **L-R detection** - Finding ligand-receptor pairs from the database
4. **Visualization** - Circos and network plots

For more advanced usage, see:

- `vignette("algorithm")` - Statistical methods and database
- `vignette("species-conversion")` - Cross-species analysis
- `vignette("visualization")` - Comprehensive visualization guide

## Session Info

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