---
title: "Differential Communication Analysis"
author: "Zaoqu Liu"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 3
    fig_caption: true
vignette: >
  %\VignetteIndexEntry{Differential Communication Analysis}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Introduction

Differential communication analysis is essential for understanding how cell-cell signaling changes between biological conditions, such as:

- **Disease vs. Normal**: Altered communication in cancer, inflammation, or autoimmune diseases
- **Treatment response**: Changes after drug treatment or immunotherapy
- **Developmental stages**: Communication dynamics during differentiation

NOVA provides comprehensive tools for comparing communication networks between conditions.

## Setup

```{r load}
library(NOVA)
library(ggplot2)
```

## Simulating Two Conditions

We'll create two simulated datasets representing control and treatment conditions.

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

# Common parameters
n_genes <- 200
n_cells <- 400
gene_names <- paste0("Gene", 1:n_genes)
clusters <- c("T_cells", "B_cells", "Macrophages", "Fibroblasts")

# Get LR database genes
lr_db <- GetLRDatabase("lrc2p")
ligands <- unique(lr_db$ligand)[1:25]
receptors <- unique(lr_db$receptor)[1:25]

# Function to create expression matrix
create_expr <- function(n_cells, seed_offset = 0, fold_changes = NULL) {
  set.seed(42 + seed_offset)
  cell_names <- paste0("Cell", 1:n_cells)
  
  expr <- matrix(0, nrow = n_genes, ncol = n_cells,
                 dimnames = list(gene_names, cell_names))
  
  # Base expression
  expressed <- sample(length(expr), size = length(expr) * 0.25)
  expr[expressed] <- abs(rnorm(length(expressed), mean = 2, sd = 1))
  
  # Map genes
  rownames(expr)[1:25] <- ligands
  rownames(expr)[26:50] <- receptors
  
  # Apply fold changes if provided
  if (!is.null(fold_changes)) {
    for (gene in names(fold_changes)) {
      if (gene %in% rownames(expr)) {
        expr[gene, ] <- expr[gene, ] * fold_changes[gene]
      }
    }
  }
  
  # Create annotation
  cluster_assign <- sample(clusters, n_cells, replace = TRUE)
  names(cluster_assign) <- cell_names
  ann <- data.frame(cell = cell_names, cluster = cluster_assign)
  
  list(expr = Matrix::Matrix(expr, sparse = TRUE), annotation = ann)
}

# Create control condition
ctrl <- create_expr(400)

# Create treatment condition with altered expression
# Simulate upregulation of some genes in treatment
treatment_fc <- setNames(rep(1.5, 10), ligands[1:10])
treat <- create_expr(400, seed_offset = 100, fold_changes = treatment_fc)
```

## Running Individual Analyses

```{r individual, eval=FALSE}
# Analyze control
ctrl_result <- ExtractEdges(
  expression = ctrl$expr,
  annotation = ctrl$annotation,
  species = "human",
  database = "lrc2p",
  min_pct = 0.05
)

# Analyze treatment
treat_result <- ExtractEdges(
  expression = treat$expr,
  annotation = treat$annotation,
  species = "human",
  database = "lrc2p",
  min_pct = 0.05
)

cat("Control edges:", nrow(ctrl_result$edges), "\n")
cat("Treatment edges:", nrow(treat_result$edges), "\n")
```

## Differential Analysis

### Running DiffEdges

```{r diff, eval=FALSE}
# Compare treatment vs control
diff_result <- DiffEdges(
  reference = ctrl_result,
  target = treat_result,
  log2fc_threshold = 0.5,
  pseudo_count = 0.001
)

print(diff_result)
```

### Understanding the Output

```{r output, eval=FALSE}
# Summary of differential analysis
summary(diff_result)

# View changed edges
head(diff_result$changed_edges)
```

## Visualization

### Differential Heatmap

```{r diff_heatmap, eval=FALSE, fig.cap="Heatmap showing log2 fold changes in communication"}
PlotDiffHeatmap(diff_result, metric = "log2fc")
```

### Volcano Plot

```{r volcano, eval=FALSE, fig.cap="Volcano plot of differential communication"}
PlotVolcano(diff_result, 
            log2fc_threshold = 0.5,
            label_top = 10,
            title = "Treatment vs Control")
```

## Summarization Functions

### By Cluster Pair

```{r by_cluster, eval=FALSE}
# Summarize changes by cluster pairs
cluster_summary <- SummarizeByCluster(diff_result)
head(cluster_summary)
```

### By LR Pair

```{r by_lr, eval=FALSE}
# Summarize changes by ligand-receptor pairs
lr_summary <- SummarizeByLR(diff_result)
head(lr_summary)
```

## Filtering Significant Changes

```{r filter, eval=FALSE}
# Get strongly upregulated edges
up_edges <- diff_result$changed_edges[log2fc > 1]
cat("Upregulated edges:", nrow(up_edges), "\n")

# Get strongly downregulated edges
down_edges <- diff_result$changed_edges[log2fc < -1]
cat("Downregulated edges:", nrow(down_edges), "\n")
```

## Interpreting Results

### Key Metrics

| Metric | Description | Interpretation |
|--------|-------------|----------------|
| `log2fc` | Log2 fold change | Positive = increased in treatment |
| `delta_mean` | Difference in expression weight | Magnitude of change |
| `delta_specificity` | Difference in specificity | Change in selectivity |

### Biological Interpretation

1. **High log2fc + High specificity**: Strong, specific upregulation
2. **High log2fc + Low specificity**: Widespread upregulation
3. **Negative log2fc**: Decreased communication
4. **Near-zero log2fc**: Stable communication

## Exporting Results

```{r export, eval=FALSE}
# Export to Excel
ExportDiff(diff_result, "differential_analysis.xlsx")

# Export to CSV
write.csv(diff_result$changed_edges, "changed_edges.csv", row.names = FALSE)
```

## Best Practices

### 1. Sample Matching

Ensure comparable cell populations between conditions:

```r
# Check cluster proportions
table(ctrl_result$annotation$cluster)
table(treat_result$annotation$cluster)
```

### 2. Multiple Testing Consideration

For large-scale analyses, consider adjusting for multiple testing:

```r
# Example: Bonferroni correction
n_tests <- nrow(diff_result$changed_edges)
alpha_adjusted <- 0.05 / n_tests
```

### 3. Biological Validation

Prioritize edges for validation based on:
- High absolute log2fc
- High specificity scores
- Known biological relevance

## Session Info

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

## Author

**Zaoqu Liu**

- Email: liuzaoqu@163.com
- GitHub: [Zaoqu-Liu](https://github.com/Zaoqu-Liu)