
Feature computation
a1_feature_computation.Rmd
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.tutoNormalization
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 inmethods. -
return— ifTRUE, saves the matrix inResults/.
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 thedorotheapackage) are curated regulons. Each collection is cached in its own file inResults/(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 frominput/ARACNE/<cancer_type>/network/network.txt(relative to the working directory), a tab-separated file withRegulatorandTargetcolumns and amorcolumn 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 nomorcolumn, the signs are computed from the samples given tocompute.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 withsource,targetandmorcolumns, all three required;moris 1 for activation and -1 for repression), used instead of fetching one. -
scale— ifTRUE(default), z-scores TF activities across samples. The scaled scores of a sample depend on the other samples of the call; usescale = FALSEto 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); withbatch(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 typecorr_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:

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


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; usescale = FALSEto 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:

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 ofcompute.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_methodsruns Quantiseq, CIBERSORTx ("CBSX"), Epidish, DeconRNASeq and DWLS by default. CIBERSORTx is only run whencbsx_mailandcbsx_tokenare given; without them it is skipped with a message. -
cancer_typeis only used withTF.collection = "ARACNE", to locate the ARACNe network. - Precomputed
deconv,dt,tfsandpathwayscan 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.