---
title: "STexampleData package overview"
author: 
  - name: Lukas M. Weber
    affiliation: "Johns Hopkins Bloomberg School of Public Health, Baltimore, MD, USA"
package: STexampleData
output: 
  BiocStyle::html_document
vignette: >
  %\VignetteIndexEntry{STexampleData package overview}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```


# Introduction

The `STexampleData` package contains a collection of spatially resolved transcriptomics (SRT) datasets, which have been formatted into the [SpatialExperiment](https://bioconductor.org/packages/SpatialExperiment) Bioconductor class, for use in examples, demonstrations, and tutorials. The datasets are from several different SRT platforms and have been sourced from various publicly available sources. Some of the datasets include images and/or ground truth annotation labels.


# Installation

To install the `STexampleData` package from Bioconductor:

```{r, eval=FALSE}
install.packages("BiocManager")
BiocManager::install("STexampleData")
```

Alternatively, the latest version can also be installed from GitHub:

```{r, eval=FALSE}
install.packages("remotes")
remotes::install_github("lmweber/STexampleData", build_vignettes = TRUE)
```


# Datasets

The package contains the following datasets:

- `Visium_humanDLPFC` (10x Genomics Visium): A single sample (sample 151673) of human brain dorsolateral prefrontal cortex (DLPFC) in the human brain, measured using the 10x Genomics Visium platform. This is a subset of the full dataset containing 12 samples from 3 neurotypical donors, published by [Maynard and Collado-Torres et al. (2021)](https://www.nature.com/articles/s41593-020-00787-0). The full dataset is available from the [spatialLIBD](http://bioconductor.org/packages/spatialLIBD) Bioconductor package.

- `Visium_mouseCoronal` (10x Genomics Visium): A single coronal section from the mouse brain, spanning one hemisphere. This dataset was previously released by 10x Genomics on their [website](https://support.10xgenomics.com/spatial-gene-expression/datasets/1.1.0/V1_Adult_Mouse_Brain).

- `seqFISH_mouseEmbryo` (seqFISH): A subset of cells (embryo 1, z-slice 2) from a previously published dataset investigating mouse embryogenesis by [Lohoff and Ghazanfar et al. (2020)](https://www.biorxiv.org/content/10.1101/2020.11.20.391896v1), generated using the seqFISH platform. The full dataset is [available online](https://marionilab.cruk.cam.ac.uk/SpatialMouseAtlas/).

- `ST_mouseOB` (Spatial Transcriptomics): A single sample from the mouse brain olfactory bulb (OB), measured with the Spatial Transcriptomics platform ([Stahl et al. 2016](https://www.science.org/doi/full/10.1126/science.aaf2403)). This dataset contains annotations for five cell layers from the original authors.

- `SlideSeqV2_mouseHPC` (Slide-seqV2): A single sample of mouse brain from the hippocampus (HPC) and surrounding regions, measured with the Slide-seqV2 platform ([Stickels et al. 2020](https://www.nature.com/articles/s41587-020-0739-1)). This dataset contains cell type annotations generated by [Cable et al. (2021)](https://www.nature.com/articles/s41587-021-00830-w).


# Load data

The following examples show how to load the example datasets as `SpatialExperiment` objects in an R session.

There are two options for loading the datasets: either using named accessor functions or by querying the ExperimentHub database.


## Load using named accessors

```{r, message=FALSE}
library(SpatialExperiment)
library(STexampleData)
```


### Visium_humanDLPFC

```{r, message=FALSE}
# load object
spe <- Visium_humanDLPFC()

# check object
spe
dim(spe)
assayNames(spe)
rowData(spe)
colData(spe)
head(spatialCoords(spe))
imgData(spe)
```


### Visium_mouseCoronal

```{r, message=FALSE}
# load object
spe <- Visium_mouseCoronal()
# check object
spe
```


### seqFISH_mouseEmbryo

```{r, message=FALSE}
# load object
spe <- seqFISH_mouseEmbryo()
# check object
spe
```


### ST_mouseOB

```{r, message=FALSE}
# load object
spe <- ST_mouseOB()
# check object
spe
```


### SlideSeqV2_mouseHPC

```{r, message=FALSE}
# load object
spe <- SlideSeqV2_mouseHPC()
# check object
spe
```


## Load by querying ExperimentHub database

```{r, message=FALSE}
library(ExperimentHub)
```

```{r, message=FALSE}
# create ExperimentHub instance
eh <- ExperimentHub()

# query STexampleData datasets
myfiles <- query(eh, "STexampleData")
myfiles

# metadata
md <- as.data.frame(mcols(myfiles))
```

```{r, message=FALSE}
# load Visium_humanDLPFC dataset using ExperimentHub query
spe <- myfiles[[1]]
spe
```


# Generating objects from raw data files

For reference, we include code scripts to generate the `SpatialExperiment` objects from the raw data files.

These scripts are saved in `/inst/scripts/` in the source code of the `STexampleData` package. The scripts include references and links to the data files from the original sources for each dataset.


# Session information

```{r}
sessionInfo()
```