Oracle Class for In Silico Gene Perturbation Analysis

Oracle is the main class in CellOracleR. It imports scRNA-seq data (Seurat object) and TF information to infer cluster-specific GRNs. It can predict future gene expression patterns and cell state transitions in response to TF perturbations.

Details

The Oracle class stores:

• Seurat object with scRNA-seq data

• TF-target gene regulatory information (TFdict)

• GRN coefficients for simulation

• Perturbation simulation results

Public fields

seurat

Seurat object containing scRNA-seq data

cluster_column

Column name in metadata containing cluster information

embedding_name

Name of dimensional reduction to use (e.g., "umap")

TFdict

Named list: key = target gene, value = vector of regulator TFs

all_target_genes

All target genes in TFdict

all_regulatory_genes

All regulatory genes in TFdict

active_regulatory_genes

Regulatory genes with active connections in GRN

high_var_genes

High variability genes

pcs

PCA results

pca

PCA model

k_knn_imputation

K used for KNN imputation

knn

KNN graph

knn_smoothing_w

KNN smoothing weights

GRN_unit

GRN calculation unit: "cluster" or "whole"

alpha_for_simulation

Regularization strength used for GRN

coef_matrix

Coefficient matrix (for GRN_unit="whole")

coef_matrix_per_cluster

List of coefficient matrices per cluster

perturb_condition

Current perturbation condition

embedding

Embedding coordinates

delta_embedding

Simulated embedding shifts

delta_embedding_random

Randomized embedding shifts (control)

transition_prob

Transition probability matrix

transition_prob_random

Random transition probability (control)

corrcoef

Correlation coefficients

corrcoef_random

Random correlation coefficients (control)

flow_grid

Grid coordinates for flow visualization

flow

Flow vectors on grid

flow_norm

Normalized flow vectors

total_p_mass

Probability mass at each grid point

mass_filter

Mass filter for visualization

colorandum

Cell colors based on cluster

Methods

Public methods

• Oracle$new()

• Oracle$import_TF_data()

• Oracle$perform_PCA()

• Oracle$knn_imputation()

• Oracle$fit_GRN_for_simulation()

• Oracle$simulate_shift()

• Oracle$estimate_transition_prob()

• Oracle$calculate_embedding_shift()

• Oracle$calculate_grid_arrows()

• Oracle$calculate_mass_filter()

• Oracle$get_links()

• Oracle$save()

• Oracle$copy()

• Oracle$print()

• Oracle$clone()

---

Method new()

Create a new Oracle object

Usage

Oracle$new(
  seurat = NULL,
  cluster_column = NULL,
  embedding_name = NULL,
  verbose = TRUE
)

Arguments

seurat

Seurat object with scRNA-seq data (normalized, not scaled)

cluster_column

Column name containing cluster assignments

embedding_name

Name of dimensional reduction (e.g., "umap", "tsne")

verbose

Print messages

Returns

A new Oracle object

---

Method import_TF_data()

Import TF-target regulatory data

Usage

Oracle$import_TF_data(
  TFinfo_df = NULL,
  TFinfo_path = NULL,
  TFdict = NULL,
  verbose = TRUE
)

Arguments

TFinfo_df

Data frame with columns: peak_id, gene_short_name, and TF columns

TFinfo_path

Path to parquet file with TF info

TFdict

Named list mapping target genes to regulator TFs

verbose

Print messages

---

Method perform_PCA()

Perform PCA on expression data

Usage

Oracle$perform_PCA(n_components = 50, use_seurat_pca = TRUE)

Arguments

n_components

Number of PCs to compute

use_seurat_pca

Use existing PCA from Seurat object

---

Method knn_imputation()

Perform KNN imputation of expression data

Usage

Oracle$knn_imputation(
  k = NULL,
  n_pca_dims = NULL,
  balanced = FALSE,
  diag_weight = 1
)

Arguments

k

Number of neighbors (default: 2.5% of cells)

n_pca_dims

Number of PCA dimensions to use for KNN

balanced

Use balanced KNN

diag_weight

Weight for self in smoothing

---

Method fit_GRN_for_simulation()

Fit GRN for perturbation simulation

Usage

Oracle$fit_GRN_for_simulation(
  GRN_unit = c("cluster", "whole"),
  alpha = 1,
  verbose_level = 1
)

Arguments

GRN_unit

"cluster" for cluster-specific GRNs or "whole" for one GRN

alpha

Regularization strength for Ridge regression

verbose_level

Verbosity: 0=silent, 1=progress, 2=detailed

---

Method simulate_shift()

Simulate gene perturbation effects

Usage

Oracle$simulate_shift(
  perturb_condition,
  n_propagation = 3,
  GRN_unit = NULL,
  clip_delta_X = FALSE,
  ignore_warning = FALSE
)

Arguments

perturb_condition

Named list: gene name -> expression value

n_propagation

Number of signal propagation steps (1-5)

GRN_unit

Override GRN unit for simulation

clip_delta_X

Clip to original expression range

ignore_warning

Ignore validation warnings

---

Method estimate_transition_prob()

Estimate transition probability

Usage

Oracle$estimate_transition_prob(
  n_neighbors = NULL,
  sigma_corr = 0.05,
  sampled_fraction = 0.3,
  calculate_randomized = TRUE,
  n_jobs = 1,
  random_seed = 123
)

Arguments

n_neighbors

Number of neighbors for KNN

sigma_corr

Correlation kernel bandwidth

sampled_fraction

Fraction of neighbors to sample

calculate_randomized

Calculate randomized control

n_jobs

Number of parallel jobs

random_seed

Random seed

---

Method calculate_embedding_shift()

Calculate embedding shifts from transition probability

Usage

Oracle$calculate_embedding_shift(sigma_corr = 0.05)

Arguments

sigma_corr

Kernel bandwidth (not used, kept for API compatibility)

---

Method calculate_grid_arrows()

Calculate grid arrows for visualization

Usage

Oracle$calculate_grid_arrows(n_grid = 40, n_neighbors = 100, smooth = 0.5)

Arguments

n_grid

Number of grid points per dimension

n_neighbors

Number of neighbors for smoothing

smooth

Smoothing parameter

---

Method calculate_mass_filter()

Calculate mass filter for visualization

Usage

Oracle$calculate_mass_filter(min_mass = 0.01)

Arguments

min_mass

Minimum mass threshold

---

Method get_links()

Get Links object for network analysis

Usage

Oracle$get_links(
  cluster_name_for_GRN_unit = NULL,
  alpha = 10,
  bagging_number = 20,
  verbose_level = 1,
  n_jobs = -1
)

Arguments

cluster_name_for_GRN_unit

Cluster column for GRN unit

alpha

Regularization strength

bagging_number

Number of bagging iterations

verbose_level

Verbosity level

n_jobs

Number of parallel jobs

Returns

Links object

---

Method save()

Save Oracle object to file

Usage

Oracle$save(file_path)

Arguments

file_path

Path to save file (should end with .celloracle.oracle)

---

Method copy()

Deep copy the Oracle object

Usage

Oracle$copy()

Returns

A new Oracle object

---

Method print()

Print Oracle object summary Process TFdict metadata Get imputed expression as data frame Get delta_X from simulation results Store simulation results in Seurat Validate perturbation condition Extract active regulatory genes from coefficient matrix

Usage

Oracle$print()

---

Method clone()

The objects of this class are cloneable with this method.

Usage

Oracle$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.