boyiguo1/escher

R package to visualize colocalization for single cell & spatially-resolved genomics data

escheR

R Package Status:

Bioc Status:

The goal of escheR is to create an unified multi-dimensional spatial visualizations for spatially-resolved transcriptomics data following Gestalt principles. Gestalt principles refer to a set of rules describing how humans perceive and interpret visual information and are commonly applied in art and designs. Our implementation is based on the state-of-art data visualization framework ggplot2 to map individual variables to different aesthetics to simultaneously display disparate variables, showing their relationship in a spatial context.

Our manuscript describing the innovative visualization is published in Bioinformatics Advances.

Installation

You can install the latest release version of escheR from Bioconductor. with using the following code will install version of the nnSVG package from Bioconductor. Additional details are shown on the Bioconductor page.

if (!require("BiocManager", quietly = TRUE)) {
    install.packages("BiocManager")
}
BiocManager::install("escheR")

The latest development version can also be installed from the devel version of Bioconductor or from GitHub following

if (!require("devtools")) install.packages("devtools")
devtools::install_github("boyiguo1/escheR")

If you have R version before v4.3 and would like to install escheR, you can follow

if (!require("devtools")) install.packages("devtools")
devtools::install_github("boyiguo1/[email protected]")

WARNING: The purpose of having the branch pre-R4.3 is to allow users to use escheR before the formal release of R 4.3 and during the early stage of R 4.3 release. This branch will not update with any further development passing escheR v0.99.6. We recommend users to update their R versions up to date.

Tutorial

Please find an end-to-end tutorial at https://boyiguo1.github.io/escheR/

Syntax

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.

• How can I make plots to visualize dimensional reduced embeddings?

  Yes, you can provide a string value to thedimred argument. The string value should be included in reducedDimNames(object). For more information, please see Beyond Sequence-based Spatially-Resolved Data.

• Can I highlight only a subset of groups/levels for a categorical variables?

  Yes, please find the example in 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.

• 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, patchwork. Please find the example via 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 by Jakub Nowosad and R package biscale 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.

  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 manuscript describing escheR is available via Bioinformatics Advances:

• Guo B, Huuki-Myers LA, Grant-Peters M, Collado-Torres L, Hicks SC (2023). “escheR: Unified multi-dimensional visualizations with Gestalt principles.” Volume 3, Issue 1, 2023, vbad179, https://doi.org/10.1093/bioadv/vbad179

Acknowledgement

The importance of visual analytics

The panel of relational plots is from the book the visual display of quantitative information by Edward Tufte. This book inspired me to think more about the meaning of visual analytics in the era of computational science, and motivates me to think about statistical graphics design and its meaning.

Development tools

• Continuous code testing is possible thanks to GitHub actions through biocthis,
• The documentation website is automatically updated thanks to pkgdown.
• The code is styled automatically thanks to styler.
• The documentation is formatted thanks to devtools and roxygen2.

escher's Issues

Add a new function to display the background tissue image

V0.99.8

• Set up Bioc Badges
• Add Bioc Check to GitHub Action
  • #5
• Invert spot coordinates such that the orientation of the spots aligns with images
  • #13

Scale the hexagon sticker to show as social preview of this repo

Improve documentation clarity regarding `reverse_y` argument and programming syntax.

Here are some suggestion on improving the clarity of documentation from @cindyfang70.

• Clarify what the purpose for the argument reverse_y
• Add syntax image to the getting started with escheR vigenette.

Thanks @cindyfang70 for the feedback!

Add brief introduction about Gestault Principles to README

Suggested by Byron Jaeger.

Bioconductor Submission Review

Package 'escheR' Review

Thank you for submition your package to Bioconductor. The package passed check and build. It is in pretty good shape. However there are several things need to be fixed. Please try to answer the comments line by line when you are ready for a second review.
Code: Note: please condsider; Important: must be addressed.

The DESCRIPTION file

• R version is not clear in DESCRIPTION.

Response: Added R(>=3.6) as dependency

The NAMESPACE file

• Selective imports using importFrom instead of import all with import.
  • in line 8 import(SpatialExperiment)
  • in line 9 import(ggplot2)
  • in line 10 import(spatialLIBD)

Response: Imported individual functions instead of entire packages

R code

• Important: No paste in message(), message, stop
  • In file R/add_fill.R:
    • at line 34 found ' stop(paste0("Please add the variable ", var, " to colData(spe)."))'
  • In file R/add_ground.R:
    • at line 37 found ' stop(paste0("Please add the variable ", var, " to colData(spe)."))'
  • In file R/add_symbol.R:
    • at line 36 found ' stop(paste0("Please add the variable ", var, " to colData(spe)."))'

Response: removed all paste functions in stop etc. Thanks for this tip.

• NOTE: :: is not suggested in source code unless you can make sure all the packages are imported. Some people think it is better to keep ::. However please note that you need to manully double check the import items when you make any change in the DESCRIPTION file during development. My recommendation is to remove one or two repeats to force the dependency check.
  • In file R/make_escheR.R:
    • at line 58 found ' d <- as.data.frame(cbind(colData(spe), SpatialExperiment::spatialCoords(spe)), optional = TRUE)'
    • at line 64 found ' SpatialExperiment::imgRaster('
    • at line 86 found ' x = pxl_col_in_fullres * SpatialExperiment::scaleFactors(spe, sample_id = sampleid, image_id = image_id) - adjust$x,'
    • at line 87 found ' y = pxl_row_in_fullres * SpatialExperiment::scaleFactors(spe, sample_id = sampleid, image_id = image_id) - adjust$y,'

Response: Thank you very much for this information. I followed your suggestion to make some functions without :: such that the source code for the dependency check. But I would still like to leave some of them in the code to enhance readability for people who are not familiar with these packages. Thanks for sharing this trick!

• Important: 1:n is not suggested in source code. Use seq_along or seq.int instead.
  • In file R/add_fill.R:
    • at line 59 found ' # setNames(c(paste0("L", 1:6), "WM", "NA", "WM2"))'

Response: removed the commented code and hence this line. But I will be more careful with my coding practice to use seq.int etc instead of 1:n. Thank you for this tip!

• Important: Remove unused code.
  • In file R/add_fill.R:
    • at line 31 found ' # browser()'
    • at line 37 found ' # if(is.numeric(p$data[,var])) {'
    • at line 38 found ' # stop("")'
    • at line 39 found ' # p <- suppressMessages({p + scale_fill_continuous()})'
    • at line 40 found ' # } else{'
    • at line 41 found ' # p <- suppressMessages({p + scale_fill_discrete()})'
    • at line 42 found ' # }'
    • at line 45 found ' # browser()'
    • at line 54 found ' # if(!is.numeric(p$data[,var]))'
    • at line 55 found ' # tmp <- tmp +'
    • at line 56 found ' # scale_fill_manual('
    • at line 57 found ' # name = "",'
    • at line 58 found ' # values = libd_layer_colors |>'
    • at line 59 found ' # setNames(c(paste0("L", 1:6), "WM", "NA", "WM2"))'
    • at line 60 found ' # )'
    • at line 63 found ' # tmp$scales <- tmp$scales[[-1]]'
  • In file R/make_escheR.R:
    • at line 51 found ' ## (http://spatial.libd.org/spatialLIBD/)'

Response: removed the commented code.

• NOTE: Avoid 'suppressWarnings'/'*Messages' if possible
  • In file R/add_fill.R:
    • at line 39 found ' # p <- suppressMessages({p + scale_fill_continuous()})'
    • at line 41 found ' # p <- suppressMessages({p + scale_fill_discrete()})'

Response: removed the commented code. But I will be more careful with the practice in general in the future. Thank you for this tip!

• NOTE: Functional programming: code repetition.
  • repetition in add_fill and add_ground and add_symbol
    • in add_fill
      • line 1: point_size = 2, ...)
      • line 2:{
      • line 3: if (!is.character(var) || length(var) != 1) {
      • line 4: stop("The argument var must be character of length one.")
      • line 5: }
      • line 6: if (!var %in% colnames(p$data)) {
      • line 7: stop(paste0("Please add the variable ", var, " to colData(spe)."))
      • line 8: }
      • line 9: p + geom_point(aes(fill = !!sym(var)), shape = 21, stroke = 0,
    • in add_ground
      • line 1: var, stroke = 0.5, point_size = 2, ...)
      • line 2:{
      • line 3: if (!is.character(var) || length(var) != 1) {
      • line 4: stop("The argument var must be character of length one.")
      • line 5: }
      • line 6: if (!var %in% colnames(p$data)) {
      • line 7: stop(paste0("Please add the variable ", var, " to colData(spe)."))
      • line 8: }
      • line 9: p + geom_point(aes(color = !!sym(var), ), shape = 21, fill = "transparent",
    • in add_symbol
      • line 1: var, size = 1, ...)
      • line 2:{
      • line 3: if (!is.character(var) || length(var) != 1) {
      • line 4: stop("The argument var must be character of length one.")
      • line 5: }
      • line 6: if (!var %in% colnames(p$data)) {
      • line 7: stop(paste0("Please add the variable ", var, " to colData(spe)."))
      • line 8: }

Response: Thank you for the suggestion! I am aware of this situation, and currently working on a check_var function for this purpose and some more checks. This improvement will be fully implemented in the next update of the package.

• Note: move theme in function make_escheR.SpatialExperiment to a sub_function.

Response: Thank you for the suggestion! I'll reserve this as an option in the next update of the package.

• Note: Use dots to pass parameters to geom_point in add_symbol function and add_fill function and let user to overwrite the defaults.

Response: Thank you for the suggestion! I had a similar idea, but I would like to have some more time to think about the design of this function. I will prioritize this tasks in the next update of this package.

Documentation

• Important: Please include Bioconductor installation instructions using BiocManager.
  • rmd file vignettes/SRT_eg.Rmd

Response: Added BiocManager installation instructions

• Note: Vignette includes motivation for submitting to Bioconductor as part of the abstract/intro of the main vignette.
  • rmd file vignettes/SRT_eg.Rmd

Response: Remove mentioning of Bioconductor submission

Originally posted by @jianhong in Bioconductor/Contributions#2988 (comment)

Update README

• Add bioconductor installation instruction
• Add a subsection introducing the installation method for the R version before 4.3.0.

Using `alpha` and `stroke` of `add_ground_bin` to address intermixing of membership for binned figures

As noted in the vignette Beyond Sequence-based Spatially-Resolved Data, the binning strategy proposed to address overplotting could lead to distorted interpretation due intermixing of data points within each bin.

A possible solution to address this is to display the proportion of majority membership within each bin using either transparency (alpha) or boundary size (stroke).

`stroke=0` Doesn't necessary remove boundry in `add_fill`

Change minor version to 0.99.0

Create Vignette for simultaneous viz for two continuous variable using RGB colorspace

Contributor: @Erik-D-Nelson

• A function to normalize continuous variables to RGB color space

  • Document the arguments (parameters) of the function

• A case study applying this concept to a Visium dataset

Organize News File

“spot_size” within the “make_escheR” function does not change the size of points

Hello!

I am trying to change the spot size of the points using the example you have online but have been unable to do so. See below the code I am running.. is there something I am doing wrong? Thanks so much!

R code

library(STexampleData)
spe <- Visium_humanDLPFC()
make_escheR(spe, spot_size=0.1) |> add_fill(var = "in_tissue")
make_escheR(spe, spot_size=5) |> add_fill(var = "in_tissue")
make_escheR(spe, spot_size=10) |> add_fill(var = "in_tissue")

All these look the same

Add spatialLIBD to the details and citation of `make_escheR`

Update Error message

THere are error message that has not been updated

Error in make_escheR.SpatialExperiment(spe[, spe$sample_id %in% c("V13M06-342_D1")]) : 
  make_escheR currently only supports spe object with 1 sample. Please find tips multiple sample plots in [TODO] vignettes.

Remove `spatialLIBD` as the dependency

Check name for spatialCoords of `spe` object

Current code default the names for the spatialCoords to be "pxl_row_in_fullres", "pxl_col_in_fullres" without giving a warning.

Need to have more flexible implementation.

Remove REMOTES in DESCRIPTION file

Confirm the margin of the plots are appropriate.

Activate github workflow to update website due to change of default branch name

Add a vignette to show fine tuning the escheR visualization

escheR doesn't work with `spe` Object whose `imgData` does't exists

Replicating Example

n <- length(z <- letters)
y <- matrix(nrow = n, ncol = n)
cd <- DataFrame(x = seq(n), y = seq(n), z)

spe1 <- SpatialExperiment(
    assay = y, 
    colData = cd, 
    spatialCoordsNames = c("x", "y"))

The plots are always upside down compared to others

Before v0.99.7, the plots generated by escheR looks upside down comparing to underlying tissue images

Possibly incorprate `ggblend`

https://twitter.com/mjskay/status/1660689831809171469

Error: Other 'type' values are not supported

if (!exists("spe"))
spe <- fetch_data("spatialDLPFC_Visium")