
Compute one-step CellTFusion
CellTFusion.RdRuns the full CellTFusion pipeline in a single call: cell-type deconvolution, TF activity inference, TF module construction, pathway activity, cell group construction, NMF latent factors and cell niches.
Usage
CellTFusion(
raw_counts,
deconv = NULL,
dt = NULL,
tfs = NULL,
pathways = NULL,
normalized = TRUE,
batch = NULL,
deconv_methods = c("Quantiseq", "CBSX", "Epidish", "DeconRNASeq", "DWLS"),
cbsx_mail = NULL,
cbsx_token = NULL,
do_parallel = FALSE,
workers = NULL,
file_name = NULL,
TF.collection = "CollecTRI",
method = "ulm",
min_targets_size = 5,
universe = NULL,
paths = NULL,
gene_sets = NULL,
min_module_size = 5,
corr_mod = 0.9,
soft_power = NULL,
consensus_quantile = 0,
clustering_method = "ward.D2",
corr = 0.7,
corr_type = "spearman",
cells_extra = NULL,
pval = 0.05,
padj = FALSE,
min_cluster_size = 3,
compute_factors = TRUE,
top_n = 5,
cancer_type = NULL,
return = TRUE,
verbose = TRUE,
seed = 123
)Arguments
- raw_counts
A matrix of raw gene expression counts (genes as rows, samples as columns). If
normalized = FALSE, a matrix of TPM-normalized values instead (not log-transformed). Always required, also whendt,tfsandpathwaysare all supplied precomputed (its samples are checked against them).- deconv
(Optional) A data frame with deconvolution features (cell-type proportions as columns x samples as rows). If
NULL(default), it is computed withmultideconv::compute.deconvolution()usingdeconv_methods. Ignored ifdtis supplied.- dt
(Optional) A precomputed cell-subgroup object, typically the output of
multideconv::compute.deconvolution.analysis()(or theProcessed_deconvolutionelement returned by a previousCellTFusion()run). If supplied, cell-type deconvolution and the deconvolution analysis step are both skipped and the pipeline proceeds straight to cell group construction using this object. It must have the same samples asraw_counts.- tfs
(Optional) A precomputed TF activity matrix (samples as rows, TFs as columns), typically the
TFs_matrixelement returned by a previousCellTFusion()run or bycompute.TFs.activity(). Whenbatchis given, a named list of such matrices (one per cohort). If supplied, TF activity inference is skipped.- pathways
(Optional) A precomputed pathway activity matrix, typically the
Pathways_scoreselement returned by a previousCellTFusion()run or bycompute.pathway.activity(). If supplied, pathway activity inference is skipped.- normalized
Logical; if TRUE (default),
raw_countsare raw counts and are normalized to log2(TPM + 1) for the TF activity and pathway activity steps (for deconvolution they are normalized to TPM only). If FALSE,raw_countsmust already be TPM-normalized and not log-transformed: the TPM values are used as they are for deconvolution and log2(TPM + 1) is computed internally for the other steps. Do not pass log-transformed values, as they would be log-transformed a second time (a warning is given when the values do not look like TPM, i.e. no value above 20 or negative values).- batch
(Optional) A vector with the cohort of each sample (e.g.
coldata$Cohort), in the same order as the columns ofraw_counts; if it is named, it is matched to the samples by name instead. It is always treated as categorical. If given, the multi-cohort mode is run: TF and pathway activities are computed per cohort, TF modules are built from a consensus network across cohorts (seeconsensus_quantile), and the cohort is controlled for in the deconvolution analysis and cell group construction. Default isNULL(single cohort); a vector with only one cohort is treated the same way.- deconv_methods
A character vector of deconvolution methods to apply. Default is
c("Quantiseq", "CBSX", "Epidish", "DeconRNASeq", "DWLS")."CBSX"(CIBERSORTx) is only run whencbsx_mailandcbsx_tokenare given; otherwise it is skipped with a message.- cbsx_mail
(Optional) Email credential for CIBERSORTx. Needed to run "CBSX"; without it, CIBERSORTx is skipped.
- cbsx_token
(Optional) Token credential for CIBERSORTx. Needed to run "CBSX"; without it, CIBERSORTx is skipped.
- do_parallel
Logical; whether to run the deconvolution methods that support it (CIBERSORTx and DWLS) in parallel, one signature per worker (passed to
multideconv::compute.deconvolution()asdoParallel). Default is FALSE.- workers
(Optional) Number of parallel workers when
do_parallel = TRUE. IfNULL(default), the number of available cores minus one is used.- file_name
(Optional) Name used in the output files saved in the "Results/" directory. If
NULLandreturn = TRUE,"CellTFusion"is used.- TF.collection
Character. The source of the TF-target network. Options are
"CollecTRI"(default),"Dorothea", or"ARACNE"."CollecTRI"uses the prebuilt collection from OmnipathR and"Dorothea"the one from thedorotheapackage."ARACNE"reads a network file (tab-separated withRegulatorandTargetcolumns, and amorcolumn with the sign of each interaction; seecompute.TFs.activity()) frominput/ARACNE/<cancer_type>/network/network.txt.
- method
Character. The
decoupleRstatistic used to score the TFs and the PROGENy pathways:"ulm"(univariate linear model, default),"mlm"(multivariate linear model),"wsum"(weighted sum) or"consensus"(consensus of the three). Passed tocompute.TFs.activity()andcompute.pathway.activity().- min_targets_size
Integer. Minimum number of target genes per regulon, passed to
compute.TFs.activity(). Default is 5.- universe
Optional. A user-specified data frame of TF-target interactions (columns
source,targetandmor, the mode of regulation: 1 activation, -1 repression). If not provided, the function will fetch the relevant network based on theTF.collectionargument.- paths
Optional. A user-specified data frame of pathways gene sets. If not provided, the function will fetch the relevant pathways based on
PROGENy.- gene_sets
Optional. A named list of custom gene sets (character vectors of gene symbols) passed to
compute.pathway.activity()'sgene_setsargument for GSVA-based scoring. IfNULL, only PROGENy is used.- min_module_size
Integer; minimum module size for WGCNA module detection. Default is 5.
- corr_mod
Numeric; correlation threshold for merging TF modules. Default is 0.9.
- soft_power
(Optional) Soft-thresholding power used to build the TF network, passed to
compute.WTCNA(): one value, or one value per cohort (in the order the cohorts first appear inbatch) in multi-cohort mode. IfNULL(default), it is chosen automatically.- consensus_quantile
Numeric between 0 and 1, used in multi-cohort mode only: quantile of the topological overlaps of each pair of TFs across cohorts used as their consensus (0, the default, is the minimum: two TFs are close only if they are close in every cohort; higher values are less strict). Passed to
compute.WTCNA().- clustering_method
Linkage method of the hierarchical clusterings (
stats::hclust()): of the TFs, to build the TF modules (compute.WTCNA()), and of the deconvolution features of each TF module, to build the cell groups (construct_cell_groups()). Default is"ward.D2".- corr
Numeric; correlation threshold used in the deconvolution analysis. Default is 0.7.
- corr_type
Correlation type used in every step that computes correlations:
"spearman"(default) or"pearson". Passed tomultideconv::compute.deconvolution.analysis()(deconvolution subgroups),compute.WTCNA()(TF network and module merging) andconstruct_cell_groups()(correlation between TF modules and deconvolution features).- cells_extra
(Optional) A character vector with the cell names to consider that are not included in the nomenclature of multideconv (see R package). This includes the group names created with
multideconv::aggregate_cell_groups()ondeconv(e.g."Lymphocytes"): if they are not listed here they are discarded.- pval
Numeric; p-value threshold used when building cell groups (selection of the deconvolution features significantly correlated with each TF module). Default is 0.05.
- padj
Logical; if TRUE, the p-values used when building cell groups are corrected for multiple testing (Benjamini-Hochberg, across the deconvolution features for each TF module) and compared with
pval. Passed toconstruct_cell_groups(). Default is FALSE.- min_cluster_size
Integer; minimum number of features of a cell group (minimum cluster size of the dynamic tree cut), passed to
construct_cell_groups(). Default is 3.- compute_factors
Logical. If TRUE (default), the NMF latent factors (
compute.latent_factors()) and the cell niches (compute_cells_niches()) are computed from the cell group scores. If FALSE, they are skipped (Latent_spacesandCells_nichesareNULL), e.g. in the cross-validation folds ofprepare_celltfusion_folds(), where only the cell group scores are used.- top_n
Integer. Number of top-contributing cell groups per NMF factor in the cell niches (see
compute_cells_niches()). Default is 5.- cancer_type
Character. Cancer type abbreviation (e.g.
"skcm"), only used whenTF.collection = "ARACNE", to locate the ARACNe network atinput/ARACNE/<cancer_type>/network/network.txt. IfNULL, the network is auto-detected when only one exists underinput/ARACNE/.- return
Logical; if TRUE, intermediate matrices and plots are written to the "Results/" folder. Default is TRUE.
- verbose
Logical; whether to print the progress and the console output and messages of every step (warnings are always shown). Default is TRUE.
- seed
Integer. Random seed of the pipeline (deconvolution methods with random steps and NMF), so that results are reproducible. Default is 123.
Value
A list containing:
- Deconvolution
A matrix with cell-type proportions (samples as rows, cell types as columns);
NULLifdtwas supplied withoutdeconv.- TFs_matrix
A matrix with TF activity scores (samples as rows, TFs as columns), or a list of matrices (one per cohort) when
batchis given. Single cohort: raw scores (not scaled), which do not depend on the other samples (e.g. for machine learning features, to be scaled with the training samples). Withbatch: scores z-scored within each cohort (correction of cohort shifts).- TF_network
The TF module network returned by
compute.WTCNA(). Its module matrix is always in the sample order ofraw_counts(also in multi-cohort mode).- Pathways_scores
Pathway activity scores returned by
compute.pathway.activity(): raw in single-cohort mode, z-scored within each cohort withbatch(asTFs_matrix).- Processed_deconvolution
The processed deconvolution subgroups (output of
multideconv::compute.deconvolution.analysis()).- Cell_groups
Output of
construct_cell_groups(): cell group scores, compositions and projection weights.- Latent_spaces
NMF latent factors returned by
compute.latent_factors()(NULLwithcompute_factors = FALSE).- Cells_niches
Top cell groups of each latent factor, with their deconvolution features and CCA coefficients (see
compute_cells_niches();NULLwithcompute_factors = FALSE).
Details
The pipeline runs with a fixed random seed (seed) so results are reproducible; the caller's random
number generator state is restored when the function returns. With normalized = TRUE, sample
names are converted with make.names() (e.g. "TCGA-XX-1234" becomes "TCGA.XX.1234"),
as multideconv::compute.deconvolution() also does; deconv rows are matched to the samples
in either form.
Examples
if (FALSE) { # \dontrun{
data("raw.counts.tuto")
res <- CellTFusion(
raw_counts = raw.counts.tuto,
normalized = TRUE,
deconv_methods = c("Quantiseq", "DeconRNASeq"),
file_name = "TestRun",
min_targets_size = 15,
min_module_size = 20,
corr_mod = 0.25,
corr = 0.7,
pval = 0.05
)
# Re-run with previously computed features, skipping straight to cell group construction
res2 <- CellTFusion(
raw_counts = raw.counts.tuto,
dt = res$Processed_deconvolution,
tfs = res$TFs_matrix,
pathways = res$Pathways_scores,
normalized = TRUE,
file_name = "TestRun_rerun",
min_module_size = 20,
corr_mod = 0.25,
pval = 0.05
)
} # }