man/plotVelocityStream.Rd
229fea0e
 % Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/plotVelocityStream.R
 \name{plotVelocityStream}
 \alias{plotVelocityStream}
 \title{Velocity stream plot in low-dimensional space}
 \usage{
 plotVelocityStream(
   sce,
   embedded,
   use.dimred = 1,
   color_by = "#444444",
   color.alpha = 0.2,
   grid.resolution = 60,
   scale = TRUE,
   stream.L = 10,
   stream.min.L = 0,
   stream.res = 4,
   stream.width = 8,
   color.streamlines = FALSE,
   color.streamlines.map = c("#440154", "#482576", "#414487", "#35608D", "#2A788E",
     "#21908C", "#22A884", "#43BF71", "#7AD151", "#BBDF27", "#FDE725"),
   arrow.angle = 8,
   arrow.length = 0.8
 )
 }
 \arguments{
 \item{sce}{A \linkS4class{SingleCellExperiment} object containing
 low-dimensional coordinates, e.g., after t-SNE, in its
 \code{\link{reducedDims}}.}
 
 \item{embedded}{A low-dimensional projection of the velocity vectors into the
 embedding of \code{sce}. This should be of the same dimensions as \code{sce}
 and is typically produced by \code{\link{embedVelocity}}.}
 
 \item{use.dimred}{String or integer scalar specifying the reduced dimensions
 to retrieve from \code{sce}.}
 
 \item{color_by}{A character scalar specifying a column in \code{colData(sce)}
 to color cells in the phase graph. Alternatively, \code{color_by} can be
 set to a valid R color to be used to color cells.}
 
 \item{color.alpha}{An integer scalar giving the transparency of colored
 cells. Possible values are between 0 (fully transparent) and 1.0 (opaque).}
 
 \item{grid.resolution}{Integer scalar specifying the resolution of the grid,
 in terms of the number of grid intervals along each axis.}
 
 \item{scale}{Logical scalar indicating whether the averaged vectors should be
 scaled by the grid resolution.}
 
 \item{stream.L}{Integer scalar giving the typical length of a streamline
 low-dimensional space units.}
 
 \item{stream.min.L}{A numeric scalar with the minimum length of segments to be shown.}
 
 \item{stream.res}{Numeric scalar specifying the resolution of estimated
 streamlines (higher numbers increase smoothness of lines but also the time
 for computation).}
 
 \item{stream.width}{A numeric scalar controlling the width of streamlines.}
 
 \item{color.streamlines}{Logical scalar. If \code{TRUE} streamlines will
 be colored by local velocity. Arrows cannot be shown in that case.}
 
 \item{color.streamlines.map}{A character vector specifying the
 color range used for mapping local velocities to streamline colors. The
 default is \code{viridisLite::viridis(11)}.}
 
 \item{arrow.angle, arrow.length}{Numeric scalars giving the \code{angle} and
 \code{length} of arrowheads.}
 }
 \value{
 A \code{ggplot2} object with the streamline plot.
 }
 \description{
 Plot velocities embedded into low-dimensional space as a stream plot. Stream
 lines are lines that follow the gradient in the velocity field and illustrate
 paths that cells could follow based on observed RNA velocities.
 }
 \details{
 \code{grid.resolution} and \code{scale} are passed to
   \code{\link{gridVectors}}, which is used to summarized the velocity vectors
   into an initial grid. A full regular grid is computed from that and used
   in \code{\link[metR]{geom_streamline}} to calculate streamlines. The
   following arguments are passed to the arguments given in parenthesis of
   \code{\link[metR]{geom_streamline}}:
   \code{stream.L} (\code{L}), \code{stream.res} (\code{res}),
   \code{stream.min.L} (\code{min.L}), \code{arrow.angle} (\code{arrow.angle})
   and \code{arrow.length} (\code{arrow.length}).
   Streamlines are computed by simple integration with a forward Euler method,
   and \code{stream.L} and \code{stream.res} are used to compute the number of
   steps and the time interval between steps for the integration.
   \code{stream.width} is multiplied with \code{..step..} estimated by
   \code{\link[metR]{geom_streamline}} to control the width of streamlines.
 }
 \examples{
 library(scuttle)
 set.seed(42)
 sce1 <- mockSCE(ncells = 100, ngenes = 500)
 sce2 <- mockSCE(ncells = 100, ngenes = 500)
 
 datlist <- list(X=counts(sce1), spliced=counts(sce1), unspliced=counts(sce2))
 
 out <- scvelo(datlist, mode = "dynamical")
 
 em <- embedVelocity(reducedDim(out, 1), out)[,1:2]
 
 plotVelocityStream(out, em)
 plotVelocityStream(out, em, color.streamlines = TRUE)
 
 }
 \seealso{
 \code{\link{gridVectors}} used to summarize velocity vectors into
   a grid (velocity field), the \pkg{ggplot2} package used for plotting,
   \code{\link[metR]{geom_streamline}} in package \pkg{metR} used to
   calculate and add streamlines from the RNA velocity field to the plot,
   \code{\link[viridisLite]{viridis}} for creation of color palettes.
 }
 \author{
 Michael Stadler
 }