about.Rmd

---
title: "STUtility - Vignette"
author:
- Joseph Bergenstråhle, Royal Institute of Technology (KTH)
- Ludvig Larsson, Royal Institute of Technology (KTH)
date: ''
#output:
#  html_document:
#    theme: darkly
#    css: style.css
#    number_sections: false
#    toc: yes
#    toc_depth: 3
#    toc_float:
#      collapsed: false
#      smooth_scroll: true
#  pdf_document:
#    number_sections: false
#    toc: yes
#    toc_depth: 3
---

<style type="text/css">
div.main-container {
  background-color: #000000 !important;
  max-width: 1400px;
  margin-left: auto;
  margin-right: auto;
}
</style>
<style>
#TOC {
  background: url("https://www.spatialresearch.org/wp-content/uploads/2019/09/str-logo-spatial_research_3@2x.png");
  background-size: contain;
  padding-top: 100px !important;
  background-repeat: no-repeat;
  op: 5%;
  opacity: 0.8;
  width: 500px;
  color: white;
  border-color: #000000 !important;
}
</style>

<style> code, pre{
  background-color: #000000 !important;
  color: white !important;
}
</style>
<style> 
body {
  color: white
}
</style>
<style>
.list-group-item.active, .list-group-item.active:focus, .list-group-item.active:hover {
    background-color: #375a7f;
}
</style>



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

# Background

## Spatial Transcriptomics (ST)

---

The tutorial aims to lay the foundation of best practice for ST data analysis. At such, the user is probably already familiar with the underlying method and a detailed description is therefore found elsewhere. Interested readers are pointed to the original publication from 2016 (https://science.sciencemag.org/content/353/6294/78). 

![Schematic Spatial Transcriptomics](assets/st_method_1.png)

In short, there are two main output components from an ST experiment; (i) the gene expression data and (ii) the image data. 

All the steps explained in this guide could be performed with only the expression data. However, the image data, apart from being fundamental to the biological interpretation, is used to filter out capture-spots that lies directly under the tissue. This filtering excludes the unwanted data points, lowering the memory burden of the data objects created as well as removing informational noise. 

An introductory animation is available on our website: http://www.spatialresearch.org/

### Selecting spots

The gene expression data consists of a count matrix with genes in rows and capture "spots" in columns. Each spot represents a small area on an ST array from which the captured transcripts have been barcoded with a unique sequence. The unique barcode makes it possible to map the transcripts onto a spatial position on the tissue section and would be equivalent to a cell specific barcode in scRNA-seq data but can tag a mixture of transcripts from multiple cells. The spatial position of a spot is an (x, y) coordinate that defines the centroid of the spot area. These spatial coordinates are stored in the spot ids (column names) and allows us to visualize gene expression (and other spot features) in the array grid system. However, if you want to overlay a visualization on top the HE image you want to make sure that the spot coordinates are exact in relation to morphological features of the image. When the spots are printed onto the ST array surface, they will sometimes deviate from the (x, y) coordinates given by the spot ids and should therefore be adjusted. In addition to the spot adjustment, you will also need to label the spots that are located directly under the tissue. Spot adjustment and selection can be done automatically using our [ST spot detector](https://github.com/SpatialTranscriptomicsResearch/st_spot_detector) web tool which outputs a table of adjusted coordinates and labels for the spots under tissue.

## Multiple samples

The STUtility tool was developed with the goal of multiple sample inputs. As with all biological data, using multiple samples add power to the analysis and is a necessity to enable comprehensive insight which otherwise suffers from stochastic uncertainty. Within this vignette, we display how you can input multiple samples, look for aggravating circumstances like batch effects and missing data, apply methods to correct such if present, get a holistic picture of your data as well as conduct more in depth analysis in various ways.

## Seurat workflow

We have extensively tried different methods and workflows for handling ST data. While all roads lead to Rome, as of the date of this writing we find the Seurat approach [https://satijalab.org/seurat/] to be the most well suited for this type of data. Seurat is an R package designed for single-cell RNAseq data. Obviously, this deviates from the data that the ST technology currently produce, as the resolution on the array implies that each capture-spot consists of transcripts originating from multiple cells. Nevertheless, the characteristics of the ST data resembles that of scRNAseq to a large extent. Note that the STUtility package requires Seurat v3.0 or higher.

The data obtained from an ST experiment can treated like a sc-RNA-seq experiment and be processed and analyzed using the Seurat package. However, what STUtility provides is a way of utilizing the spatial component of the dataset, mostly for visualization purposes. All the image related information is stored in the Seurat object but _only_ using the workflow described in the Getting Started section. 

## 10X Visium array

In late 2018, the company Spatial Transcriptomics was acquired by 10X Genomics, which since then have been developing the new version of the technological platform that our research group have been using in the past years, called _Visium_. There are some changes in the experimental protocol for the Visium, and the type of output and subsequently input to this R tool. Since our goal is to have this R tool compatible to past and future versions of the technology, both are supported. If you are working with the Visium platform, please see [The 10X Visium platform]. 

## Naming conventions

For users familiar with the Seurat workflow, there are a number of Seruat plotting functions, e.g. `Seurat::FeaturePlot()`, those plotting functions all have a "ST version", which is called upon by adding "ST." prior to the original function name e.g. `STutility::ST.FeaturePlot()`.

The external STUtility functions are following a PascalCase convention. 

&nbsp;
<hr />
<p style="text-align: center;">A work by <a href="j.bergenstrahle@scilifelab.se">Joseph Bergenstråhle</a> and <a href="ludvig.larsson@scilifelab.se">Ludvig Larsson</a></p>

<!-- Add icon library -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">

<!-- Add font awesome icons -->
<p style="text-align: center;">
    <a href="https://www.spatialresearch.org" class="fa fa-beer"></a>
</p>

&nbsp;