---
title: "Import and representation of MERFISH mouse hypothalamus data"
author: 
  - name: Ludwig Geistlinger    
    affiliation: Center for Computational Biomedicine, Harvard Medical School
  - name: Tyrone Lee  
    affiliation: Center for Computational Biomedicine, Harvard Medical School
  - name: Jeffrey Moffitt
    affiliation: Department of Microbiology, Harvard Medical School
  - name: Robert Gentleman
    affiliation: Center for Computational Biomedicine, Harvard Medical School
output:
  BiocStyle::html_document:
    self_contained: yes 
    toc: true
    toc_float: true
    toc_depth: 2
    code_folding: show
date: "`r doc_date()`"
vignette: >
  % \VignetteIndexEntry{Mouse hypothalamus}
  % \VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
    collapse = TRUE,
    comment = "#>",
    crop = NULL ## Related to https://stat.ethz.ch/pipermail/bioc-devel/2020-April/016656.html
)
```

# Installation

To install the package, start R and enter: 

```{r, eval = FALSE}
if(!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("MerfishData")
``` 

# Setup

After the installation, we proceed by loading the package and additional packages
used in the vignette.

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

# Data

[Moffitt et al., 2018](https://doi.org/10.1126/science.aau5324) 
developed an imaging-based cell type identification and mapping method and
combined it with single-cell RNA-sequencing to create a molecularly annotated
and spatially resolved cell atlas of the mouse hypothalamic preoptic region.

Def. hypothalamic preoptic region: is a part of the anterior hypothalamus that 
controls essential social behaviors and homeostatic functions.

Cell segmentation was carried out based on total polyadenylated mRNA and
DAPI nuclei costains. Combinatorial smFISH imaging was used for the 
identification and spatial expression profiling of 161 genes in 1,027,848 cells
from 36 mice (16 female, 20 male).

The data was obtained from the 
[datadryad data publication](https://doi.org/10.5061/dryad.8t8s248).

This vignette demonstrates how to obtain the MERFISH mouse hypothalamic preoptic
region dataset from [Moffitt et al., 2018](https://doi.org/10.1126/science.aau5324)
from Bioconductor's [ExperimentHub](https://bioconductor.org/packages/ExperimentHub).

```{r}
eh <- ExperimentHub()
query(eh, c("MerfishData", "hypothalamus"))
```

Note: complementary scRNA-seq of ~31,000 cells dissociated and captured from the
preoptic region of the hypothalamus from multiple male and female mice is available
on GEO ([GSE113576](https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE113576)).

## Segmented data

It is also possible to obtain the data in a [SpatialExperiment](https://bioconductor.org/packages/ExperimentHub), which integrates experimental data and cell metadata, and provides designated accessors for the spatial coordinates.

```{r, message = FALSE}
spe <- MouseHypothalamusMoffitt2018()
spe
```

Inspect the data components:

```{r}
assay(spe)[1:5,1:5]
assay(spe, "molecules")["Aldh1l1",1]
colData(spe)
head(spatialCoords(spe))
```

Def. Bregma: The bregma is the anatomical point on the skull at which the coronal
suture is intersected perpendicularly by the sagittal suture. Used here as a 
reference point for the twelve 1.8- by 1.8-mm imaged slices along the z-axis.

The anterior position of the preoptic region is at Bregma +0.26.

```{r}
table(spatialCoords(spe)[,"z"])
```

Cell type assignment:

```{r}
table(spe$cell_class)
```

# Visualization

Visualize cell centroids and annotated cell type labels as in Figure 3E of the 
[paper](https://doi.org/10.1126/science.aau5324)
for six different anterior-posterior positions from a single female mouse.

```{r}
relz <- c(0.26, 0.16, 0.06, -0.04, -0.14, -0.24)
cdat <- data.frame(colData(spe), spatialCoords(spe))
cdat <- subset(cdat, cell_class != "Ambiguous")
cdat$cell_class <- sub(" [1-4]$", "", cdat$cell_class)
cdat <- subset(cdat, z %in% relz)
cdat$z <- as.character(cdat$z)
zum <- paste(0:5 * 100, "um")
names(zum) <- as.character(relz)
cdat$z <- unname(zum[cdat$z]) 
```

```{r, fig.wide = TRUE, fig.width = 10, fig.height = 10}
pal <- get_palette("simpsons", 9)
names(pal) <- c("Endothelial", "Excitatory", "OD Immature", "Astrocyte", "Mural",
                "Microglia", "Ependymal", "Inhibitory", "OD Mature")
ggscatter(cdat, x = "x", y = "y", color = "cell_class", facet.by = "z",
          shape = 20, size = 1, palette = pal) +
          guides(color = guide_legend(override.aes = list(size = 3)))
```

# Interactive exploration

The MERFISH mouse hypothalamus dataset is part of the
[gallery of publicly available MERFISH datasets](https://moffittlab.connect.hms.harvard.edu/merfish/merfish_homepage.html).

This gallery consists of dedicated 
[iSEE](https://bioconductor.org/packages/iSEE) and 
[Vitessce](http://vitessce.io/) instances, published on 
[Posit Connect](https://posit.co/products/enterprise/connect/), 
that enable the interactive exploration of different segmentations,
the expression of marker genes, and overlay of
cell metadata on a spatial grid or a microscopy image.

# SessionInfo

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