Introduction to fastCNV

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

CNV heatmap showing chromosomal alterations across cells. Blue indicates deletions, red indicates amplifications.

CNV heatmap showing chromosomal alterations across cells. Blue indicates deletions, red indicates amplifications.

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 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:

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:

# 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

CNV profile for a single cell showing chr7 gain and chr10 loss.

CNV profile for a single cell showing chr7 gain and chr10 loss.

Supported Data Types

Single-Cell RNA-seq

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

10X Visium

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

10X Visium HD

result <- fastCNV_10XHD(
  seuratObjHD = visium_hd_seurat,
  sampleName = "VisiumHD_sample",
  referenceVar = "region",
  referenceLabel = c("Normal_tissue"),
  doPlot = TRUE
)

Next Steps

Session Info

sessionInfo()
#> R version 4.6.0 (2026-04-24)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 24.04.4 LTS
#> 
#> Matrix products: default
#> BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3 
#> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.so;  LAPACK version 3.12.0
#> 
#> locale:
#>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
#>  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8    
#>  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
#>  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
#>  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
#> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
#> 
#> time zone: Etc/UTC
#> tzcode source: system (glibc)
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] rmarkdown_2.31
#> 
#> loaded via a namespace (and not attached):
#>  [1] digest_0.6.39    R6_2.6.1         fastmap_1.2.0    xfun_0.59       
#>  [5] maketools_1.3.2  cachem_1.1.0     knitr_1.51       htmltools_0.5.9 
#>  [9] buildtools_1.0.0 lifecycle_1.0.5  cli_3.6.6        sass_0.4.10     
#> [13] jquerylib_0.1.4  compiler_4.6.0   sys_3.4.3        tools_4.6.0     
#> [17] evaluate_1.0.5   bslib_0.11.0     yaml_2.3.12      otel_0.2.0      
#> [21] jsonlite_2.0.0   rlang_1.2.0

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 ([email protected])

GitHub: https://github.com/Zaoqu-Liu/fastCNV