Skip to contents

CellOracleR

📖 Documentation: https://zaoqu-liu.github.io/CellOracleR/

Overview

CellOracleR is a comprehensive R implementation of the CellOracle framework for in silico gene perturbation analysis in single-cell RNA sequencing data. This package enables systematic prediction of cell state transitions following transcription factor (TF) perturbations by integrating gene regulatory network (GRN) inference with single-cell trajectory analysis.

Scientific Background

Understanding how transcription factors regulate cell fate decisions is fundamental to developmental biology and regenerative medicine. CellOracleR leverages the mathematical framework of GRN-based signal propagation to simulate the transcriptomic consequences of TF knockouts or overexpression, enabling researchers to:

  • Predict perturbation outcomes before conducting experiments
  • Identify key regulators of cell fate transitions
  • Dissect regulatory mechanisms underlying cellular differentiation
  • Prioritize targets for functional validation studies

Methodological Framework

The CellOracleR workflow comprises four interconnected analytical modules:

┌─────────────────────────────────────────────────────────────────────┐
│                        CellOracleR Pipeline                         │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────────────┐  │
│  │   Base GRN   │───▶│ GRN Fitting  │───▶│ Perturbation         │  │
│  │ Construction │    │ (Ridge Reg.) │    │ Simulation           │  │
│  └──────────────┘    └──────────────┘    └──────────────────────┘  │
│        │                    │                      │                │
│        ▼                    ▼                      ▼                │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────────────┐  │
│  │ Motif        │    │ Cluster-     │    │ Transition           │  │
│  │ Scanning     │    │ specific GRN │    │ Probability          │  │
│  └──────────────┘    └──────────────┘    └──────────────────────┘  │
│                                                   │                 │
│                                                   ▼                 │
│                                          ┌──────────────────────┐  │
│                                          │ Cell Fate            │  │
│                                          │ Prediction           │  │
│                                          └──────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘

Installation 

# Install from R-universe
install.packages("CellOracleR", repos = "https://zaoqu-liu.r-universe.dev")

From GitHub 

# Install development version from GitHub
if (!requireNamespace("remotes", quietly = TRUE))
    install.packages("remotes")
remotes::install_github("Zaoqu-Liu/CellOracleR")

System Requirements

  • R ≥ 4.0.0
  • C++ compiler with C++17 support
  • Dependencies: Seurat (V4/V5), glmnet, igraph, Matrix, R6

For motif analysis functionality, Bioconductor packages are required:

if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install(c("TFBSTools", "motifmatchr", "JASPAR2020", 
                       "BSgenome", "GenomicRanges"))

Quick Start

Basic Workflow 

library(CellOracleR)
library(Seurat)

# 1. Create Oracle object from Seurat
oracle <- create_oracle(
    seurat_obj, 
    cluster_column = "cell_type",
    embedding_name = "umap"
)

# 2. Import TF-target gene regulatory information
oracle$import_TF_data(TFdict = tf_target_dictionary)

# 3. Perform dimensionality reduction and imputation
oracle$perform_PCA(n_components = 50)
oracle$knn_imputation(k = 30)

# 4. Fit cluster-specific GRNs for simulation
oracle$fit_GRN_for_simulation(
    GRN_unit = "cluster",
    alpha = 10
)

# 5. Simulate TF knockout
oracle$simulate_shift(
    perturb_condition = list(GATA1 = 0),  # Knockout GATA1
    n_propagation = 3
)

# 6. Estimate transition probabilities and visualize
oracle$estimate_transition_prob()
oracle$calculate_embedding_shift()
oracle$calculate_grid_arrows(n_grid = 40)

# 7. Visualize perturbation effects
plot_simulation_flow(oracle)

Network Analysis 

# Extract GRN as Links object for network analysis
links <- oracle$get_links(
    alpha = 10,
    bagging_number = 200
)

# Filter to significant regulatory edges
links$filter_links(p = 0.001, threshold_number = 2000)

# Compute network centrality metrics
links$get_network_score()

# Identify hub transcription factors
hubs <- identify_hubs(links, top_n = 20, method = "degree")

# Visualize regulatory network
plot_network_graph(links, cluster = "Progenitor")

Key Features

🧬 GRN Inference

  • Ridge regression with L2 regularization for robust coefficient estimation
  • Bootstrap aggregation (bagging) for variance reduction
  • Cluster-specific or whole-dataset GRN fitting
  • Parallel processing via the future framework

📊 Perturbation Simulation

  • Signal propagation through regulatory networks
  • Support for knockouts, overexpression, and partial perturbations
  • Out-of-distribution detection and clipping
  • Efficient C++ backend via RcppArmadillo

🔬 Trajectory Analysis

  • Markov chain simulation of cell state transitions
  • Transition probability estimation from expression shifts
  • Pseudotime computation and fate probability analysis
  • Terminal state identification

📈 Visualization

  • Vector field plots showing predicted cell movements
  • Network graphs with centrality-based layouts
  • Degree distribution analysis
  • Full ggplot2 integration for publication-quality figures

Seurat Compatibility

CellOracleR is designed for seamless integration with the Seurat ecosystem:

Feature Seurat V4 Seurat V5
Data import ✅ ✅
Assay handling ✅ ✅
Layer access ✅ ✅
Reduction extraction ✅ ✅
Metadata integration ✅ ✅

Performance

CellOracleR achieves high computational efficiency through:

  • Vectorized R operations for data manipulation
  • Rcpp/RcppArmadillo for performance-critical functions
  • Sparse matrix support via the Matrix package
  • Parallel computation using the future framework

Typical runtime for a dataset of 10,000 cells × 3,000 genes: - GRN fitting (200 bootstrap iterations): ~5-10 minutes - Perturbation simulation: ~30 seconds - Transition probability estimation: ~1 minute

Citation

If you use CellOracleR in your research, please cite both the original CellOracle paper and this R implementation:

Original CellOracle: > Kamimoto, K., Hoffmann, C.M., & Morris, S.A. (2023). CellOracle: Dissecting cell identity via network inference and in silico gene perturbation. Molecular Systems Biology, 19(5), e11547. https://doi.org/10.15252/msb.202211547

CellOracleR (R implementation): > Liu, Z. (2025). CellOracleR: An R implementation of CellOracle for in silico gene perturbation analysis. GitHub repository, https://github.com/Zaoqu-Liu/CellOracleR

License

CellOracleR is released under the Apache License 2.0.

Contact

Deciphering cell fate through computational perturbation