Getting Started with FastCCCR

Introduction

FastCCCR is a high-performance R package developed by Zaoqu Liu for cell-cell communication (CCC) analysis in single-cell RNA sequencing data. This vignette provides a comprehensive guide to get started with FastCCCR.

Why FastCCCR?

Traditional CCC analysis methods face several challenges:

Computational inefficiency: Permutation-based p-value computation is time-consuming
Method variability: Different scoring methods yield inconsistent results
Limited scalability: Difficult to apply to large-scale atlas data

FastCCCR addresses these challenges through:

Exact null distribution computation via FFT convolution
Cauchy combination of multiple statistical methods
Reference-based inference for rapid query analysis

Installation

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

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

Quick Example

Loading the Package

library(FastCCCR)
library(data.table)

Understanding the Data Structure

FastCCCR works with Seurat objects. The key requirements are:

Normalized expression data in the data slot
Cell type annotations in the metadata

Simulated Data Demo

Let’s demonstrate the core functionality with a simulated example:

# Create simulated expression data
set.seed(42)
n_cells <- 100
n_genes <- 50

# Simulate normalized expression
expr_mat <- matrix(
  rlnorm(n_cells * n_genes, meanlog = 0, sdlog = 1),
  nrow = n_genes,
  ncol = n_cells
)
rownames(expr_mat) <- paste0("Gene", 1:n_genes)
colnames(expr_mat) <- paste0("Cell", 1:n_cells)

# Simulate cell types
cell_types <- sample(c("TypeA", "TypeB", "TypeC"), n_cells, replace = TRUE)

# Create data.tables for demonstration
counts_dt <- as.data.table(t(expr_mat))
counts_dt[, barcode := colnames(expr_mat)]
setkey(counts_dt, barcode)

labels_dt <- data.table(
  barcode = colnames(expr_mat),
  cell_type = cell_types
)
setkey(labels_dt, barcode)

Core Distribution Operations

FastCCCR uses a sophisticated Distribution class for exact statistical inference:

# Create a normal distribution
d1 <- Distribution$new(dtype = "normal", loc = 10, scale = 2)
d2 <- Distribution$new(dtype = "normal", loc = 15, scale = 3)

# Addition: Sum of two independent random variables
d_sum <- d1$add(d2)
cat("Sum: Mean =", d_sum$get_mean(), ", SD =", d_sum$get_std(), "\n")
#> Sum: Mean = 25 , SD = 3.605551

# Power: Sum of n i.i.d. copies
d_pow <- d1$power(5L)
cat("Power(5): Mean =", d_pow$get_mean(), ", SD =", d_pow$get_std(), "\n")
#> Power(5): Mean = 50 , SD = 4.472136

# Divide: Average of n i.i.d. copies
d_avg <- d_pow$divide(5L)
cat("Average: Mean =", d_avg$get_mean(), ", SD =", d_avg$get_std(), "\n")
#> Average: Mean = 10 , SD = 0.8944272

P-value Computation

# Compute p-value for an observed value
d_null <- Distribution$new(dtype = "normal", loc = 0, scale = 1)

test_values <- c(0, 1.96, 2.58, 3.0)
for (v in test_values) {
  pval <- get_pvalue(v, d_null)
  cat(sprintf("P(Z > %.2f) = %.4f\n", v, pval))
}
#> P(Z > 0.00) = 0.5000
#> P(Z > 1.96) = 0.0250
#> P(Z > 2.58) = 0.0049
#> P(Z > 3.00) = 0.0013

Cauchy Combination Example

# Simulate p-values from multiple methods
pval1 <- data.table(pair = c("A|B", "A|C"), int1 = c(0.02, 0.15))
pval2 <- data.table(pair = c("A|B", "A|C"), int1 = c(0.05, 0.08))
pval3 <- data.table(pair = c("A|B", "A|C"), int1 = c(0.01, 0.20))

# Combine using Cauchy distribution
combined <- cauchy_combine(list(pval1, pval2, pval3))
print(combined)
#> Key: <pair>
#>      pair       int1
#>    <char>      <num>
#> 1:    A|B 0.01765632
#> 2:    A|C 0.12513852

Workflow Overview

The complete FastCCCR workflow consists of the following steps:

┌─────────────────────────────────────────────────────────────┐
│                    FastCCCR Workflow                        │
├─────────────────────────────────────────────────────────────┤
│  1. Data Preprocessing                                       │
│     └── Extract expression & cell type labels               │
│                                                             │
│  2. Single-Unit Summary                                     │
│     └── Mean / Median / Quantile per cluster                │
│                                                             │
│  3. Complex Aggregation                                     │
│     └── Minimum / Average for protein complexes             │
│                                                             │
│  4. L-R Combination                                         │
│     └── Arithmetic / Geometric mean                         │
│                                                             │
│  5. Null Distribution                                       │
│     └── FFT convolution of single-cell PMFs                 │
│                                                             │
│  6. P-value Computation                                     │
│     └── Compare observed vs null distribution               │
│                                                             │
│  7. Cauchy Combination (optional)                           │
│     └── Combine multiple method results                     │
└─────────────────────────────────────────────────────────────┘

Supported Databases

FastCCCR provides native support for multiple ligand-receptor databases:

Database	Version	Description
CellPhoneDB	v4.1.0, v5.0.0	Curated human L-R interactions
CellChat	v1.6.1	Human and mouse interactions
NicheNet	v1.1.1, v2.1.5	Ligand-target gene relationships

Next Steps

Algorithm Details: Learn the mathematical foundations in the Algorithm vignette
Reference-Based Inference: Build and use reference panels in the Reference vignette
Visualization: Explore plotting options in the Visualization vignette

Session Information

sessionInfo()
#> R version 4.4.0 (2024-04-24)
#> Platform: aarch64-apple-darwin20
#> Running under: macOS 15.6.1
#> 
#> Matrix products: default
#> BLAS:   /Library/Frameworks/R.framework/Versions/4.4-arm64/Resources/lib/libRblas.0.dylib 
#> LAPACK: /Library/Frameworks/R.framework/Versions/4.4-arm64/Resources/lib/libRlapack.dylib;  LAPACK version 3.12.0
#> 
#> locale:
#> [1] C
#> 
#> time zone: Asia/Shanghai
#> tzcode source: internal
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] data.table_1.18.0 FastCCCR_1.0.0   
#> 
#> loaded via a namespace (and not attached):
#>  [1] cli_3.6.5         knitr_1.51        rlang_1.1.7       xfun_0.56        
#>  [5] otel_0.2.0        textshaping_1.0.4 jsonlite_2.0.0    listenv_0.10.0   
#>  [9] htmltools_0.5.9   ragg_1.5.0        sass_0.4.10       rmarkdown_2.30   
#> [13] grid_4.4.0        evaluate_1.0.5    jquerylib_0.1.4   fastmap_1.2.0    
#> [17] yaml_2.3.12       lifecycle_1.0.5   compiler_4.4.0    codetools_0.2-20 
#> [21] fs_1.6.6          Rcpp_1.1.1        htmlwidgets_1.6.4 future_1.69.0    
#> [25] lattice_0.22-7    systemfonts_1.3.1 digest_0.6.39     R6_2.6.1         
#> [29] parallelly_1.46.1 parallel_4.4.0    bslib_0.9.0       Matrix_1.7-4     
#> [33] tools_4.4.0       globals_0.18.0    pkgdown_2.1.3     cachem_1.1.0     
#> [37] desc_1.4.3

Citation

If you use FastCCCR in your research, please cite:

Liu, Z. (2026). FastCCCR: Fast Cell-Cell Communication Analysis with Statistical Framework. https://github.com/Zaoqu-Liu/FastCCCR

Contact

Author: Zaoqu Liu
Email: liuzaoqu@163.com
GitHub: https://github.com/Zaoqu-Liu

Zaoqu Liu

2026-01-26