CellTFusion • CellTFusion

CellTFusion integrates immune cell type deconvolution with transcription factor (TF)–gene regulatory networks to characterize immune cell states in the tumor microenvironment (TME) from bulk RNA-seq data.

Starting from a count matrix, CellTFusion builds cell groups — sets of deconvolution features whose abundance follows the activity of a TF co-activity module — and summarizes them into latent factors, a compact representation of the TME that can be annotated as TME states, tested against clinical variables and used as features for machine learning.

Installation

To avoid GitHub API rate limit issues, set up a Personal Access Token (PAT) before installing:

# install.packages(c("usethis", "gitcreds"))
usethis::create_github_token()
gitcreds::gitcreds_set()

Install CellTFusion from GitHub:

# install.packages("pak")
pak::pkg_install("VeraPancaldiLab/CellTFusion")

Quick start

The CellTFusion() wrapper runs the whole pipeline in one call, using the example data shipped with the package. Intermediate results and plots are saved in a Results/ folder in the working directory.

library(CellTFusion)

res <- CellTFusion(
  raw.counts     = CellTFusion::raw.counts.tuto,
  normalized     = TRUE,
  deconv_methods = c("Quantiseq", "Epidish"),
  cancer_type    = "skcm",
  file_name      = "Tutorial"
)

head(res$Latent_spaces$Z)  # latent factor scores (samples x factors)
res$TME_states             # mapping of each latent factor to a TCGA meta-program

Pipeline

Step	Function	Tutorial
Cell type deconvolution	`multideconv::compute.deconvolution()`	Feature computation
TF activity inference	`compute.TFs.activity()`	Feature computation
TF co-activity modules	`compute.WTCNA()`	Feature computation
Pathway activity	`compute.pathway.activity()`	Feature computation
Cell groups	`construct_cell_groups()`	Cell groups and latent factors
Latent factors	`compute.latent_factors()`	Cell groups and latent factors
Cell niches	`compute_cells_niches()`	Cell groups and latent factors
Hallmark GSEA per factor	`compute_factor_gsea()`	TME state characterization
Meta-program mapping	`map_factors_to_metaprograms()`	TME state characterization
TME subtype annotation	`map_factors_to_TME()`	TME state characterization
Clinical associations	`scores.stat.analysis()`	Statistical analysis
Survival analysis	`compute.survival.analysis()`	Statistical analysis
Cross-validation with `pipeML`	`prepare_celltfusion_folds()`	Machine learning workflows
Projection of new cohorts	`project_test_factors()`	Machine learning workflows
Multi-cohort analysis	`CellTFusion(batch = TRUE)`	Multi-cohort analysis

Tutorials

Step-by-step tutorials are available in the Articles section of the navigation bar:

Feature computation — cell type deconvolution, TF activity, TF co-activity modules and pathway activity
Cell groups and latent factors — build cell groups, extract latent factors and characterize cell niches
TME state characterization — Hallmark GSEA, TCGA meta-programs and TME subtypes
Statistical analysis — associations with clinical variables and survival
Machine learning workflows — use latent factors as features and project independent cohorts
Multi-cohort analysis — correct for cohort effects with batch = TRUE

Shiny app

CellTFusion includes an interactive app to run the pipeline on the example data or on your own data:

shiny::runApp(system.file("shiny", package = "CellTFusion"))

Citation

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