Package 'escheR'

Title: Unified multi-dimensional visualizations with Gestalt principles
Description: The creation of effective visualizations is a fundamental component of data analysis. In biomedical research, new challenges are emerging to visualize multi-dimensional data in a 2D space, but current data visualization tools have limited capabilities. To address this problem, we leverage Gestalt principles to improve the design and interpretability of multi-dimensional data in 2D data visualizations, layering aesthetics to display multiple variables. The proposed visualization can be applied to spatially-resolved transcriptomics data, but also broadly to data visualized in 2D space, such as embedding visualizations. We provide this open source R package escheR, which is built off of the state-of-the-art ggplot2 visualization framework and can be seamlessly integrated into genomics toolboxes and workflows.
Authors: Boyi Guo [aut, cre] , Stephanie C. Hicks [aut] , Erik D. Nelson [ctb]
Maintainer: Boyi Guo <[email protected]>
License: MIT + file LICENSE
Version: 1.5.0
Built: 2024-07-02 05:22:13 UTC
Source: https://github.com/bioc/escheR

Help Index

Check if rowData(spe) contains reserved name

Description

Internal Funciton

Usage

.contain_reserved_col_name(col_name)

Arguments

col_name

the colnames

Value

TRUE when col_name contains reserved names, FALSE

Adding fill to highlight the figure in the spatial map

Description

Adding fill to highlight the figure in the spatial map

Usage

add_fill(p, var, point_size = 2, ...)

add_fill_bin(p, var, bins = 30, point_size = 2.8, fun = sum, ...)

Arguments

p

a spatial map created by make_escheR(), with or without other layers of aesthetics.
var

A character(1) with the name of the colData(spe) column that has the values to be used as the background.
point_size

A numeric(1) specifying the size of the spot in the ggplot. Defaults to 2.
...

Reserved for future arguments.
bins

numeric vector giving number of bins in both vertical and horizontal directions. Set to 30 by default.
fun

function for summary. See more detail in stat_summary_hex

Value

an ggplot object.

Examples

library(STexampleData)

spe <- Visium_humanDLPFC()

make_escheR(spe) |>
    add_fill(var = "ground_truth")

Adding border to highlight the ground in the spatial map

Description

Adding border to highlight the ground in the spatial map

Usage

add_ground(p, var, stroke = 0.5, point_size = 2, ...)

add_ground_bin(p, var, bins = 30, stroke = 1, point_size = 3, ...)

Arguments

p

a spatial map created by make_escheR(), with or without other layers of aesthetics.
var

A character(1) with the name of the colData(spe) column that has the values to be used as the background.
stroke

A numeric(1) specifying the thickness of the border.
point_size

A numeric(1) specifying the size of the spot in the ggplot. Defaults to 2.
...

Reserved for future arguments.
bins

numeric vector giving number of bins in both vertical and horizontal directions. Set to 30 by default.

Value

an ggplot object.

Examples

library(STexampleData)

spe <- Visium_humanDLPFC()

make_escheR(spe) |>
    add_ground(var = "ground_truth")

Adding symbols to each spot in the spatial map

Description

Adding symbols to each spot in the spatial map

Usage

add_symbol(p, var, size = 1, ...)

Arguments

p

a spatial map created by make_escheR(), with or without other layers of aesthetics.
var

A character(1) with the name of the colData(spe) column that has the values to be used as the background.
size

A numeric(1) specifying the size of the symbols in the ggplot. Defaults to 1.
...

Reserved for future arguments.

Value

an ggplot object.

Examples

library(STexampleData)

spe <- Visium_humanDLPFC()

# Convert a continuous variable to categorical
spe$in_tissue <- factor(spe$in_tissue)

make_escheR(spe) |>
    add_ground(var = "ground_truth") |>
    add_symbol(var = "in_tissue", size = 0.5)

Create a new spatial map for spatial transcriptomics data

Description

make_escheR() is a generic function to initialize a ggplot object that contains a spatial map. Because the ggplot object saves the input spatial transcriptomics data, the transcriptomics data will be used in the following layering process to add more aesthestic components in the plot following the grammar of graphics and ggplot2 syntax.

Usage

make_escheR(object, spot_size = 2, ...)

## S3 method for class 'SingleCellExperiment'
make_escheR(object, spot_size = 2, dimred = "PCA", ...)

## S3 method for class 'SpatialExperiment'
make_escheR(object, spot_size = 2, dimred = NULL, y_reverse = TRUE, ...)

## S3 method for class 'data.frame'
make_escheR(object, spot_size = 2, .x, .y, ...)

Arguments

object

a data object that contains the spatial transcriptomics data. Currently only working for spatial transcriptomics data as SpatialExperiment objects.
spot_size

A numeric(1) specifying the size of the spot in the ggplot. Defaults to 2.
...

Reserved for future arguments.
dimred

String or integer scalar specifying the existing dimensionality reduction results to use.
y_reverse

(logical) Whether to reverse y coordinates, which is often required for 10x Genomics Visium data. Default = TRUE.
.x

the X-coordinate
.y

the Y-coordinate

Value

an ggplot object that contains the spatial transcriptomics data.

References

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

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)