DOCSEARCHbyAlgolia
Submit Docs

scVelo Documentation

repository·main·Indexed 19 days ago

https://github.com/theislab/scvelo

A scalable toolkit for RNA velocity analysis in single cells. scVelo provides methods to recover directed dynamic information from splicing kinetics using three distinct estimation models: a steady-state/deterministic model, a stochastic model, and a likelihood-based dynamical model using an EM framework. The library includes modules for preprocessing (scv.pp), analysis tools for velocity estimation and trajectory inference (scv.tl), and visualization functions (scv.pl) for velocity embeddings and graphs.

Tokens
7.9K
Snippets
30
Records
45
Agent score
68%

What's inside scVelo

  1. Overview of scVelo for RNA velocity analysis

    main

    scVelo is a scalable toolkit designed for RNA velocity analysis in single cells. It leverages splicing kinetics to recover directed dynamic information. The toolkit provides methods for inferring RNA velocity using two primary frameworks:

    1. Expectation-Maximization (EM) framework: Includes the EM (dynamical) and steady-state models.
    2. Metabolic labeling: Methods for estimating RNA velocity using metabolically labeled transcripts.

    Key Applications:

    • Estimating RNA velocity to study cellular dynamics.
    • Identifying putative driver genes and regulatory change regimes.
    • Inferring latent time to reconstruct temporal sequences of transcriptomic events.
    • Estimating reaction rates for transcription, splicing, and degradation.
    • Using statistical tests to detect different kinetics regimes.

  2. Compare RNA velocity estimation models in scVelo

    main

    scVelo provides three distinct approaches for estimating RNA velocity, allowing users to balance computational efficiency against model complexity and biological accuracy:

    1. Steady-state / deterministic model:

      • Mechanism: Estimates velocities as the deviation of the observed spliced/unspliced ratio from an inferred steady-state ratio.
      • Assumptions: Assumes a common splicing rate across all genes and that transcriptional phases (induction/repression) last long enough to reach steady-state equilibrium.
      • Use Case: Fast, but prone to errors if the population is heterogeneous or if steady-state assumptions are violated.

    2. Stochastic model:

      • Mechanism: Treats transcription, splicing, and degradation as probabilistic events using a Markov process approximated by moment equations. It utilizes second-order moments (covariation) to better capture steady states.
      • Use Case: Recommended if runtime is a priority. It is highly efficient (e.g., taking only a few minutes for 30k cells) and provides higher consistency than the deterministic model.

    3. Dynamical model:

      • Mechanism: A likelihood-based framework that solves the full transcriptional dynamics of splicing kinetics for each gene using an expectation-maximization (EM) framework.
      • Capabilities: Infers gene-specific rates (transcription, splicing, degradation), recovers a universal cell-internal latent time (the cell's internal clock), and identifies transcriptional states (induction, repression, active, and inactive).
      • Use Case: Recommended for best results and deepest biological insight. It is the most powerful but also the most computationally expensive (can take up to an hour).

  3. How the dynamical model solves splicing kinetics

    main

    The dynamical model in scVelo uses a likelihood-based expectation-maximization (EM) framework to solve the following splicing dynamics equations for each gene:

    $$\frac{du(t)}{dt}= \alpha_k(t) - \beta u(t)$$ $$\frac{ds(t)}{dt}= \beta u(t) - \gamma s(t)$$

    Where:

    • $u(t)$ is the unspliced mRNA.
    • $s(t)$ is the spliced mRNA.
    • $\alpha_k(t)$ is the transcriptional induction rate.
    • $\beta$ is the splicing rate.
    • $\gamma$ is the degradation rate.

    The EM Process:

    • Expectation Step: Assigns a latent time to observed mRNA values by minimizing distance to the phase trajectory and assigns transcriptional states (induction, repression, active, or inactive) based on likelihood.
    • Maximization Step: Optimizes the overall likelihood by updating the reaction rate parameters.

    This model allows for the identification of regulatory changes, such as cell fate commitment stages, and the detection of driver genes.

  4. Visualize RNA velocity embeddings

    main

    Once velocities and velocity graphs are computed, you can visualize them in embeddings (like UMAP) using several methods:

    • scv.pl.velocity_embedding(): Standard projection.
    • scv.pl.velocity_embedding_grid(): Visualizes velocities as a grid.
    • scv.pl.velocity_embedding_stream(): Visualizes velocities as streamlines.

    Additionally, you can use tool-specific plotting functions to inspect results in detail, such as scv.pl.velocity() for gene-specific velocities or scv.pl.velocity_graph() for the graph structure.

    # Visualize in an embedding (e.g., UMAP)
scv.pl.velocity_embedding(adata, basis='umap', **params)
scv.pl.velocity_embedding_grid(adata, basis='umap', **params)
scv.pl.velocity_embedding_stream(adata, basis='umap', **params)

# Detailed inspection
scv.pl.velocity(adata, var_names=['gene_A', 'gene_B'], **params)
scv.pl.velocity_graph(adata, **params)

  5. Analyze time-dependent kinetic rate parameters

    main
    Use the Kinetic parameter analysis notebook to study how time-variable kinetic rates influence the curvature patterns of gene activation. This analysis is critical for understanding how changes in transcription and degradation rates over time shape the observed RNA velocity.

  6. Install scVelo via PyPI

    main

    Install the stable version of scVelo using pip. It is recommended to use Python 3.6 or later and Miniconda. If you encounter a Permission denied error, use the --user flag to install to your user directory.

    pip install -U scvelo

# If you get a Permission denied error:
pip install -U scvelo --user

  7. Explore potential pitfalls in RNA velocity modeling

    main

    Use the Perspectives notebook to understand common modeling errors and pitfalls in RNA velocity analysis. This includes studying specific biological use cases such as:

    • Multiple kinetics in Dentate Gyrus: Understanding how varying kinetic rates affect results.
    • Transcriptional boost in erythroid lineage: Identifying how sudden changes in transcription impact velocity.
    • Misleading arrow projections in mature PBMCs: Recognizing when velocity vectors may provide incorrect biological interpretations.

  9. Import RNA velocity data

    main

    scVelo requires two count matrices: pre-mature (unspliced) and mature (spliced) abundances. These are typically stored in an AnnData object (adata) within adata.layers.

    You can load data from various formats (loom, h5ad, csv, etc.) using sc.read(). If you have a preprocessed AnnData object and need to add spliced/unspliced counts from a separate file, use scv.utils.merge().

    # Load data from a file
adata = sc.read(filename, cache=True)

# Merge existing preprocessed adata with spliced/unspliced counts from a loom file
ldata = sc.read(filename.loom, cache=True)
adata = scv.utils.merge(adata, ldata)

# Or use a built-in dataset for testing
adata = scv.datasets.pancreas()

  10. Initialize scVelo and Scanpy

    main

    To begin using scVelo, import both scanpy and scvelo. You can also call scv.set_figure_params() to apply scVelo's default matplotlib settings for improved visualization quality.

    import scanpy as sc
import scvelo as scv

# Set default matplotlib parameters for beautified visualization
scv.set_figure_params()

  11. Install the scVelo development version

    main

    To use the latest development features, you can install directly from the GitHub repository. You can either install it directly via pip or clone the repository and install it in editable mode (-e). Editable mode ensures that changes in the cloned source are immediately reflected in your environment.

    # Option 1: Direct install from GitHub
pip install git+https://github.com/theislab/scvelo@main

# Option 2: Clone and install in editable mode
git clone https://github.com/theislab/scvelo && cd scvelo
git checkout --track origin/main
pip install -e .

  12. Install optional scVelo dependencies

    main

    Some scVelo features require additional packages that are not included in the base installation:

    • Directed PAGA and Louvain modularity: Requires igraph and louvain.
    • Fast neighbor search (hnswlib): Requires pybind11 and hnswlib.
    # For directed PAGA and Louvain modularity
pip install igraph louvain

# For fast neighbor search via hnswlib
pip install pybind11 hnswlib