--- title: "looOmics: leave-one-out sensitivity analysis for omics differential models" author: "Tanay Belapurkar" date: "`r Sys.Date()`" output: BiocStyle::html_document vignette: > %\VignetteIndexEntry{looOmics: leave-one-out sensitivity analysis} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r knitr-setup, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>", fig.width = 7, fig.height = 4.5 ) ``` # Purpose Differential-analysis results on high-dimensional omics data (gene expression, microbiome abundance tables) can be driven by a small number of samples. `looOmics` quantifies this by refitting the model once per left-out sample and measuring how much the coefficients move. **This is a sensitivity analysis, not a bad-sample detector.** An influential sample may reflect genuine biological heterogeneity — a real subgroup, an extreme but valid responder. Flagged samples should be inspected, not automatically removed. The package reruns the relevant pipeline for every leave-one-out fit where appropriate: for the DESeq2 engine, for example, size factors and dispersions are re-estimated for every fit. # Quick start The recommended interface is a `SummarizedExperiment`. The first example uses a simulated matrix to introduce the workflow; subsequent examples show Bioconductor-native inputs. ```{r setup} library(looOmics) ``` We simulate 200 features, 16 samples, a two-level condition effect on the first 30 features, and one planted influential sample (S09): ```{r sim} set.seed(42) n_feat <- 200 samples <- sprintf("S%02d", 1:16) condition <- factor(rep(c("A", "B"), each = 8)) batch <- factor(rep(c("kit1", "kit2"), times = 8)) assay <- matrix(rnorm(n_feat * 16), n_feat, 16, dimnames = list(paste0("g", 1:n_feat), samples)) assay[1:30, condition == "B"] <- assay[1:30, condition == "B"] + 1.2 # planted influential sample: S09 (group B) has extreme values on g1-g20 assay[1:20, "S09"] <- assay[1:20, "S09"] + 6 col_data <- data.frame( condition = condition, batch = batch, depth = round(rnorm(16, mean = 5e6, sd = 4e5)), extraction = factor(rep(c("good", "good", "good", "bad"), times = 4)), row.names = samples ) ``` ## Run the leave-one-out analysis ```{r loo} res <- loo_sensitivity(assay, ~ condition + batch, col_data = col_data) res ``` ## Bioconductor input interoperability `looOmics` uses `SummarizedExperiment` as its primary Bioconductor input interface. The assay stores features in rows and samples in columns, while `colData` stores the biological and technical sample metadata used both in the differential model and in downstream influence profiling. ```{r summarized-experiment} se <- SummarizedExperiment::SummarizedExperiment( assays = list(logcounts = assay), colData = S4Vectors::DataFrame(col_data) ) res_se <- loo_sensitivity( se, ~ condition + batch, engine = "lm", assay_name = "logcounts", parallel = FALSE ) res_se ``` For count-based RNA-seq analyses, use raw non-negative integer counts with the DESeq2 engine. The engine reconstructs and refits the DESeq2 workflow for each omitted sample, re-estimating size factors and dispersions rather than rounding or reusing normalized values. ```{r deseq2-summarized-experiment} set.seed(21) count_samples <- sprintf("C%02d", 1:12) count_condition <- factor(rep(c("control", "treated"), each = 6), levels = c("control", "treated")) count_meta <- data.frame(condition = count_condition, row.names = count_samples) count_matrix <- matrix( rnbinom(100 * 12, mu = 100, size = 10), nrow = 100, dimnames = list(paste0("gene", 1:100), count_samples) ) count_matrix[1:20, count_condition == "treated"] <- count_matrix[1:20, count_condition == "treated"] + 80L se_counts <- SummarizedExperiment::SummarizedExperiment( assays = list(counts = count_matrix), colData = S4Vectors::DataFrame(count_meta) ) res_deseq2 <- loo_sensitivity( se_counts, ~ condition, engine = "deseq2", assay_name = "counts", parallel = FALSE, fitType = "mean" ) res_deseq2 ``` The `shifts` table records, for every feature, model term, and left-out sample, the full-sample coefficient, the LOO coefficient, the raw shift (`delta`), the standardized deletion shift (`dfbetas`), full and LOO p-values, BH-adjusted q-values, within-term feature ranks, rank changes, and whether the feature's significance status flipped. A positive `rank_change` means the feature moved to a numerically larger (weaker) rank after sample deletion: ```{r shifts} head(tidy(res, what = "shifts")) ``` For ordinary linear models `dfbetas` coincides with classical DFBETAS; for other engines it is the analogous deletion-based standardized shift. ## Flag influential samples ```{r flag} res <- flag_influential(res, method = "topk", k = 2) res ``` The planted sample S09 is recovered as the most influential sample: ```{r topflags} flags <- tidy(res, what = "flags") flags[order(-flags$score), ] ``` Per-term influence scores show which model terms drive each sample's score: ```{r byterm} head(influence_by_term(res)) ``` ## Profile flags against metadata ```{r profile} res <- profile_flags(res, model_covariates = c("condition", "batch")) profiles(res) ``` The profile evaluates associations between flagged status and all selected sample metadata, including the original model variables (`condition` and `batch`) as well as technical variables (`depth` and `extraction`). In-model variables are explicitly labeled. P-values are BH-adjusted across the univariate family; an adjusted logistic model is fit only when the sample size and design support it. Covariates that cannot be tested are reported with reasons rather than silently dropped. ## Plot ```{r plot, fig.alt = "Bar plot of per-sample influence scores; the planted sample S09 stands out."} plot(res) ``` # Relationship to existing Bioconductor tools `limma` and `DESeq2` provide established differential-expression modeling frameworks (Ritchie et al., 2015; Love et al., 2014). `looOmics` does not replace either package: it repeatedly refits these engines after omitting one sample at a time, then compares coefficients, standard errors, adjusted p-values, and within-term feature rankings. It also connects sample influence to biological and technical metadata. This provides an additional sensitivity-analysis layer around existing differential-analysis workflows. For limma, users should supply appropriately normalized and log-transformed expression values. For DESeq2, users should supply raw integer counts. The package deliberately does not silently convert normalized or transformed values into counts. # Parallel execution `looOmics` never changes the `future` plan itself; users control it: ```{r parallel, eval = FALSE} future::plan(future::multisession, workers = 4) res <- loo_sensitivity(se, ~ condition + batch, engine = "lm") future::plan(future::sequential) ``` # References - Love, M. I., Huber, W., and Anders, S. (2014). Moderated estimation of fold change and dispersion for RNA-seq data with DESeq2. *Genome Biology*, 15, 550. [doi:10.1186/s13059-014-0550-8](https://doi.org/10.1186/s13059-014-0550-8). - Ritchie, M. E., Phipson, B., Wu, D., Hu, Y., Law, C. W., Shi, W., and Smyth, G. K. (2015). limma powers differential expression analyses for RNA-sequencing and microarray studies. *Nucleic Acids Research*, 43(7), e47. [doi:10.1093/nar/gkv007](https://doi.org/10.1093/nar/gkv007). # Session information ```{r session} sessionInfo() ```