Skip to contents
library(CellTFusion)
#> Warning: replacing previous import 'S4Arrays::makeNindexFromArrayViewport' by
#> 'DelayedArray::makeNindexFromArrayViewport' when loading 'HDF5Array'
#> Warning: replacing previous import 'S4Arrays::makeNindexFromArrayViewport' by
#> 'DelayedArray::makeNindexFromArrayViewport' when loading 'SummarizedExperiment'
#> 

CellTFusion combines two families of features computed from bulk RNA-seq data: cell type deconvolution and transcription factor (TF) activity, the latter summarized into TF co-activity modules. Pathway activities are computed alongside. This tutorial runs each step on its own, with its key arguments and outputs. All of them are run automatically, in this order, by the CellTFusion() wrapper (see Running the full pipeline).

Load the example data:

raw.counts <- CellTFusion::raw.counts.tuto
traitdata  <- CellTFusion::traitdata.tuto

Normalization

TF and pathway activities are computed from log2-transformed TPM values. Deconvolution methods use TPM without the log transform; this is handled internally by compute.deconvolution(). If your data are already TPM-normalized (and not log-transformed), use normalized = FALSE in CellTFusion(): the TPM values are then used as they are for deconvolution and log2(TPM + 1) is computed internally for the other steps.

counts.norm <- data.frame(ADImpute::NormalizeTPM(raw.counts, log = TRUE))

Cell type deconvolution

Cell type proportions are estimated with compute.deconvolution() from the companion package multideconv, which runs several deconvolution methods (Quantiseq, Epidish, DeconRNASeq, DWLS and CIBERSORTx) with multiple signatures. The result is a matrix of samples x method-signature-cell type features.

Key arguments:

  • raw.counts — count matrix (genes x samples).
  • methods — deconvolution methods to run.
  • normalized — whether to TPM-normalize the counts before deconvolution.
  • credentials.mail / credentials.token — CIBERSORTx credentials, only needed if "CBSX" is in methods.
  • return — if TRUE, saves the matrix in Results/.
deconv <- multideconv::compute.deconvolution(
  raw.counts,
  methods    = c("Quantiseq", "Epidish"),
  normalized = TRUE,
  return     = FALSE
)

TF activity

compute.TFs.activity() infers the activity of each TF in each sample from the expression of its targets, using decoupleR (Badia-i-Mompel et al. 2022) and a TF-target network (regulon). By default the univariate linear model is used (method = "ulm"); "mlm", "wsum" and "consensus" (the consensus of the three) are also available.

Key arguments:

  • counts_norm — log-normalized expression matrix (genes x samples), typically log2(TPM + 1).
  • TF.collection — source of the regulon:
    • "CollecTRI" (default) (Müller-Dott et al. 2023), fetched from OmnipathR, and "Dorothea" (confidence levels A and B, from the dorothea package) are curated regulons. Each collection is cached in its own file in Results/ (TF_target_collection_<collection>.csv) and reused in later runs.
    • "ARACNE" uses a data-driven, cohort-specific network inferred with ARACNe (Margolin et al. 2006), which derives TF-target edges from the mutual information between expression profiles across a cohort and removes indirect interactions. This is useful for a large, homogeneous cohort in which curated interactions may not hold. The network is read from input/ARACNE/<cancer_type>/network/network.txt (relative to the working directory), a tab-separated file with Regulator and Target columns and a mor column with the sign of each interaction (1 activation, -1 repression). The sign should be computed once, as the sign of the Spearman correlation between the TF and its target in the cohort used to build the network. If the file has no mor column, the signs are computed from the samples given to compute.TFs.activity() and a warning is given: they then depend on these samples and can differ between cohorts or between a training and a test set.
  • min_targets_size — minimum number of targets per regulon; TFs with fewer targets are dropped (default 5).
  • universe — optional user-supplied regulon (data frame with source, target and mor columns, all three required; mor is 1 for activation and -1 for repression), used instead of fetching one.
  • scale — if TRUE (default), z-scores TF activities across samples. The scaled scores of a sample depend on the other samples of the call; use scale = FALSE to compare scores computed in separate calls.
tfs <- compute.TFs.activity(
  counts_norm       = counts.norm,
  TF.collection    = "CollecTRI",
  min_targets_size = 5,
  return           = TRUE
)

To use your own regulon:

universe <- decoupleR::get_collectri(organism = "human", split_complexes = FALSE)
tfs <- compute.TFs.activity(counts.norm, universe = universe)

To use a cohort-specific ARACNe network:

tfs_aracne <- compute.TFs.activity(
  counts_norm    = counts.norm,
  TF.collection = "ARACNE",
  cancer_type   = "skcm"   # reads input/ARACNE/skcm/network/network.txt
)

TF co-activity modules

compute.WTCNA() groups TFs with similar activity patterns into modules using Weighted TF Co-activity Network Analysis (WTCNA), an adaptation of WGCNA (Langfelder and Horvath 2008) to TF activities. Each module is summarized by one score per sample, its eigengene.

Key arguments:

  • tfs — TF activity matrix (samples x TFs); with batch (cohort of each sample), the TF activities of all the cohorts (see Multi-cohort analysis).
  • network_type — "signed" (default) or "unsigned". In a signed network, TFs with negatively correlated activities are not connected.
  • clustering_method — linkage of the hierarchical clustering of the TFs on their TOM dissimilarity; "ward.D2" by default (WGCNA uses "average", which joins two groups of TFs according to the average dissimilarity between their TFs).
  • min_module_size — minimum number of TFs per module. TFs that fit no module (grey) are left out, with a message.
  • corr_mod — correlation (of type corr_type) above which module eigengenes are merged, in single- and multi-cohort mode.
  • corr_type — "spearman" (default) or "pearson", in single- and multi-cohort mode.
network <- compute.WTCNA(
  tfs        = tfs,
  network_type      = "signed",
  clustering_method = "average",
  min_module_size            = 15,
  corr_mod          = 0.9,
  return            = TRUE
)

With return = TRUE, diagnostic plots are saved in Results/. First, the scale-free topology fit used to choose the soft-thresholding power:

Scale-free topology model fit versus soft-thresholding power

Then the TF dendrogram with module colors, before and after merging highly correlated modules:

TF dendrogram with module colors before mergingTF dendrogram with module colors after merging

network[[1]] ("TFs module matrix") contains the module scores (samples x modules) used to build cell groups.

Pathway activity

compute.pathway.activity() estimates pathway activities with decoupleR (Badia-i-Mompel et al. 2022) and the PROGENy pathway footprints (Schubert et al. 2018), by default with the univariate linear model (method = "ulm", as in compute.TFs.activity()). If a list of gene sets is given, GSVA scores are computed as well.

Key arguments:

  • counts_norm — log-normalized expression matrix, e.g. log2(TPM + 1) (genes x samples).
  • gene_sets — optional named list of gene sets; if provided, GSVA scores are returned in addition to PROGENy.
  • paths — optional custom PROGENy-style table (source, target, weight); by default the human PROGENy model is used.
  • scale — z-score each pathway across the samples (default). The scaled scores of a sample depend on the other samples of the call; use scale = FALSE to compare scores computed in separate calls.
pathways <- compute.pathway.activity(
  counts_norm = counts.norm,
  return  = TRUE
)

The result is a samples x pathways matrix (14 PROGENy pathways by default). Clustering it gives an overview of which pathways co-vary across the cohort:

Heatmap of PROGENy pathway activities clustered by sample and pathway

Reduction of deconvolution features

Deconvolution features from different methods and signatures are often highly correlated. compute.deconvolution.analysis() from multideconv groups correlated features of the same cell type into subgroups, reducing redundancy before building cell groups.

Key arguments:

  • deconvolution — output of compute.deconvolution().
  • corr — minimum correlation to group features into a subgroup.
  • corr_type — "spearman" (default) or "pearson".
  • batch — optional cohort vector; correlations then control for cohort (see Multi-cohort analysis).
dt <- multideconv::compute.deconvolution.analysis(
  deconvolution = deconv,
  corr          = 0.7,
  return        = FALSE
)

Running the full pipeline

CellTFusion() runs all the steps above, then builds cell groups, latent factors and cell niches:

res <- CellTFusion(
  raw_counts     = raw.counts,
  normalized     = TRUE,
  deconv_methods = c("Quantiseq", "Epidish"),
  TF.collection  = "CollecTRI",
  corr           = 0.7,
  corr_mod       = 0.9,
  pval           = 0.05,
  file_name      = "Tutorial",
  return         = TRUE
)

A few defaults worth knowing:

  • deconv_methods runs Quantiseq, CIBERSORTx ("CBSX"), Epidish, DeconRNASeq and DWLS by default. CIBERSORTx is only run when cbsx_mail and cbsx_token are given; without them it is skipped with a message.
  • cancer_type is only used with TF.collection = "ARACNE", to locate the ARACNe network.
  • Precomputed deconv, dt, tfs and pathways can be passed to skip the corresponding steps (see Cell groups and latent factors).

res contains every intermediate object: $Deconvolution, $TFs_matrix, $TF_network, $Pathways_scores, $Processed_deconvolution, $Cell_groups, $Latent_spaces and $Cells_niches.

Next: Cell groups and latent factors.

References

Badia-i-Mompel, Pau, Jesús Vélez Santiago, Jana Braunger, et al. 2022. “decoupleR: Ensemble of Computational Methods to Infer Biological Activities from Omics Data.” Bioinformatics Advances 2 (1): vbac016. https://doi.org/10.1093/bioadv/vbac016.
Langfelder, Peter, and Steve Horvath. 2008. “WGCNA: An r Package for Weighted Correlation Network Analysis.” BMC Bioinformatics 9 (1): 559. https://doi.org/10.1186/1471-2105-9-559.
Margolin, Adam A., Ilya Nemenman, Katia Basso, et al. 2006. “ARACNE: An Algorithm for the Reconstruction of Gene Regulatory Networks in a Mammalian Cellular Context.” BMC Bioinformatics 7 (Suppl 1): S7. https://doi.org/10.1186/1471-2105-7-S1-S7.
Müller-Dott, Sophia, Eirini Tsirvouli, Miguel Vazquez, et al. 2023. “Expanding the Coverage of Regulons from High-Confidence Prior Knowledge for Accurate Estimation of Transcription Factor Activities.” Nucleic Acids Research 51 (20): 10934–49. https://doi.org/10.1093/nar/gkad841.
Schubert, Michael, Bertram Klinger, Martina Klünemann, et al. 2018. “Perturbation-Response Genes Reveal Signaling Footprints in Cancer Gene Expression.” Nature Communications 9 (1): 20. https://doi.org/10.1038/s41467-017-02391-6.