index.qmd

---
sidebar: false
toc: false
execute: 
  eval: false
---

# Spatial Transcriptomics

| Audience | Computational skills required| Duration |
:----------|:----------|:----------|
| Biologists | [Introduction to R](https://hbctraining.github.io/Intro-to-R-flipped/) | 4-session online workshop (~8 hours of trainer-led time)|

### Description

This repository has teaching materials for a hands-on **Introduction to Spatial Transcriptomics** workshop. This workshop begins with experimental design considerations and an overview of current spatial transcriptomics technologies. From there, participants will load in **Visium HD** colorectal cancer samples as a practical example of a spatial analysis workflow. The first half of the workflow will be learning how to load data, assess quality, and filter out low-quality bins using Seurat in R. Once the data has been cleaned, a standard single-cell workflow will be used: highly variable gene selection, PCA, UMAP, k-nearest neighbors, and clustering. Then, we will apply a deconvolution algorithm to annotate the celltypes in the dataset.

Building upon this foundation, participants will then conduct **analyses that incorporate the physical locations of bins on the tissue**. This includes spatial clustering, where groups are assigned based upon both gene expression and proximity to neighboring bins in the tissue. Moran's I will be utilized to identify spatially variable genes, where expression of genes change across different regions of the tissue. The workshop will conclude with a cell-cell communication analysis to assess ligand-receptor interactions between cells that are in close proximity with one another.

Working knowledge of R is required or completion of the [Introduction to R workshop](https://hbctraining.github.io/Intro-to-R-flipped/). 

::: callout-note
# Length of workshop
Please note that the schedule linked below assumes that learners will spend between 3-4 hours on reading through, and completing exercises from selected lessons between classes. The online component of the workshop focuses on more exercises and discussion/Q & A.

These materials were developed for a trainer-led workshop, but are also amenable to self-guided learning.
:::

### Learning Objectives

- Experimental design best practices of current spatial transcriptomics technologies
- Data loading and quality control of Visium HD samples
- Standard single-cell workflows adapted for spatial data, including highly variable gene selection, PCA, UMAP, kNN, and clustering
- Cell type annotation with deconvolution using `RCTD` for sequencing-based technologies
- Spatial-specific analyses that utilize the physical location of bins/cells on the tissue, including:
   - Spatial clustering with `BANKSY`
   - Spatially variable gene detection with Moran's I
   - Cell-cell communication with `CellChat`


### Lessons

- [Workshop schedule (trainer-led learning)](schedule/schedule.qmd)
- [Self-learning](schedule/self-learning.qmd)

### Installation Requirements

#### Applications
Download the most recent versions of R and RStudio for your laptop:

 - [R](http://lib.stat.cmu.edu/R/CRAN/) **(version 4.3.0 or above)**
 - [RStudio](https://www.rstudio.com/products/rstudio/download/#download)

#### Packages for R

::: callout-note
# Instructions for installing R packages

1. **Install the packages in the order listed below.**

2. **All the package names listed below are case sensitive.**

3. **Mac with Apple Silicon (M1/M2/etc.):**  
    - If running R 4.3.0 up to 4.4.3, download and install this gfortran tool *before* installing your packages:  
   <https://mac.r-project.org/tools/gfortran-12.2-universal.pkg>
    - If running R 4.5.0 or newer, download and install this gfortran tool *before* installing your packages:  
   <https://mac.r-project.org/tools/gfortran-14.2-universal.pkg>
   - More information on this can be found [here](https://mac.r-project.org/tools/)

4. **Updating old packages:**  
   If R asks in the console:  
   `Update all/some/none? [a/s/n]:`  
   type **`a`** and press <kbd>Enter</kbd>/<kbd>Return</kbd> to update any old packages.  
   _Note: Updating can take a while, so allow extra time before starting._

5. **“Binary version available but the source version is later” message:**  
   If you see:  
   `Do you want to install from sources the package which needs compilation? y/n`  
   type **`n`** (no) and press <kbd>Enter</kbd>/<kbd>Return</kbd>
:::

**(1)** Install the following packages:

**Please install them one-by-one as follows:**

```{r}
# Package managers (install first)
install.packages("remotes")
install.packages("devtools")
install.packages("BiocManager")

# CRAN packages
install.packages("tidyverse")
install.packages("scales")
install.packages("future")
install.packages("R.utils")
install.packages("arrow")
install.packages("hdf5r")
install.packages("qs2")
install.packages("Rfast2")
install.packages("leidenbase")
install.packages("harmony")
install.packages("Seurat")

# Bioconductor packages
BiocManager::install("EnhancedVolcano")
BiocManager::install("clusterProfiler")
BiocManager::install("org.Hs.eg.db")
BiocManager::install("msigdbr")
BiocManager::install("ComplexHeatmap")
BiocManager::install("BiocNeighbors")

# GitHub packages
remotes::install_github("prabhakarlab/Banksy")
remotes::install_github("satijalab/seurat-wrappers")
devtools::install_github("dmcable/spacexr", 
                         build_vignettes = FALSE)
devtools::install_github("jinworks/CellChat")
devtools::install_github("immunogenomics/presto")
```

::: {.callout-warning collapse="true"}
# Error: Failed to install `<Github_package>` from GitHub:
If you get the following error when trying to download packages from GitHub:

```{r}
#| label: package_install_error
#| eval: false
Using GitHub PAT from the git credential store.
Error: Failed to install '<Github_package>' from GitHub:
HTTP error 401.
Bad credentials
```

You will need to update your GitHub token. You can do this by installing the `usethis` and `gitcreds` packages:

```{r}
#| label: install_usethis
#| eval: false
# Install usethis and gitcreds packages
install.packages("usethis")
install.packages("gitcreds")
```

Once `usethis` have been installed, we will need to create a new GitHub token for our computer using:

```{r}
#| label: create_github_token
#| eval: false
# Create a new GitHub token
usethis::create_github_token()
```

This should take you to GitHub and allow you to create a new token. Enter a name for the token in the "Note" field, select an expiration for the token and click <kbd>Generate token</kbd> at the bottom of the webpage. This should generate a token for you that you can use.

Now we will need to set that token in R Studio, so run this command:

```{r}
#| label: set_token
#| eval: false
gitcreds::gitcreds_set()
```

It should return an option that looks like:

```{r}
#| label: set_token_prompt
#| eval: false
-> Your current credentials for 'https://github.com':

  protocol: https
  host    : github.com
  username: PersonalAccessToken
  password: <-- hidden -->
-> What would you like to do? 

1: Abort update with error, and keep the existing credentials
2: Replace these credentials
3: See the password / token
```

From here, you will select `2` and press <kbd>Enter</kbd>/<kbd>Return</kbd>. You should then be prompted with:

```{r}
#| label: enter_token
#| eval: false
-> Removing current credentials...
? Enter new password or token: 
```

Copy and paste your newly generated token in this field and press <kbd>Enter</kbd>/<kbd>Return</kbd>. It should return:

```{r}
#| label: successfully_add_token
#| eval: false
-> Adding new credentials...
-> Removing credentials from cache...
-> Done.
```

At this point you have successfully updated your GitHub token and you can try re-installing the packages from GitHub.
:::

**(2)** Finally, please check that all the packages were installed successfully by **loading them one at a time** using the `library()` function.  

```{r}
# Package managers
library(remotes)
library(devtools)
library(BiocManager)

# CRAN
library(tidyverse)
library(scales)
library(future)
library(R.utils)
library(arrow)
library(hdf5r)
library(qs2)
library(Rfast2)
library(leidenbase)
library(harmony)
library(Seurat)

# Bioconductor
library(EnhancedVolcano)
library(clusterProfiler)
library(org.Hs.eg.db)
library(msigdbr)
library(ComplexHeatmap)
library(BiocNeighbors)

# GitHub
library(Banksy)
library(SeuratWrappers)
library(spacexr)
library(CellChat)
library(presto)
```

**(3)** Once all packages have been loaded, run `sessionInfo()`.  

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

---

**(4)** Copy the output of `sessioninfo()` and paste it in the input text box below or on [this website](https://hcbc.connect.hms.harvard.edu/spatial_transcriptomics_sessionInfo_checks/). Then click the <kbd>Check my sessionInfo()</kbd> button. It will let you know if you are missing any packages. Take a screenshot of the message confirming that all packages have been successfully installed (you will get a message letting you know that no packages are missing) and email it to us before the first session.

<p align="center">

<iframe src="https://hcbc.connect.hms.harvard.edu/spatial_transcriptomics_sessionInfo_checks/" width="800px" height="800px" data-external="1">

</iframe>


### Citation

To cite material from this course in your publications, please use:

::: callout-important
# Citation
**Create Zenodo citation**
:::

A lot of time and effort went into the preparation of these materials. Citations help us understand the needs of the community, gain recognition for our work and attract further funding to support our teaching activities. Thank you for citing this material if it helped you in your data analysis!