Merge branch 'main' into gh-pages

Author: mvfki

NAMESPACE

@@ -12,9 +12,11 @@ S3method(plotBinary,simMat)
 S3method(plotQuaternary,Seurat)
 S3method(plotQuaternary,SingleCellExperiment)
 S3method(plotQuaternary,default)
+S3method(plotQuaternary,simMat)
 S3method(plotTernary,Seurat)
 S3method(plotTernary,SingleCellExperiment)
 S3method(plotTernary,default)
+S3method(plotTernary,simMat)
 S3method(print,quatPlot)
 S3method(selectTopFeatures,Seurat)
 S3method(selectTopFeatures,SingleCellExperiment)

NEWS.md

@@ -1,11 +1,12 @@
-## CytoSimplex 0.1.99
+## CytoSimplex 0.2.0
 
 - Added support for coloring dots by categorical or continuous variable, with options to use customized or built-in color palettes.
 - Changed interactive 3D support of quaternary simplex plot from *rgl* to *plotly*. Now the default is `interactive = TRUE` for `plotQuaternary()` and it returns a `plotly` object.
 - Added interactive support for ternary simplex plot, using plotly, triggered with `interactive = TRUE`
 - Fixed wilcoxon bug
 - Added `readH5ADObsNames()`, `readH5ADObsVar()`, `readH5ADUnsSpMat()`, `readVelocytoLoom()` for loading commonly seen necessary information from H5AD and LOOM files of RNA velocity analysis
 - Added example tutorial for HSPC analysis in the manuscript
+- Fixed error in `plotQuaternary()`
 
 ## CytoSimplex 0.1.1
 

R/data.R

@@ -1,5 +1,5 @@
 #' Mouse bone marrow scRNAseq example data
-#' @format \linkS4class{dgCMatrix} object
+#' @format \link[Matrix]{dgCMatrix-class} object
 #' @source https://www.nature.com/articles/s41467-023-38034-2
 #' @references Matsushita, Y., Liu, J., Chu, A.K.Y. et al. Bone marrow endosteal
 #' stem cells dictate active osteogenesis and aggressive tumorigenesis. Nat
@@ -15,7 +15,7 @@
 "rnaCluster"
 
 #' Velocity graph of the example mouse bone marrow data
-#' @format \linkS4class{dgCMatrix} object
+#' @format \link[Matrix]{dgCMatrix-class} object
 #' @source https://www.nature.com/articles/s41467-023-38034-2
 #' @references Matsushita, Y., Liu, J., Chu, A.K.Y. et al. Bone marrow endosteal
 #' stem cells dictate active osteogenesis and aggressive tumorigenesis. Nat

R/quaternary.R

@@ -368,6 +368,7 @@ plotQuaternary.SingleCellExperiment <- function(
 #' @param ... Not used
 #' @method plotQuaternary simMat
 #' @return A "quatPlot" object, can be displayed by printing.
+#' @export
 plotQuaternary.simMat <- function(
         x,
         veloMat = NULL,

R/ternary.R

@@ -380,6 +380,7 @@ plotTernary.SingleCellExperiment <- function(
 #' Default \code{FALSE}.
 #' @param ... Not used
 #' @method plotTernary simMat
+#' @export
 plotTernary.simMat <- function(
         x,
         title = NULL,
@@ -655,13 +656,14 @@ plotTernary.simMat <- function(
     dotSize <- dotSize %||% 4
     arrowLinewidth <- arrowLinewidth %||% 2
     df <- as.data.frame(as.matrix(x[,1:3]))
+    hoverDF <- cbind(ID = rownames(x), df)
     legendTitle <- colorArg$palette$legendTitle
     if (colorArg$type == "categorical") {
         df[[legendTitle]] <- colorArg$colorBy
         fig <- plotly::plot_ly(
             data = df, type = "scatterternary", mode = "markers",
             a = I(df[[1]]), b = I(df[[2]]), c = I(df[[3]]),
-            hovertemplate = .plotly_formatCustomData(df),
+            hovertemplate = .plotly_formatCustomData(hoverDF),
             color = stats::formula(paste0("~", legendTitle)),
             colors = colorArg$palette$colors,
             marker = list(
@@ -674,7 +676,7 @@ plotTernary.simMat <- function(
         fig <- plotly::plot_ly(
             data = df, type = "scatterternary", mode = "markers",
             a = I(df[[1]]), b = I(df[[2]]), c = I(df[[3]]),
-            hovertemplate = .plotly_formatCustomData(df),
+            hovertemplate = .plotly_formatCustomData(hoverDF),
             marker = list(
                 color = stats::formula(paste0("~", legendTitle)),
                 autocolorscale = FALSE,
@@ -696,7 +698,7 @@ plotTernary.simMat <- function(
         fig <- plotly::plot_ly(
             data = df, type = "scatterternary", mode = "markers",
             a = I(df[[1]]), b = I(df[[2]]), c = I(df[[3]]),
-            hovertemplate = .plotly_formatCustomData(df),
+            hovertemplate = .plotly_formatCustomData(hoverDF),
             marker = list(
                 color = colorArg$colors,
                 size = dotSize

_pkgdown.yml

@@ -14,7 +14,11 @@ navbar:
     - text: API
       href: reference/index.html
     - text: Changelog
-      href: NEWS.html
+      href: news/index.html
   right:
+    - text: Welch Lab
+      href: https://welch-lab.github.io/
     - icon: fab fa-github fa-lg
       href: https://github.com/welch-lab/CytoSimplex
+    - icon: fab fa-twitter fa-lg
+      href: https://twitter.com/LabWelch

man/rnaRaw.Rd

@@ -1,7 +1,7 @@
 ---
 title: "Simplex Visualization of Cell Fate Similarity in Single-Cell Data"
 author: "Yichen Wang, Jialin Liu"
-date: "2023-05-15"
+date: "2024-04-22"
 output: rmarkdown::html_vignette
 vignette: >
   %\VignetteIndexEntry{Simplex Visualization of Cell Fate Similarity in Single-Cell Data}
@@ -49,14 +49,25 @@ head(stats)
 
 ## Generating ternary plots
 
-`plotTernary()` shows sample similarity in a ternary simplex -- equilateral triangle. The closer a dot, a cell, is to one vertex, the more similar the cell is to the cell cluster(s) the vertex represents. We recommend that users select the top marker genes for each terminal and only use them is the features for calculating the similarity.
+`plotTernary()` shows sample similarity in a ternary simplex -- equilateral triangle. The closer a dot, a cell, is to one vertex, the more similar the cell is to the cell cluster(s) the vertex represents. We recommend that users select the top marker genes for each terminal and only use them as the features for calculating the similarity.
 
 ```{R plotTernary, fig.height = 4, fig.width = 5}
 vt.tern <- c("OS", "RE", "CH")
 gene.tern <- selectTopFeatures(rnaRaw, clusterVar = rnaCluster, vertices = vt.tern)
 plotTernary(rnaRaw, clusterVar = rnaCluster, vertices = vt.tern, features = gene.tern)
 ```
 
+>The static figure depends on `ggplot2`, which is widely used for visualization in R. The binary simplex is plotted normally in ggplot 2D coordinates, while for the ternary simplex, the barycentric coordinate is drawn with 2D segments with cartesian coordinate, instead of implementing a ternary barycentric coordinate system. Users wishing to add customized alteration should pay attention to this.
+
+### Interactive ternary plot
+
+The same figure above can be shown in an interactive panel, powered by [plotly](https://plotly.com/r/). The interactive plot allows users to zoom in and out, and hover over the dots to see the cell names and the values of inferred similarity. To enable this feature, users only need to add `interactive = TRUE` in the function call. 
+
+```{R plotTernaryInteractive, fig.height = 4, fig.width = 5}
+plotTernary(rnaRaw, clusterVar = rnaCluster, vertices = vt.tern, features = gene.tern, 
+            interactive = TRUE)
+```
+
 ## Adding velocity information to ternary plot
 
 RNA velocity is a quantitative measurement of cellular transitions from single-cell transcriptomics experiments and reveals transient cellular dynamics among a heterogeneous cell population (<a href="https://www.pnas.org/doi/10.1073/pnas.2105859118" target="_blank">Qiao, PNAS 2021</a>). We implemented a velocity visualization strategy that could be applied to ternary and quaternary simplex plot. The velocity information input format must be an N x N graph (sparse matrix, where N denotes number of cells). We have included a graph that matches with the cells in the example dataset in this package. This graph is a subset of the output from <a href="https://github.com/welch-lab/VeloVAE" target="_black">Python module `veloVAE`</a>, as part of the processed data from the publication mentioned at the start. 
@@ -69,13 +80,13 @@ print(paste0("Class of `rnaVelo`: ", class(rnaVelo),
 
 We create a number of square grids in the 2D plain of the ternary simplex (or cube grids in 3D space of the quaternary simplex), and aggregate the cells fall into each grid with taking the mean of velocity towards each of the vertices. Finally, we draw an arrow from the grid center pointing to each vertex with the length representing the aggregated mean velocity. 
 
+Interactive view with velocity information is also supported. The aggregated potential value can also be shown when hovering above the arrows.
+
 ```{R ternVelo, fig.width = 5, fig.height = 4}
 plotTernary(rnaRaw, clusterVar = rnaCluster, vertices = vt.tern, 
-            features = gene.tern, veloGraph = rnaVelo)
+            features = gene.tern, veloGraph = rnaVelo, interactive = TRUE)
 ```
 
->The previous two functions mainly depends of `ggplot2`, which is widely used to create figures in R. The binary simplex is plotted normally in ggplot 2D coordinates, while for the ternary simplex, the barycentric coordinate is drawn with 2D segments with cartesian coordinate, instead of implementing a ternary barycentric coordinate system. Users wishing to add customized alteration should pay attention to this.
-
 ## Exploration with each cluster
 
 An argument `splitCluster` is supported for all three plotting functions. By setting `splitCluster = TRUE`, A list of plots will be returned, with one containing all cells, and each of the other sub-plots containing only dots (cells) belonging to one cluster in the annotation specified. 
@@ -104,9 +115,7 @@ As shown in the subplots, the OCT stem cells has the transitional potential towa
 
 ## Create quaternary simplex plot
 
-`plotQuaternary()` shows sample similarity in a quaternary simplex -- tetrahedron. The 3D visualization depends on package `plot3D` for creating static figure, and `rgl` for creating interactive 3D display. (Linux users may refer to [`rgl` documentation](https://dmurdoch.github.io/rgl/#installing-opengl-support) for installation guide) 
-
-For a quaternary simplex, we need one more cluster as a vertex. Here, we add the cells annotated as osteoblast-reticular transition cells (`"ORT"`) into the vertex list. We also add the velocity information in this example, as it will not be shown by default.
+For a quaternary simplex, we need one more cluster as a vertex. Here, we add the cells annotated as osteoblast-reticular transition cells (`"ORT"`) into the vertex list. We also add the velocity information in this example, as it will not be shown by default. Note that we provide interactive quaternary plot by default.
 
 ```{R plotQuaternary, fig.height = 4, fig.width = 6}
 vt.quat <- c("OS", "RE", "CH", "ORT")
@@ -115,7 +124,7 @@ plotQuaternary(rnaRaw, clusterVar = rnaCluster, vertices = vt.quat,
                features = gene.quat, veloGraph = rnaVelo)
 ```
 
-The 3D tetrahedron shown is automatically generated with an **interactive** web widget. If a static view is preferred, users can set `interactive = FALSE` in the function call, and adjust the view angle with `theta` and `phi` arguments.
+If a static view is preferred, users can set `interactive = FALSE` in the function call, and adjust the view angle with `theta` and `phi` arguments.
 
 We have also implemented of GIF image generator that rotates the tetrahedron rounding the z-axis. Note that package `magick` is required for this feature. (<a href="https://cran.r-project.org/package=magick/vignettes/intro.html#Installing_magick" target="_blank">See here for how to install `magick` in detail</a>)