# ggspavis overview

Lukas M. Weber1, Helena L. Crowell2 and Yixing E. Dong3

1Boston University, Boston, MA, USA
2University of Zurich, Zurich, Switzerland
3University of Lausanne, Lausanne, Switzerland

#### 29 October 2024

#### Package

ggspavis 1.12.0

# Contents

# 1 Introduction

The `ggspavis` package contains a set of visualization functions for spatial transcriptomics data, designed to work with the SpatialExperiment Bioconductor object class.

# 2 Examples

Load some example datasets from the STexampleData or spatialLIBD package and create some example plots to demonstrate `ggspavis`.

    library(ggspavis)
    library(STexampleData)
    library(patchwork)
    library(scater)

## 2.1 10x Genomics Visium: Mouse coronal brain section

First we start with a demo for a 10x Genomics Visium mouse brain dataset. We generate visualizations of library size and expression levels of selected genes. Both `plotVisium()` and `plotSpots()` reflect the spatial coordinates of spots, with the former also overlaying spots on the H&E histology image. Note that `plotVisium()` accepts a `SpatialExperiment` class object, while other functions in the package accept either `SpatialExperiment` or `SingleCellExperiment` class objects.

    # load data in SpatialExperiment format
    spe <- Visium_mouseCoronal()
    rownames(spe) <- rowData(spe)$gene_name
    colData(spe)$sum <- colSums(counts(spe))

### 2.1.1 Continuous annotations

#### 2.1.1.1 plotVisium

With `plotVisium()` annotated by a continuous variable, you can adjust palette, legend position, scaling of the variable, and whether to highlight spots that are in tissue, etc.

Note that we also use the `patchwork` package to display multiple figures in panels here.

    p1 <- plotVisium(spe, annotate = "sum", highlight = "in_tissue",
                     legend_position = "none")
    p2 <- plotVisium(spe, annotate = "sum", highlight = "in_tissue",
                     pal = "darkred") +
      guides(fill = guide_colorbar(title = "Libsize"))

    # display panels using patchwork
    p1 | p2

`plotVisium()` can also be used to visualize gene expression.

    p1 <- plotVisium(spe, annotate = "Gapdh", highlight = "in_tissue")
    p2 <- plotVisium(spe, annotate = "Mbp", highlight = "in_tissue")

    # display panels using patchwork
    p1 | p2

Two other possibilites with `plotVisium()` are to show only spots or only the H&E image.

    p1 <- plotVisium(spe, annotate = "Mbp", highlight = "in_tissue", image = FALSE)
    p2 <- plotVisium(spe, annotate = "Mbp", highlight = "in_tissue", spots = FALSE)

    # display panels using patchwork
    p1 | p2

#### 2.1.1.2 plotSpots

Using `plotSpots()`, for a 10x Genomics Visium dataset, by default we subset to spots that are over tissue. Palettes in `plotSpots()` can be changed in a similar manner to `plotVisium()`.

    p1 <- plotSpots(spe, annotate = "Gapdh")
    p2 <- plotSpots(spe, annotate = "Mbp", pal = "viridis")

    # display panels using patchwork
    p1 | p2

## 2.2 10x Genomics Visium: Human brain (DLPFC)

### 2.2.1 Discrete annotations

`plotSpots()` and `plotVisium()` can also be used to visualize discrete or categorical annotation variables, such as cluster labels as colors on the spatial coordinates. We will introduce this functionality using the Visium human brain dorsolateral prefrontal cortex (DLPFC) dataset.

    # load data in SpatialExperiment format
    spe <- Visium_humanDLPFC()
    rownames(spe) <- rowData(spe)$gene_name
    colData(spe)$libsize <- colSums(counts(spe))

First, we check the manually annotated reference labels, highlighting the spots that are in tissue, using `plotVisium()`.

    plotVisium(spe, annotate = "ground_truth", highlight = "in_tissue",
               pal = "libd_layer_colors")

For `plotSpots()`, we leave the palette as NULL, and since the reference annotations are categorical, eight distinct colors are automatically generated. (Similarly, leaving the palette as NULL for a continuous variable will generate a default three-color gradient of “blue-beige-red”.)

    p1 <- plotSpots(spe, annotate = "ground_truth") +
      ggtitle("Reference")
    p2 <- plotSpots(spe, annotate = "libsize") +
      ggtitle("Library size")

    # display panels using patchwork
    p1 | p2

We can also overlay text labels over the clusters using the `text_by` argument.

## 2.3 Quality control (QC) plots

### 2.3.1 Spot-level QC

We next derive some spot-level quality control (QC) flags for plotting. We use the `scater` package to add QC metrics to our data object.

    # calculate QC metrics using scater
    spe <- addPerCellQCMetrics(spe,
      subsets = list(mito = grepl("(^MT-)|(^mt-)", rowData(spe)$gene_name)))

    # apply QC thresholds
    colData(spe)$low_libsize <- colData(spe)$sum < 400 | colData(spe)$detected < 400
    colData(spe)$high_mito <- colData(spe)$subsets_mito_percent > 30

`plotSpotQC(plot_type = "spot")` reflects the spatial coordinates of the spots, where spots of interests can be labeled by a flag with TRUE or FALSE levels. The TRUE level are highlighted by red color.

We can investigate spots with low library size using histograms, violin plots, and spot plots.

    p1 <- plotSpotQC(spe, plot_type = "histogram",
                     x_metric = "sum", annotate = "low_libsize", )
    p2 <- plotSpotQC(spe, plot_type = "violin",
                     x_metric = "sum", annotate = "low_libsize", point_size = 0.1)
    p3 <- plotSpotQC(spe, plot_type = "spot", in_tissue = "in_tissue",
                     annotate = "low_libsize", point_size = 0.2)

    # display panels using patchwork
    p1 | p2 | p3

Similarly, we can investigate spots with high mitochondrial proportion of reads.

    p1 <- plotSpotQC(spe, plot_type = "histogram",
                     x_metric = "subsets_mito_percent", annotate = "high_mito", )
    p2 <- plotSpotQC(spe, plot_type = "violin",
                     x_metric = "subsets_mito_percent", annotate = "high_mito", point_size = 0.1)
    p3 <- plotSpotQC(spe, plot_type = "spot", in_tissue = "in_tissue",
                     annotate = "high_mito", point_size = 0.2)

    # display panels using patchwork
    p1 | p2 | p3

We can also use a scatter plot to check the trend between two variables, for example mitochondrial proportion vs. library size. We can also highlight spots by putting thresholds on the x and/or y axes.

    plotSpotQC(spe, plot_type = "scatter",
               x_metric = "subsets_mito_percent", y_metric = "sum",
               x_threshold = 30, y_threshold = 400)

### 2.3.2 Feature-level QC

Perform feature-level (gene-level) QC and visualize the result with a histogram. For example, for Visium, we demonstrate an arbitrary threshold that a gene should be detected in at least 20 spots to be considered not lowly abundant. The plot includes log1p transformation for easier visualization.

    rowData(spe)$feature_sum <- rowSums(counts(spe))
    rowData(spe)$low_abundance <- rowSums(counts(spe) > 0) < 20

    p1 <- plotFeatureQC(spe, plot_type = "histogram",
                        x_metric = "feature_sum", annotate = "low_abundance")
    p2 <- plotFeatureQC(spe, plot_type = "violin",
                        x_metric = "feature_sum", annotate = "low_abundance")

    # display panels using patchwork
    p1 | p2

## 2.4 Reduced dimension plots

We can also use the `plotDimRed()` function to generate reduced dimension plots, e.g. PCA or UMAP.

# 3 Session information

    sessionInfo()

    ## R version 4.4.1 (2024-06-14 ucrt)
    ## Platform: x86_64-w64-mingw32/x64
    ## Running under: Windows Server 2022 x64 (build 20348)
    ##
    ## Matrix products: default
    ##
    ##
    ## locale:
    ## [1] LC_COLLATE=C
    ## [2] LC_CTYPE=English_United States.utf8
    ## [3] LC_MONETARY=English_United States.utf8
    ## [4] LC_NUMERIC=C
    ## [5] LC_TIME=English_United States.utf8
    ##
    ## time zone: America/New_York
    ## tzcode source: internal
    ##
    ## attached base packages:
    ## [1] stats4    stats     graphics  grDevices utils     datasets  methods
    ## [8] base
    ##
    ## other attached packages:
    ##  [1] scater_1.34.0               scuttle_1.16.0
    ##  [3] patchwork_1.3.0             STexampleData_1.13.3
    ##  [5] SpatialExperiment_1.16.0    SingleCellExperiment_1.28.0
    ##  [7] SummarizedExperiment_1.36.0 Biobase_2.66.0
    ##  [9] GenomicRanges_1.58.0        GenomeInfoDb_1.42.0
    ## [11] IRanges_2.40.0              S4Vectors_0.44.0
    ## [13] MatrixGenerics_1.18.0       matrixStats_1.4.1
    ## [15] ExperimentHub_2.14.0        AnnotationHub_3.14.0
    ## [17] BiocFileCache_2.14.0        dbplyr_2.5.0
    ## [19] BiocGenerics_0.52.0         ggspavis_1.12.0
    ## [21] ggplot2_3.5.1               BiocStyle_2.34.0
    ##
    ## loaded via a namespace (and not attached):
    ##  [1] DBI_1.2.3               gridExtra_2.3           rlang_1.1.4
    ##  [4] magrittr_2.0.3          compiler_4.4.1          RSQLite_2.3.7
    ##  [7] mgcv_1.9-1              png_0.1-8               vctrs_0.6.5
    ## [10] pkgconfig_2.0.3         crayon_1.5.3            fastmap_1.2.0
    ## [13] magick_2.8.5            XVector_0.46.0          labeling_0.4.3
    ## [16] utf8_1.2.4              rmarkdown_2.28          ggbeeswarm_0.7.2
    ## [19] UCSC.utils_1.2.0        tinytex_0.53            purrr_1.0.2
    ## [22] bit_4.5.0               xfun_0.48               zlibbioc_1.52.0
    ## [25] cachem_1.1.0            beachmat_2.22.0         jsonlite_1.8.9
    ## [28] blob_1.2.4              highr_0.11              DelayedArray_0.32.0
    ## [31] BiocParallel_1.40.0     irlba_2.3.5.1           parallel_4.4.1
    ## [34] R6_2.5.1                bslib_0.8.0             RColorBrewer_1.1-3
    ## [37] jquerylib_0.1.4         Rcpp_1.0.13             bookdown_0.41
    ## [40] knitr_1.48              splines_4.4.1           Matrix_1.7-1
    ## [43] tidyselect_1.2.1        viridis_0.6.5           abind_1.4-8
    ## [46] yaml_2.3.10             codetools_0.2-20        curl_5.2.3
    ## [49] lattice_0.22-6          tibble_3.2.1            withr_3.0.2
    ## [52] KEGGREST_1.46.0         evaluate_1.0.1          Biostrings_2.74.0
    ## [55] pillar_1.9.0            BiocManager_1.30.25     filelock_1.0.3
    ## [58] generics_0.1.3          BiocVersion_3.20.0      munsell_0.5.1
    ## [61] scales_1.3.0            glue_1.8.0              tools_4.4.1
    ## [64] BiocNeighbors_2.0.0     ScaledMatrix_1.14.0     ggside_0.3.1
    ## [67] grid_4.4.1              AnnotationDbi_1.68.0    colorspace_2.1-1
    ## [70] nlme_3.1-166            GenomeInfoDbData_1.2.13 beeswarm_0.4.0
    ## [73] BiocSingular_1.22.0     vipor_0.4.7             rsvd_1.0.5
    ## [76] cli_3.6.3               rappdirs_0.3.3          fansi_1.0.6
    ## [79] viridisLite_0.4.2       S4Arrays_1.6.0          dplyr_1.1.4
    ## [82] gtable_0.3.6            sass_0.4.9              digest_0.6.37
    ## [85] SparseArray_1.6.0       ggrepel_0.9.6           rjson_0.2.23
    ## [88] farver_2.1.2            memoise_2.0.1           htmltools_0.5.8.1
    ## [91] lifecycle_1.0.4         httr_1.4.7              mime_0.12
    ## [94] bit64_4.5.2