Browse code

Add plotting functions to visualize RNA velocities (#30)

* add plotVelocity

* add return.intermediates argument to gridVectors

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

* add plotVelocityStream

* fix minor issues and asthetics

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

* add metR to Imports

* 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

* add missing ggplot2::

* 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

* fix NOTE about requireNamespace

* use identical() instead of == when a single logical is expected

Co-authored-by: Kevin Rue <kevinrue67@gmail.com>

Michael Stadler authored on 21/02/2021 11:55:35 • GitHub committed on 21/02/2021 11:55:35
Showing1 changed files
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
+}