Quick Start Guide

Introduction

CellProgramMapper maps single-cell RNA sequencing data to reference gene expression programs (GEPs) using non-negative matrix factorization. This guide demonstrates the essential workflow in 5 minutes.

Installation

# From R-universe (recommended)
install.packages("CellProgramMapper", 
                 repos = "https://zaoqu-liu.r-universe.dev")

# Or from GitHub
devtools::install_github("Zaoqu-Liu/CellProgramMapper")

Quick Example

library(CellProgramMapper)

# Map a Seurat object to T-cell reference
result <- CellProgramMapper(
  query = seurat_obj,
  reference = "TCAT.V1"
)

# View results
print(result)

# Get usage matrix
usage <- get_usage(result, normalized = TRUE)

# Add to Seurat object
seurat_obj <- add_results_to_seurat(seurat_obj, result)

Available References

library(CellProgramMapper)

refs <- available_references()
print(refs[, c("Name", "Cell_Type", "Species")])
#>                         Name Cell_Type      Species
#> 1                    TCAT.V1   T-cells Homo sapiens
#> 2          MYELOID.GLIOMA.V1   Myeloid Homo sapiens
#> 3 BONEMARROW.CD34POS.HSPC.V1       HSC Homo sapiens

Input Formats

CellProgramMapper accepts multiple input types:

# 1. Seurat object (V4 or V5)
result <- CellProgramMapper(query = seurat_obj, reference = "TCAT.V1")

# 2. Matrix (cells × genes)
result <- CellProgramMapper(query = counts_matrix, reference = "TCAT.V1")

# 3. File path (h5ad, mtx)
result <- CellProgramMapper(query = "data.h5ad", reference = "TCAT.V1")

Working with Results

Access Usage Matrix

# Normalized (rows sum to 1)
usage_norm <- get_usage(result, normalized = TRUE)

# Raw
usage_raw <- get_usage(result, normalized = FALSE)

Access Scores

# Get computed scores
scores <- get_scores(result)

Save Results

save_results(result, output_dir = "./output", prefix = "my_analysis")

Demonstration with Simulated Data

set.seed(42)

# Simulate reference (5 programs × 100 genes)
H <- matrix(runif(5 * 100, 0, 1), nrow = 5)
colnames(H) <- paste0("Gene", 1:100)
rownames(H) <- paste0("GEP", 1:5)

# Simulate query (50 cells × 100 genes)
W_true <- matrix(runif(50 * 5, 0, 1), nrow = 50)
X <- W_true %*% H + matrix(rnorm(50 * 100, 0, 0.1), nrow = 50)
X[X < 0] <- 0
colnames(X) <- paste0("Gene", 1:100)
rownames(X) <- paste0("Cell", 1:50)

# Run CellProgramMapper
result <- CellProgramMapper(
  query = X,
  reference = H,
  verbose = FALSE
)
#> Warning: Query data does not appear to be integer counts. For best results,
#> provide raw UMI/read counts.

# Visualize
usage <- get_usage(result, normalized = TRUE)
usage_mat <- as.matrix(usage)

par(mfrow = c(1, 2), mar = c(4, 4, 2, 1))

# Heatmap
image(t(usage_mat), col = colorRampPalette(c("white", "#08306b"))(100),
      xlab = "Programs", ylab = "Cells", main = "Usage Matrix",
      axes = FALSE)
axis(1, at = seq(0, 1, length.out = 5), labels = colnames(usage_mat))

# Bar plot for first cell
barplot(as.numeric(usage[1, ]), col = "#1976d2", 
        names.arg = colnames(usage),
        main = paste("Cell1 Usage"),
        xlab = "GEP", ylab = "Usage")
Simulated GEP usage visualization

Simulated GEP usage visualization

Performance Tips

# For large datasets, use parallel processing
result <- CellProgramMapper(
  query = seurat_obj,
  reference = "TCAT.V1",
  n_workers = 4
)

# Data is automatically batched for memory efficiency

Next Steps

Session Info

sessionInfo()
#> R version 4.6.1 (2026-06-24)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 26.04 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.32.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] pheatmap_1.0.13         CellProgramMapper_1.0.0 rmarkdown_2.31         
#> 
#> loaded via a namespace (and not attached):
#>  [1] Matrix_1.7-5        gtable_0.3.6        future.apply_1.20.2
#>  [4] jsonlite_2.0.0      compiler_4.6.1      Rcpp_1.1.1-1.1     
#>  [7] parallel_4.6.1      jquerylib_0.1.4     globals_0.19.1     
#> [10] scales_1.4.0        yaml_2.3.12         fastmap_1.2.0      
#> [13] lattice_0.22-9      R6_2.6.1            curl_7.1.0         
#> [16] knitr_1.51          future_1.70.0       maketools_1.3.2    
#> [19] bslib_0.11.0        RColorBrewer_1.1-3  rlang_1.2.0        
#> [22] cachem_1.1.0        xfun_0.59           sass_0.4.10        
#> [25] sys_3.4.3           otel_0.2.0          cli_3.6.6          
#> [28] digest_0.6.39       grid_4.6.1          rappdirs_0.3.4     
#> [31] lifecycle_1.0.5     evaluate_1.0.5      glue_1.8.1         
#> [34] data.table_1.18.4   farver_2.1.2        listenv_1.0.0      
#> [37] codetools_0.2-20    buildtools_1.0.0    parallelly_1.48.0  
#> [40] tools_4.6.1         htmltools_0.5.9