Package 'CellODE'

Description

CellODE is an R package for single-cell trajectory inference using Variational Autoencoder (VAE) and Neural Ordinary Differential Equations (Neural ODE). The package automatically infers cellular dynamics from single-cell RNA sequencing data, providing:

• Pseudotime estimation

• Latent space representation

• Vector field analysis

• Trajectory visualization

Details

CellODE is designed for seamless integration with Seurat objects (supporting both V4 and V5). The core model (TNODE) combines a VAE for dimensionality reduction with a Neural ODE for modeling continuous cellular dynamics.

The main workflow involves:

1. Creating a Trainer object with your Seurat data

2. Training the model using trainer$train()

3. Extracting pseudotime using trainer$get_time()

4. Getting latent representations using trainer$get_latentsp()

5. Visualizing results with plot_pseudotime() and plot_vector_field()

Author(s)

Zaoqu Liu [email protected]

References

Li, S. et al. (2023). scTour: A deep learning architecture for robust inference and accurate prediction of cellular dynamics. bioRxiv. https://doi.org/10.1101/2023.01.13.523988

See Also

Useful links:

• https://zaoqu-liu.github.io/CellODE/

• https://github.com/Zaoqu-Liu/CellODE

• Report bugs at https://github.com/Zaoqu-Liu/CellODE/issues

Description

Calculate cosine similarity between vector field and cell-neighbor latent state difference. This function matches scTour's cosine_similarity exactly. The calculation borrows the ideas from scvelo.

Uses optimized C++ implementation for performance on large datasets.

Usage

cosine_similarity(
  zs,
  vf,
  reverse = FALSE,
  n_neigh = 20,
  t = NULL,
  var_transform = FALSE,
  neighbor_indices = NULL
)

Arguments

Value

Sparse matrix of cosine similarities

Description

Functions for data preparation and handling

Description

Extract expression matrix from Seurat object, supporting both V4 and V5.

Usage

extract_expression(seurat_obj, assay = "RNA", slot = "counts")

Arguments

Value

Dense matrix (cells x genes)

Description

Calculate L2 norm along specified axis. Handles both dense and sparse matrices.

Usage

l2_norm(x, axis = -1)

Arguments

Value

Vector of L2 norms

Description

Load a trained CellODE model from file.

Usage

load_model(path, seurat_obj)

Arguments

Value

Trainer object with loaded model

Description

Calculate log probability under negative binomial distribution. Adapted from scvi-tools.

Usage

log_nb(x, mu, theta, eps = 1e-08)

Arguments

Value

Tensor of log probabilities

References

Gayoso et al. scvi-tools. https://github.com/YosefLab/scvi-tools

Description

Calculate log probability under zero-inflated negative binomial. Adapted from scvi-tools.

Usage

log_zinb(x, mu, theta, pi, eps = 1e-08)

Arguments

Value

Tensor of log probabilities

References

Gayoso et al. scvi-tools. https://github.com/YosefLab/scvi-tools

Description

Create a torch dataset from expression matrix.

Usage

MakeDataset(X, loss_mode = "nb")

Arguments

Value

torch::dataset object

Description

VAE components and Latent ODE function using torch nn_module

Description

Calculate KL divergence between two normal distributions. This is the standard formulation from torchdiffeq.

Usage

normal_kl(mu1, lv1, mu2, lv2)

Arguments

Value

Tensor of KL divergence values

References

RTQichen. torchdiffeq. https://github.com/rtqichen/torchdiffeq

Description

ODE solvers with support for gradient computation

Description

Solve ODE forward in time. This is the main integration function that matches scTour's odeint behavior.

Usage

odeint(func, z0, t, method = "euler", options = list())

Arguments

Value

Tensor of states at each time point (n_times x n_latent)

Examples

## Not run: 
states <- odeint(ode_func, z0, t, method = "euler")

## End(Not run)

Description

Visualize training and validation loss curves from CellODE training.

Usage

plot_loss(
  trainer,
  smooth = FALSE,
  title = "Training Progress",
  colors = c(Training = "#2E86AB", Validation = "#E94F37")
)

Arguments

Value

ggplot2 object

Examples

## Not run: 
plot_loss(trainer)

## End(Not run)

Description

Visualize pseudotime trajectory with direction arrows computed using grid-based vector field algorithm. Colors cells by pseudotime gradient and overlays arrows showing developmental direction.

Usage

plot_pseudotime(
  seurat_obj,
  time_key = "pseudotime",
  embedding_key = "umap",
  dims = c(1, 2),
  point_size = 0.8,
  point_palette = "Spectral",
  point_palcolor = NULL,
  point_alpha = 0.8,
  arrow_show = TRUE,
  arrow_density = 1.5,
  arrow_length = 0.12,
  arrow_width = 0.6,
  arrow_color = "grey20",
  arrow_angle = 25,
  arrow_type = c("open", "closed"),
  show_axes = TRUE,
  aspect_ratio = 1,
  title = "Pseudotime",
  subtitle = NULL,
  xlab = NULL,
  ylab = NULL,
  legend_position = "right",
  return_layer = FALSE,
  seed = 11
)

Arguments

Value

ggplot2 object or list of layers

Examples

## Not run: 
# Basic pseudotime visualization
plot_pseudotime(seurat_obj, time_key = "pseudotime")

# Custom styling
plot_pseudotime(seurat_obj, point_palette = "viridis",
                arrow_color = "darkred", arrow_density = 0.5)

## End(Not run)

Description

Visualize cellular dynamics vector field on 2D embedding using distance-weighted directional arrows. Computes direction vectors at grid centers by combining distance-based weights and pseudotime gradients from the latent space dynamics. Supports three rendering modes: raw (per-cell arrows), grid (smoothed arrows), and stream (streamlines for flow visualization).

Usage

plot_vector_field(
  seurat_obj,
  zs_key = "X_zs",
  vf_key = "X_VF",
  embedding_key = "umap",
  t_key = NULL,
  plot_type = c("grid", "raw", "stream"),
  reverse = FALSE,
  n_neigh = 20,
  var_transform = FALSE,
  scale = 10,
  self_transition = FALSE,
  point_size = 0.5,
  point_palette = "Spectral",
  point_palcolor = NULL,
  point_alpha = 0.8,
  arrow_density = 0.5,
  arrow_length = 0.15,
  arrow_width = 0.6,
  arrow_color = "grey20",
  arrow_angle = 25,
  arrow_head_size = 50,
  arrow_type = c("open", "closed"),
  smooth = 0.5,
  grid_density = 1,
  min_mass = 1,
  stream_n = 15,
  stream_L = 5,
  stream_color = NULL,
  stream_width = c(0.2, 0.8),
  color_by = NULL,
  show_axes = TRUE,
  aspect_ratio = 1,
  title = "Vector Field",
  subtitle = NULL,
  xlab = NULL,
  ylab = NULL,
  legend_position = "right",
  return_layer = FALSE,
  seed = 11
)

Arguments

Value

ggplot2 object or list of layers if return_layer = TRUE

Examples

## Not run: 
# Basic usage after CellODE training
plot_vector_field(seurat_obj, plot_type = "grid")

# Raw mode with custom colors
plot_vector_field(seurat_obj, plot_type = "raw",
                  arrow_color = "darkred", arrow_density = 0.3)

# Color points by pseudotime
plot_vector_field(seurat_obj, color_by = "pseudotime",
                  point_palette = "viridis")

## End(Not run)

Description

High-quality visualization for pseudotime and vector field

Author(s)

Zaoqu Liu

Description

Functions for predicting pseudotime, latent space, and vector field

Description

Predict latent representations for query cells.

Usage

predict_latentsp(
  trainer,
  query_seurat,
  mode = "fine",
  alpha_z = 0.5,
  alpha_predz = 0.5,
  step_size = NULL,
  step_wise = FALSE,
  batch_size = NULL,
  assay = "RNA"
)

Arguments

Value

List with mix_zs, zs, pred_zs matrices

Description

Predict latent space for query (unobserved) time intervals. Matches scTour's predict_ltsp_from_time function exactly.

Usage

predict_ltsp_from_time(
  trainer,
  t,
  reverse = FALSE,
  step_wise = TRUE,
  step_size = NULL,
  alpha_z = 0.5,
  alpha_predz = 0.5,
  k = 20,
  assay = "RNA"
)

Arguments

Value

Matrix of predicted latent space

Description

Predict developmental pseudotime for query cells.

Usage

predict_time(trainer, query_seurat, reverse = FALSE, assay = "RNA")

Arguments

Value

Numeric vector of pseudotime values

Description

Predict vector field for query cells.

Usage

predict_vector_field(trainer, t, z)

Arguments

Value

Matrix of vector field

Description

Post-inference adjustment to reverse the pseudotime.

Usage

reverse_time(t)

Arguments

Value

Reversed pseudotime (1 - t)

Description

Split dataset into training and validation sets.

Usage

split_data(X, percent, val_frac = 0.1, loss_mode = "nb")

Arguments

Value

List with train_data and val_data

Description

Split indices into training and validation sets.

Usage

split_index(n_cells, percent, val_frac = 0.1)

Arguments

Value

List with train_idx and val_idx

Description

Complete model combining VAE and Neural ODE for cellular dynamics inference. This is the core model of CellODE.

Usage

TNODE(
  n_int,
  n_latent = 5L,
  n_ode_hidden = 25L,
  n_vae_hidden = 128L,
  batch_norm = FALSE,
  ode_method = "euler",
  step_size = NULL,
  alpha_recon_lec = 0.5,
  alpha_recon_lode = 0.5,
  alpha_kl = 1,
  loss_mode = "nb"
)

Arguments

Value

nn_module for TNODE model

Description

Trainer class for model training and inference

Description

R6 class for implementing the CellODE training process.

Public fields

Methods

Public methods

• Trainer$new()

• Trainer$train()

• Trainer$get_time()

• Trainer$get_vector_field()

• Trainer$get_latentsp()

• Trainer$save_model()

• Trainer$load_model()

• Trainer$clone()

Method new()

Initialize Trainer

Usage

Trainer$new(
  seurat_obj,
  assay = "RNA",
  slot = NULL,
  percent = NULL,
  n_latent = 5L,
  n_ode_hidden = 25L,
  n_vae_hidden = 128L,
  batch_norm = FALSE,
  ode_method = "euler",
  step_size = NULL,
  alpha_recon_lec = 0.5,
  alpha_recon_lode = 0.5,
  alpha_kl = 1,
  loss_mode = "nb",
  nepoch = NULL,
  batch_size = 1024L,
  drop_last = FALSE,
  lr = 0.001,
  wt_decay = 1e-06,
  eps = 0.01,
  random_state = 0L,
  val_frac = 0.1,
  use_gpu = TRUE
)

Arguments

Method train()

Train the model

Usage

Trainer$train()

Method get_time()

Get pseudotime for all cells

Usage

Trainer$get_time()

Returns

Numeric vector of pseudotime values

Method get_vector_field()

Get vector field

Usage

Trainer$get_vector_field(t, z)

Arguments

Returns

Matrix of vector field

Method get_latentsp()

Get latent space representation

Usage

Trainer$get_latentsp(
  alpha_z = 0.5,
  alpha_predz = 0.5,
  step_size = NULL,
  step_wise = FALSE,
  batch_size = NULL
)

Arguments

Returns

List with mix_zs, zs, pred_zs matrices

Method save_model()

Save trained model

Usage

Trainer$save_model(path)

Arguments

Method load_model()

Load trained model

Usage

Trainer$load_model(path)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

Trainer$clone(deep = FALSE)

Arguments

Description

Mathematical utilities for loss computation and ODE solving

Description

Functions for vector field computation and visualization

Description

Calculate weighted unitary displacement vectors under embedding. This function matches scTour's vector_field_embedding exactly. The calculation borrows the ideas from scvelo.

Usage

vector_field_embedding(T_mat, E, scale = 10, self_transition = FALSE)

Arguments

Value

Matrix of displacement vectors

Description

Estimate displacement vectors on a grid. This function matches scTour's vector_field_embedding_grid exactly. The calculation borrows the ideas from scvelo.

Usage

vector_field_embedding_grid(E, V, smooth = 0.5, stream = FALSE, density = 1)

Arguments

Value

List with E_grid and V_grid

Description

Functions called on package load/attach