% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/velocityplot.R
\name{VelocityPlot}
\alias{VelocityPlot}
\title{Cell velocity plot}
\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{
\item{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.}

\item{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 \code{embedding}.}

\item{plot_type}{A character string specifying the visualization method. \code{"raw"} plots arrows directly from each cell's embedding position. \code{"grid"} averages velocities onto a regular grid and plots arrows at grid points. \code{"stream"} computes smooth streamline paths from the gridded velocity field. Default is \code{"raw"}.}

\item{split_by}{Not supported for VelocityPlot. Setting this parameter will raise an error.}

\item{group_by}{An optional vector of the same length as the number of rows in \code{embedding} specifying a grouping variable for cells. When provided, arrows are colored by group using \code{group_palette}. Only applies to \code{plot_type = "raw"}; ignored with a warning for \code{"grid"} and \code{"stream"}. Default is \code{NULL}.}

\item{group_name}{A character string specifying the legend title for the grouping variable. Default is \code{"Group"}.}

\item{group_palette}{A character string specifying the color palette to use for the grouping variable. Passed to \code{\link{palette_this}}. Default is \code{"Paired"}.}

\item{group_palcolor}{An optional character vector of specific colors for the grouping variable. If \code{NULL}, colors are generated from \code{group_palette}. Default is \code{NULL}.}

\item{n_neighbors}{An integer value specifying the number of nearest neighbors for computing grid velocities. Only used when \code{plot_type} is \code{"grid"} or \code{"stream"}. Default is \code{ceiling(nrow(embedding) / 50)}.}

\item{density}{A numeric value specifying the grid density along each dimension. Only used when \code{plot_type} is \code{"grid"} or \code{"stream"}. For \code{plot_type = "raw"}, when \code{density} is between 0 and 1, it specifies the fraction of cells to randomly subsample. Default is 1.}

\item{smooth}{A numeric value specifying the standard deviation multiplier for the Gaussian kernel when averaging cell velocities onto grid points. Only used when \code{plot_type} is \code{"grid"} or \code{"stream"}. Default is 0.5.}

\item{scale}{A numeric value specifying the scaling factor for the velocity vectors. Applied to raw and grid arrows. For \code{plot_type = "stream"}, this is fixed to 1 internally. Default is 1.}

\item{min_mass}{A numeric value specifying the minimum mass threshold for retaining grid points. Only used when \code{plot_type} is \code{"grid"} or \code{"stream"}. Default is 1.}

\item{cutoff_perc}{A numeric value specifying the percentile cutoff for removing low-density grid points. Only used when \code{plot_type} is \code{"stream"}. Default is 5.}

\item{arrow_angle}{A numeric value specifying the angle of the arrowheads in degrees. Applied to \code{\link[grid]{arrow}} when \code{plot_type} is \code{"raw"} or \code{"grid"}. Default is 20.}

\item{arrow_color}{A character string specifying the color of the velocity arrows. For \code{plot_type = "stream"}, this sets only the arrowhead color. Default is \code{"black"}.}

\item{arrow_alpha}{A numeric value between 0 and 1 specifying the transparency of the velocity arrows. Only used when \code{plot_type = "raw"} or \code{"grid"}; for \code{plot_type = "stream"}, use \code{streamline_alpha} instead. Default is 1.}

\item{keep_na}{A logical or character value specifying how to handle NA values in \code{group_by}. Unlike other plot functions, VelocityPlot does not support named lists for per-column control. See \code{keep_na} in \code{common_args} for details of supported values. Default is \code{FALSE}.}

\item{keep_empty}{One of \code{FALSE}, \code{TRUE}, or \code{"level"} specifying how to handle empty factor levels in \code{group_by}. Unlike other plot functions, VelocityPlot does not support named lists for per-column control. See \code{keep_empty} in \code{common_args} for details. Default is \code{FALSE}.}

\item{streamline_l}{A numeric value specifying the integration length of the streamlines. Passed to \code{\link[metR]{geom_streamline}} as the \code{L} parameter. Default is 5.}

\item{streamline_minl}{A numeric value specifying the minimum streamline length. Shorter streamlines are not drawn. Passed to \code{\link[metR]{geom_streamline}} as the \code{min.L} parameter. Default is 1.}

\item{streamline_res}{A numeric value specifying the resolution of the streamline integration. Passed to \code{\link[metR]{geom_streamline}} as the \code{res} parameter. Default is 1.}

\item{streamline_n}{A numeric value specifying the number of streamlines to draw. Passed to \code{\link[metR]{geom_streamline}} as the \code{n} parameter. Default is 15.}

\item{streamline_width}{A numeric vector of length 2 specifying the range of line widths for streamlines. Passed to \code{scale_size(range = ...)}. Only used when \code{streamline_color} is \code{NULL}. Default is \code{c(0, 0.8)}.}

\item{streamline_alpha}{A numeric value between 0 and 1 specifying the transparency of the velocity streamlines. Default is 1.}

\item{streamline_color}{An optional character string specifying a fixed color for streamlines. When \code{NULL} (the default), streamlines are colored by velocity magnitude using \code{streamline_palette}.}

\item{streamline_palette}{A character string specifying the color palette for streamline velocity magnitude. Passed to \code{\link{palette_this}}. Only used when \code{streamline_color} is \code{NULL}. Default is \code{"RdYlBu"}.}

\item{streamline_palcolor}{An optional character vector of specific colors for the streamline velocity gradient. If \code{NULL}, colors are generated from \code{streamline_palette}. Default is \code{NULL}.}

\item{palreverse}{A logical value indicating whether to reverse the palette. Default is FALSE.}

\item{streamline_bg_color}{A character string specifying the background (outline) color applied to streamlines to create a stroke effect. Default is \code{"white"}.}

\item{streamline_bg_stroke}{A numeric value specifying the additional line width of the background stroke relative to the foreground streamline. Default is 0.5.}

\item{aspect.ratio}{A numeric value specifying the aspect ratio of the plot.}

\item{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.}

\item{subtitle}{A character string specifying the subtitle of the plot.}

\item{xlab}{A character string specifying the x-axis label.}

\item{ylab}{A character string specifying the y-axis label.}

\item{legend.position}{A character string specifying the position of the legend.
if \code{waiver()}, for single groups, the legend will be "none", otherwise "right".}

\item{legend.direction}{A character string specifying the direction of the legend.}

\item{theme}{A character string or a theme class (i.e. ggplot2::theme_classic) specifying the theme to use.
Default is "theme_this".}

\item{theme_args}{A list of arguments to pass to the theme function.}

\item{return_layer}{A logical value indicating whether to return only the ggplot layers instead of the full assembled plot. When \code{TRUE}, returns a list of ggplot layers suitable for combining with other ggplot objects. Default is \code{FALSE}.}

\item{seed}{The random seed to use. Default is 8525.}
}
\value{
A ggplot object representing the cell velocity plot, with \code{height} and \code{width} attributes set for consistent rendering. If \code{return_layer = TRUE}, returns a list of ggplot layers instead.
}
\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.
}
\section{Rendering Pipeline}{

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

\examples{
\donttest{
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)
}
}
\seealso{
\code{\link{DimPlot}} \code{\link{FeatureDimPlot}}
}
