Mapping Vector Field of Single Cells


Import dynamo as:

import dynamo as dyn

Data IO

(See more at anndata-docs)

read(filename[, backed, as_sparse, …])

Read .h5ad-formatted hdf5 file.

read_h5ad(filename[, backed, as_sparse, …])

Read .h5ad-formatted hdf5 file.

read_loom(filename, *[, sparse, cleanup, …])

Read .loom-formatted hdf5 file.

Preprocessing (pp)

pp.recipe_monocle(adata[, normalized, …])

This function is partly based on Monocle R package (

pp.cell_cycle_scores(adata[, layer, …])

Call cell cycle positions for cells within the population.

Estimation (est)


Classes in est are internally to Tools. See our estimation classes here: estimation

Tools (tl)

kNN and moments of expressions

tl.neighbors(adata[, X_data, genes, basis, …])

Function to search nearest neighbors of the adata object.

tl.mnn(adata[, n_pca_components, …])

Function to calculate mutual nearest neighbor graph across specific data layers.

tl.moments(adata[, genes, group, …])

Calculate kNN based first and second moments (including uncentered covariance) for

Kinetic parameters and RNA/protein velocity

tl.dynamics(adata[, tkey, t_label_keys, …])

Inclusive model of expression dynamics considers splicing, metabolic labeling and protein translation.

Dimension reduction

tl.reduceDimension(adata[, X_data, genes, …])

Compute a low dimension reduction projection of an annodata object first with PCA, followed by non-linear dimension reduction methods

tl.DDRTree(X, maxIter, sigma, gamma[, eps, …])

This function is a pure Python implementation of the DDRTree algorithm.

tl.psl(Y[, sG, dist, K, C, param_gamma, d, …])

This function is a pure Python implementation of the PSL algorithm.


tl.hdbscan(adata[, X_data, genes, layer, …])

Apply hdbscan to cluster cells in the space defined by basis.

tl.cluster_field(adata[, basis, …])

Cluster cells based on vector field features.

Velocity projection

tl.cell_velocities(adata[, ekey, vkey, X, …])

Compute transition probability and project high dimension velocity vector to existing low dimension embedding.

tl.confident_cell_velocities(adata, group, …)

Confidently compute transition probability and project high dimension velocity vector to existing low dimension embeddings using progeintors and mature cell groups priors.

Velocity metrics

tl.cell_wise_confidence(adata[, X_data, …])

Calculate the cell-wise velocity confidence metric.

tl.gene_wise_confidence(adata, group[, …])

Diagnostic measure to identify genes contributed to “wrong” directionality of the vector flow.

Markov chain

tl.generalized_diffusion_map(adata, **kwargs)

Apply the diffusion map algorithm on the transition matrix build from Itô kernel.

tl.stationary_distribution(adata[, method, …])

Compute stationary distribution of cells using the transition matrix.

tl.diffusion(M[, P0, steps, backward])

Find the state distribution of a Markov process.

tl.expected_return_time(M[, backward])

Find the expected returning time.

Markers and differential expressions

tl.moran_i(adata[, X_data, genes, layer, …])

Identify genes with strong spatial autocorrelation with Moran’s I test.

tl.find_group_markers(adata, group[, genes, …])

Find marker genes for each group of cells based on gene expression or velocity values as specified by the layer.

tl.two_groups_degs(adata, genes, layer, …)

Find marker genes between two groups of cells based on gene expression or velocity values as specified by the layer.

tl.top_n_markers(adata[, with_moran_i, …])

Filter cluster deg (Moran’s I test) results and retrieve top markers for each cluster.

tl.glm_degs(adata[, X_data, genes, layer, …])

Differential genes expression tests using generalized linear regressions.


tl.converter(data_in[, from_type, to_type, dir])

convert adata to loom object - we may save_fig to a temp directory automatically - we may write a on-the-fly converter which doesn’t involve saving and reading files

Vector field (vf)

Vector field reconstruction


Vector field class is internally to vf.VectorField. See our vector field classes here: vector field

vf.SparseVFC(X, Y, Grid[, M, a, beta, ecr, …])

Apply sparseVFC (vector field consensus) algorithm to learn a functional form of the vector field from random samples with outlier on the entire space robustly and efficiently.

vf.VectorField(adata[, basis, layer, dims, …])

Learn a function of high dimensional vector field from sparse single cell samples in the entire space robustly.

Vector field topology

vf.topography(adata[, basis, layer, X, …])

Map the topography of the single cell vector field in (first) two dimensions.

Beyond RNA velocity

vf.speed(adata[, basis, VecFld, method])

Calculate the speed for each cell with the reconstructed vector field function.

vf.divergence(adata[, cell_idx, sampling, …])

Calculate divergence for each cell with the reconstructed vector field function.

vf.curl(adata[, basis, vector_field_class])

Calculate Curl for each cell with the reconstructed vector field function.

vf.acceleration(adata[, basis, …])

Calculate acceleration for each cell with the reconstructed vector field function.

vf.curvature(adata[, basis, vector_field_class])

Calculate curvature for each cell with the reconstructed vector field function.

vf.torsion(adata[, basis, vector_field_class])

Calculate torsion for each cell with the reconstructed vector field function.

Acceleration field

vf.cell_accelerations(adata[, vf_basis, …])

Compute RNA acceleration field via reconstructed vector field and project it to low dimensional embeddings.

Vector field ranking

vf.rank_speed_genes(adata[, group, genes, vkey])

Rank gene’s absolute, positive, negative speed by different cell groups.

vf.rank_divergence_genes(adata[, group, …])

Rank gene’s absolute, positive, negative divergence by different cell groups.

vf.rank_acceleration_genes(adata[, group, …])

Rank gene’s absolute, positive, negative acceleration by different cell groups.

vf.rank_curvature_genes(adata[, group, …])

Rank gene’s absolute, positive, negative curvature by different cell groups.

Single cell potential: three approaches

vf.gen_fixed_points(func, auto_func, …[, …])

Calculate the fixed points of (learned) vector field function .

vf.gen_gradient(dim, N, Function, …)

Calculate the gradient of the (learned) vector field function for the least action path (LAP) symbolically

vf.IntGrad(points, Function, DiffusionMatrix, dt)

Calculate the action of the path based on the (reconstructed) vector field function and diffusion matrix (Eq.


Diffusion matrix can be variable dependent

vf.action(n_points, tmax, point_start, …)

It calculates the minimized action value given an intial path, ODE, and diffusion matrix.

vf.Potential(adata[, DiffMat, method])

Function to map out the pseudo-potential landscape.

vf.path_integral(VecFnc, x_lim, y_lim, …)

A deterministic map of Waddington’s epigenetic landscape for cell fate specification Sudin Bhattacharya, Qiang Zhang and Melvin E.

vf.alignment(numPaths, numTimeSteps, …[, …])

Align potential values so all path-potentials end up at same global min and then generate potential surface with interpolation on a grid.

vf.Wang_action(X_input, F, D, dim, N[, lamada_])

Calculate action by path integral by Wang’s method.

vf.Wang_LAP(F, n_points, point_start, point_end)

Calculating least action path based methods from Jin Wang and colleagues (

vf.transition_rate(X_input, F[, D, lambda_])

Calculate the rate to convert from one cell state to another cell state by taking the optimal path.

vf.MFPT(X_input, F[, D, lambda_])

Calculate the MFPT (mean first passage time) to convert from one cell state to another cell state by taking the optimal path.

vf.Ao_pot_map(vecFunc, X[, D])

Mapping potential landscape with the algorithm developed by Ao method.

vf.solveQ(D, F[, debug])

Function to calculate Q matrix by a least square method

Stochastic processes

vf.diffusionMatrix(adata[, X_data, V_data, …])

“Calculate the diffusion matrix from the estimated velocity vector and the reconstructed vector field.

Vector field graph

vf.vfGraph(*args, **kwds)

A class for manipulating the graph creating from the transition matrix, built from the (reconstructed) vector field.

Prediction (pd)

pd.fate(adata, init_cells[, init_states, …])

Predict the historical and future cell transcriptomic states over arbitrary time scales.

pd.fate_bias(adata, group[, basis, inds, …])

Calculate the lineage (fate) bias of states whose trajectory are predicted.

pd.state_graph(adata, group[, approx, …])

Estimate the transition probability between cell types using method of vector field integrations.

Plotting (pl)


pl.basic_stats(adata[, group, figsize, …])

Plot the basic statics (nGenes, nCounts and pMito) of each category of adata.

pl.show_fraction(adata[, genes, group, …])

Plot the fraction of each category of data used in the velocity estimation.

pl.feature_genes(adata[, layer, mode, …])

Plot selected feature genes on top of the mean vs.

pl.variance_explained(adata[, threshold, …])

Plot the accumulative variance explained by the principal components.

pl.exp_by_groups(adata, genes[, layer, …])

Plot the (labeled) expression values of genes across different groups (time points).

Cell cycle staging

pl.cell_cycle_scores(adata[, cells, …])

Plot a heatmap of cells ordered by cell cycle position

Scatter base

pl.scatters(adata[, basis, x, y, color, …])

Plot an embedding as points.

Phase diagram: conventional scRNA-seq

pl.phase_portraits(adata, genes[, x, y, …])

Draw the phase portrait, expression values , velocity on the low dimensional embedding.

Kinetic models: labeling based scRNA-seq

pl.dynamics(adata, vkey[, unit, …])

Plot the data and fitting of different metabolic labeling experiments.


pl.kinetic_curves(adata, genes[, mode, …])

Plot the gene expression dynamics over time (pseudotime or inferred real time) as kinetic curves.

pl.kinetic_heatmap(adata, genes[, mode, …])

Plot the gene expression dynamics over time (pseudotime or inferred real time) in a heatmap.

pl.jacobian_kinetics(adata[, source_genes, …])

Plot the gene expression dynamics over time (pseudotime or inferred real time) in a heatmap.

Dimension reduction

pl.pca(adata, *args, **kwargs)

Scatter plot with pca basis.

pl.tsne(adata, *args, **kwargs)

Scatter plot with tsne basis.

pl.umap(adata, *args, **kwargs)

Scatter plot with umap basis.

pl.trimap(adata, *args, **kwargs)

Scatter plot with trimap basis.

Neighbor graph

pl.nneighbors(adata[, x, y, color, basis, …])

Plot nearest neighbor graph of cells used to embed data into low dimension space.

pl.state_graph(adata, group[, basis, x, y, …])

Plot a summarized cell type (state) transition graph.

Vector field plots: velocities and accelerations

pl.cell_wise_vectors(adata[, basis, x, y, …])

Plot the velocity or acceleration vector of each cell.

pl.grid_vectors(adata[, basis, x, y, color, …])

Plot the velocity or acceleration vector of each cell on a grid.

pl.streamline_plot(adata[, basis, x, y, …])

Plot the velocity vector of each cell.

pl.line_integral_conv(adata[, basis, …])

Visualize vector field with quiver, streamline and line integral convolution (LIC), using velocity estimates on a grid from the associated data.

pl.plot_energy(adata[, basis, vecfld_dict, …])

Plot the energy and energy change rate over each optimization iteration.

Vector field topology

pl.plot_flow_field(vecfld, x_range, y_range)

Plots the flow field with line thickness proportional to speed.

pl.plot_fixed_points(vecfld[, marker, …])

Plot fixed points stored in the VectorField2D class.

pl.plot_nullclines(vecfld[, lw, background, …])

Plot nullclines stored in the VectorField2D class.

pl.plot_separatrix(vecfld, x_range, y_range, t)

Plot separatrix on phase portrait.

pl.plot_traj(f, y0, t[, args, lw, …])

Plots a trajectory on a phase portrait.

pl.topography(adata[, basis, x, y, color, …])

Plot the streamline, fixed points (attractor / saddles), nullcline, separatrices of a recovered dynamic system for single cells.

Beyond RNA velocity

pl.speed(adata[, basis, color, frontier])

Scatter plot with cells colored by the estimated velocity speed (and other information if provided).

pl.divergence(adata[, basis, color, cmap, …])

Scatter plot with cells colored by the estimated divergence (and other information if provided).

pl.curl(adata[, basis, color, cmap, …])

Scatter plot with cells colored by the estimated curl (and other information if provided).

pl.curvature(adata[, basis, color, frontier])

Scatter plot with cells colored by the estimated curvature (and other information if provided).

pl.jacobian(adata[, source_genes, …])

Scatter plot with pca basis.

pl.jacobian_heatmap(adata, cell_idx[, …])

Plot the Jacobian matrix for each cell as a heatmap.

Potential landscape

pl.show_landscape(adata, Xgrid, Ygrid, Zgrid)

Plot the quasi-potential landscape.

Cell fate

pl.fate_bias(adata, group[, basis, …])

Plot the lineage (fate) bias of cells states whose vector field trajectories are predicted.

Save figures

pl.save_fig([path, prefix, dpi, ext, …])

Save a figure from pyplot.

Moive (mv)

mv.StreamFuncAnim(adata[, basis, dims, …])

Animating cell fate commitment prediction via reconstructed vector field function.

mv.animate_fates(adata[, basis, dims, …])

Animating cell fate commitment prediction via reconstructed vector field function.

Simulation (sim)

Simple ODE vector field simulation

sim.two_genes_motif(x[, t, a1, a2, b1, b2, …])

The ODE model for the famous Pu.1-Gata.1 like network motif with self-activation and mutual inhibition.

sim.neurogenesis(x[, t, mature_mu, n, k, a, …])

The ODE model for the neurogenesis system that used in benchmarking Monocle 2, Scribe and dynamo (here), original from Xiaojie Qiu, et.

sim.toggle(ab[, t, beta, gamma, n])

Right hand side (rhs) for toggle ODEs.

sim.Ying_model(x[, t])

network used in the potential landscape paper from Ying, et.

Gillespie simulation

sim.Gillespie([a, b, la, aa, ai, si, be, …])

A simulator of RNA dynamics that includes RNA bursting, transcription, metabolic labeling, splicing, transcription, RNA/protein degradation

sim.Simulator([motif, clip])

Simulate the gene expression dynamics via deterministic ODE model

sim.state_space_sampler(ode, dim[, clip, …])

Sample N points from the dim dimension gene expression space while restricting the values to be between min_val and max_val.

sim.evaluate(reference, prediction[, metric])

Function to evaluate the vector field related reference quantities vs.

External (ext)

ext.ddhodge(adata[, X_data, layer, basis, …])

Modeling Latent Flow Structure using Hodge Decomposition based on the creation of sparse diffusion graph from the reconstructed vector field function.

ext.scribe(adata[, genes, TFs, Targets, …])

Apply Scribe to calculate causal network from spliced/unspliced, metabolic labeling based and other “real” time series datasets.

ext.mutual_inform(adata, genes, layer_x, layer_y)

Calculate mutual information (as well as pearson correlation) of genes between two different layers.

ext.scifate_glmnet(adata[, …])

Reconstruction of regulatory network (Cao, et. al, Nature Biotechnology, 2020) from TFs to other target


Package versions


Adapted from answer 2 in

Clean up adata

cleanup(adata[, del_prediction])

clean up adata before saving it to a file

Figures configuration

configuration.set_figure_params([dynamo, …])

Set resolution/size, styling and format of figures.


formatting helper function that can be used to save publishable figures