VelOT Documentation

VelOT (Velocity via Optimal Transport) is a kinetic-free framework for estimating RNA velocity from single-cell transcriptomic data.

Why VelOT?

Existing RNA velocity methods (velocyto, scVelo) rely on modeling the molecular kinetics of splicing and degradation, requiring spliced/unspliced count matrices and assumptions about transcriptional steady states that frequently fail in complex biological systems.

VelOT takes a fundamentally different approach. It treats velocity inference as an optimal transport problem in gene expression space:

• Kinetic-free: no spliced/unspliced counts needed — works with any gene expression matrix.

• Principled directionality: pseudotime-informed cost matrices enforce biologically consistent forward transport.

• Continuous velocity fields: a neural network smoothing step produces a velocity function that can be evaluated at any point in expression space, not just at observed cell positions.

• Robust evaluation: built-in metrics (ICCoh, CBDir) and a benchmarking framework for systematic velocity quality assessment.

Key Features

🔬 Preprocessing	Automated pipeline with pseudotime via Diffusion Pseudotime
🪟 Spatial-temporal windowing	Two-level strategy ensuring local, biologically meaningful OT
🚚 Optimal transport velocity	Structured cost matrices with pseudotime and KNN penalties
🧠 Neural smoothing	MLP-based continuous velocity field with confidence weighting
📊 Visualization	Stream plots, trajectory analysis, metric dashboards
📏 Evaluation	ICCoh, CBDir metrics with built-in benchmarking

Quick Example

import velot

adata = velot.datasets.pancreas()
adata = velot.pp.prepare(adata, root_cluster="Ductal", cluster_key="clusters")
velot.tl.velocity(adata)
velot.pl.velocity_stream(adata, color="clusters")

Getting Started

• Installation
  • Requirements
  • Quick install (recommended)
  • Developer installation
  • Verify Installation
  • Dependencies
• Quick Start
  • Minimal Example
  • Step-by-Step Example
  • Evaluating Velocity Quality
  • Trajectory Analysis

Tutorials

• Real erythroid dataset
• Real pancreas dataset

User Guide

• VelOT: Complete Methodology
  • Overview
  • Stage 1: Preprocessing and Pseudotime Inference
  • Stage 2: Spatial-Temporal Windowing
  • Stage 3: Optimal Transport Velocity Estimation
  • Stage 4: Neural Velocity Field Smoothing
  • Stage 5: Velocity Projection to UMAP
  • Summary of Notation

API Reference

• Preprocessing (velot.pp)
• Tools (velot.tl)
• Plotting (velot.pl)
• Metrics (velot.metrics)
• Datasets (velot.datasets)
• Benchmarking (velot.benchmark)

About

• Changelog
• Citation
• Contributing

• Index

If you use VelOT in your research, please cite:

@article {velot2026,
   author = {Rincon de la Rosa, Lucas and Perez Garcia, David and Alentorn, Agusti},
   title = {VelOT: kinetic-free RNA velocity inference via optimal transport, flow-field smoothing, and VAMP coarse-graining of cellular dynamics},
   elocation-id = {2026.06.04.730132},
   year = {2026},
   doi = {10.64898/2026.06.04.730132},
   publisher = {Cold Spring Harbor Laboratory},
   URL = {https://www.biorxiv.org/content/early/2026/06/06/2026.06.04.730132},
   eprint = {https://www.biorxiv.org/content/early/2026/06/06/2026.06.04.730132.full.pdf},
   journal = {bioRxiv}
   }