---
title: "Introduction to fastCNV"
author: "Zaoqu Liu"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to fastCNV}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 5,
  eval = FALSE
)
```

## Overview

**fastCNV** is an R package developed for efficient and accurate inference of Copy Number Variations (CNVs) from single-cell RNA sequencing (scRNA-seq) and spatial transcriptomics data. It provides a comprehensive framework for:

- Detecting chromosomal amplifications and deletions
- Identifying tumor subclones based on CNV profiles
- Reconstructing clonal phylogenetic trees
- Generating publication-ready visualizations

### Example Output: CNV Heatmap

```{r cnv-heatmap-example, echo=FALSE, eval=TRUE, out.width="100%", fig.cap="CNV heatmap showing chromosomal alterations across cells. Blue indicates deletions, red indicates amplifications."}
knitr::include_graphics("figures/cnv_heatmap.png")
```

### Key Features

| Feature | Description |
|---------|-------------|
| **High Performance** | Optimized for large datasets (>100,000 cells) |
| **Multi-Platform** | Supports scRNA-seq, Visium, and Visium HD |
| **Reference-Based** | Uses normal cells for robust normalization |
| **Seurat Integration** | Seamless workflow with Seurat 4.x/5.x |

## Installation

### From R-universe (Recommended)

```{r install-runiverse}
install.packages("fastCNV", repos = "https://zaoqu-liu.r-universe.dev")
```

### From GitHub

```{r install-github}
if (!requireNamespace("remotes", quietly = TRUE)) {
  install.packages("remotes")
}
remotes::install_github("Zaoqu-Liu/fastCNV")
```

## Quick Start

### Basic Workflow

The main function `fastCNV()` provides an all-in-one workflow:

```{r basic-workflow}
library(fastCNV)

# Load your Seurat object
# seurat_obj <- readRDS("your_seurat_object.rds")

# Run CNV analysis
result <- fastCNV(
  seuratObj = seurat_obj,
  sampleName = "Sample1",
  referenceVar = "cell_type",
  referenceLabel = c("Normal_epithelial", "Fibroblast"),
  prepareCounts = TRUE,
  getCNVPerChromosomeArm = TRUE,
  getCNVClusters = TRUE,
  doPlot = TRUE
)
```

### Understanding the Parameters

| Parameter | Description | Default |
|-----------|-------------|---------|
| `seuratObj` | Seurat object or list of Seurat objects | Required |
| `sampleName` | Sample identifier(s) | Required |
| `referenceVar` | Metadata column for cell type annotation | Required |
| `referenceLabel` | Cell types to use as reference | Required |
| `windowSize` | Number of genes per sliding window | 150 |
| `topNGenes` | Top expressed genes to consider | 7000 |
| `prepareCounts` | Aggregate counts (for spatial data) | TRUE |
| `aggregFactor` | Aggregation factor for spatial data | 10 |

### Examining Results

After running `fastCNV()`, the results are stored in the Seurat object's metadata:

```{r examine-results}
# Check CNV clusters
table(result$cnv_clusters)

# View CNV scores
head(result@assays$CNVScores)

# Access chromosome arm-level CNVs
head(result$cnv_per_arm)
```

### Example Output: Single Cell CNV Profile

```{r cnv-profile-example, echo=FALSE, eval=TRUE, out.width="100%", fig.cap="CNV profile for a single cell showing chr7 gain and chr10 loss."}
knitr::include_graphics("figures/cnv_profile.png")
```

## Supported Data Types

### Single-Cell RNA-seq

```{r scrna}
result <- fastCNV(
  seuratObj = scrna_seurat,
  sampleName = "scRNA_sample",
  referenceVar = "celltype",
  referenceLabel = c("T_cells", "B_cells"),
  prepareCounts = FALSE  # No aggregation needed
)
```

### 10X Visium

```{r visium}
result <- fastCNV(
  seuratObj = visium_seurat,
  sampleName = "Visium_sample",
  referenceVar = "region",
  referenceLabel = c("Normal_tissue"),
  prepareCounts = TRUE,
  aggregFactor = 10
)
```

### 10X Visium HD

```{r visium-hd}
result <- fastCNV_10XHD(
  seuratObjHD = visium_hd_seurat,
  sampleName = "VisiumHD_sample",
  referenceVar = "region",
  referenceLabel = c("Normal_tissue"),
  doPlot = TRUE
)
```

## Next Steps

- See the [Algorithm Methodology](algorithm.html) vignette for detailed explanations
- Explore [Advanced Visualization](visualization.html) options
- Learn about [Multi-Sample Analysis](multi-sample.html) workflows

## Session Info

```{r session-info, eval=TRUE}
sessionInfo()
```

## Citation

If you use fastCNV in your research, please cite:

> Cabrejas G, Groeneveld C, et al. **fastCNV: Fast and accurate inference of copy number variations from single-cell RNA sequencing data.** *bioRxiv* 2025.

## Contact

**Maintainer**: Zaoqu Liu ([liuzaoqu@163.com](mailto:liuzaoqu@163.com))

**GitHub**: [https://github.com/Zaoqu-Liu/fastCNV](https://github.com/Zaoqu-Liu/fastCNV)