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
CellTFusion requires R version 4.3.3 or higher.
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 — normalization,
deconvolution, TF activity scoring, TF module construction, pathway
scoring, cell groups, NMF latent factors and cell niches — 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 = NULL, # only used with TF.collection = "ARACNE" (input/ARACNE/<cancer_type>/)
file_name = "TestRun",
min_targets_size = 5,
min_module_size = 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",
min_module_size = 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 and cell niches. 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 obtain the latent
factors of new samples, project their cell group scores with
project_factors(res$Latent_spaces, test_scores) (see the Machine
learning
workflows
article).
test_scores <- compute.test.set(
dt = res$Processed_deconvolution, # deconvolution subgroups of the training set
cell_groups = res$Cell_groups, # trained cell groups
group_names = names(res$Cell_groups$Composition), # cell groups to replicate (all by default)
deconv_test = deconv_test # deconvolution matrix of the test set (before subgrouping)
)To use the cell group scores 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 scored on the resulting
cell groups. 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: cell group scores on the cell groups of the final model
features_test <- compute.test.set(ml_res$Custom_output$Processed_deconvolution, ml_res$Custom_output$Cell_groups,
deconv_test = 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