VelocityPlot: Cell velocity plot
In plotthis: High-Level Plotting Built Upon 'ggplot2' and Other Plotting Packages

VelocityPlot

R Documentation

Cell velocity plot

Description

Plots RNA velocity vectors on a low-dimensional embedding (e.g., UMAP, t-SNE) to visualize the direction and magnitude of cellular state transitions. Supports three visualization modes: raw arrows at each cell position, arrows on a regular grid, and streamline paths. Optionally colors arrows by cell metadata groups.

Usage

VelocityPlot(
  embedding,
  v_embedding,
  plot_type = c("raw", "grid", "stream"),
  split_by = NULL,
  group_by = NULL,
  group_name = "Group",
  group_palette = "Paired",
  group_palcolor = NULL,
  n_neighbors = NULL,
  density = 1,
  smooth = 0.5,
  scale = 1,
  min_mass = 1,
  cutoff_perc = 5,
  arrow_angle = 20,
  arrow_color = "black",
  arrow_alpha = 1,
  keep_na = FALSE,
  keep_empty = FALSE,
  streamline_l = 5,
  streamline_minl = 1,
  streamline_res = 1,
  streamline_n = 15,
  streamline_width = c(0, 0.8),
  streamline_alpha = 1,
  streamline_color = NULL,
  streamline_palette = "RdYlBu",
  streamline_palcolor = NULL,
  palreverse = FALSE,
  streamline_bg_color = "white",
  streamline_bg_stroke = 0.5,
  aspect.ratio = 1,
  title = "Cell velocity",
  subtitle = NULL,
  xlab = NULL,
  ylab = NULL,
  legend.position = "right",
  legend.direction = "vertical",
  theme = "theme_this",
  theme_args = list(),
  return_layer = FALSE,
  seed = 8525
)

Arguments

`embedding`	A matrix or data frame of dimension n_obs x n_dim specifying the low-dimensional embedding coordinates (e.g., UMAP, t-SNE) of the cells. The first two columns are used for the x and y axes.
`v_embedding`	A matrix or data frame of dimension n_obs x n_dim specifying the velocity vectors for each cell. Must have the same dimensions as `embedding`.
`plot_type`	A character string specifying the visualization method. `"raw"` plots arrows directly from each cell's embedding position. `"grid"` averages velocities onto a regular grid and plots arrows at grid points. `"stream"` computes smooth streamline paths from the gridded velocity field. Default is `"raw"`.
`split_by`	Not supported for VelocityPlot. Setting this parameter will raise an error.
`group_by`	An optional vector of the same length as the number of rows in `embedding` specifying a grouping variable for cells. When provided, arrows are colored by group using `group_palette`. Only applies to `plot_type = "raw"`; ignored with a warning for `"grid"` and `"stream"`. Default is `NULL`.
`group_name`	A character string specifying the legend title for the grouping variable. Default is `"Group"`.
`group_palette`	A character string specifying the color palette to use for the grouping variable. Passed to `palette_this`. Default is `"Paired"`.
`group_palcolor`	An optional character vector of specific colors for the grouping variable. If `NULL`, colors are generated from `group_palette`. Default is `NULL`.
`n_neighbors`	An integer value specifying the number of nearest neighbors for computing grid velocities. Only used when `plot_type` is `"grid"` or `"stream"`. Default is `ceiling(nrow(embedding) / 50)`.
`density`	A numeric value specifying the grid density along each dimension. Only used when `plot_type` is `"grid"` or `"stream"`. For `plot_type = "raw"`, when `density` is between 0 and 1, it specifies the fraction of cells to randomly subsample. Default is 1.
`smooth`	A numeric value specifying the standard deviation multiplier for the Gaussian kernel when averaging cell velocities onto grid points. Only used when `plot_type` is `"grid"` or `"stream"`. Default is 0.5.
`scale`	A numeric value specifying the scaling factor for the velocity vectors. Applied to raw and grid arrows. For `plot_type = "stream"`, this is fixed to 1 internally. Default is 1.
`min_mass`	A numeric value specifying the minimum mass threshold for retaining grid points. Only used when `plot_type` is `"grid"` or `"stream"`. Default is 1.
`cutoff_perc`	A numeric value specifying the percentile cutoff for removing low-density grid points. Only used when `plot_type` is `"stream"`. Default is 5.
`arrow_angle`	A numeric value specifying the angle of the arrowheads in degrees. Applied to `arrow` when `plot_type` is `"raw"` or `"grid"`. Default is 20.
`arrow_color`	A character string specifying the color of the velocity arrows. For `plot_type = "stream"`, this sets only the arrowhead color. Default is `"black"`.
`arrow_alpha`	A numeric value between 0 and 1 specifying the transparency of the velocity arrows. Only used when `plot_type = "raw"` or `"grid"`; for `plot_type = "stream"`, use `streamline_alpha` instead. Default is 1.
`keep_na`	A logical or character value specifying how to handle NA values in `group_by`. Unlike other plot functions, VelocityPlot does not support named lists for per-column control. See `keep_na` in `common_args` for details of supported values. Default is `FALSE`.
`keep_empty`	One of `FALSE`, `TRUE`, or `"level"` specifying how to handle empty factor levels in `group_by`. Unlike other plot functions, VelocityPlot does not support named lists for per-column control. See `keep_empty` in `common_args` for details. Default is `FALSE`.
`streamline_l`	A numeric value specifying the integration length of the streamlines. Passed to `geom_streamline` as the `L` parameter. Default is 5.
`streamline_minl`	A numeric value specifying the minimum streamline length. Shorter streamlines are not drawn. Passed to `geom_streamline` as the `min.L` parameter. Default is 1.
`streamline_res`	A numeric value specifying the resolution of the streamline integration. Passed to `geom_streamline` as the `res` parameter. Default is 1.
`streamline_n`	A numeric value specifying the number of streamlines to draw. Passed to `geom_streamline` as the `n` parameter. Default is 15.
`streamline_width`	A numeric vector of length 2 specifying the range of line widths for streamlines. Passed to `scale_size(range = ...)`. Only used when `streamline_color` is `NULL`. Default is `c(0, 0.8)`.
`streamline_alpha`	A numeric value between 0 and 1 specifying the transparency of the velocity streamlines. Default is 1.
`streamline_color`	An optional character string specifying a fixed color for streamlines. When `NULL` (the default), streamlines are colored by velocity magnitude using `streamline_palette`.
`streamline_palette`	A character string specifying the color palette for streamline velocity magnitude. Passed to `palette_this`. Only used when `streamline_color` is `NULL`. Default is `"RdYlBu"`.
`streamline_palcolor`	An optional character vector of specific colors for the streamline velocity gradient. If `NULL`, colors are generated from `streamline_palette`. Default is `NULL`.
`palreverse`	A logical value indicating whether to reverse the palette. Default is FALSE.
`streamline_bg_color`	A character string specifying the background (outline) color applied to streamlines to create a stroke effect. Default is `"white"`.
`streamline_bg_stroke`	A numeric value specifying the additional line width of the background stroke relative to the foreground streamline. Default is 0.5.
`aspect.ratio`	A numeric value specifying the aspect ratio of the plot.
`title`	A character string specifying the title of the plot. A function can be used to generate the title based on the default title. This is useful when split_by is used and the title needs to be dynamic.
`subtitle`	A character string specifying the subtitle of the plot.
`xlab`	A character string specifying the x-axis label.
`ylab`	A character string specifying the y-axis label.
`legend.position`	A character string specifying the position of the legend. if `waiver()`, for single groups, the legend will be "none", otherwise "right".
`legend.direction`	A character string specifying the direction of the legend.
`theme`	A character string or a theme class (i.e. ggplot2::theme_classic) specifying the theme to use. Default is "theme_this".
`theme_args`	A list of arguments to pass to the theme function.
`return_layer`	A logical value indicating whether to return only the ggplot layers instead of the full assembled plot. When `TRUE`, returns a list of ggplot layers suitable for combining with other ggplot objects. Default is `FALSE`.
`seed`	The random seed to use. Default is 8525.

Value

A ggplot object representing the cell velocity plot, with height and width attributes set for consistent rendering. If return_layer = TRUE, returns a list of ggplot layers instead.

Rendering Pipeline

The VelocityPlot function proceeds through the following steps:

Input validation — Verifies that embedding and v_embedding are matrices or data frames of equal dimensions, that group_by matches the number of rows (if provided), and that split_by is NULL (unsupported and raises an error).
Axis label resolution — Uses the column names of embedding as axis labels, falling back to "Reduction 1" and "Reduction 2" when column names are NULL.
Grouping setup — Converts group_by to a factor and applies keep_na / keep_empty logic to filter or recode missing values and empty factor levels.
Plot-type dispatch — Branches on plot_type:
- raw — Optionally subsamples cells when density < 1, scales velocity vectors by scale, computes arrow lengths proportional to the embedding range, and renders geom_segment with arrowheads. When group_by is provided, arrows are colored by group using group_palette.
- grid — Delegates to .compute_velocity_on_grid to interpolate the sparse cell velocities onto a regular grid, then renders geom_segment with arrowheads at each grid point. group_by is ignored with a warning.
- stream — Delegates to .compute_velocity_on_grid with adjust_for_stream = TRUE, then renders smooth streamline paths via geom_streamline. When streamline_color is provided, streamlines use a fixed color with a background stroke; when NULL, streamlines are colored by velocity magnitude using streamline_palette. group_by is ignored with a warning.
Layer return or plot assembly — If return_layer = TRUE, returns the list of ggplot layers. Otherwise, constructs a full ggplot object with labels, theme, aspect ratio, legend configuration, and height / width attributes via calculate_plot_dimensions().

Examples


data(dim_example)
dim_example$clusters[dim_example$clusters == "Ductal"] <- NA

# Basic velocity plot with group coloring
VelocityPlot(dim_example[, 1:2], dim_example[, 3:4], group_by = dim_example$clusters)

# Handle NA groups with keep_na / keep_empty
VelocityPlot(dim_example[, 1:2], dim_example[, 3:4], group_by = dim_example$clusters,
    keep_na = TRUE, keep_empty = TRUE)
VelocityPlot(dim_example[, 1:2], dim_example[, 3:4], group_by = dim_example$clusters,
    keep_na = TRUE, keep_empty = 'level')
VelocityPlot(dim_example[, 1:2], dim_example[, 3:4], group_by = dim_example$clusters,
    keep_na = TRUE, keep_empty = FALSE)

plotthis documentation built on July 9, 2026, 5:07 p.m.