Velotest is a hypothesis test for how well a 2D embedding of positional and velocity data represents the original high dimensional data. It's purpose is to help practitioners using 2D embeddings of single cell RNA sequencing data with RNA velocity decide which 2D velocity vectors are faithfully representing the high-dimensional data.

Installation

You can simply install the package via pip:

pip install velotest

If you want to change bits of the code, install it in editable mode:

pip install -e "."

In both cases you'll need additional dependencies to build the docs, run tests, or reproduce the figures from the paper, which you can install via the extras docs, dev, or experiment, either separately or in combination. For example, to install the docs extra, run pip install velotest[docs], or to install both the docs and dev extras, run pip install velotest[docs,dev]. Similarly, if you installed in editable mode, you can run pip install -e ".[docs]".

Usage

If you have the embeddings and original data as individual arrays/tensor (see below for use with an anndata object), you can use our general interface:

from velotest.hypothesis_testing import run_hypothesis_test

uncorrected_p_values, h0_rejected, _, _, _ = run_hypothesis_test(high_d_position, high_d_velocity, low_d_position, low_d_velocity_position)

where low_d_velocity_position is the tip's position of the 2D velocity vector, NOT the velocity vector originating in low_d_position.

An application on single-cell sequencing data (runnable notebook: notebooks/demo.ipynb) could look like this (following scvelo's tutorial):

from velotest.hypothesis_testing import run_hypothesis_test_on
import scvelo

adata = scvelo.datasets.pancreas()
scvelo.pp.filter_and_normalize(adata, min_shared_counts=20, n_top_genes=2000)
scvelo.pp.moments(adata, n_pcs=30, n_neighbors=30)

# Compute velocity
scvelo.tl.velocity(adata)

# Compute 2D embedding of velocity vectors
scvelo.tl.velocity_graph(adata)
scvelo.pl.velocity_embedding(adata)

# Run test
uncorrected_p_values, h0_rejected, _ = run_hypothesis_test_on(adata)

For plotting, you can use the plotting module. Have a look at notebooks/demo.ipynb for an example. Refer to Read the Docs for a more detailed API documentation.

Details

Next, we will briefly summarize how the test works, for details see our paper. The tests tries to assess how well the 2D velocity vectors represent the high-dimensional velocity vectors. We quantify this by computing the mean cosine similarity between the high-dimensional velocity vector and the difference vectors to a set of neighbors in the high-dimensional space. For a data point i, we use the mean cosine similarity between the velocity v_i and the difference vector x_j-x_i for all x_j in a set of neighbors of \tilde{x}_i as the test statistic. This set of neighbors is chosen based on the points the velocity \tilde{v}_i points to in 2D. \tilde{v}_i and \tilde{x}_i are the 2D embeddings of v_i and x_i, respectively.

The null hypothesis is that the visualised 2D velocity vector is no more aligned with the high-dimensional velocity than a visually distinct random 2D direction. It is rejected if the number of random neighborhoods with a higher statistic as the statistic from the velocity-based neighborhood exceeds the level we would expect for a certain significance level.

It was originally developed for the analysis of single cell RNA sequencing data, but can be applied to any application with positional and velocity data.

Reproducing plots from paper

Make sure that you have the experiment extra installed (see Installation section above).

Then, you can reproduce all figures by simply running make_all_figures.py in the experiments folder:

cd experiments
python make_all_figures.py --multirun=dataset=pancreas_stochastic,pancreas_dynamical,dentateyrus,bonemarrow,covid,gastrulation_erythroid,nystroem,developing_mouse_brain,organogenesis,veloviz

This will create a fig folder in the experiments folder with all figures based on the configuration in configs/. This uses hydra to manage the configurations, so you can also modify individual configurations using the command line with python make_all_figures.py dataset=pancreas_stochastic dataset.number_neighbors_to_sample_from=300.