DOCSEARCHbyAlgolia
Submit Docs

velocyto.py

repository·master·Indexed 41 days ago

https://github.com/velocyto-team/velocyto.py

A library and CLI tool for RNA velocity analysis. It provides a programmatic analysis pipeline via the VelocytoLoom object and a command-line interface for read counting. Note that this repository is no longer maintained; users are directed to STARSolo for modern alternatives.

Tokens
11.4K
Snippets
33
Records
49
Agent score
52%

What's inside velocyto

  1. Overview of velocyto.py

    master

    Velocyto is a library designed for the analysis of RNA velocity. It provides two primary ways to interact with its functionality:

    1. Command Line Interface (CLI): A tool for running velocity analysis via terminal commands.
    2. Analysis Pipeline: A programmatic approach for performing RNA velocity analysis.

    Note on API Stability: The project is approaching a v1.0 release. Until then, the API is subject to minor changes. Users should be aware that the CLI API has been recently improved and differs from older versions.

  2. Use the Velocyto Library API

    master

    For programmatic access, Velocyto exposes several core modules that allow you to perform specific stages of the RNA velocity workflow within your own Python scripts. The primary modules are:

    • Analysis module: Core analysis functions.
    • Estimation module: Velocity estimation logic.
    • Neighbors module: Computation of nearest neighbors.
    • Diffusion module: Diffusion-based velocity modeling.
    • Serialization module: Handling data input and output formats.

  3. Input file requirements for BAM and GTF files

    master

    BAM File Requirements

    To work correctly, the input BAM file must:

    1. Be sorted by mapping position.
    2. Represent either a single sample (multiple cells) or a single cell.
    3. Contain error-corrected cell barcodes in a CB or XC TAG.
    4. Contain error-corrected molecular barcodes in a UB or XM TAG. Note: For SmartSeq2, requirements 3 and 4 are not needed as there are no UMIs.

    GTF File Requirements

    The GTF must follow the GENCODE format. Specifically, for lines labeled as exon in the 3rd column, the 9th column must contain:

    1. transcript_id (unique identifier)
    2. transcript_name (Optional; defaults to transcript_id if missing)
    3. gene_id (unique identifier)
    4. gene_name (Optional; defaults to gene_id if missing)
    5. exon_number (Recommended; if missing, velocyto sorts and numbers them in memory)

  4. How velocyto subcommands work

    master

    The velocyto command is a CLI tool with several subcommands. While velocyto run is the general-purpose command for the read counting pipeline, velocyto provides several technology-specific wrappers that are recommended for ease of use:

    • run10x: Optimized for 10X Chromium samples.
    • run_smartseq2: Optimized for UMI-less, non-stranded, full-length techniques like SmartSeq2.
    • run_dropest: Optimized for DropSeq, InDrops, and related techniques.

    These wrappers automatically pass appropriate options for each technology and perform minimal input validation. For advanced or custom techniques, use velocyto run directly or implement a new logic via the Logic interface API.

  5. Initialize and manage a VelocytoLoom object

    master

    The core of the velocyto analysis is the VelocytoLoom object. You load data from a .loom file into this object to begin analysis.

    Key Behaviors:

    • Stateful API: Most methods do not return values; instead, they modify the internal state of the VelocytoLoom object and generate new attributes (e.g., normalized matrices, filtered gene lists).
    • Order Matters: Because methods operate on object attributes, the sequence of calls is critical for meaningful results. Follow the standard pipeline: Filtering $\rightarrow$ Normalization $\rightarrow$ Imputation $\rightarrow$ Gamma Fit $\rightarrow$ Velocity Calculation.
    • Persistence: You can save the entire state of your analysis (including all generated attributes) to an HDF5 file and reload it later.
    import velocyto as vcy

# Load data
vlm = vcy.VelocytoLoom("YourData.loom")

# Save analysis state
vlm.dump_hdf5("my_velocyto_analysis")

# Reload analysis state in a new session
vlm_reloaded = vcy.load_velocyto_hdf5("my_velocyto_analysis.hdf5")

  6. Use the velocyto.logic module to customize molecule counting

    master

    The velocyto.logic module is an experimental feature (introduced in version 0.12.0) that allows users to modify the logic used to categorize molecules into groups such as spliced, unspliced, and ambiguous.

    This module is intended for developers who need to:

    • Adapt velocyto to different sequencing technologies.
    • Introduce new rules or heuristics to improve the accuracy or sensitivity of molecule counting.
    • Change counting logic without rewriting the entire pipeline.

    Warning: The API and design of this module are experimental and are expected to change significantly in future versions.

  7. Understand the two main components of Velocyto

    master

    Velocyto is divided into two distinct functional parts:

    1. Command Line Interface (CLI): A pipeline used to process .bam or .sam files to generate .loom files containing spliced, unspliced, and ambiguous expression matrices.
    2. Python Library: A set of functions used to perform RNA velocity estimation using the matrices produced by the CLI.

  10. Install velocyto via PyPI

    master

    To install the latest stable version of the velocyto command line tool and library, use pip. This will automatically install pysam and loompy as dependencies.

    Note: velocyto is currently in an alpha release and is updated frequently. If you installed via pip, it is recommended to periodically run the update command with the --no-deps flag to ensure you get the latest version without breaking dependency management.

    To verify the installation, run velocyto --help.

    pip install velocyto

# To update to the latest version frequently:
pip install -U --no-deps velocyto

  11. Access sample analyses in Jupyter notebooks

    master

    Sample analyses and walkthroughs for using velocyto are provided as Jupyter notebooks. These are maintained in a separate repository and can be used to understand common workflows and implementation patterns for RNA velocity analysis.

    https://github.com/velocyto-team/velocyto-notebooks/tree/master/python

  12. Project velocity onto low-dimensional embeddings

    master

    To visualize velocity, project the extrapolated cell state (stored in vlm.Sx_sz_t) onto a low-dimensional embedding (e.g., t-SNE or UMAP).

    Process:

    1. Attach Embedding: Calculate an embedding (using scikit-learn or similar) and assign it as a new attribute to the vlm object (e.g., vlm.ts).
    2. Estimate Transitions: Use estimate_transition_prob to calculate transition probabilities on the embedding. Note: This is computationally intensive and benefits from multi-threading.
    3. Calculate Shift: Use calculate_embedding_shift to find the velocity vector in the embedding space.
    from sklearn.manifold import TSNE

# 1. Attach embedding to vlm object
bh_tsne = TSNE()
vlm.ts = bh_tsne.fit_transform(vlm.pcs[:, :25])

# 2. Estimate transition probabilities and shift
# Warning: Slow on large datasets
vlm.estimate_transition_prob(hidim="Sx_sz", embed="ts", transform="sqrt", psc=1, 
                             n_neighbors=3500, knn_random=True, sampled_fraction=0.5)
vlm.calculate_embedding_shift(sigma_corr=0.05, expression_scaling=True)