---
title: "STexampleData overview"
author: 
  - name: Lukas M. Weber
    affiliation: "Boston University, Boston, MA, USA"
  - name: Yixing E. Dong
    affiliation: "University of Lausanne, Lausanne, Switzerland"
package: STexampleData
output: 
  BiocStyle::html_document
vignette: >
  %\VignetteIndexEntry{STexampleData 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 spatial transcriptomics 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 technological platforms and have been sourced from various publicly available sources. Some of the datasets include images and/or reference annotation labels.


# Installation

The `STexampleData` package can be installed from Bioconductor:

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


# 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. (2022)](https://www.nature.com/articles/s41587-021-01006-2), 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. 2021](https://www.nature.com/articles/s41587-020-0739-1)). This dataset contains cell type annotations generated by [Cable et al. (2022)](https://www.nature.com/articles/s41587-021-00830-w).

- `Janesick_breastCancer_Chromium` (10x Genomics Chromium): 10x Genomics Chromium single-cell RNA sequencing data from human breast cancer dataset by [Janesick et al. (2023)](https://www.nature.com/articles/s41467-023-43458-x). High resolution mapping of the breast cancer tumor microenvironment using integrated single-cell, spatial, and in situ analysis of FFPE tissue. Contains annotations for cell type from the original authors.

- `Janesick_breastCancer_Visium` (10x Genomics Visium): 10x Genomics Visium spatial transcriptomics data from human breast cancer dataset by [Janesick et al. (2023)](https://www.nature.com/articles/s41467-023-43458-x). High resolution mapping of the breast cancer tumor microenvironment using integrated single-cell, spatial, and in situ analysis of FFPE tissue.

- `Janesick_breastCancer_Xenium_rep1` (10x Genomics Xenium): 10x Genomics Xenium in situ spatial data (sample 1, replicate 1) from human breast cancer dataset by [Janesick et al. (2023)](https://www.nature.com/articles/s41467-023-43458-x). High resolution mapping of the breast cancer tumor microenvironment using integrated single-cell, spatial, and in situ analysis of FFPE tissue.

- `Janesick_breastCancer_Xenium_rep2` (10x Genomics Xenium): 10x Genomics Xenium in situ spatial data (sample 1, replicate 2) from human breast cancer dataset by [Janesick et al. (2023)](https://www.nature.com/articles/s41467-023-43458-x). High resolution mapping of the breast cancer tumor microenvironment using integrated single-cell, spatial, and in situ analysis of FFPE tissue.

- `CosMx_lungCancer` (NanoString CosMx): NanoString CosMx human non-small cell lung cancer (NSCLC) dataset. Contains data from one sample (patient 9, slice 1). This dataset was previously released by NanoString on their [website](https://nanostring.com/resources/smi-ffpe-dataset-lung9-rep1-data/).

- `MERSCOPE_ovarianCancer` (Vizgen MERSCOPE): Vizgen MERSCOPE human ovarian cancer dataset. Contains data from one sample (patient 2, sample 1). This dataset was previously released by Vizgen on their [website](https://info.vizgen.com/ffpe-showcase).

- `STARmapPLUS_mouseBrain` (STARmap PLUS): STARmap PLUS mouse brain data by [Shi et al. (2023)](https://www.nature.com/articles/s41586-023-06569-5). Contains data from one sample (well 05), including annotations for cell type and tissue regions from the original authors.


# 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
```


### Janesick_breastCancer_Chromium

```{r, message=FALSE}
# load object
# note: this dataset is in SingleCellExperiment format
sce <- Janesick_breastCancer_Chromium()
# check object
sce
```


### Janesick_breastCancer_Visium

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


### Janesick_breastCancer_Xenium_rep1

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


### Janesick_breastCancer_Xenium_rep2

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


### CosMx_lungCancer

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


### MERSCOPE_ovarianCancer

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


### STARmapPLUS_mouseBrain

```{r, message=FALSE}
# load object
spe <- STARmapPLUS_mouseBrain()
# 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
```

```{r, message=FALSE}
# load 'Visium_humanDLPFC' dataset using ExperimentHub ID
spe <- myfiles[["EH9516"]]
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()
```