---
title: "Getting Started with NOVA"
author: "Zaoqu Liu"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 3
vignette: >
  %\VignetteIndexEntry{Getting Started with NOVA}
  %\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

**NOVA** (Network Of Versatile cell-cell communication Analysis) is a high-performance R package designed for inferring and visualizing ligand-receptor mediated cell-to-cell communication networks from single-cell and bulk transcriptomic data.

### Key Features

- **Comprehensive LR Database**: Utilizes connectomeDB2020 with 2,293 literature-curated ligand-receptor pairs
- **Specificity-weighted Scoring**: Identifies biologically relevant communication signals
- **Multi-species Support**: 21 species via NCBI HomoloGene orthology mapping
- **Seurat Integration**: Native support for Seurat V4 and V5 objects
- **High Performance**: Vectorized operations with C++ acceleration
- **Rich Visualization**: Heatmaps, networks, chord diagrams, and more

## Installation

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

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

## Quick Start

### Loading the Package

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

### Simulating Example Data

For demonstration, we'll create simulated single-cell expression data:
```{r simulate}
set.seed(42)

# Create expression matrix (genes x cells)
n_genes <- 500
n_cells <- 300
gene_names <- paste0("Gene", 1:n_genes)
cell_names <- paste0("Cell", 1:n_cells)

# Simulate sparse expression
expr <- matrix(0, nrow = n_genes, ncol = n_cells,
               dimnames = list(gene_names, cell_names))

# Add expression for ~30% of entries
expressed <- sample(length(expr), size = length(expr) * 0.3)
expr[expressed] <- abs(rnorm(length(expressed), mean = 2, sd = 1))

# Convert to sparse matrix for efficiency
expr <- Matrix::Matrix(expr, sparse = TRUE)

# Create cluster annotation
clusters <- sample(c("T_cells", "B_cells", "Macrophages", "Fibroblasts"), 
                   n_cells, replace = TRUE)
names(clusters) <- cell_names
annotation <- data.frame(cell = cell_names, cluster = clusters)
```

### Loading LR Database

```{r lr_database}
# Load the curated ligand-receptor database
lr_db <- GetLRDatabase("lrc2p")
head(lr_db)
cat("Total LR pairs:", nrow(lr_db), "\n")
```

### Running NOVA Analysis

```{r extract, eval=FALSE}
# Note: In real analysis, use actual gene symbols that match the LR database
# Here we simulate matching genes for demonstration
ligands <- unique(lr_db$ligand)[1:20]
receptors <- unique(lr_db$receptor)[1:20]
rownames(expr)[1:20] <- ligands
rownames(expr)[21:40] <- receptors

# Run NOVA
result <- ExtractEdges(
  expression = expr,
  annotation = annotation,
  species = "human",
  database = "lrc2p",
  min_pct = 0.1
)

# View results
print(result)
```

### Exploring Results

```{r results, eval=FALSE}
# Summary statistics
summary(result)

# Get edges for specific cluster pair
edges_subset <- GetEdges(result, 
                          sending = "T_cells", 
                          target = "Macrophages")
head(edges_subset)
```

## Working with Seurat Objects

NOVA seamlessly integrates with Seurat:

```{r seurat, eval=FALSE}
# Convert Seurat object to NOVA input
nova_input <- SeuratToNOVA(
  seurat_obj,
  assay = "RNA",
  slot = "data",
  cluster_col = "cell_type"
)

# Run analysis
result <- ExtractEdges(
  expression = nova_input$expression,
  annotation = nova_input$annotation,
  species = "mouse"
)

# Store results back in Seurat object
seurat_obj <- AddNOVAResults(seurat_obj, result)
```

## Basic Visualization

### Communication Heatmap

```{r heatmap, eval=FALSE}
# Create heatmap of communication strength
PlotHeatmap(result, metric = "count")
PlotHeatmap(result, metric = "specificity")
```

### Network Graph

```{r network, eval=FALSE}
# Network visualization
PlotNetwork(result, layout = "circle")
```

## Session Info

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

## Author

**Zaoqu Liu**

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

## Citation

If you use NOVA in your research, please cite:

> Liu, Z. (2026). NOVA: Network Of Versatile Cell-Cell Communication Analysis. 
> R package version 1.0.0. https://github.com/Zaoqu-Liu/NOVA