RaCInG

RaCInG (Random Cell-cell Interaction Generator) reconstructs patient-specific cell-cell communication networks from bulk RNA-seq data and extracts network-level features using either a kernel-based or Monte Carlo workflow.

This package is the R implementation of the original RaCInG Python framework, as described in van Santvoort et al. (2025), repackaged for seamless integration with R/Bioconductor analysis pipelines. It is additionally coupled with multideconv for deconvolution and cell-type subgroup identification, and with OmnipathR/liana for ligand-receptor prior knowledge.

Installation

Install from GitHub

# install.packages("remotes")
remotes::install_github("VeraPancaldiLab/RaCInG_package")
library(RaCInG)

Install from a local clone

# install.packages("devtools")
devtools::install(".")

Optional preprocessing dependencies

If you want to start directly from raw counts with prepare_input_files(), install the optional helper packages used during deconvolution and prior-network construction:

install.packages(c("ggplot2", "nnls"))
# ADImpute and OmnipathR are available from Bioconductor:
BiocManager::install(c("ADImpute", "OmnipathR"))
# liana and multideconv are GitHub-only:
remotes::install_github(c("saezlab/liana", "VeraPancaldiLab/multideconv"))

Workflow at a glance

Goal	Function	Output
Build input matrices from raw counts	prepare_input_files()	Named list with L, R, C, LR matrices and labels
Compute direct communication (deterministic)	compute_racing_kernel()	Kernel arrays + feature matrix
Compute direct communication and/or GSCC by simulation	compute_racing_montecarlo()	Per-patient mean and sd across simulated graphs
Decompose a direct score into ligand-receptor pairs	computeLRContributions() + plotLRContributions()	Ranked contributions and a dot plot
Compare patient groups	wilcox_group_test() + top_features_plot()	Statistics table and ranked bar plot
Relate features to a continuous score	correlate_features_with_score() + correlation_plot()	Correlation table and rainfall plot

Quick start

Try the workflow on the bundled, pre-processed melanoma example (no optional dependencies needed):

library(RaCInG)
data(skcm_example)

kernel_res <- compute_racing_kernel(input_data = skcm_example)
head(kernel_res$features)

# Which ligand-receptor pairs drive Tumor <-> CD8+ T communication?
lr <- computeLRContributions(
  Lmatrix = skcm_example$Lmatrix, Rmatrix = skcm_example$Rmatrix,
  Cmatrix = skcm_example$Cmatrix, LRmatrix = skcm_example$LRmatrix,
  celltypes = skcm_example$celltypes, sender = "Tumor", receiver = "CD8+ T"
)
plotLRContributions(lr, top_n = 10)

Or start from your own raw counts:

# Build input matrices from a real bulk RNA-seq counts matrix
# (bundled with the optional `multideconv` dependency)
data(raw_counts, package = "multideconv")
counts_matrix <- as.matrix(raw_counts)

input <- prepare_input_files(
  counts = counts_matrix,
  output_folder = "Results/",
  file_name = "example"
)

# Run kernel method (from raw counts)
kernel_res <- compute_racing_kernel(
  counts = counts_matrix,
  file_name = "example",
  output_folder = tempdir(),
  communication_type = "D"
)

# Or pass pre-computed inputs to skip preprocessing
kernel_res <- compute_racing_kernel(
  input_data = input,
  communication_type = "D"
)

# Monte Carlo method
mc_res <- compute_racing_montecarlo(
  input_data = input,
  file_name = "example",
  output_folder = tempdir(),
  communication_type = c("D", "GSCC"),
  Ncells = 100,
  Ngraphs = 10,
  Ndegree = 3
)

# Compare clinical groups: one label per patient (replace with your own annotation)
grouping <- rep(c("Responder", "Non-responder"), length.out = nrow(kernel_res$features))
wilcox_results <- wilcox_group_test(kernel_res$features, grouping)
top_features_plot(wilcox_results)

The kernel method computes direct communication ("D"). The Monte Carlo method computes direct communication and/or the giant strongly connected component ("GSCC"); requesting both (c("D", "GSCC")) extracts them from the same simulated graphs in one call. compute_racing_montecarlo() additionally takes ncores to parallelize independent patients across cores.

Documentation

• 📘 Vignette: Getting started with RaCInG
• 🌐 Website: https://VeraPancaldiLab.github.io/RaCInG_package/
• 🐍 Original Python implementation: https://github.com/SysBioOncology/RaCInG

Citation

If you use this package, please cite the RaCInG publication:

van Santvoort M, Lapuente-Santana Ó, Zopoglou M, Zackl C, Finotello F, van der Hoorn P & Eduati F (2025). Mathematically mapping the network of cells in the tumor microenvironment. Cell Reports Methods, 5(2), 100985.

R Package Development

This R package implementation was developed by Marcelo Hurtado from the Pancaldi team, led by Vera Pancaldi. Marcelo is currently the primary maintainer of the package.