---
title: "Rmagic Bone Marrow Tutorial"
output:
  html_document:
    df_print: paged
    toc: yes
    toc_depth: '3'
---

<!-- bonemarrow_tutorial.md is generated from bonemarrow_tutorial.Rmd. Please edit that file -->

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

## MAGIC (Markov Affinity-Based Graph Imputation of Cells)

* MAGIC imputes missing data values on sparse data sets, restoring the structure of the data
* It also proves dimensionality reduction and gene expression visualizations
* MAGIC can be performed on a variety of datasets
* Here, we show the effectiveness of MAGIC on erythroid and myeloid cells developing in mouse bone marrow.

Markov Affinity-based Graph Imputation of Cells (MAGIC) is an algorithm for denoising and transcript recover of single cells applied to single-cell RNA sequencing data, as described in Van Dijk D *et al.* (2018), *Recovering Gene Interactions from Single-Cell Data Using Data Diffusion*, Cell <https://www.cell.com/cell/abstract/S0092-8674(18)30724-4>.

### Installation

If you haven't yet installed MAGIC, you can find installation instructions in our [GitHub README](https://github.com/KrishnaswamyLab/MAGIC/tree/master/Rmagic).

We'll install a couple more tools for this tutorial.

```{r install_extras, eval=FALSE}
if (!require(viridis)) install.packages("viridis")
if (!require(ggplot2)) install.packages("ggplot2")
if (!require(readr)) install.packages("readr")
if (!require(phateR)) install.packages("phateR")
```

If you have never used PHATE, you should also install PHATE from the command line as follows:

```{bash install_python_phate, eval=FALSE}
pip install --user phate
```

### Loading packages

We load the Rmagic package and a few others for convenience functions.

```{r load_packages}
library(Rmagic)
library(ggplot2)
library(readr)
library(viridis)
library(phateR)
```

### Loading data

In this tutorial, we will analyse myeloid and erythroid cells in mouse bone marrow, as described in Paul et al., 2015. The example data is located in the PHATE Github repository and we can load it directly from the web. You can run this tutorial with your own data by downloading <https://raw.githubusercontent.com/KrishnaswamyLab/MAGIC/master/Rmagic/inst/examples/bonemarrow_tutorial.Rmd> and opening it in RStudio.

```{r load_data}
# load data
bmmsc <- read_csv("https://github.com/KrishnaswamyLab/PHATE/raw/master/data/BMMC_myeloid.csv.gz")
bmmsc <- bmmsc[, 2:ncol(bmmsc)]
bmmsc[1:5, 1:10]
```

### Filtering data

First, we need to remove lowly expressed genes and cells with small library size.

```{r}
# keep genes expressed in at least 10 cells
keep_cols <- colSums(bmmsc > 0) > 10
bmmsc <- bmmsc[, keep_cols]
# look at the distribution of library sizes
ggplot() +
  geom_histogram(aes(x = rowSums(bmmsc)), bins = 50) +
  geom_vline(xintercept = 1000, color = "red")
```

```{r}
# keep cells with at least 1000 UMIs
keep_rows <- rowSums(bmmsc) > 1000
bmmsc <- bmmsc[keep_rows, ]
```

### Normalizing data

We should library size normalize and transform the data prior to MAGIC. Many people use a log transform, which requires adding a "pseudocount" to avoid log(0). We square root instead, which has a similar form but doesn't suffer from instabilities at zero.

```{r normalize}
bmmsc <- library.size.normalize(bmmsc)
bmmsc <- sqrt(bmmsc)
```

### Running MAGIC

Running MAGIC is as simple as running the `magic` function.

```{r run_magic}
# run MAGIC
bmmsc_MAGIC <- magic(bmmsc, genes = c("Mpo", "Klf1", "Ifitm1"))
```

We can plot the data before and after MAGIC to visualize the results.

```{r plot_raw}
ggplot(bmmsc) +
  geom_point(aes(Mpo, Klf1, color = Ifitm1)) +
  scale_color_viridis(option = "B")
ggsave("BMMSC_data_R_before_magic.png", width = 5, height = 5)
```

The data suffers from dropout to the point that we cannot infer anything about the gene-gene relationships.

```{r plot_magic}
ggplot(bmmsc_MAGIC) +
  geom_point(aes(Mpo, Klf1, color = Ifitm1)) +
  scale_color_viridis(option = "B")
```

As you can see, the gene-gene relationships are much clearer after MAGIC. These relationships also match the biological progression we expect to see - Ifitm1 is a stem cell marker, Klf1 is an erythroid marker, and Mpo is a myeloid marker.

### Rerunning MAGIC with new parameters

The data is a little too smooth - we can increase `t` from the default value of 3 to increase the amount of diffusion. We pass the original result to the argument `init` to avoid recomputing intermediate steps.

```{r decrease_t}
bmmsc_MAGIC <- magic(bmmsc,
  genes = c("Mpo", "Klf1", "Ifitm1"),
  t = 4, init = bmmsc_MAGIC
)
ggplot(bmmsc_MAGIC) +
  geom_point(aes(Mpo, Klf1, color = Ifitm1)) +
  scale_color_viridis(option = "B")
ggsave("BMMSC_data_R_after_magic.png", width = 5, height = 5)
```

### Visualizing MAGIC values on PCA

We can visualize the results of MAGIC on PCA with `genes="pca_only"`.

```{r run_pca}
bmmsc_MAGIC_PCA <- magic(bmmsc,
  genes = "pca_only",
  t = 4, init = bmmsc_MAGIC
)
# ggplot(bmmsc_MAGIC_PCA) +
geom_point(aes(x = PC1, y = PC2, color = bmmsc_MAGIC$result$Klf1)) +
  scale_color_viridis(option = "B") +
  labs(color = "Klf1")
ggsave("BMMSC_data_R_pca_colored_by_magic.png", width = 5, height = 5)
```


### Visualizing MAGIC values on PHATE

We can visualize the results of MAGIC on PHATE as follows.

```{r run_phate}
bmmsc_PHATE <- phate(bmmsc)
ggplot(bmmsc_PHATE) +
  geom_point(aes(x = PHATE1, y = PHATE2, color = bmmsc_MAGIC$result$Klf1)) +
  scale_color_viridis(option = "B") +
  labs(color = "Klf1")
ggsave("BMMSC_data_R_phate_colored_by_magic.png", width = 5, height = 5)
```

### Using MAGIC for downstream analysis

We can look at the entire smoothed matrix with `genes='all_genes'`, passing the original result to the argument `init` to avoid recomputing intermediate steps. Note that this matrix may be large and could take up a lot of memory.

```{r run_magic_full_matrix}
bmmsc_MAGIC <- magic(bmmsc,
  genes = "all_genes",
  t = 4, init = bmmsc_MAGIC
)
as.data.frame(bmmsc_MAGIC)[1:5, 1:10]
```

## Help

If you have any questions or require assistance using MAGIC, please contact us at <https://krishnaswamylab.org/get-help>.
