
Prepare CellTFusion cross-validation folds for pipeML
prepare_celltfusion_folds.RdFold construction function for pipeML::compute_features.training.ML() (argument
fold_construction_fun) that computes CellTFusion cell group scores within each
cross-validation fold, without information leakage: cell groups are learned with CellTFusion() on the
training samples of each fold only, and the test samples of the fold are scored on them with
compute.test.set(). The features of the models are the cell group scores; the latent factors are a
downstream characterization: they are not computed in the folds, and are computed in final mode (unless
compute_factors = FALSE is passed) for the characterization of the final model; new samples can be projected
onto them with project_factors(). It works for classification and survival tasks.
Usage
prepare_celltfusion_folds(
data,
folds = NULL,
bestune = NULL,
deconv,
raw_counts = NULL,
batch = NULL,
do_parallel = FALSE,
workers = NULL,
return = TRUE,
verbose = TRUE,
...
)Arguments
- data
Data frame provided by
pipeML: samples as rows and genes as columns (thefeatures_traingiven tocompute_features.training.ML(), i.e. the transposed count matrix), plus the outcome columns (targetfor classification,timeandeventfor survival).- folds
Named list with the training rows of each fold, provided by
pipeML.- bestune
Provided by
pipeMLwhen building the features of the final model;NULLwhile running the folds.- deconv
Deconvolution matrix of all the samples (samples x features, e.g. from
multideconv::compute.deconvolution()), with rows in the same order asdata. Deconvolution is computed independently for each sample, so computing it once for all samples does not leak information between folds.- raw_counts
Optional count matrix (genes x samples; TPM values if
normalized = FALSEis passed toCellTFusion()) with the samples ofdata. Its columns are matched to the samples ofdeconvby name (an error is raised if they are not the same samples); without column names, they must be in the same order asdata.pipeMLconverts the column names offeatures_trainwithmake.names()(e.g."HLA-A"becomes"HLA.A"), so gene symbols indatamay no longer match TF regulons and gene sets; passingraw_countskeeps the original gene symbols. IfNULL(default),t(data)is used.- batch
Optional vector with the cohort of each sample, in the same order as
data(e.g.coldata$Cohort). If given,CellTFusion()runs in multi-cohort mode (seeCellTFusion()) and the test samples of each cohort are scored separately, z-scored on their own means and SDs. DefaultNULL(single cohort).- do_parallel
Logical; whether to compute the folds in parallel. Default is FALSE (one after the other).
- workers
(Optional) Number of parallel workers when
do_parallel = TRUE. IfNULL(default), the number of available cores minus one is used.- return
Logical; in final mode, whether
CellTFusion()saves its outputs and plots inResults/. Outputs are never saved for the folds. Default TRUE.- verbose
Logical; whether
CellTFusion()prints its progress messages. Default TRUE.- ...
Other arguments passed to
CellTFusion()(e.g.normalized,TF.collection,min_targets_size,min_module_size,corr_mod,corr,pval,cancer_type).dt,tfsandpathwaysare not allowed, as they must be computed within each fold.
Value
In fold mode (
bestune = NULL): each fold is saved toResults/fold_<fold name>.rds, whichpipeMLreads back, as a list withtrain_data(cell group scores of the training samples plus the outcome columns),test_data(cell group scores of the test samples, plustimeandeventfor survival),obs_test(observed outcome of the test samples),rowIndex(rows of the test samples) andfold_name. The list of folds is returned invisibly. IfCellTFusion()fails in a fold (e.g. no cell groups are found on its training samples, or a cell group cannot be scored in the test samples), that fold is skipped with a warning and is not saved; an error is raised only if all the folds fail.In final mode (
bestuneprovided): a list with (1) the cell group scores of all the samples plus the outcome columns, (2) theCellTFusion()result on all the samples, available asCustom_outputin thepipeMLresult and used to compute the features of new samples withcompute.test.set(), and (3)bestune.
Details
Pass the fixed arguments (deconv, and optionally raw_counts, batch
and any CellTFusion() argument) through fold_construction_args_fixed. Tunable
arguments (fold_construction_args_tunable) are not supported. With batch, a warning names the folds and cohorts
with fewer than 10 test samples (their test samples are z-scored on their own means and SDs, which is unreliable with
few samples; folds that hold out whole cohorts avoid it, whereas pipeML's LODO = TRUE stratifies the
folds by cohort, so every fold tests part of each cohort). With do_parallel = TRUE, the first fold is
computed before the others start in parallel, so that the TF and pathway collections cached in
Results/ are downloaded only once; the package must be installed for the parallel workers.
Examples
if (FALSE) { # \dontrun{
raw_counts <- CellTFusion::raw.counts.tuto
traitdata <- CellTFusion::traitdata.tuto
deconv <- CellTFusion::deconv.tuto # deconvolution of all the samples
# Classification
ml_res <- pipeML::compute_features.training.ML(
features_train = t(raw_counts),
task_type = "classification",
target_var = traitdata$Best.Confirmed.Overall.Response,
trait.positive = "PD",
metric = "AUROC",
k_folds = 5,
n_rep = 1,
fold_construction_fun = prepare_celltfusion_folds,
fold_construction_args_fixed = list(deconv = deconv, raw_counts = raw_counts)
)
# Features of new samples: scored on the cell groups learned on all the training samples
final <- ml_res$Custom_output
features_test <- compute.test.set(final$Processed_deconvolution, final$Cell_groups,
deconv_test = deconv_test)
# Survival (time and event of each sample)
surv_res <- pipeML::compute_features.training.ML(
features_train = t(raw_counts),
task_type = "survival",
time_var = traitdata$os,
event_var = traitdata$censOS,
k_folds = 5,
n_rep = 1,
fold_construction_fun = prepare_celltfusion_folds,
fold_construction_args_fixed = list(deconv = deconv, raw_counts = raw_counts)
)
} # }