tidySpatialExperiment provides a bridge between the
SpatialExperiment
package and the tidyverse ecosystem. It
creates an invisible layer that allows you to interact with a
SpatialExperiment object as if it were a tibble; enabling the use of
functions from dplyr,
tidyr,
ggplot2 and
plotly. But, underneath, your data
remains a SpatialExperiment object.
tidySpatialExperiment also provides six additional utility functions.
Resources
If you would like to learn more about tidySpatialExperiment and
tidyomics, the following links are a good place to start:
Aggregate cell-feature abundance into a pseudobulk SummarizedExperiment object
rectangle
Select cells in a rectangular region of space
ellipse
Select cells in an elliptical region of space
gate
Interactively or programmatically select cells in an arbitrary region of space
Installation
You can install the stable version of tidySpatialExperiment from
Bioconductor.
if (!requireNamespace("BiocManager", quietly = TRUE))
install.packages("BiocManager")
BiocManager::install("tidySpatialExperiment")
Or, you can install the development version of tidySpatialExperiment
from GitHub.
if (!requireNamespace("pak", quietly = TRUE))
install.packages("pak")
pak::pak("william-hutchison/tidySpatialExperiment")
Load data
Here, we attach tidySpatialExperiment and an example SpatialExperiment
object.
# Load example SpatialExperiment object
library(tidySpatialExperiment)
example(read10xVisium)
SpatialExperiment-tibble abstraction
A SpatialExperiment object represents assay-feature values as rows and
cells as columns. Additional information about the cells is stored in
the reducedDims, colData and spatialCoords slots.
tidySpatialExperiment provides a SpatialExperiment-tibble abstraction,
representing cells as rows and cell data as columns, in accordance with
the tidy observation-variable convention. The cell data is made up of
information stored in the colData and spatialCoords slots.
The default view is now of the SpatialExperiment-tibble abstraction.
Most functions from dplyr are available for use with the
SpatialExperiment-tibble abstraction. For example, filter() can be
used to filter cells by a variable of interest.
The ggplot() function can be used to create a plot directly from a
SpatialExperiment object. This example also demonstrates how tidy
operations can be combined to build up more complex analysis.
spe |>
filter(sample_id == "section1" & in_tissue) |>
# Add a column with the sum of feature counts per cell
mutate(count_sum = purrr::map_int(.cell, ~
spe[, .x] |>
counts() |>
sum()
)) |>
# Plot with tidySpatialExperiment and ggplot2
ggplot(aes(x = reorder(.cell, count_sum), y = count_sum)) +
geom_point() +
coord_flip()
Plot with plotly
The plot_ly() function can also be used to create a plot from a
SpatialExperiment object.
spe |>
filter(sample_id == "section1") |>
plot_ly(
x = ~ array_col,
y = ~ array_row,
color = ~ in_tissue,
type = "scatter"
)
Utilities
Append feature data to cell data
The tidyomics ecosystem places an emphasis on interacting with cell
data. To interact with feature data, the join_features() function can
be used to append assay-feature values to cell data.
Sometimes, it is necessary to aggregate the gene-transcript abundance
from a group of cells into a single value. For example, when comparing
groups of cells across different samples with fixed-effect models.
The aggregate_cells() function can be used to aggregate cells by a
specified variable and assay, returning a SummarizedExperiment object.
For the interactive selection of cells in space, tidySpatialExperiment
experiment provides gate(). This function uses
tidygate, shiny and plotly to
launch an interactive plot overlaying cells in position with image data.
Additional parameters can be used to specify point colour, shape, size
and alpha, either with a column in the SpatialExperiment object or a
constant value.
A record of which points appear in which gates is appended to the
SpatialExperiment object in the .gated column. To select cells which
appear within any gates, filter for non-NA values. To select cells which
appear within a specific gate, string pattern matching can be used.
Details of the interactively drawn gates are saved to
tidygate_env$gates. This variable is overwritten each time interactive
gates are drawn, so save it right away if you would like to access it
later.
# Save if needed
tidygate_env$gates |>
write_rds("important_gates.rds")
If previously drawn gates are supplied to the programmatic_gates
argument, cells will be gated programmatically. This feature allows the
reproduction of previously drawn interactive gates.
Removing the .cell column will return a tibble. This is consistent
with the behaviour in other tidyomics packages.
spe |>
select(-.cell) |>
head()
# tidySpatialExperiment says: Key columns are missing. A data frame is
# returned for independent data analysis.
# # A tibble: 6 × 4
# in_tissue array_row array_col sample_id
# <lgl> <int> <int> <chr>
# 1 FALSE 0 16 section1
# 2 TRUE 50 102 section1
# 3 TRUE 3 43 section1
# 4 TRUE 59 19 section1
# 5 TRUE 14 94 section1
# # ℹ 1 more row
The sample_id column cannot be removed with tidyverse functions, and
can only be modified if the changes are accepted by SpatialExperiment’s
colData() function.
The pxl_col_in_fullres and px_row_in_fullres columns cannot be
removed or modified with tidyverse functions. This is consistent with
the behaviour of dimension reduction data in other tidyomics packages.
# Attempting to remove pxl_col_in_fullres produces an error
spe |>
select(-pxl_col_in_fullres)
# Error in `select_helper()`:
# ! Can't select columns that don't exist.
# ✖ Column `pxl_col_in_fullres` doesn't exist.
# Attempting to modify pxl_col_in_fullres produces an error
spe |>
mutate(pxl_col_in_fullres)
# Error in `dplyr::mutate()`:
# ℹ In argument: `pxl_col_in_fullres`.
# Caused by error:
# ! object 'pxl_col_in_fullres' not found
tidySpatialExperiment - part of tidyomics
Introduction
tidySpatialExperiment provides a bridge between the SpatialExperiment package and the tidyverse ecosystem. It creates an invisible layer that allows you to interact with a
SpatialExperimentobject as if it were a tibble; enabling the use of functions from dplyr, tidyr, ggplot2 and plotly. But, underneath, your data remains aSpatialExperimentobject.tidySpatialExperiment also provides six additional utility functions.
Resources
If you would like to learn more about tidySpatialExperiment and tidyomics, the following links are a good place to start:
The tidyomics ecosystem also includes packages for:
Working with genomic features:
Working with transcriptomic features:
SummarizedExperimentobjects.SingleCellExperimentobjects.Seuratobjects.Working with cytometry features:
And a few associated packages:
Functions and utilities
SpatialExperimentdplyrarrange,bind_rows,bind_cols,distinct,filter,group_by,summarise,select,mutate,rename,left_join,right_join,inner_join,slice,sample_n,sample_frac,count,add_counttidyrnest,unnest,unite,separate,extract,pivot_longerggplot2ggplotplotlyplot_lyas_tibbletbl_dfjoin_featuresaggregate_cellsSummarizedExperimentobjectrectangleellipsegateInstallation
You can install the stable version of tidySpatialExperiment from Bioconductor.
Or, you can install the development version of tidySpatialExperiment from GitHub.
Load data
Here, we attach tidySpatialExperiment and an example
SpatialExperimentobject.SpatialExperiment-tibble abstraction
A
SpatialExperimentobject represents assay-feature values as rows and cells as columns. Additional information about the cells is stored in thereducedDims,colDataandspatialCoordsslots.tidySpatialExperiment provides a SpatialExperiment-tibble abstraction, representing cells as rows and cell data as columns, in accordance with the tidy observation-variable convention. The cell data is made up of information stored in the
colDataandspatialCoordsslots.The default view is now of the SpatialExperiment-tibble abstraction.
But, our data maintains its status as a
SpatialExperimentobject. Therefore, we have access to allSpatialExperimentfunctions.Integration with the tidyverse ecosystem
Manipulate with dplyr
Most functions from dplyr are available for use with the SpatialExperiment-tibble abstraction. For example,
filter()can be used to filter cells by a variable of interest.And
mutatecan be used to add new variables, or modify the value of an existing variable.Tidy with tidyr
Most functions from tidyr are also available. Here,
nest()is used to group the data bysample_id, andunnest()is used to ungroup the data.Plot with ggplot2
The
ggplot()function can be used to create a plot directly from aSpatialExperimentobject. This example also demonstrates how tidy operations can be combined to build up more complex analysis.Plot with plotly
The
plot_ly()function can also be used to create a plot from aSpatialExperimentobject.Utilities
Append feature data to cell data
The tidyomics ecosystem places an emphasis on interacting with cell data. To interact with feature data, the
join_features()function can be used to append assay-feature values to cell data.Aggregate cells
Sometimes, it is necessary to aggregate the gene-transcript abundance from a group of cells into a single value. For example, when comparing groups of cells across different samples with fixed-effect models.
The
aggregate_cells()function can be used to aggregate cells by a specified variable and assay, returning aSummarizedExperimentobject.Elliptical and rectangular region selection
The
ellipse()andrectangle()functions can be used to select cells by their position in space.Interactive gating
For the interactive selection of cells in space, tidySpatialExperiment experiment provides
gate(). This function uses tidygate, shiny and plotly to launch an interactive plot overlaying cells in position with image data. Additional parameters can be used to specify point colour, shape, size and alpha, either with a column in the SpatialExperiment object or a constant value.A record of which points appear in which gates is appended to the SpatialExperiment object in the
.gatedcolumn. To select cells which appear within any gates, filter for non-NA values. To select cells which appear within a specific gate, string pattern matching can be used.Details of the interactively drawn gates are saved to
tidygate_env$gates. This variable is overwritten each time interactive gates are drawn, so save it right away if you would like to access it later.If previously drawn gates are supplied to the
programmatic_gatesargument, cells will be gated programmatically. This feature allows the reproduction of previously drawn interactive gates.Special column behaviour
Removing the
.cellcolumn will return a tibble. This is consistent with the behaviour in other tidyomics packages.The
sample_idcolumn cannot be removed with tidyverse functions, and can only be modified if the changes are accepted by SpatialExperiment’scolData()function.The
pxl_col_in_fullresandpx_row_in_fullrescolumns cannot be removed or modified with tidyverse functions. This is consistent with the behaviour of dimension reduction data in other tidyomics packages.Citation
If you use tidySpatialExperiment in published research, please cite The tidyomics ecosystem: enhancing omic data analyses.
Session information