Integration of immune-cell type deconvolution features and prior-knowledge networks of TFs-gene interactions to characterize potential cell states of the tumor microenvironment using bulk RNAseq data
Figure 1. A schematic overview of the `CellTFusion` pipeline
To avoid GitHub API rate limit issues during installation, we recommend setting up GitHub authentication by creating and storing a Personal Access Token (PAT). You can do this with the following steps:
# install.packages(c("usethis", "gitcreds"))
usethis::create_github_token() #Create a Personal Access Token (if you don't have)
gitcreds::gitcreds_set() #Add the tokenYou can install the development version of CellTFusion from
GitHub with:
# install.packages("pak")
pak::pkg_install("VeraPancaldiLab/CellTFusion")You can run the CellTFusion Shiny interface in two ways.
From an installed package:
library(CellTFusion)
shiny::runApp(system.file("shiny", package = "CellTFusion"))From this source repository:
shiny::runApp("inst/shiny")In the app, click Load tutorial data for a quick demo, then click Run CellTFusion. Results and downloadable files are written to your working directory.
These are basic examples which shows you how to use CellTFusion for
different tasks. For a detailed tutorial, see Get
started
Before running CellTFusion, make sure to set your working directory.
The Results/ folder, where outputs will be saved, will be created in
this directory.
setwd('~/path/to/directory')
library(CellTFusion)If you want to run the full pipeline in one step — including
normalization, deconvolution, TF activity scoring, module construction,
and pathway scoring — use the CellTFusion() wrapper function.
res <- CellTFusion(
raw.counts = raw.counts,
normalized = TRUE,
deconv_methods = c("Quantiseq", "DeconRNASeq"), # Choose from Quantiseq, Epidish, DeconRNASeq, DWLS, CBSX
cbsx.mail = "your_email", # Needed to run CBSX (CIBERSORTx)
cbsx.token = "your_token", # Needed to run CBSX (CIBERSORTx)
TF.collection = "CollecTRI", # "CollecTRI", "Dorothea", or "ARACNE"
cancer_type = "skcm", # TCGA cancer type, used for meta-program mapping
file_name = "TestRun",
min_targets_size = 5,
minMod = 5,
corr_mod = 0.9, # modules whose scores correlate above 0.9 are merged
corr = 0.7,
pval = 0.05,
return = TRUE
)If cell subgroups (dt), TF activity (tfs), and/or pathway activity
(pathways) have already been computed — e.g. from a previous
CellTFusion() run — you can pass them back in to skip recomputing
those steps. Once all three are supplied, the pipeline proceeds to the
TF modules and cell group construction:
res2 <- CellTFusion(
raw.counts = raw.counts,
normalized = TRUE,
dt = res$Processed_deconvolution,
tfs = res$TFs_matrix,
pathways = res$Pathways_scores,
file_name = "TestRun_rerun",
minMod = 5,
corr_mod = 0.9,
pval = 0.05,
return = TRUE
)NOTE: CIBERSORTx ("CBSX") is one of the default deconvolution
methods, but it is not an open-source program. It is only run when you
provide your email and token with the cbsx.mail and cbsx.token
parameters (request a token at
CIBERSORTx); without
them it is skipped with a message.
CellTFusion() returns a named list with the outputs of each pipeline
stage — cell-type deconvolution, TF activity, TF module network, pathway
scores, cell groups, latent factors, cell niches, and TME state mapping.
Cell groups are derived internally via construct_cell_groups() and are
available at res$Cell_groups:
res$Cell_groups$Cell_groups # data frame of cell group scores (samples x groups)
res$Cell_groups$Composition # deconvolution features of each group
res$Cell_groups$Weights # CCA projection parameters per group (used to score new samples)For a step-by-step walkthrough of every pipeline stage, see the Get started vignette and the articles section.
Use this function to apply the trained cell groups to an external test
set and calculate group-specific composite scores. To directly obtain
the latent factors of new samples, use
project_test_factors(res, deconv_test) (see the Machine learning
workflows
article).
test_scores <- compute.test.set(
deconv_res = res$Processed_deconvolution, # deconvolution subgroups of the training set
cell_groups = res$Cell_groups, # trained cell groups
features = names(res$Cell_groups$Composition), # cell groups to replicate
deconvolution_test = deconv_test # deconvolution matrix of the test set (before subgrouping)
)To use the latent factors as features in
pipeML without information
leakage, pass prepare_celltfusion_folds() as the fold construction
function: CellTFusion() is then run on the training samples of each
cross-validation fold, and the test samples are projected onto the
resulting latent factors. It works for classification and survival
tasks.
ml_res <- pipeML::compute_features.training.ML(
features_train = t(raw.counts),
task_type = "classification",
target_var = traitdata$Response,
trait.positive = "R",
metric = "AUROC",
fold_construction_fun = prepare_celltfusion_folds,
fold_construction_args_fixed = list(deconv = deconv, raw.counts = raw.counts)
)
# Features of new samples, projected onto the final model
features_test <- project_test_factors(ml_res$Custom_output, deconv_test)See the Machine learning workflows article for details.
If you encounter any problems or have questions about the package, we encourage you to open an issue here. We’ll do our best to assist you!
CellTFusion was developed by Marcelo
Hurtado in supervision of Vera
Pancaldi and is part of the
Pancaldi team. Currently, Marcelo
is the primary maintainer of this package.
If you use CellTFusion in a scientific publication, please cite:
Hurtado, M., & Pancaldi, V. (2026). CellTFusion: A transcriptional regulatory network framework for the identification of functional multicellular states from bulk RNA-seq data. bioRxiv. https://doi.org/10.64898/2026.06.30.735682