| Title: | Bootstrap Prediction Uncertainty and Its Biological Drivers in Gene-Expression Models |
|---|---|
| Description: | Fits bootstrap ensembles of penalized regression models on bulk gene-expression data, derives per-sample uncertainty scores from out-of-bag predictions, and tests whether technical covariates explain that uncertainty. The bootstrap method is described by Efron and Tibshirani (1993, ISBN:9780412042317), and elastic-net regression follows Friedman, Hastie, and Tibshirani (2010) <doi:10.18637/jss.v033.i01>. The optional immunedeconv package, used for immune-cell deconvolution, is available from GitHub <https://github.com/omnideconv/immunedeconv>. |
| Authors: | Tanay Belapurkar [aut, cre] |
| Maintainer: | Tanay Belapurkar <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.3 |
| Built: | 2026-11-03 18:41:58 UTC |
| Source: | https://github.com/cran/uncertR |
Resamples samples with replacement B times, fits an elastic-net model on
each bootstrap sample, and predicts only the samples that were not drawn
(out-of-bag, OOB). Every sample therefore accumulates a distribution of
honest (non-in-sample) predictions.
boot_uncertainty( expr, y, B = 200, alpha = 0.5, lambda_mode = c("global", "per_boot"), nfolds = 5, seed = NULL )boot_uncertainty( expr, y, B = 200, alpha = 0.5, lambda_mode = c("global", "per_boot"), nfolds = 5, seed = NULL )
expr |
Genes x samples matrix (bulk expression, e.g. log2 TPM), or a
|
y |
Numeric outcome vector (e.g. log IC50 or AUC), one per sample. |
B |
Number of bootstrap replicates. |
alpha |
glmnet mixing parameter (1 = lasso, 0 = ridge). |
lambda_mode |
|
nfolds |
Folds for cross-validation. |
seed |
Optional integer for reproducibility. |
An object of class boot_unc.
Cell-type fractions sum to a constant, so use CLR before regression.
clr_transform(fractions, pseudo = 0.001)clr_transform(fractions, pseudo = 0.001)
fractions |
Samples x cell types matrix of non-negative fractions. |
pseudo |
Pseudocount replacing zeros. |
A numeric matrix with the same dimensions as fractions,
containing centered log-ratio-transformed values. Each row is
centered by subtracting the mean of its log-transformed components.
Tissue/lineage labels often have many tiny groups that make the driver
model unstable. Levels with fewer than min_n samples become "Other".
collapse_rare_levels(x, min_n = 15)collapse_rare_levels(x, min_n = 15)
x |
Character or factor vector. |
min_n |
Minimum group size. |
A factor in which levels represented by fewer than min_n
observations are replaced with "Other". Levels meeting the threshold
are retained.
Combines technical covariates computed from expr, optional deconvolution
scores (patient tumors only; not meaningful for cell lines), and any
user-supplied covariates (e.g. tissue lineage, growth rate, mutation status).
tumor_covariates(expr, methods = NULL, extra = NULL, technical = TRUE)tumor_covariates(expr, methods = NULL, extra = NULL, technical = TRUE)
expr |
Genes x samples matrix (HGNC symbols, TPM-like scale for deconvolution). |
methods |
Character vector of |
extra |
Optional data frame of extra covariates; rownames = samples. |
technical |
If |
Data frame, one row per sample.
Fits a joint linear model of (log) uncertainty on covariates and reports the partial R^2 of each covariate with a permutation p-value and BH FDR. Optionally removes the dependence of uncertainty on the predicted value first, since uncertainty is often mechanically tied to how extreme a prediction is.
uncertainty_drivers( unc, covariates, adjust_for = c("prediction", "none"), log_transform = TRUE, n_perm = 500, seed = NULL )uncertainty_drivers( unc, covariates, adjust_for = c("prediction", "none"), log_transform = TRUE, n_perm = 500, seed = NULL )
unc |
An |
covariates |
Data frame of covariates, rownames = sample IDs. |
adjust_for |
|
log_transform |
Model log(uncertainty) (recommended; positive, skewed). |
n_perm |
Number of permutations. |
seed |
Optional seed. |
An object of class unc_drivers.
Per-sample uncertainty score from OOB predictions
uncertainty_score( fit, metric = c("ci_width", "sd", "iqr"), level = 0.95, min_oob = 10 )uncertainty_score( fit, metric = c("ci_width", "sd", "iqr"), level = 0.95, min_oob = 10 )
fit |
A |
metric |
|
level |
Interval level for |
min_oob |
Samples with fewer OOB predictions get |
An object of class unc_scores holding a data frame with
pred_mean, uncertainty, y, abs_error, and n_oob.
Run this before interpreting drivers. If uncertainty is not associated with absolute out-of-bag error, explaining it is not meaningful.
validate_uncertainty(unc)validate_uncertainty(unc)
unc |
An |
List with Spearman correlation and mean error by uncertainty quartile.