# Transcription factor activity inference from scRNA-seq

Pau Badia-i-Mompel1

1Heidelberg Universiy

#### 4 June 2025

#### Package

decoupleR 2.15.0

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(dplyr)
    library(tibble)
    library(tidyr)
    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 CollecTRI network

CollecTRI is a comprehensive resource containing a curated collection of TFs and their transcriptional targets compiled from 12 different resources. This collection provides an increased coverage of transcription factors and a superior performance in identifying perturbed TFs compared to our previous DoRothEA network and other literature based GRNs. Similar to DoRothEA, interactions are weighted by their mode of regulation (activation or inhibition).

For this example we will use the human version (mouse and rat are also available). We can use `decoupleR` to retrieve it from `OmniPath`. The argument `split_complexes` keeps complexes or splits them into subunits, by default we recommend to keep complexes together.

    net <- get_collectri(organism='human', split_complexes=FALSE)
    #> Warning in OmnipathR::import_tf_mirna_interactions(genesymbols = TRUE, resources = "CollecTRI", : 'OmnipathR::import_tf_mirna_interactions' is deprecated.
    #> Use 'tf_mirna' instead.
    #> See help("Deprecated")
    #> Warning in readLines(con = path, encoding = encoding): incomplete final line found on
    #> 'https://omnipathdb.org/resources'
    net
    #> # A tibble: 43,178 × 3
    #>    source target   mor
    #>    <chr>  <chr>  <dbl>
    #>  1 MYC    TERT       1
    #>  2 SPI1   BGLAP      1
    #>  3 SMAD3  JUN        1
    #>  4 SMAD4  JUN        1
    #>  5 STAT5A IL2        1
    #>  6 STAT5B IL2        1
    #>  7 RELA   FAS        1
    #>  8 WT1    NR0B1      1
    #>  9 NR0B2  CASP1      1
    #> 10 SP1    ALDOA      1
    #> # ℹ 43,168 more rows

# 4 Activity inference with Univariate Linear Model (ULM)

To infer TF enrichment scores we will run the Univariate Linear Model (`ulm`) method. For each sample in our dataset (`mat`) and each TF in our network (`net`), it fits a linear model that predicts the observed gene expression based solely on the TF’s TF-Gene interaction weights. Once fitted, the obtained t-value of the slope is the score. If it is positive, we interpret that the TF is active and if it is negative we interpret that it is inactive.

ulm

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 ulm
    acts <- run_ulm(mat=mat, net=net, .source='source', .target='target',
                    .mor='mor', minsize = 5)
    acts
    #> # A tibble: 80,640 × 5
    #>    statistic source condition         score p_value
    #>    <chr>     <chr>  <chr>             <dbl>   <dbl>
    #>  1 ulm       ABL1   AAACATACAACCAC-1  2.64  0.00820
    #>  2 ulm       ABL1   AAACGCTGTTTCTG-1  0.893 0.372
    #>  3 ulm       ABL1   AACCTTTGGACGGA-1  2.79  0.00525
    #>  4 ulm       ABL1   AACGCCCTCGTACA-1  1.80  0.0721
    #>  5 ulm       ABL1   AACGTCGAGTATCG-1  1.63  0.104
    #>  6 ulm       ABL1   AACTCACTCAAGCT-1  1.71  0.0871
    #>  7 ulm       ABL1   AAGATGGAAAACAG-1  1.12  0.264
    #>  8 ulm       ABL1   AAGATTACCGCCTT-1  2.43  0.0151
    #>  9 ulm       ABL1   AAGCCATGAACTGC-1  1.62  0.105
    #> 10 ulm       ABL1   AAGGTCTGCAGATC-1 -0.292 0.771
    #> # ℹ 80,630 more rows

# 5 Visualization

From the obtained results, we store them in our object as a new assay called `tfsulm`:

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

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

    # Scale the data
    data <- ScaleData(data)
    data@assays$tfsulm@data <- data@assays$tfsulm@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) <- "tfsulm"
    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$tfsulm@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, EBF1 for B cells RFX5 for the myeloid lineage and EOMES for the lymphoid.

# 7 Session information

    #> ─ Session info ───────────────────────────────────────────────────────────────────────────────────────────────────────
    #>  setting  value
    #>  version  R version 4.5.0 (2025-04-11 ucrt)
    #>  os       Windows Server 2022 x64 (build 20348)
    #>  system   x86_64, mingw32
    #>  ui       RTerm
    #>  language (EN)
    #>  collate  C
    #>  ctype    English_United States.utf8
    #>  tz       America/New_York
    #>  date     2025-06-04
    #>  pandoc   2.7.3 @ C:/PROGRA~1/Pandoc/ (via rmarkdown)
    #>  quarto   NA
    #>
    #> ─ Packages ───────────────────────────────────────────────────────────────────────────────────────────────────────────
    #>  package          * version   date (UTC) lib source
    #>  abind              1.4-8     2024-09-12 [2] CRAN (R 4.5.0)
    #>  backports          1.5.0     2024-05-23 [2] CRAN (R 4.5.0)
    #>  bibtex             0.5.1     2023-01-26 [2] CRAN (R 4.5.0)
    #>  BiocManager        1.30.25   2024-08-28 [2] CRAN (R 4.5.0)
    #>  BiocParallel       1.43.3    2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
    #>  BiocStyle        * 2.37.0    2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
    #>  bit                4.6.0     2025-03-06 [2] CRAN (R 4.5.0)
    #>  bit64              4.6.0-1   2025-01-16 [2] CRAN (R 4.5.0)
    #>  blob               1.2.4     2023-03-17 [2] CRAN (R 4.5.0)
    #>  bookdown           0.43      2025-04-15 [2] CRAN (R 4.5.0)
    #>  bslib              0.9.0     2025-01-30 [2] CRAN (R 4.5.0)
    #>  cachem             1.1.0     2024-05-16 [2] CRAN (R 4.5.0)
    #>  cellranger         1.1.0     2016-07-27 [2] CRAN (R 4.5.0)
    #>  checkmate          2.3.2     2024-07-29 [2] CRAN (R 4.5.0)
    #>  chromote           0.5.1     2025-04-24 [2] CRAN (R 4.5.0)
    #>  cli                3.6.5     2025-04-23 [2] CRAN (R 4.5.0)
    #>  cluster            2.1.8.1   2025-03-12 [2] CRAN (R 4.5.0)
    #>  codetools          0.2-20    2024-03-31 [2] CRAN (R 4.5.0)
    #>  cowplot            1.1.3     2024-01-22 [2] CRAN (R 4.5.0)
    #>  crayon             1.5.3     2024-06-20 [2] CRAN (R 4.5.0)
    #>  curl               6.2.3     2025-05-24 [2] CRAN (R 4.5.0)
    #>  data.table         1.17.4    2025-05-26 [2] CRAN (R 4.5.0)
    #>  DBI                1.2.3     2024-06-02 [2] CRAN (R 4.5.0)
    #>  decoupleR        * 2.15.0    2025-06-04 [1] Bioconductor 3.22 (R 4.5.0)
    #>  deldir             2.0-4     2024-02-28 [2] CRAN (R 4.5.0)
    #>  dichromat          2.0-0.1   2022-05-02 [2] CRAN (R 4.5.0)
    #>  digest             0.6.37    2024-08-19 [2] CRAN (R 4.5.0)
    #>  dotCall64          1.2       2024-10-04 [2] CRAN (R 4.5.0)
    #>  dplyr            * 1.1.4     2023-11-17 [2] CRAN (R 4.5.0)
    #>  evaluate           1.0.3     2025-01-10 [2] CRAN (R 4.5.0)
    #>  farver             2.1.2     2024-05-13 [2] CRAN (R 4.5.0)
    #>  fastDummies        1.7.5     2025-01-20 [2] CRAN (R 4.5.0)
    #>  fastmap            1.2.0     2024-05-15 [2] CRAN (R 4.5.0)
    #>  fastmatch          1.1-6     2024-12-23 [2] CRAN (R 4.5.0)
    #>  fgsea              1.35.2    2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
    #>  fitdistrplus       1.2-2     2025-01-07 [2] CRAN (R 4.5.0)
    #>  fs                 1.6.6     2025-04-12 [2] CRAN (R 4.5.0)
    #>  future             1.49.0    2025-05-09 [2] CRAN (R 4.5.0)
    #>  future.apply       1.11.3    2024-10-27 [2] CRAN (R 4.5.0)
    #>  generics           0.1.4     2025-05-09 [2] CRAN (R 4.5.0)
    #>  ggplot2          * 3.5.2     2025-04-09 [2] CRAN (R 4.5.0)
    #>  ggrepel          * 0.9.6     2024-09-07 [2] CRAN (R 4.5.0)
    #>  ggridges           0.5.6     2024-01-23 [2] CRAN (R 4.5.0)
    #>  globals            0.18.0    2025-05-08 [2] CRAN (R 4.5.0)
    #>  glue               1.8.0     2024-09-30 [2] CRAN (R 4.5.0)
    #>  goftest            1.2-3     2021-10-07 [2] CRAN (R 4.5.0)
    #>  gridExtra          2.3       2017-09-09 [2] CRAN (R 4.5.0)
    #>  gtable             0.3.6     2024-10-25 [2] CRAN (R 4.5.0)
    #>  hms                1.1.3     2023-03-21 [2] CRAN (R 4.5.0)
    #>  htmltools          0.5.8.1   2024-04-04 [2] CRAN (R 4.5.0)
    #>  htmlwidgets        1.6.4     2023-12-06 [2] CRAN (R 4.5.0)
    #>  httpuv             1.6.16    2025-04-16 [2] CRAN (R 4.5.0)
    #>  httr               1.4.7     2023-08-15 [2] CRAN (R 4.5.0)
    #>  httr2              1.1.2     2025-03-26 [2] CRAN (R 4.5.0)
    #>  ica                1.0-3     2022-07-08 [2] CRAN (R 4.5.0)
    #>  igraph             2.1.4     2025-01-23 [2] CRAN (R 4.5.0)
    #>  irlba              2.3.5.1   2022-10-03 [2] CRAN (R 4.5.0)
    #>  jquerylib          0.1.4     2021-04-26 [2] CRAN (R 4.5.0)
    #>  jsonlite           2.0.0     2025-03-27 [2] CRAN (R 4.5.0)
    #>  KernSmooth         2.23-26   2025-01-01 [2] CRAN (R 4.5.0)
    #>  knitr              1.50      2025-03-16 [2] CRAN (R 4.5.0)
    #>  labeling           0.4.3     2023-08-29 [2] CRAN (R 4.5.0)
    #>  later              1.4.2     2025-04-08 [2] CRAN (R 4.5.0)
    #>  lattice            0.22-7    2025-04-02 [2] CRAN (R 4.5.0)
    #>  lazyeval           0.2.2     2019-03-15 [2] CRAN (R 4.5.0)
    #>  lifecycle          1.0.4     2023-11-07 [2] CRAN (R 4.5.0)
    #>  listenv            0.9.1     2024-01-29 [2] CRAN (R 4.5.0)
    #>  lmtest             0.9-40    2022-03-21 [2] CRAN (R 4.5.0)
    #>  logger             0.4.0     2024-10-22 [2] CRAN (R 4.5.0)
    #>  lubridate          1.9.4     2024-12-08 [2] CRAN (R 4.5.0)
    #>  magick             2.8.6     2025-03-23 [2] CRAN (R 4.5.0)
    #>  magrittr           2.0.3     2022-03-30 [2] CRAN (R 4.5.0)
    #>  MASS               7.3-65    2025-02-28 [2] CRAN (R 4.5.0)
    #>  Matrix             1.7-3     2025-03-11 [2] CRAN (R 4.5.0)
    #>  matrixStats        1.5.0     2025-01-07 [2] CRAN (R 4.5.0)
    #>  memoise            2.0.1     2021-11-26 [2] CRAN (R 4.5.0)
    #>  mime               0.13      2025-03-17 [2] CRAN (R 4.5.0)
    #>  miniUI             0.1.2     2025-04-17 [2] CRAN (R 4.5.0)
    #>  nlme               3.1-168   2025-03-31 [2] CRAN (R 4.5.0)
    #>  OmnipathR          3.17.0    2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
    #>  parallelly         1.45.0    2025-06-02 [2] CRAN (R 4.5.0)
    #>  patchwork        * 1.3.0     2024-09-16 [2] CRAN (R 4.5.0)
    #>  pbapply            1.7-2     2023-06-27 [2] CRAN (R 4.5.0)
    #>  pheatmap         * 1.0.12    2019-01-04 [2] CRAN (R 4.5.0)
    #>  pillar             1.10.2    2025-04-05 [2] CRAN (R 4.5.0)
    #>  pkgconfig          2.0.3     2019-09-22 [2] CRAN (R 4.5.0)
    #>  plotly             4.10.4    2024-01-13 [2] CRAN (R 4.5.0)
    #>  plyr               1.8.9     2023-10-02 [2] CRAN (R 4.5.0)
    #>  png                0.1-8     2022-11-29 [2] CRAN (R 4.5.0)
    #>  polyclip           1.10-7    2024-07-23 [2] CRAN (R 4.5.0)
    #>  prettyunits        1.2.0     2023-09-24 [2] CRAN (R 4.5.0)
    #>  processx           3.8.6     2025-02-21 [2] CRAN (R 4.5.0)
    #>  progress           1.2.3     2023-12-06 [2] CRAN (R 4.5.0)
    #>  progressr          0.15.1    2024-11-22 [2] CRAN (R 4.5.0)
    #>  promises           1.3.3     2025-05-29 [2] CRAN (R 4.5.0)
    #>  ps                 1.9.1     2025-04-12 [2] CRAN (R 4.5.0)
    #>  purrr              1.0.4     2025-02-05 [2] CRAN (R 4.5.0)
    #>  R.methodsS3        1.8.2     2022-06-13 [2] CRAN (R 4.5.0)
    #>  R.oo               1.27.1    2025-05-02 [2] CRAN (R 4.5.0)
    #>  R.utils            2.13.0    2025-02-24 [2] CRAN (R 4.5.0)
    #>  R6                 2.6.1     2025-02-15 [2] CRAN (R 4.5.0)
    #>  RANN               2.6.2     2024-08-25 [2] CRAN (R 4.5.0)
    #>  rappdirs           0.3.3     2021-01-31 [2] CRAN (R 4.5.0)
    #>  RColorBrewer       1.1-3     2022-04-03 [2] CRAN (R 4.5.0)
    #>  Rcpp               1.0.14    2025-01-12 [2] CRAN (R 4.5.0)
    #>  RcppAnnoy          0.0.22    2024-01-23 [2] CRAN (R 4.5.0)
    #>  RcppHNSW           0.6.0     2024-02-04 [2] CRAN (R 4.5.0)
    #>  readr              2.1.5     2024-01-10 [2] CRAN (R 4.5.0)
    #>  readxl             1.4.5     2025-03-07 [2] CRAN (R 4.5.0)
    #>  RefManageR       * 1.4.0     2022-09-30 [2] CRAN (R 4.5.0)
    #>  reshape2           1.4.4     2020-04-09 [2] CRAN (R 4.5.0)
    #>  reticulate         1.42.0    2025-03-25 [2] CRAN (R 4.5.0)
    #>  rlang              1.1.6     2025-04-11 [2] CRAN (R 4.5.0)
    #>  rmarkdown          2.29      2024-11-04 [2] CRAN (R 4.5.0)
    #>  ROCR               1.0-11    2020-05-02 [2] CRAN (R 4.5.0)
    #>  RSpectra           0.16-2    2024-07-18 [2] CRAN (R 4.5.0)
    #>  RSQLite            2.4.0     2025-05-31 [2] CRAN (R 4.5.0)
    #>  Rtsne              0.17      2023-12-07 [2] CRAN (R 4.5.0)
    #>  rvest              1.0.4     2024-02-12 [2] CRAN (R 4.5.0)
    #>  sass               0.4.10    2025-04-11 [2] CRAN (R 4.5.0)
    #>  scales             1.4.0     2025-04-24 [2] CRAN (R 4.5.0)
    #>  scattermore        1.2       2023-06-12 [2] CRAN (R 4.5.0)
    #>  sctransform        0.4.2     2025-04-30 [2] CRAN (R 4.5.0)
    #>  selectr            0.4-2     2019-11-20 [2] CRAN (R 4.5.0)
    #>  sessioninfo        1.2.3     2025-02-05 [2] CRAN (R 4.5.0)
    #>  Seurat           * 5.3.0     2025-04-23 [2] CRAN (R 4.5.0)
    #>  SeuratObject     * 5.1.0     2025-04-22 [2] CRAN (R 4.5.0)
    #>  shiny              1.10.0    2024-12-14 [2] CRAN (R 4.5.0)
    #>  sp               * 2.2-0     2025-02-01 [2] CRAN (R 4.5.0)
    #>  spam               2.11-1    2025-01-20 [2] CRAN (R 4.5.0)
    #>  spatstat.data      3.1-6     2025-03-17 [2] CRAN (R 4.5.0)
    #>  spatstat.explore   3.4-3     2025-05-21 [2] CRAN (R 4.5.0)
    #>  spatstat.geom      3.4-1     2025-05-20 [2] CRAN (R 4.5.0)
    #>  spatstat.random    3.4-1     2025-05-20 [2] CRAN (R 4.5.0)
    #>  spatstat.sparse    3.1-0     2024-06-21 [2] CRAN (R 4.5.0)
    #>  spatstat.univar    3.1-3     2025-05-08 [2] CRAN (R 4.5.0)
    #>  spatstat.utils     3.1-4     2025-05-15 [2] CRAN (R 4.5.0)
    #>  stringi            1.8.7     2025-03-27 [2] CRAN (R 4.5.0)
    #>  stringr            1.5.1     2023-11-14 [2] CRAN (R 4.5.0)
    #>  survival           3.8-3     2024-12-17 [2] CRAN (R 4.5.0)
    #>  tensor             1.5       2012-05-05 [2] CRAN (R 4.5.0)
    #>  tibble           * 3.2.1     2023-03-20 [2] CRAN (R 4.5.0)
    #>  tidyr            * 1.3.1     2024-01-24 [2] CRAN (R 4.5.0)
    #>  tidyselect         1.2.1     2024-03-11 [2] CRAN (R 4.5.0)
    #>  timechange         0.3.0     2024-01-18 [2] CRAN (R 4.5.0)
    #>  tinytex            0.57      2025-04-15 [2] CRAN (R 4.5.0)
    #>  tzdb               0.5.0     2025-03-15 [2] CRAN (R 4.5.0)
    #>  utf8               1.2.5     2025-05-01 [2] CRAN (R 4.5.0)
    #>  uwot               0.2.3     2025-02-24 [2] CRAN (R 4.5.0)
    #>  vctrs              0.6.5     2023-12-01 [2] CRAN (R 4.5.0)
    #>  viridisLite        0.4.2     2023-05-02 [2] CRAN (R 4.5.0)
    #>  vroom              1.6.5     2023-12-05 [2] CRAN (R 4.5.0)
    #>  websocket          1.4.4     2025-04-10 [2] CRAN (R 4.5.0)
    #>  withr              3.0.2     2024-10-28 [2] CRAN (R 4.5.0)
    #>  xfun               0.52      2025-04-02 [2] CRAN (R 4.5.0)
    #>  XML                3.99-0.18 2025-01-01 [2] CRAN (R 4.5.0)
    #>  xml2               1.3.8     2025-03-14 [2] CRAN (R 4.5.0)
    #>  xtable             1.8-4     2019-04-21 [2] CRAN (R 4.5.0)
    #>  yaml               2.3.10    2024-07-26 [2] CRAN (R 4.5.0)
    #>  zip                2.3.3     2025-05-13 [2] CRAN (R 4.5.0)
    #>  zoo                1.8-14    2025-04-10 [2] CRAN (R 4.5.0)
    #>
    #>  [1] F:/biocbuild/bbs-3.22-bioc/tmpdir/RtmpgfrSEm/Rinstfc802963720c
    #>  [2] F:/biocbuild/bbs-3.22-bioc/R/library
    #>  * ── Packages attached to the search path.
    #>
    #> ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────