#### Add plotting functions to visualize RNA velocities (#30)

* add return.intermediates argument to gridVectors

* add tests for gridVectors(..., return.intermediates=TRUE)

* fix minor issues and asthetics

* add ggplot2 to Depends (required by metR::geom_streamline)

* import all of ggplot2

* add tests for plotting functions

* add tests for new utils

* improve test coverage

* move requirements for plotting to Suggests

* do not plot or test without installed requirments

* replace "colour" by "color"

* use sym() in ggplot2::aes

* move specific helpers to plotVelocity.R

* remove or replace .isValidColor in plotVelocityStream

* move .isValidColor from utils.R to plotVelocity.R

* remove empty test file

* remove or replace .isValidColor

* remove redundant checks

* use ggplot2/patchwork in plotVelocity instead of base graphics

* hide non-standard evaluation from R CMD check

* dummy push to trigger new build on gha

* use ggplot2::stat for double-dot aesthetics

* dummy push to trigger new build on gha

* add tests to improve coverage

 1 1 new file mode 100644 ... ... @@ -0,0 +1,121 @@ 1 +% Generated by roxygen2: do not edit by hand 2 +% Please edit documentation in R/plotVelocityStream.R 3 +\name{plotVelocityStream} 4 +\alias{plotVelocityStream} 5 +\title{Velocity stream plot in low-dimensional space} 6 +\usage{ 7 +plotVelocityStream( 8 + sce, 9 + embedded, 10 + use.dimred = 1, 11 + color_by = "#444444", 12 + color.alpha = 0.2, 13 + grid.resolution = 60, 14 + scale = TRUE, 15 + stream.L = 10, 16 + stream.min.L = 0, 17 + stream.res = 4, 18 + stream.width = 8, 19 + color.streamlines = FALSE, 20 + color.streamlines.map = c("#440154", "#482576", "#414487", "#35608D", "#2A788E", 21 + "#21908C", "#22A884", "#43BF71", "#7AD151", "#BBDF27", "#FDE725"), 22 + arrow.angle = 8, 23 + arrow.length = 0.8 24 +) 25 +} 26 +\arguments{ 27 +\item{sce}{A \linkS4class{SingleCellExperiment} object containing 28 +low-dimensional coordinates, e.g., after t-SNE, in its 29 +\code{\link{reducedDims}}.} 30 + 31 +\item{embedded}{A low-dimensional projection of the velocity vectors into the 32 +embedding of \code{sce}. This should be of the same dimensions as \code{sce} 33 +and is typically produced by \code{\link{embedVelocity}}.} 34 + 35 +\item{use.dimred}{String or integer scalar specifying the reduced dimensions 36 +to retrieve from \code{sce}.} 37 + 38 +\item{color_by}{A character scalar specifying a column in \code{colData(sce)} 39 +to color cells in the phase graph. Alternatively, \code{color_by} can be 40 +set to a valid R color to be used to color cells.} 41 + 42 +\item{color.alpha}{An integer scalar giving the transparency of colored 43 +cells. Possible values are between 0 (fully transparent) and 1.0 (opaque).} 44 + 45 +\item{grid.resolution}{Integer scalar specifying the resolution of the grid, 46 +in terms of the number of grid intervals along each axis.} 47 + 48 +\item{scale}{Logical scalar indicating whether the averaged vectors should be 49 +scaled by the grid resolution.} 50 + 51 +\item{stream.L}{Integer scalar giving the typical length of a streamline 52 +low-dimensional space units.} 53 + 54 +\item{stream.min.L}{A numeric scalar with the minimum length of segments to be shown.} 55 + 56 +\item{stream.res}{Numeric scalar specifying the resolution of estimated 57 +streamlines (higher numbers increase smoothness of lines but also the time 58 +for computation).} 59 + 60 +\item{stream.width}{A numeric scalar controlling the width of streamlines.} 61 + 62 +\item{color.streamlines}{Logical scalar. If \code{TRUE} streamlines will 63 +be colored by local velocity. Arrows cannot be shown in that case.} 64 + 65 +\item{color.streamlines.map}{A character vector specifying the 66 +color range used for mapping local velocities to streamline colors. The 67 +default is \code{viridisLite::viridis(11)}.} 68 + 69 +\item{arrow.angle, arrow.length}{Numeric scalars giving the \code{angle} and 70 +\code{length} of arrowheads.} 71 +} 72 +\value{ 73 +A \code{ggplot2} object with the streamline plot. 74 +} 75 +\description{ 76 +Plot velocities embedded into low-dimensional space as a stream plot. Stream 77 +lines are lines that follow the gradient in the velocity field and illustrate 78 +paths that cells could follow based on observed RNA velocities. 79 +} 80 +\details{ 81 +\code{grid.resolution} and \code{scale} are passed to 82 + \code{\link{gridVectors}}, which is used to summarized the velocity vectors 83 + into an initial grid. A full regular grid is computed from that and used 84 + in \code{\link[metR]{geom_streamline}} to calculate streamlines. The 85 + following arguments are passed to the arguments given in parenthesis of 86 + \code{\link[metR]{geom_streamline}}: 87 + \code{stream.L} (\code{L}), \code{stream.res} (\code{res}), 88 + \code{stream.min.L} (\code{min.L}), \code{arrow.angle} (\code{arrow.angle}) 89 + and \code{arrow.length} (\code{arrow.length}). 90 + Streamlines are computed by simple integration with a forward Euler method, 91 + and \code{stream.L} and \code{stream.res} are used to compute the number of 92 + steps and the time interval between steps for the integration. 93 + \code{stream.width} is multiplied with \code{..step..} estimated by 94 + \code{\link[metR]{geom_streamline}} to control the width of streamlines. 95 +} 96 +\examples{ 97 +library(scuttle) 98 +set.seed(42) 99 +sce1 <- mockSCE(ncells = 100, ngenes = 500) 100 +sce2 <- mockSCE(ncells = 100, ngenes = 500) 101 + 102 +datlist <- list(X=counts(sce1), spliced=counts(sce1), unspliced=counts(sce2)) 103 + 104 +out <- scvelo(datlist, mode = "dynamical") 105 + 106 +em <- embedVelocity(reducedDim(out, 1), out)[,1:2] 107 + 108 +plotVelocityStream(out, em) 109 +plotVelocityStream(out, em, color.streamlines = TRUE) 110 + 111 +} 112 +\seealso{ 113 +\code{\link{gridVectors}} used to summarize velocity vectors into 114 + a grid (velocity field), the \pkg{ggplot2} package used for plotting, 115 + \code{\link[metR]{geom_streamline}} in package \pkg{metR} used to 116 + calculate and add streamlines from the RNA velocity field to the plot, 117 + \code{\link[viridisLite]{viridis}} for creation of color palettes. 118 +} 119 +\author{ 120 +Michael Stadler 121 +}