Skip to contents
library(CellTFusion)
#> Warning: replacing previous import 'S4Arrays::makeNindexFromArrayViewport' by
#> 'DelayedArray::makeNindexFromArrayViewport' when loading 'HDF5Array'
#> Warning: replacing previous import 'S4Arrays::makeNindexFromArrayViewport' by
#> 'DelayedArray::makeNindexFromArrayViewport' when loading 'SummarizedExperiment'
#> 

CellTFusion cell group scores can be used as features to predict clinical outcomes with the pipeML package:

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

The features of the models are the cell group scores. Cell groups are learned from the data (TF modules, correlations with the deconvolution features, CCA weights), so they must be learned within each cross-validation fold: learning them on all the training samples before cross-validation would let the test samples of each fold influence the features and overestimate performance. prepare_celltfusion_folds() does this for pipeML: in each fold, CellTFusion() is run on the training samples only, and the test samples are scored on the resulting cell groups with compute.test.set(). The latent factors are a downstream characterization and are not used as features (project_factors() projects the cell group scores of new samples onto them when needed).

Input data

Split the example data into a training and a test set. The deconvolution is computed once for all the samples: it is computed independently for each sample, so this does not leak information between samples.

raw.counts <- CellTFusion::raw.counts.tuto
traitdata  <- CellTFusion::traitdata.tuto

deconv <- multideconv::compute.deconvolution(
  raw.counts,
  methods    = c("Quantiseq", "Epidish"),
  normalized = TRUE,
  return     = FALSE
)

index <- caret::createDataPartition(traitdata$Best.Confirmed.Overall.Response, p = 0.8, list = FALSE)

raw.counts_train <- raw.counts[, index]
traitdata_train  <- traitdata[index, ]
deconv_train     <- deconv[index, ]

raw.counts_test  <- raw.counts[, -index]
traitdata_test   <- traitdata[-index, ]
deconv_test      <- deconv[-index, ]

Training

Pass prepare_celltfusion_folds() as fold_construction_fun, and its arguments through fold_construction_args_fixed:

  • deconv — deconvolution of the training samples, in the same order as features_train.
  • raw_counts — count matrix of the training samples, matched to the samples of deconv by name (an error is raised if they differ). pipeML converts gene names with make.names() (e.g. HLA-A becomes HLA.A); passing the counts keeps the original gene symbols.
  • any other CellTFusion() argument, e.g. TF.collection, min_module_size or corr.
ml_res <- pipeML::compute_features.training.ML(
  features_train = t(raw.counts_train),
  task_type      = "classification",
  target_var     = traitdata_train$Best.Confirmed.Overall.Response,
  trait.positive = "PD",
  metric         = "AUROC",
  k_folds        = 5,
  n_rep          = 5,
  ncores         = 2,
  fold_construction_fun        = prepare_celltfusion_folds,
  fold_construction_args_fixed = list(deconv     = deconv_train,
                                      raw_counts = raw.counts_train,
                                      TF.collection = "CollecTRI")
)

The final model is trained on the cell group scores of all the training samples (cell groups learned on all of them). The corresponding CellTFusion() result is returned in ml_res$Custom_output.

Prediction on an independent cohort

Score the test samples on the cell groups of ml_res$Custom_output, then predict:

features_test <- data.frame(compute.test.set(ml_res$Custom_output$Processed_deconvolution, ml_res$Custom_output$Cell_groups,
                                              deconv_test = deconv_test))

pred <- pipeML::compute_prediction(
  model          = ml_res$Model,
  test_data      = features_test,
  target_var     = traitdata_test$Best.Confirmed.Overall.Response,
  trait.positive = "PD",
  task_type      = "classification"
)

pred$AUC$AUROC

Survival outcomes

The same function is used for survival models, with the follow-up time and event of each sample (the tutorial traitdata includes the overall survival: os and censOS):

surv_res <- pipeML::compute_features.training.ML(
  features_train = t(raw.counts_train),
  task_type      = "survival",
  time_var       = traitdata_train$os,
  event_var      = traitdata_train$censOS,
  k_folds        = 5,
  n_rep          = 5,
  ncores         = 2,
  fold_construction_fun        = prepare_celltfusion_folds,
  fold_construction_args_fixed = list(deconv = deconv_train, raw_counts = raw.counts_train)
)

features_test <- data.frame(compute.test.set(surv_res$Custom_output$Processed_deconvolution, surv_res$Custom_output$Cell_groups,
                                              deconv_test = deconv_test))

surv_pred <- pipeML::compute_prediction(
  model     = surv_res$Model,
  test_data = features_test,
  task_type = "survival",
  time_var  = traitdata_test$os,
  event_var = traitdata_test$censOS
)

surv_pred$c_index

Multi-cohort data

For samples from several cohorts, pass batch: the cohort of each training sample, in the same order as features_train. CellTFusion() then corrects for cohort in each fold (see Multi-cohort analysis), and the test samples of each cohort are scored separately, z-scored on their own means and SDs. A cohort with fewer than 10 test samples in a fold gives a warning, as its scores are then based on few samples. With LODO = TRUE, pipeML stratifies the folds by cohort and outcome (batch_var), so that every fold keeps samples of each cohort in its training and test sets:

ml_res <- pipeML::compute_features.training.ML(
  features_train = t(raw.counts_train),
  task_type      = "classification",
  target_var     = coldata_train$Response,
  trait.positive = "R",
  metric         = "AUROC",
  LODO           = TRUE,
  batch_var      = coldata_train$Cohort,
  fold_construction_fun        = prepare_celltfusion_folds,
  fold_construction_args_fixed = list(deconv     = deconv_train,
                                      raw_counts = raw.counts_train,
                                      batch      = coldata_train$Cohort)
)

For a model trained with batch, score each new cohort separately with compute.test.set(), as its samples are z-scored on their own means and SDs; a warning is given with fewer than 10 samples, and a single sample cannot be scored this way (all its scores would be 0).

Note: prepare_celltfusion_folds() runs CellTFusion() in every fold. Use do_parallel = TRUE (and workers) in fold_construction_args_fixed to compute several folds in parallel (the package must be installed).