IntegratedLearner - Integrated machine learning for multi-omics prediction and classification

The repository houses the IntegratedLearner R package for multi-omics prediction and classification. Binary, multiclass, continuous, and survival outcomes are supported through a single high-level interface.

Optional dependency for BART workflows:

Code entry points

Use IntegratedLearner() to fit models and the S3 generics predict(), plot(), print(), and update() to work with fitted models. Existing low-level IL_*, ILsurv, and solver exports are retained for compatibility; package-provided SuperLearner wrappers use sl_* names.

Seven small MAE tutorial fixtures live in inst/extdata and total about 258 KB. Each assay has at most 25 variable features; paired cohorts share feature IDs and order. All samples and outcomes are retained. Read the RDS files directly using readRDS(system.file("extdata", "PRISM_MAE.rds", package = "IntegratedLearner")); see the fixture inventory and selection recipe. The former data() objects, raw tables, and duplicate PCL datasets have been removed. PCL inputs remain supported using user-supplied data.

Installation

IntegratedLearner was accepted into Bioconductor. It is initially available through Bioconductor devel once the nightly build succeeds. In a Bioconductor devel environment, install it with:

if (!requireNamespace("BiocManager", quietly = TRUE)) {
  install.packages("BiocManager")
}
BiocManager::install("IntegratedLearner")

To install directly from GitHub, use:

BiocManager::install("himelmallick/IntegratedLearner")

Features

Quickstart Guide

The package vignette demonstrates binary, multiclass, continuous, and survival workflows using MultiAssayExperiment as the primary interface, with PCL retained for backward compatibility.

Background

IntegratedLearner provides an integrated machine learning framework to 1) consolidate predictions by borrowing information across several longitudinal and cross-sectional omics data layers, 2) decipher the mechanistic role of individual omics features that can potentially lead to new sets of testable hypotheses, and 3) quantify uncertainty of the integration process. Two integration paradigms are supported: early and late.

Within a Bioconductor workflow, the intended pattern is: assemble aligned assays in MultiAssayExperiment, inspect the object with experiments(), assay(), colData(), and sampleMap(), fit IntegratedLearner(), and then pass predictions, layer weights, and feature summaries into downstream interpretation or visualization steps. IntegratedLearner focuses on supervised multi-omics prediction/integration rather than general container management or unsupervised integration.

For binary/continuous outcomes, late fusion proceeds by 1) fitting a machine learning algorithm (base_learner) per layer and 2) combining layer-wise cross-validated predictions using a meta model (meta_learner). A common default is BART as base learner (base_learner = "sl_bart") with sl_nnls_auc as the meta-learner.

For multiclass outcomes (family = binomial() with more than two outcome classes), IntegratedLearner dispatches to a native multiclass backend that performs multiclass probability modeling at layer, stacked, and concatenated levels. Optional filtering and screening are supported via filter_method/filter_pct and run_screening/screen_pct.

Multiclass fits also return two late-fusion methods by default, independently of run_stacked: majority counts each layer's predicted class, and weighted_average combines class probabilities using nonnegative layer weights that sum to one. Weights minimize multiclass log loss on out-of-fold layer predictions; training outputs fit weights separately outside each held-out fold. Set run_majority = FALSE or run_weighted = FALSE to disable either method. Majority ties use the first class in fit$class_levels. Its prob.*$majority matrices contain vote fractions, which are not calibrated probabilities, so their log loss should be interpreted accordingly. Fully nested evaluation or an untouched validation set is needed to assess the complete learned fusion pipeline.

For survival outcomes, IntegratedLearner dispatches to the native survival engine (ILsurv) with configurable late-fusion weighting (COX/IBS). Supported survival learners include Cox, penalized Cox, tree ensembles, boosting, and XGBoost-based survival variants (see full list below).

Naming conventions:

Feature workflow (when enabled):

  1. Filtering happens first (filter_method, filter_pct) on the training feature table.
  2. Screening happens second (run_screening = TRUE, screen_pct) within CV folds and again for final model fit.

Basic Usage

Recommended MAE-first Bioconductor workflow:

library(IntegratedLearner)

PRISM_MAE <- readRDS(system.file(
  "extdata", "PRISM_MAE.rds", package = "IntegratedLearner", mustWork = TRUE
))

mae_train <- PRISM_MAE

names(MultiAssayExperiment::experiments(mae_train))
head(as.data.frame(S4Vectors::DataFrame(MultiAssayExperiment::colData(mae_train)))[, 1:4])
head(MultiAssayExperiment::sampleMap(mae_train))

se <- MultiAssayExperiment::experiments(mae_train)[[1]]
SummarizedExperiment::assayNames(se)

Then fit the model directly from the MAE:

# MAE mode (binary/continuous)
IntegratedLearner(
  MAE_train = mae_train,
  experiment = c("metabolome", "species"),
  assay.type = c("abundance", "abundance"),
  outcome_col = "Y",
  subject_id_col = "subjectID",
  folds = 5,
  base_learner = "sl_bart",
  meta_learner = "sl_nnls_auc",
  filter_method = "prevalence",
  filter_pct = 40,
  run_screening = TRUE,
  screen_pct = 30,
  family = binomial()
)

# MAE mode (multiclass)
IntegratedLearner(
  MAE_train = mae_train,
  experiment = c("metabolome", "species"),
  assay.type = c("abundance", "abundance"),
  outcome_col = "diseaseCat",   # column in colData(MAE_train)
  subject_id_col = "sample_id", # subject/sample ID column in colData(MAE_train)
  folds = 5,
  base_learner = "randomforest",
  meta_learner = "randomforest",
  filter_method = "variance",
  filter_pct = 50,
  run_screening = TRUE,
  screen_pct = 25,
  family = binomial()
)

# MAE mode (survival)
IntegratedLearner(
  MAE_train = mae_train,
  MAE_valid = mae_valid,        # optional
  experiment = c("taxonomy", "pathway"),
  assay.type = c("relative_abundance", "pathway_abundance"),
  outcome_col = "surv_outcome", # survival outcome column in colData(MAE_train)
  subject_id_col = "patient_id",
  folds = 5,
  base_learner = "surv.coxph",
  filter_method = "variance",
  filter_pct = 40,
  run_screening = TRUE,
  screen_pct = 25
)

# MAE mode (survival with custom metadata column names)
IntegratedLearner(
  MAE_train = mae_train,
  MAE_valid = mae_valid,        # optional
  experiment = c("taxonomy", "pathway"),
  assay.type = c("relative_abundance", "pathway_abundance"),
  outcome_col = "time_to_event_obj",
  subject_id_col = "participant_id",
  folds = 5,
  base_learner = "surv.coxph"
)

# Legacy PCL mode remains supported for backward compatibility
IntegratedLearner(
  PCL_train = pcl_train,
  PCL_valid = pcl_valid,        # optional
  outcome_col = "disease_status",
  subject_id_col = "participant_id",
  folds = 5,
  base_learner = "sl_bart",
  meta_learner = "sl_nnls_auc",
  filter_method = "prevalence",
  filter_pct = 40,
  run_screening = TRUE,
  screen_pct = 30,
  family = binomial()
)

Custom metadata names are optional. If omitted, defaults remain outcome_col = "Y" and subject_id_col = "subjectID" (backward compatible).

Arguments

Call set.seed() before fitting to make the run reproducible. To display fit progress, wrap the call in progressr::with_progress(). Print the fitted object with print(fit) to see its summary.

Automatic outcome coercion:

Supported model families:

Supported fusion modules:

The IntegratedLearner workflow

Flow Chart

Value

For continuous/binary fits (IL_conbin path):

For multiclass fits (IL_multiclass path):

The current multiclass importance calculation compares each feature's mean in one class against its mean in all other classes, divided by the feature's standard deviation across training samples. Positive scores indicate higher values in that class; negative scores indicate lower values. These are univariate associations calculated after optional feature filtering, including features that supervised screening may exclude. They are shared across fusion methods and do not attribute predictions to the fitted models. Grouping by omics layer is already available:

head(fit$feature_importance_signed_by_class[, 1, drop = FALSE])
head(fit$feature_importance_signed_by_layer_by_class[[1]])
head(fit$feature_importance_global)

Multiclass results also follow the survival-style organization, with all enabled methods returned together. fit$late_methods lists the available late-fusion methods. By default these are stacked, majority, and weighted_average.

fit$train_out$single                   # Per-layer predictions and metrics
fit$train_out$early                    # Concatenated model
fit$train_out$late$stacked
fit$train_out$late$majority
fit$train_out$late$weighted_average

fit$valid_out$late$weighted_average$valid_prob
fit$valid_out$late$weighted_average$valid_class
fit$valid_out$late$weighted_average$valid_logloss
fit$train_out$late$weighted_average$weights
fit$train_out$late$weighted_average$weights_by_fold

Each method includes a metrics table plus split-specific scalar metrics: train_accuracy, train_balanced_accuracy, train_auc, train_logloss, or their valid_ equivalents. Prediction results provide the same valid_out structure, including probabilities and classes when outcome labels are absent; metrics then remain NULL. Without validation data, fit$valid_out is NULL. Disabled early fusion gives early = NULL; disabled late methods are omitted from late. The existing flat multiclass outputs remain available.

For survival fits (ILsurv path):

Survival probability calibration is fitted only to training outcomes and OOF risks. Its Cox coefficients, baseline survival (or training Kaplan-Meier fallback), and missing-risk replacement remain fixed when predicting validation probabilities. Validation outcomes are used for scoring and censoring-weight estimation, not calibration fitting. IBS fusion is scored directly on its weighted survival curves. All branches use the shared training-derived brier_time_grid for Brier/IBS comparison; AUC keeps its separate event-time grid. Training summaries remain internal estimates, because calibration and fusion weights are fitted using training outcomes.

Citation

If you use IntegratedLearner in your work, please cite the following:

Mallick H et al. (2024). An Integrated Bayesian Framework for Multi-omics Prediction and Classification. Statistics in Medicine 43(5):983–1002.

Issues

We are happy to troubleshoot any issues with the package. Please contact the maintainer via email or open an issue in the GitHub repository.