tidySpatialExperiment - part of tidyomics <img src="man/figures/logo.png" id="tidySpatialExperiment_logo" align="right" width="125"/>

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 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:

The tidyomics ecosystem also includes packages for:

Working with genomic features:
- plyranges, for tidy manipulation of genomic range data.
- nullranges, for tidy generation of genomic ranges representing the null hypothesis.
- plyinteractions, for tidy manipulation of genomic interaction data.
Working with transcriptomic features:
- tidySummarizedExperiment, for tidy manipulation of SummarizedExperiment objects.
- tidySingleCellExperiment, for tidy manipulation of SingleCellExperiment objects.
- tidyseurat, for tidy manipulation of Seurat objects.
- tidybulk, for bulk RNA-seq analysis.
Working with cytometry features:
- tidytof, for tidy manipulation of high-dimensional cytometry data.
And a few associated packages:
- tidygate, for manual gating of points in space.
- tidyheatmap, for modular heatmap contruction.

Functions and utilities

| Package | Functions available | |---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | SpatialExperiment | All | | dplyr | arrange,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_count | | tidyr | nest, unnest, unite, separate, extract, pivot_longer | | ggplot2 | ggplot | | plotly | plot_ly |

| Utility | Description | |-------------------|----------------------------------------------------------------------------------| | as_tibble | Convert cell data to a tbl_df | | join_features | Append feature data to cell data | | aggregate_cells | 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.

spe
#  # A SpatialExperiment-tibble abstraction: 50 × 7
#  # Features = 50 | Cells = 50 | Assays = counts
#    .cell              in_tissue array_row array_col sample_id pxl_col_in_fullres
#    <chr>              <lgl>         <int>     <int> <chr>                  <int>
#  1 AAACAACGAATAGTTC-1 FALSE             0        16 section1                2312
#  2 AAACAAGTATCTCCCA-1 TRUE             50       102 section1                8230
#  3 AAACAATCTACTAGCA-1 TRUE              3        43 section1                4170
#  4 AAACACCAATAACTGC-1 TRUE             59        19 section1                2519
#  5 AAACAGAGCGACTCCT-1 TRUE             14        94 section1                7679
#  # ℹ 45 more rows
#  # ℹ 1 more variable: pxl_row_in_fullres <int>

But, our data maintains its status as a SpatialExperiment object. Therefore, we have access to all SpatialExperiment functions.

spe |>
    colData() |>
    head()
#  DataFrame with 6 rows and 4 columns
#                     in_tissue array_row array_col   sample_id
#                     <logical> <integer> <integer> <character>
#  AAACAACGAATAGTTC-1     FALSE         0        16    section1
#  AAACAAGTATCTCCCA-1      TRUE        50       102    section1
#  AAACAATCTACTAGCA-1      TRUE         3        43    section1
#  AAACACCAATAACTGC-1      TRUE        59        19    section1
#  AAACAGAGCGACTCCT-1      TRUE        14        94    section1
#  AAACAGCTTTCAGAAG-1     FALSE        43         9    section1

spe |> 
    spatialCoords() |>
    head()
#                     pxl_col_in_fullres pxl_row_in_fullres
#  AAACAACGAATAGTTC-1               2312               1252
#  AAACAAGTATCTCCCA-1               8230               7237
#  AAACAATCTACTAGCA-1               4170               1611
#  AAACACCAATAACTGC-1               2519               8315
#  AAACAGAGCGACTCCT-1               7679               2927
#  AAACAGCTTTCAGAAG-1               1831               6400

spe |>
    imgData()
#  DataFrame with 1 row and 4 columns
#      sample_id    image_id   data scaleFactor
#    <character> <character> <list>   <numeric>
#  1    section1      lowres   ####   0.0510334

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.

spe |>
   filter(array_col < 5)
#  # A SpatialExperiment-tibble abstraction: 3 × 7
#  # Features = 50 | Cells = 3 | Assays = counts
#    .cell              in_tissue array_row array_col sample_id pxl_col_in_fullres
#    <chr>              <lgl>         <int>     <int> <chr>                  <int>
#  1 AAACATGGTGAGAGGA-1 FALSE            62         0 section1                1212
#  2 AAACGAAGATGGAGTA-1 FALSE            58         4 section1                1487
#  3 AAAGAATGACCTTAGA-1 FALSE            64         2 section1                1349
#  # ℹ 1 more variable: pxl_row_in_fullres <int>

And mutate can be used to add new variables, or modify the value of an existing variable.

spe |>
    mutate(in_region = c(in_tissue & array_row < 10))
#  # A SpatialExperiment-tibble abstraction: 50 × 8
#  # Features = 50 | Cells = 50 | Assays = counts

TidySpatialExperiment

Install / Use

README