Skip to contents

Plot Transition Vectors on a Reduced Dimensional Embedding

PlotTransitionVectors.Rd

This function visualizes cell-state transitions in a Seurat object by plotting transition vectors on a dimensionality-reduced embedding (e.g., UMAP). It computes transition vectors based on a specified perturbation and overlays them on a scatter plot of the cells, allowing insights into cell-state shifts following the perturbation.

Usage

PlotTransitionVectors(
  seurat_obj,
  perturbation_name,
  color.by,
  reduction = "umap",
  n_threads = 4,
  arrow_scale = 1,
  grid_resolution = 25,
  max_pct = 0.9,
  point_alpha = 0.25,
  point_size = 1
)

Arguments

seurat_obj

A Seurat object containing single-cell data, including metadata and embeddings.

perturbation_name

A character string specifying the name of the perturbation. This is used to calculate transition vectors based on the perturbed assay.

color.by

A character string indicating the metadata column to color the scatter plot points by.

reduction

A character string specifying the name of the dimensional reduction to use for the embedding (default: 'umap').

n_threads

An integer specifying the number of threads to use for parallel processing (default: 4).

arrow_scale

A numeric value to scale the transition vectors, adjusting their length on the plot (default: 1).

grid_resolution

An integer specifying the resolution of the grid for overlaying transition vectors. A higher resolution yields a finer grid, which can provide more detailed vector placement (default: 25).

max_pct

A numeric value between 0 and 1 indicating the maximum percentile of vector lengths to display. This parameter helps limit the display of outlier vector lengths, making the plot easier to interpret (default: 0.90).

point_alpha

A numeric value controlling the transparency of scatter plot points, with 1 being fully opaque and 0 being fully transparent (default: 0.25).

point_size

A numeric value defining the size of the scatter plot points (default: 1).

Value

A ggplot object showing the scatter plot of cells colored by the specified metadata and overlaid with transition vectors indicating cell-state shifts.

Details

This function retrieves the embedding coordinates from the specified dimensional reduction in the Seurat object. It then calculates the transition vectors using PerturbationVectors, which returns vector coordinates (ars) and distances (arsd). A grid of arrows is created using grid_vectors, allowing for visual simplification of transitions by grouping vectors into a grid at the specified resolution. The resulting plot includes the scatter plot of cells with color defined by color.by and arrows showing the direction and relative magnitude of transitions.