Merge pull request #28 from boyiguo1/v1.2.0

V1.2.0

R/make_escheR.R

@@ -32,10 +32,23 @@
 #'
 #' @examples
 #' library(STexampleData)
-#'
+#' # SpatialExperiment Object
 #' spe <- Visium_humanDLPFC()
-#'
 #' make_escheR(spe)
+#'
+#' # SingleCellExperiment Object
+#' sce <- SingleCellExperiment(counts(spe))
+#' reducedDims(sce) <- list(
+#'    # Example embedding
+#'     EG = matrix(seq.int(1, ncol(spe)*2), ncol = 2)
+#'     )
+#' make_escheR(sce, dimred = "EG")
+#'
+#' # data.frame Object
+#' x <- spatialCoords(spe)[,1]
+#' y <- spatialCoords(spe)[,2]
+#' df <- colData(spe) |> data.frame()
+#' make_escheR(object = df, .x = x , .y = y)
 make_escheR <- function(object, spot_size = 2, ...) {
   UseMethod("make_escheR", object)
 }
@@ -80,8 +93,8 @@ make_escheR.SingleCellExperiment <- function(
          " is not found in reducedDim(object).")
 
 
-  if(ncol(reducedDim(sce, dimred)) <= 2)
-    stop("reducedDim(object, ", dimred, " ) must have more than 2 columns.")
+  if(ncol(reducedDim(sce, dimred)) < 2)
+    stop("reducedDim(object, ", dimred, " ) must have at least 2 columns.")
 
   # TODO (Medium): How about dimension reduction assays?
   coord_df <- reducedDim(sce, dimred)[ , c(1,2), drop = FALSE]
@@ -135,14 +148,11 @@ make_escheR.SpatialExperiment <- function(
     object,
     spot_size = 2,
     dimred=NULL,
-    # assay_name = "counts",
     y_reverse = TRUE,
     ...) {
 
 
-  # TODO (must): To plot low dimension embeddings
   if(!is.null(dimred)){
-    # TODO (must): does it work? Test it via low dimensional embeddings vignettes
     return(
       make_escheR.SingleCellExperiment(
         object = object,
@@ -230,7 +240,7 @@ make_escheR.SpatialExperiment <- function(
     # TODO (medium): maybe move the theme to an outside function
     xlab("") +
     ylab("") #+
-    # coord_fixed() +
+    coord_fixed()
     # theme_void() #+
   # theme_set(theme_bw(base_size = 20)) +
   # theme(
@@ -249,9 +259,9 @@ make_escheR.SpatialExperiment <- function(
   # Inspiration from
   # https://github.com/lmweber/ggspavis/blob/004e1528829641cd2112e4264bb7fb708316c0e5/R/plotSpots.R#L102
   # This could move out of the function to the cotumization part I think.
-  # if(y_reverse){
-  #   p <- p + scale_y_reverse()
-  # }
+  if(y_reverse){
+    p <- p + scale_y_reverse()
+  }
 
 
 
@@ -287,11 +297,8 @@ make_escheR.data.frame <- function(
         y = .data$.y
       )
     ) +
-    # TODO (medium): maybe move the theme to an outside function
     xlab("") +
-    ylab("")# +
-    # coord_fixed() +
-    # theme_void() #+
+    ylab("")
 
 }
 

README.md

@@ -51,26 +51,58 @@ devtools::install_github("boyiguo1/[email protected]")
 Please find an end-to-end tutorial at [https://boyiguo1.github.io/escheR/](https://boyiguo1.github.io/escheR/articles/SRT_eg.html)
 
 ## Syntax
-![](man/figures/escheR_syntax.pdf)
+![](man/figures/syntax.png)
 
 # Frequently Asked Questions
 
 * Can I use `escheR` on `SingleCellExperiment` object?
 
+  Yes. Starting from Version 1.2.0, `escheR` supports the visualization of 
+  dimensionality reduced embeddings of a `SingleCellExperiment` object by
+  providing values to the argument `dimred`. For more information, please see
+  [Beyond Sequence-based Spatially-Resolved Data](https://boyi-guo.com/escheR/articles/more_than_visium.html#visualized-dimensionality-reduced-embedding-with-singlecellexperiment).
+
 * How can I make plots to visualize dimensional reduced embeddings?
 
-* Can I highlight only one group/level of a multi-level categorical variables?
+  Yes, you can provide a string value to the`dimred` argument. The string value
+  should be included in `reducedDimNames(object)`. For more information, please
+  see [Beyond Sequence-based Spatially-Resolved Data](https://boyi-guo.com/escheR/articles/more_than_visium.html#visualized-dimensionality-reduced-embedding-with-singlecellexperiment).
+
+* Can I highlight only a subset of groups/levels for a categorical variables?
+
+  Yes, please find the example in [Adjusting aesthetics](https://boyi-guo.com/escheR/articles/SRT_eg.html#adjusting-aesthetics).
 
 * Can `escheR` be directly applied to `Seurat` or `Giotto` objects?
 
+  Unfortunately, `Seurat` or `Giotto` objects can not be directly pipe into
+  `make_escheR` function. Instead, we provide a generic function that works
+  with a `data.frame` object as input. Please find example via [Beyond Bioconductor Eco-system](https://boyi-guo.com/escheR/articles/more_than_visium.html#beyond-bioconductor-eco-system).
+
 * How can I make a paneled figure containing multiple `escheR` plots?
 
+  You can compile and arrange individual plots by `escheR` via functions, e.g. [`cowplot::plot_grid`](https://wilkelab.org/cowplot/articles/plot_grid.html), [`patchwork`](https://patchwork.data-imaginist.com/index.html). Please find the
+  example via [Plot Multiple Samples](https://boyi-guo.com/escheR/articles/SRT_eg.html#plot-multiple-samples).
+
 * How can I choose color palettes for `add_fill` and `add_ground` to minimize interference?
 
+  Interested user can explore the topic on bivariate color palette. The [blog post](https://jakubnowosad.com/posts/2020-08-25-cbc-bp2/) by Jakub Nowosad and R package [`biscale`](https://cran.r-project.org/web/packages/biscale/vignettes/bivariate_palettes.html) could be helpful.
+
 * Can I apply `escheR` to plot image-based spatially resolved data?
 
+  In principle, `escheR` can be used to visualize image-based spatially-resolved (SR)
+  data. See examples via [Image-based SpatialExperiment Object](https://boyi-guo.com/escheR/articles/more_than_visium.html#image-based-spatialexperiment-object).
+
+  Nevertheless, we are still optimizing the design principles for image-based SR
+  data due to the difference in throughput compared to the sequence-based
+  spatially resolved data. Optimization for image-based SR data visualization
+  will be the main focus of our upcoming updates. We are open to working with
+  new ideas and seek collaboration.
+
 * Can I plot polygons as each data points to show cell morphology?
 
+  Unfortunately, not now. We acknowledge it would be a very important feature to
+  consider, and we are motivated to implement it in our future updates.
+
 # Citation
 
 Our preprint describing `escheR` is available from bioRxiv:

vignettes/SRT_eg.Rmd

@@ -58,7 +58,7 @@ Starting from Version 1.2.0 [TODO: add link], `escheR` package supports three da
 
 In the following example, we demonstrate the how to use `escheR` with a [`SpatialExperiment`](https://bioconductor.org/packages/release/bioc/html/SpatialExperiment.html) object. Please visit our other tutorials for [TODO: add items and list]. 
 
-# Tutorial
+# Making escheR Plot
 ## Load Packages
 
 To run the demonstration, there are two necessary packages to load, `escheR` and `STexampleData`. [`STexampleData`](https://bioconductor.org/packages/STexampleData) contains a pre-processed 10x Visium dataset.
@@ -86,7 +86,7 @@ Here is a summary of the `SpatialExperiment` object called `spe`.
 spe
 ```
 
-## Setting up for escheR plot
+## Set up an `escheR` plot
 Similar to `ggplot2::ggplot()`, we first use the function `make_escheR()` to create an empty plot. The input of `make_escheR()` is a [`SpatialExperiment`](https://bioconductor.org/packages/release/bioc/html/SpatialExperiment.html) object. The output of the function is a `ggplot` object with no layer in it. 
 ```{r create_plot}
 p <- make_escheR(spe)
@@ -120,6 +120,8 @@ p2 |>
 
 It is okay to change the ordering of these `add_*` functions. However, we advise to always have the `add_fill` as the first step to achieve the best visual effect due to the laying mechanism. 
 
+
+# Customize escheR Plot
 ## Adjusting aesthetics
 
 To change the aesthetics of each layer, one can simply use the `scale_*` from `ggplot2` to optimize the final visual presentation. For example, to optimize `add_fill`, one can use `scale_fill_*`; to optimize `add_ground`, one can use `scale_color_*`; to optimize `add_sumbol`, one use `scale_shape_*`. Here, we demonstrate how to change the color for the ground layer ( `add_ground`) using `scale_color_manual`.
@@ -142,7 +144,31 @@ p_final <- p2 +
   labs(title = "Example Title")
 ```
 
-## Plot Multiple Samples
+
+## Show a subset of levels
+The easiest way to show only a subset of levels of a categorical variable is to
+create a new variable where all the unwanted levels will be set to NA values.
+Please see the example below
+
+```{r subset}
+table(spe$ground_truth, useNA = "ifany")
+
+spe$tmp_fac <- factor(spe$ground_truth,
+                      levels = c("Layer1", "Layer2"))
+table(spe$tmp_fac, useNA = "ifany")
+
+make_escheR(spe) |> 
+  add_ground(var = "ground_truth") |> 
+  add_symbol(var = "tmp_fac", size = 0.4) + 
+  scale_shape_manual(
+    values=c(3, 16),    #> Set different symbols for the 2 levels
+    breaks = c("Layer1", "Layer2") #> Remove NA from legend
+  )
+```
+
+
+
+## Multi-sample Figure
 By design, `make_escheR` operates on only one sample. In order to create a figure compiling the spatial plots for multiple samples, individual plots are required via a series of calls to `make_escheR`, possibly via a `for` loop or an iterator function (e.g. `lapply`). 
 
 ```{r make_plot_list, eval = FALSE}
@@ -174,6 +200,18 @@ ggarrange(
   common.legend = TRUE)
 ```
 
+# Save escheR plot
+The procedure to save `escheR` plots is exactly the same as saving a `ggplot` object.
+In the example below, we use the funciton `ggplot2::ggsave()` to save `escheR` plots in the `pdf` format.
+
+```{r save_escheR, eval = FALSE}
+ggsave(
+  filename = "path/file_name.pdf",
+  plot = p_final
+)
+```
+
+
 # Session information
 
 ```{r}