DOCSEARCHbyAlgolia
Submit Docs

Dynamo

repository·master·Indexed 19 days ago

https://github.com/aristoteleo/dynamo-release

A computational framework for mapping transcriptomic vector fields in single cells. Dynamo enables researchers to infer RNA velocity, reconstruct continuous vector fields, and predict cell fate transitions and perturbation outcomes using metabolic labeling and differential geometry. Key capabilities include RNA velocity estimation, potential landscape mapping, and the use of the least-action-path method to predict optimal reprogramming paths.

Tokens
64.6K
Snippets
189
Records
317
Agent score
67%

What's inside dynamo-release

  1. Overview of Dynamo

    master

    Dynamo is an analytical framework for mapping transcriptomic vector fields of single cells. It provides an inclusive model of expression dynamics by integrating metabolic labeling-based scRNA-seq and multiomics data.

    Key capabilities include:

    • RNA Velocity Estimation: Robust estimation using multiple methods (including negative binomial distribution-based approaches) and strategies to correct problematic velocity vectors.
    • Metabolic Labeling Modeling: Explicitly models RNA metabolic labeling, transcription, splicing, and degradation for one-shot, pulse, chase, and mixture experiments.
    • Vector Field Analysis: Uses dynamical systems approaches to identify stable cell types (fixed points) and state boundaries (separatrices).
    • Differential Geometry: Calculates RNA acceleration, curvature, divergence, and the RNA Jacobian to extract mechanistic insights and regulatory networks.
    • Predictive Modeling: Employs the least-action-path method to predict optimal reprogramming paths and uses in silico perturbations to predict cell-fate diversions caused by genetic changes.

  2. Overview of Dynamo capabilities

    master

    Dynamo is a framework for mapping transcriptomic vector fields of single cells. It provides an inclusive model for expression dynamics using metabolic labeling-based scRNA-seq or multiomics data.

    Key capabilities include:

    • Vector field reconstruction
    • Potential landscape mapping
    • Differential geometry analyses
    • Most probable paths and in silico perturbation predictions

  3. Overview of dynamo modules

    master

    Dynamo follows a modular structure similar to other single-cell analysis toolkits (like Scanpy or Seurat). The core modules are:

    • dyn.read*: Data loading
    • dyn.pp.*: Preprocessing
    • dyn.tl.*: Tool analysis
    • dyn.pl.*: Plotting

    Dynamo-specific modules include:

    • dyn.est.*: Estimation framework for expression dynamics.
      • dyn.est.csc.*: Conventional scRNA-seq modeling (standard RNA velocity).
      • dyn.est.tsc.*: Time-resolved metabolic labeling based scRNA-seq modeling.
    • dyn.vf.*: Vector field reconstruction and vector calculus.
    • dyn.pd.*: Cell fate prediction.
    • dyn.mv.*: Movie creation for cell fate predictions.
    • dyn.sim.*: Stochastic simulation of metabolic labeling experiments.
    • dyn.ext.*: Integration with external tools.

  4. Overview of Least Action Path (LAP) analysis workflow

    master

    Least Action Path (LAP) is used to predict the most probable transition path between two cell states by minimizing the path's action. The workflow typically involves:

    1. Initialization: Compute a neighbor graph of cells (in UMAP or PCA space) and use shortest paths between representative cells as an initial guess.
    2. Execution: Run LAP analyses between pairwise combinations of cells.
    3. Projection: If the vector field was learned in PCA space, the optimized LAP can be projected back to the original gene expression space to reveal transcriptomic kinetics.
    4. Downstream Analysis: Use the identified path to prioritize transcription factors (TFs) via the path integral of the mean square displacement (MSD) and perform ROC analyses.

  5. Calculate TF priority scores from ranks

    master

    To convert raw MSD ranks into a normalized priority score (where higher is better), use the following formula:

    $$\text{priority score} = 1 - \frac{#\text{ rank}}{#\text{ TF}}$$

    In the tutorial implementation, the rank is first normalized by the total number of TFs (e.g., rank /= 133) and then subtracted from 1. This results in a score where a value near 1.0 indicates a top-ranked TF for that transition.

  6. Identify key regulatory genes using Mean Squared Displacement (MSD)

    master

    To identify transcription factors (TFs) or regulatory genes that drive a specific cell fate transition, you can analyze the gene expression variations along the calculated Least Action Path (LAP).

    Dynamo ranks genes based on the Mean Squared Displacement (MSD) of their expression relative to their initial expression at the start of the path. A high MSD indicates that the gene's expression changes significantly during the transition, suggesting it may be a key regulator.

    Formula for MSD of gene $i$: $$\mathrm{MSD}i = \sum{t=0}^{T} \big(y_i(t) - y_i(0)\big)^2$$

    where:

    • $y_i(t)$ is the expression of gene $i$ at time $t$ along the path.
    • $y_i(0)$ is the initial expression of gene $i$ at the starting state.
    • $T$ is the total traversal time.

  7. Distinguish between dyn.pd.plot_kinetic_heatmap and dyn.pl.kinetic_heatmap

    master

    Dynamo provides two distinct functions for kinetic heatmaps that are not interchangeable:

    1. dyn.pd.plot_kinetic_heatmap: Part of the prediction module. It is used to compute and plot kinetics along a Least Action Path (LAP). It requires adata, cells_indices_dict, source_cell_type, and target_cell_type.
    2. dyn.pl.kinetic_heatmap: Part of the plot module. It is used for ddhodge pseudotime and vector-field heatmaps. It requires adata, genes, and a mode.

  8. Understand Preprocessor output keys and metadata

    master

    The Preprocessor workflow generates several important keys in the AnnData object (adata) that are used for downstream analysis and validation.

    Observation Metadata (adata.obs and adata.var):

    • pass_basic_filter: Indicates if the data passed initial filtering criteria.

    Variable Metadata (adata.var):

    • use_for_pca: Boolean flag indicating if a gene is suitable for PCA.

    Multidimensional Scaling (adata.obsm):

    • X_pca: The principal component analysis coordinates.

    Normalized Layers (adata.layers):

    • X_spliced: Spliced transcript counts (recipe-dependent).
    • X_unspliced: Unspliced transcript counts (recipe-dependent).

  9. Comparison of RNA velocity methods: Traditional vs. Metabolic Labeling

    master

    When choosing an analysis approach for transcriptomic dynamics, consider the following differences between traditional RNA velocity and Dynamo's metabolic labeling approach:

    FeatureTraditional RNA VelocityDynamo (Metabolic Labeling)
    Data SourceRelies on mis-priming of intron reads (often biased/inaccurate)Measures 'old' vs 'new' RNA via controllable labeling
    Predictive PowerPrimarily descriptive; short-term direction/magnitudePredictive; captures true physical dynamics (molecules/hour)
    ScalingScaled by splicing rate; lacks direct physical meaningProvides real physical measurements of transcription/degradation
    ComplexitySimple $U - \gamma / \beta S$ modelSophisticated moment-equation framework

  10. Requirements for AnnData state when performing in-silico perturbation

    master

    To perform in-silico perturbations using Dynamo, your AnnData object must be preprocessed and contain specific metadata in .uns and .obsm slots. The following keys are required:

    Required .uns keys

    • VecFld_pca: The PCA-space vector field.
    • jacobian_pca: The PCA-space Jacobian (required if using the default j_delta_x method).
    • PCs: PCA projection matrices.
    • pca_mean: PCA projection matrices.

    Required .obsm keys

    • X_pca: PCA embeddings.
    • X_umap: UMAP embeddings (or the embedding specified via emb_basis).

    Internal requirements

    • adata.obsp['cosine_transition_matrix']: Used internally by cell_velocities.

  11. Branch Selection for Velocity Workflows

    master

    When configuring dynamo, choosing the correct branch is critical for matching specific analytical goals:

    ParameterOptionUse Case
    recipe'monocle'Required for the total-RNA one-shot workflow family.
    group'time'Use for smoothing and fitting with time-specific neighborhoods.
    one_shot_method'sci_fate'For parity with standard total-RNA tutorials.
    one_shot_method'combined'When using the steady-state-plus-absolute-gamma branch.
    model'deterministic'Default for total-RNA workflows.
    cell_velocities(method=...)'cosine'Standard total-RNA projection.
    cell_velocities(method=...)'pearson'Alternative kernel projection.
    streamline_plot(method=...)'gaussian'Default streamline rendering.
    streamline_plot(method=...)'SparseVFC'Advanced rendering after vector field reconstruction.

  12. Best practices for gene ID conversion and preprocessing integration

    master

    To avoid data integrity issues and downstream risks, follow this order of operations:

    1. Convert IDs first: Perform gene symbol conversion on your object.
    2. Preprocess second: Run your preprocessing pipeline after the IDs are converted.

    Warning: Avoid renaming adata.var_names after preprocessing has already occurred, unless you are explicitly attempting to repair a previously processed object and accept the associated risks.