scRNA-seq yield many molecular readouts that are hard to interpret by themselves. One way of summarizing this information is by inferring transcription factor (TF) activities from prior knowledge.

In this notebook we showcase how to use decoupleR for transcription factor activity inference with a down-sampled PBMCs 10X data-set. The data consists of 160 PBMCs from a Healthy Donor. The original data is freely available from 10x Genomics here from this webpage.

1 Loading packages

First, we need to load the relevant packages, Seurat to handle scRNA-seq data and decoupleR to use statistical methods.

## We load the required packages
library(Seurat)
library(decoupleR)

# Only needed for data handling and plotting
library(tidyverse)
library(patchwork)
library(ggplot2)
library(pheatmap)

2 Loading the data-set

Here we used a down-sampled version of the data used in the Seurat vignette. We can open the data like this:

inputs_dir <- system.file("extdata", package = "decoupleR")
data <- readRDS(file.path(inputs_dir, "sc_data.rds"))

We can observe that we have different cell types:

DimPlot(data, reduction = "umap", label = TRUE, pt.size = 0.5) + NoLegend()

3 DoRothEA network

DoRothEA is a comprehensive resource containing a curated collection of TFs and their transcriptional targets. Since these regulons were gathered from different types of evidence, interactions in DoRothEA are classified in different confidence levels, ranging from A (highest confidence) to D (lowest confidence). Moreover, each interaction is weighted by its confidence level and the sign of its mode of regulation (activation or inhibition).

For this example we will use the human version (mouse is also available) and we will use the confidence levels ABC. We can use decoupleR to retrieve it from OmniPath:

net <- get_dorothea(organism='human', levels=c('A', 'B', 'C'))
net
#> # A tibble: 32,277 × 4
#>    source confidence target     mor
#>    <chr>  <chr>      <chr>    <dbl>
#>  1 ADNP   C          ATF7IP   0.333
#>  2 ADNP   C          DYRK1A   0.333
#>  3 ADNP   C          TLK1     0.333
#>  4 ADNP   C          ZMYM4    0.333
#>  5 AHR    C          ARHGAP15 0.333
#>  6 AHR    C          ARID5B   0.333
#>  7 AHR    B          ASAP1    0.5  
#>  8 AHR    C          CREB5    0.333
#>  9 AHR    C          CTNNA1   0.333
#> 10 AHR    C          CTNNA2   0.333
#> # … with 32,267 more rows

4 Activity inference with Weighted Mean

To infer activities we will run the Weighted Mean method (wmean). It infers regulator activities by first multiplying each target feature by its associated weight which then are summed to an enrichment score wmean. Furthermore, permutations of random target features can be performed to obtain a null distribution that can be used to compute a z-score norm_wmean, or a corrected estimate corr_wmean by multiplying wmean by the minus log10 of the obtained empirical p-value.

In this example we use wmean but we could have used any other. To see what methods are available use show_methods().

To run decoupleR methods, we need an input matrix (mat), an input prior knowledge network/resource (net), and the name of the columns of net that we want to use.

# Extract the normalized log-transformed counts
mat <- as.matrix(data@assays$RNA@data)

# Run wmean
acts <- run_wmean(mat=mat, net=net, .source='source', .target='target',
                  .mor='mor', times = 100, minsize = 5)
acts
#> # A tibble: 131,520 × 5
#>    statistic  source condition         score p_value
#>    <chr>      <chr>  <chr>             <dbl>   <dbl>
#>  1 corr_wmean AHR    AAACATACAACCAC-1 0.947     0.02
#>  2 corr_wmean AHR    AAACGCTGTTTCTG-1 0.203     0.24
#>  3 corr_wmean AHR    AACCTTTGGACGGA-1 1.49      0.02
#>  4 corr_wmean AHR    AACGCCCTCGTACA-1 0.0682    0.56
#>  5 corr_wmean AHR    AACGTCGAGTATCG-1 0.0285    0.36
#>  6 corr_wmean AHR    AACTCACTCAAGCT-1 0.389     0.14
#>  7 corr_wmean AHR    AAGATGGAAAACAG-1 0.173     0.24
#>  8 corr_wmean AHR    AAGATTACCGCCTT-1 1.32      0.02
#>  9 corr_wmean AHR    AAGCCATGAACTGC-1 0.560     0.08
#> 10 corr_wmean AHR    AAGGTCTGCAGATC-1 0.149     0.28
#> # … with 131,510 more rows

5 Visualization

From the obtained results, we will select the norm_wmean activities and store them in our object as a new assay called tfswmean:

# Extract norm_wmean and store it in tfswmean in pbmc
data[['tfswmean']] <- acts %>%
  filter(statistic == 'norm_wmean') %>%
  pivot_wider(id_cols = 'source', names_from = 'condition',
              values_from = 'score') %>%
  column_to_rownames('source') %>%
  Seurat::CreateAssayObject(.)

# Change assay
DefaultAssay(object = data) <- "tfswmean"

# Scale the data
data <- ScaleData(data)
data@assays$tfswmean@data <- data@assays$tfswmean@scale.data

This new assay can be used to plot activities. Here we observe the activity inferred for PAX5 across cells, which it is particulary active in B cells. Interestingly, PAX5 is a known TF crucial for B cell identity and function. The inference of activities from “foot-prints” of target genes is more informative than just looking at the molecular readouts of a given TF, as an example here is the gene expression of PAX5, which is not very informative by itself:

p1 <- DimPlot(data, reduction = "umap", label = TRUE, pt.size = 0.5) + 
  NoLegend() + ggtitle('Cell types')
p2 <- (FeaturePlot(data, features = c("PAX5")) & 
  scale_colour_gradient2(low = 'blue', mid = 'white', high = 'red')) +
  ggtitle('PAX5 activity')
DefaultAssay(object = data) <- "RNA"
p3 <- FeaturePlot(data, features = c("PAX5")) + ggtitle('PAX5 expression')
DefaultAssay(object = data) <- "tfswmean"
p1 | p2 | p3

6 Exploration

We can also see what is the mean activity per group of the top 20 more variable TFs:

n_tfs <- 25
# Extract activities from object as a long dataframe
df <- t(as.matrix(data@assays$tfswmean@data)) %>%
  as.data.frame() %>%
  mutate(cluster = Idents(data)) %>%
  pivot_longer(cols = -cluster, names_to = "source", values_to = "score") %>%
  group_by(cluster, source) %>%
  summarise(mean = mean(score))

# Get top tfs with more variable means across clusters
tfs <- df %>%
  group_by(source) %>%
  summarise(std = sd(mean)) %>%
  arrange(-abs(std)) %>%
  head(n_tfs) %>%
  pull(source)

# Subset long data frame to top tfs and transform to wide matrix
top_acts_mat <- df %>%
  filter(source %in% tfs) %>%
  pivot_wider(id_cols = 'cluster', names_from = 'source',
              values_from = 'mean') %>%
  column_to_rownames('cluster') %>%
  as.matrix()

# Choose color palette
palette_length = 100
my_color = colorRampPalette(c("Darkblue", "white","red"))(palette_length)

my_breaks <- c(seq(-3, 0, length.out=ceiling(palette_length/2) + 1),
               seq(0.05, 3, length.out=floor(palette_length/2)))

# Plot
pheatmap(top_acts_mat, border_color = NA, color=my_color, breaks = my_breaks) 

Here we can observe other known marker TFs appearing, PAX5 for B cells RFX5 for the myeloid lineage and JUND for the lymphoid.

7 Session information

#> ─ Session info ───────────────────────────────────────────────────────────────────────────────────────────────────────
#>  setting  value
#>  version  R version 4.1.3 (2022-03-10)
#>  os       Ubuntu 20.04.4 LTS
#>  system   x86_64, linux-gnu
#>  ui       X11
#>  language (EN)
#>  collate  C
#>  ctype    en_US.UTF-8
#>  tz       America/New_York
#>  date     2022-04-03
#>  pandoc   2.5 @ /usr/bin/ (via rmarkdown)
#> 
#> ─ Packages ───────────────────────────────────────────────────────────────────────────────────────────────────────────
#>  package         * version date (UTC) lib source
#>  abind             1.4-5   2016-07-21 [2] CRAN (R 4.1.3)
#>  assertthat        0.2.1   2019-03-21 [2] CRAN (R 4.1.3)
#>  backports         1.4.1   2021-12-13 [2] CRAN (R 4.1.3)
#>  BiocManager       1.30.16 2021-06-15 [2] CRAN (R 4.1.3)
#>  BiocParallel      1.28.3  2022-04-03 [2] Bioconductor
#>  BiocStyle       * 2.22.0  2022-04-03 [2] Bioconductor
#>  bit               4.0.4   2020-08-04 [2] CRAN (R 4.1.3)
#>  bit64             4.0.5   2020-08-30 [2] CRAN (R 4.1.3)
#>  bookdown          0.25    2022-03-16 [2] CRAN (R 4.1.3)
#>  broom             0.7.12  2022-01-28 [2] CRAN (R 4.1.3)
#>  bslib             0.3.1   2021-10-06 [2] CRAN (R 4.1.3)
#>  cellranger        1.1.0   2016-07-27 [2] CRAN (R 4.1.3)
#>  checkmate         2.0.0   2020-02-06 [2] CRAN (R 4.1.3)
#>  cli               3.2.0   2022-02-14 [2] CRAN (R 4.1.3)
#>  cluster           2.1.3   2022-03-28 [2] CRAN (R 4.1.3)
#>  codetools         0.2-18  2020-11-04 [2] CRAN (R 4.1.3)
#>  colorspace        2.0-3   2022-02-21 [2] CRAN (R 4.1.3)
#>  cowplot           1.1.1   2020-12-30 [2] CRAN (R 4.1.3)
#>  crayon            1.5.1   2022-03-26 [2] CRAN (R 4.1.3)
#>  curl              4.3.2   2021-06-23 [2] CRAN (R 4.1.3)
#>  data.table        1.14.2  2021-09-27 [2] CRAN (R 4.1.3)
#>  DBI               1.1.2   2021-12-20 [2] CRAN (R 4.1.3)
#>  dbplyr            2.1.1   2021-04-06 [2] CRAN (R 4.1.3)
#>  decoupleR       * 2.0.1   2022-04-03 [1] Bioconductor
#>  deldir            1.0-6   2021-10-23 [2] CRAN (R 4.1.3)
#>  digest            0.6.29  2021-12-01 [2] CRAN (R 4.1.3)
#>  dplyr           * 1.0.8   2022-02-08 [2] CRAN (R 4.1.3)
#>  ellipsis          0.3.2   2021-04-29 [2] CRAN (R 4.1.3)
#>  evaluate          0.15    2022-02-18 [2] CRAN (R 4.1.3)
#>  fansi             1.0.3   2022-03-24 [2] CRAN (R 4.1.3)
#>  farver            2.1.0   2021-02-28 [2] CRAN (R 4.1.3)
#>  fastmap           1.1.0   2021-01-25 [2] CRAN (R 4.1.3)
#>  fastmatch         1.1-3   2021-07-23 [2] CRAN (R 4.1.3)
#>  fgsea             1.20.0  2022-04-03 [2] Bioconductor
#>  fitdistrplus      1.1-8   2022-03-10 [2] CRAN (R 4.1.3)
#>  forcats         * 0.5.1   2021-01-27 [2] CRAN (R 4.1.3)
#>  fs                1.5.2   2021-12-08 [2] CRAN (R 4.1.3)
#>  future            1.24.0  2022-02-19 [2] CRAN (R 4.1.3)
#>  future.apply      1.8.1   2021-08-10 [2] CRAN (R 4.1.3)
#>  generics          0.1.2   2022-01-31 [2] CRAN (R 4.1.3)
#>  ggplot2         * 3.3.5   2021-06-25 [2] CRAN (R 4.1.3)
#>  ggrepel         * 0.9.1   2021-01-15 [2] CRAN (R 4.1.3)
#>  ggridges          0.5.3   2021-01-08 [2] CRAN (R 4.1.3)
#>  globals           0.14.0  2020-11-22 [2] CRAN (R 4.1.3)
#>  glue              1.6.2   2022-02-24 [2] CRAN (R 4.1.3)
#>  goftest           1.2-3   2021-10-07 [2] CRAN (R 4.1.3)
#>  gridExtra         2.3     2017-09-09 [2] CRAN (R 4.1.3)
#>  gtable            0.3.0   2019-03-25 [2] CRAN (R 4.1.3)
#>  haven             2.4.3   2021-08-04 [2] CRAN (R 4.1.3)
#>  highr             0.9     2021-04-16 [2] CRAN (R 4.1.3)
#>  hms               1.1.1   2021-09-26 [2] CRAN (R 4.1.3)
#>  htmltools         0.5.2   2021-08-25 [2] CRAN (R 4.1.3)
#>  htmlwidgets       1.5.4   2021-09-08 [2] CRAN (R 4.1.3)
#>  httpuv            1.6.5   2022-01-05 [2] CRAN (R 4.1.3)
#>  httr              1.4.2   2020-07-20 [2] CRAN (R 4.1.3)
#>  ica               1.0-2   2018-05-24 [2] CRAN (R 4.1.3)
#>  igraph            1.3.0   2022-04-01 [2] CRAN (R 4.1.3)
#>  irlba             2.3.5   2021-12-06 [2] CRAN (R 4.1.3)
#>  jquerylib         0.1.4   2021-04-26 [2] CRAN (R 4.1.3)
#>  jsonlite          1.8.0   2022-02-22 [2] CRAN (R 4.1.3)
#>  KernSmooth        2.23-20 2021-05-03 [2] CRAN (R 4.1.3)
#>  knitr             1.38    2022-03-25 [2] CRAN (R 4.1.3)
#>  labeling          0.4.2   2020-10-20 [2] CRAN (R 4.1.3)
#>  later             1.3.0   2021-08-18 [2] CRAN (R 4.1.3)
#>  lattice           0.20-45 2021-09-22 [2] CRAN (R 4.1.3)
#>  lazyeval          0.2.2   2019-03-15 [2] CRAN (R 4.1.3)
#>  leiden            0.3.9   2021-07-27 [2] CRAN (R 4.1.3)
#>  lifecycle         1.0.1   2021-09-24 [2] CRAN (R 4.1.3)
#>  listenv           0.8.0   2019-12-05 [2] CRAN (R 4.1.3)
#>  lmtest            0.9-40  2022-03-21 [2] CRAN (R 4.1.3)
#>  logger            0.2.2   2021-10-19 [2] CRAN (R 4.1.3)
#>  lubridate         1.8.0   2021-10-07 [2] CRAN (R 4.1.3)
#>  magick            2.7.3   2021-08-18 [2] CRAN (R 4.1.3)
#>  magrittr          2.0.3   2022-03-30 [2] CRAN (R 4.1.3)
#>  MASS              7.3-56  2022-03-23 [2] CRAN (R 4.1.3)
#>  Matrix            1.4-1   2022-03-23 [2] CRAN (R 4.1.3)
#>  matrixStats       0.61.0  2021-09-17 [2] CRAN (R 4.1.3)
#>  mgcv              1.8-40  2022-03-29 [2] CRAN (R 4.1.3)
#>  mime              0.12    2021-09-28 [2] CRAN (R 4.1.3)
#>  miniUI            0.1.1.1 2018-05-18 [2] CRAN (R 4.1.3)
#>  modelr            0.1.8   2020-05-19 [2] CRAN (R 4.1.3)
#>  munsell           0.5.0   2018-06-12 [2] CRAN (R 4.1.3)
#>  nlme              3.1-157 2022-03-25 [2] CRAN (R 4.1.3)
#>  OmnipathR         3.2.8   2022-04-03 [2] Bioconductor
#>  parallelly        1.30.0  2021-12-17 [2] CRAN (R 4.1.3)
#>  patchwork       * 1.1.1   2020-12-17 [2] CRAN (R 4.1.3)
#>  pbapply           1.5-0   2021-09-16 [2] CRAN (R 4.1.3)
#>  pheatmap        * 1.0.12  2019-01-04 [2] CRAN (R 4.1.3)
#>  pillar            1.7.0   2022-02-01 [2] CRAN (R 4.1.3)
#>  pkgconfig         2.0.3   2019-09-22 [2] CRAN (R 4.1.3)
#>  plotly            4.10.0  2021-10-09 [2] CRAN (R 4.1.3)
#>  plyr              1.8.7   2022-03-24 [2] CRAN (R 4.1.3)
#>  png               0.1-7   2013-12-03 [2] CRAN (R 4.1.3)
#>  polyclip          1.10-0  2019-03-14 [2] CRAN (R 4.1.3)
#>  prettyunits       1.1.1   2020-01-24 [2] CRAN (R 4.1.3)
#>  progress          1.2.2   2019-05-16 [2] CRAN (R 4.1.3)
#>  promises          1.2.0.1 2021-02-11 [2] CRAN (R 4.1.3)
#>  purrr           * 0.3.4   2020-04-17 [2] CRAN (R 4.1.3)
#>  R6                2.5.1   2021-08-19 [2] CRAN (R 4.1.3)
#>  RANN              2.6.1   2019-01-08 [2] CRAN (R 4.1.3)
#>  rappdirs          0.3.3   2021-01-31 [2] CRAN (R 4.1.3)
#>  RColorBrewer      1.1-2   2014-12-07 [2] CRAN (R 4.1.3)
#>  Rcpp              1.0.8.3 2022-03-17 [2] CRAN (R 4.1.3)
#>  RcppAnnoy         0.0.19  2021-07-30 [2] CRAN (R 4.1.3)
#>  readr           * 2.1.2   2022-01-30 [2] CRAN (R 4.1.3)
#>  readxl            1.4.0   2022-03-28 [2] CRAN (R 4.1.3)
#>  RefManageR      * 1.3.0   2020-11-13 [2] CRAN (R 4.1.3)
#>  reprex            2.0.1   2021-08-05 [2] CRAN (R 4.1.3)
#>  reshape2          1.4.4   2020-04-09 [2] CRAN (R 4.1.3)
#>  reticulate        1.24    2022-01-26 [2] CRAN (R 4.1.3)
#>  rlang             1.0.2   2022-03-04 [2] CRAN (R 4.1.3)
#>  rmarkdown         2.13    2022-03-10 [2] CRAN (R 4.1.3)
#>  ROCR              1.0-11  2020-05-02 [2] CRAN (R 4.1.3)
#>  rpart             4.1.16  2022-01-24 [2] CRAN (R 4.1.3)
#>  rstudioapi        0.13    2020-11-12 [2] CRAN (R 4.1.3)
#>  Rtsne             0.15    2018-11-10 [2] CRAN (R 4.1.3)
#>  rvest             1.0.2   2021-10-16 [2] CRAN (R 4.1.3)
#>  sass              0.4.1   2022-03-23 [2] CRAN (R 4.1.3)
#>  scales            1.1.1   2020-05-11 [2] CRAN (R 4.1.3)
#>  scattermore       0.8     2022-02-14 [2] CRAN (R 4.1.3)
#>  sctransform       0.3.3   2022-01-13 [2] CRAN (R 4.1.3)
#>  sessioninfo       1.2.2   2021-12-06 [2] CRAN (R 4.1.3)
#>  Seurat          * 4.1.0   2022-01-14 [2] CRAN (R 4.1.3)
#>  SeuratObject    * 4.0.4   2021-11-23 [2] CRAN (R 4.1.3)
#>  shiny             1.7.1   2021-10-02 [2] CRAN (R 4.1.3)
#>  spatstat.core     2.4-2   2022-04-01 [2] CRAN (R 4.1.3)
#>  spatstat.data     2.1-4   2022-03-29 [2] CRAN (R 4.1.3)
#>  spatstat.geom     2.4-0   2022-03-29 [2] CRAN (R 4.1.3)
#>  spatstat.random   2.2-0   2022-03-30 [2] CRAN (R 4.1.3)
#>  spatstat.sparse   2.1-0   2021-12-17 [2] CRAN (R 4.1.3)
#>  spatstat.utils    2.3-0   2021-12-12 [2] CRAN (R 4.1.3)
#>  stringi           1.7.6   2021-11-29 [2] CRAN (R 4.1.3)
#>  stringr         * 1.4.0   2019-02-10 [2] CRAN (R 4.1.3)
#>  survival          3.3-1   2022-03-03 [2] CRAN (R 4.1.3)
#>  tensor            1.5     2012-05-05 [2] CRAN (R 4.1.3)
#>  tibble          * 3.1.6   2021-11-07 [2] CRAN (R 4.1.3)
#>  tidyr           * 1.2.0   2022-02-01 [2] CRAN (R 4.1.3)
#>  tidyselect        1.1.2   2022-02-21 [2] CRAN (R 4.1.3)
#>  tidyverse       * 1.3.1   2021-04-15 [2] CRAN (R 4.1.3)
#>  tzdb              0.3.0   2022-03-28 [2] CRAN (R 4.1.3)
#>  utf8              1.2.2   2021-07-24 [2] CRAN (R 4.1.3)
#>  uwot              0.1.11  2021-12-02 [2] CRAN (R 4.1.3)
#>  vctrs             0.4.0   2022-03-30 [2] CRAN (R 4.1.3)
#>  viridisLite       0.4.0   2021-04-13 [2] CRAN (R 4.1.3)
#>  vroom             1.5.7   2021-11-30 [2] CRAN (R 4.1.3)
#>  withr             2.5.0   2022-03-03 [2] CRAN (R 4.1.3)
#>  xfun              0.30    2022-03-02 [2] CRAN (R 4.1.3)
#>  xml2              1.3.3   2021-11-30 [2] CRAN (R 4.1.3)
#>  xtable            1.8-4   2019-04-21 [2] CRAN (R 4.1.3)
#>  yaml              2.3.5   2022-02-21 [2] CRAN (R 4.1.3)
#>  zoo               1.8-9   2021-03-09 [2] CRAN (R 4.1.3)
#> 
#>  [1] /tmp/RtmpevfGyO/Rinst31899021cbf31c
#>  [2] /home/biocbuild/bbs-3.14-bioc/R/library
#> 
#> ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────