Rmagic Bone Marrow Tutorial

Installation

If you haven’t yet installed MAGIC, you can find installation instructions in our GitHub README.

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

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:

pip install --user phate

Loading packages

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

library(Rmagic)

## Loading required package: Matrix

library(ggplot2)

## Warning: package 'ggplot2' was built under R version 3.5.3

library(readr)
library(viridis)

## Loading required package: viridisLite

library(phateR)

## 
## Attaching package: 'phateR'

## The following object is masked from 'package:Rmagic':
## 
##     library.size.normalize

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.

# load data
bmmsc <- read_csv("https://github.com/KrishnaswamyLab/PHATE/raw/master/data/BMMC_myeloid.csv.gz")

## Warning: Missing column names filled in: 'X1' [1]

## Parsed with column specification:
## cols(
##   .default = col_integer(),
##   X1 = col_character()
## )

## See spec(...) for full column specifications.

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.

# 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')

# 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.

bmmsc <- library.size.normalize(bmmsc)
bmmsc <- sqrt(bmmsc)

Running MAGIC

Running MAGIC is as simple as running the magic function.

# run MAGIC
bmmsc_MAGIC <- magic(bmmsc, genes=c("Mpo", "Klf1", "Ifitm1"))

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

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.

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 decrease t from the automatic value to reduce the amount of diffusion. We pass the original result to the argument init to avoid recomputing intermediate steps.

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".

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.

bmmsc_PHATE <- phate(bmmsc, knn=4, decay=100, t=20)
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.

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