---
title: "TENxVisiumData"
author:
- name: Helena L. Crowell
  affiliation: Department of Molecular Life Sciences, University of Zurich, Zurich, Switzerland
output:
  BiocStyle::html_document:
    toc_float: true
package: TENxVisiumData
abstract: |
  The TENxVisiumData ExperimentHub package provides a collection of Visium spatial gene expression datasets by 10X Genomics. Data cover various organisms and tissues, and are formatted into objects of class SpatialExperiment.
vignette: |
  %\VignetteIndexEntry{TENxVisiumData}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r include = FALSE}
knitr::opts_chunk$set(message = FALSE, warning = FALSE, error = FALSE)
```

# Available datasets

The `TENxVisiumData` package provides an R/Bioconductor resource for 
[Visium spatial gene expression datasets by 10X Genomics](https://support.10xgenomics.com/spatial-gene-expression/datasets). The package currently includes 13 datasets from 23 samples across two organisms (human and mouse) and 13 tissues:

* HumanBreastCancerIDC
  * [Human Breast Cancer (Block A Section 1)](https://support.10xgenomics.com/spatial-gene-expression/datasets/1.1.0/V1_Breast_Cancer_Block_A_Section_1)
  * [Human Breast Cancer (Block A Section 2)](https://support.10xgenomics.com/spatial-gene-expression/datasets/1.1.0/V1_Breast_Cancer_Block_A_Section_2)
* HumanBreastCancerILC
  * [Human Breast Cancer: Whole Transcriptome Analysis](https://support.10xgenomics.com/spatial-gene-expression/datasets/1.2.0/Parent_Visium_Human_BreastCancer)
  * [Human Breast Cancer: Targeted, Immunology Panel](https://support.10xgenomics.com/spatial-gene-expression/datasets/1.2.0/Targeted_Visium_Human_BreastCancer_Immunology)
* HumanCerebellum
  * [Human Cerebellum: Whole Transcriptome Analysis](https://support.10xgenomics.com/spatial-gene-expression/datasets/1.2.0/Parent_Visium_Human_Cerebellum)
  * [Human Cerebellum: Targeted, Neuroscience Panel](https://support.10xgenomics.com/spatial-gene-expression/datasets/1.2.0/Targeted_Visium_Human_Cerebellum_Neuroscience)
* HumanColorectalCancer
  * [Human Colorectal Cancer: Whole Transcriptome Analysis](https://support.10xgenomics.com/spatial-gene-expression/datasets/1.2.0/Parent_Visium_Human_ColorectalCancer)
  * [Human Colorectal Cancer: Targeted, Gene Signature Panel](https://support.10xgenomics.com/spatial-gene-expression/datasets/1.2.0/Targeted_Visium_Human_ColorectalCancer_GeneSignature)
* HumanGlioblastoma
  * [Human Glioblastoma: Whole Transcriptome Analysis](https://support.10xgenomics.com/spatial-gene-expression/datasets/1.2.0/Parent_Visium_Human_Glioblastoma)
  * [Human Glioblastoma: Targeted, Pan-Cancer Panel](https://support.10xgenomics.com/spatial-gene-expression/datasets/1.2.0/Targeted_Visium_Human_Glioblastoma_Pan_Cancer)
* HumanHeart
  * [Human Heart](https://support.10xgenomics.com/spatial-gene-expression/datasets/1.1.0/V1_Human_Heart)
* HumanLymphNode
  * [Human Lymph Node](https://support.10xgenomics.com/spatial-gene-expression/datasets/1.1.0/V1_Human_Lymph_Node)
* HumanOvarianCancer
  * [Human Ovarian Cancer: Whole Transcriptome Analysis](https://support.10xgenomics.com/spatial-gene-expression/datasets/1.2.0/Parent_Visium_Human_OvarianCancer)
  * [Human Ovarian Cancer: Targeted, Immunology Panel](https://support.10xgenomics.com/spatial-gene-expression/datasets/1.2.0/Targeted_Visium_Human_OvarianCancer_Immunology)
  * [Human Ovarian Cancer: Targeted, Pan-Cancer Panel](https://support.10xgenomics.com/spatial-gene-expression/datasets/1.2.0/Targeted_Visium_Human_OvarianCancer_Pan_Cancer)
* HumanSpinalCord
  * [Human Spinal Cord: Whole Transcriptome Analysis](https://support.10xgenomics.com/spatial-gene-expression/datasets/1.2.0/Parent_Visium_Human_SpinalCord)
  * [Human Spinal Cord: Targeted, Neuroscience Panel](https://support.10xgenomics.com/spatial-gene-expression/datasets/1.2.0/Targeted_Visium_Human_SpinalCord_Neuroscience)
* MouseBrainCoronal
  * [Mouse Brain Section (Coronal)](https://support.10xgenomics.com/spatial-gene-expression/datasets/1.1.0/V1_Adult_Mouse_Brain)
* MouseBrainSagittalAnterior
  * [Mouse Brain Serial Section 1 (Sagittal-Anterior)](https://support.10xgenomics.com/spatial-gene-expression/datasets/1.1.0/V1_Mouse_Brain_Sagittal_Anterior)
  * [Mouse Brain Serial Section 2 (Sagittal-Anterior)](https://support.10xgenomics.com/spatial-gene-expression/datasets/1.1.0/V1_Mouse_Brain_Sagittal_Anterior_Section_2)
* MouseBrainSagittalPosterior
  * [Mouse Brain Serial Section 1 (Sagittal-Posterior)](https://support.10xgenomics.com/spatial-gene-expression/datasets/1.1.0/V1_Mouse_Brain_Sagittal_Posterior)
  * [Mouse Brain Serial Section 2 (Sagittal-Posterior)](https://support.10xgenomics.com/spatial-gene-expression/datasets/1.1.0/V1_Mouse_Brain_Sagittal_Posterior_Section_2)
* MouseKidneyCoronal
  * [Mouse Kidney Section (Coronal)](https://support.10xgenomics.com/spatial-gene-expression/datasets/1.1.0/V1_Mouse_Kidney)

A list of currently available datasets can be obtained using the `ExperimentHub` interface:

```{r}
library(ExperimentHub)
eh <- ExperimentHub()
(q <- query(eh, "TENxVisium"))
```

# Loading the data

To retrieve a dataset, we can use a dataset's corresponding named function `<id>()`, where `<id>` should correspond to one a valid dataset identifier (see `?TENxVisiumData`). E.g.:

```{r}
library(TENxVisiumData)
spe <- HumanHeart()
```

Alternatively, data can loaded directly from Bioconductor's `r Biocpkg("ExerimentHub")` as follows. First, we initialize a hub instance and store the complete list of records in a variable `eh`. Using `query()`, we then identify any records made available by the `TENxVisiumData` package, as well as their accession IDs (EH1234). Finally, we can load the data into R via `eh[[id]]`, where `id` corresponds to the data entry's identifier we'd like to load. E.g.:

```{r}
library(ExperimentHub)
eh <- ExperimentHub()        # initialize hub instance
q <- query(eh, "TENxVisium") # retrieve 'TENxVisiumData' records
id <- q$ah_id[1]             # specify dataset ID to load
spe <- eh[[id]]              # load specified dataset
```

# Data representation

Each dataset is provided as a `r Biocpkg("SpatialExperiment")` (SPE), which extends the `r Biocpkg("SingleCellExperiment")` (SCE) class with features specific to spatially resolved data: 

```{r}
spe
```

For details on the SPE class, we refer to the package's vignette. Briefly, the SPE harbors the following data in addition to that stored in a SCE:

`spatialCoords`; a numeric matrix of spatial coordinates, stored inside the object's `int_colData`:

```{r}
head(spatialCoords(spe))
```

`spatialData`; a `DFrame` of spatially-related sample metadata, stored as part of the object's `colData`. This `colData` subset is in turn determined by the `int_metadata` field `spatialDataNames`:

```{r}
head(spatialData(spe))
```

`imgData`; a `DFrame` containing image-related data, stored inside the `int_metadata`:

```{r}
imgData(spe)
```

Datasets with multiple sections are consolidated into a single SPE with `colData` field `sample_id` indicating each spot's sample of origin. E.g.:

```{r}
spe <- MouseBrainSagittalAnterior()
table(spe$sample_id)
```

Datasets of targeted analyses are provided as a *nested* SPE, with whole transcriptome measurements as primary data, and those obtained from targeted panels as `altExp`s. E.g.:

```{r}
spe <- HumanOvarianCancer()
altExpNames(spe)
```

<style type="text/css"> .smaller { font-size: 10px } </style>

# Session information {- .smaller}

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