NEWS

---

debrowser 1.41.2

Bug fixes

• Dropped the sodium dependency, which broke R CMD check on the Bioconductor Linux builder (nebbiolo2 has no libsodium, so the check failed with "Package suggested but not available: 'sodium'" before running any other stage). Auth crypto now uses scrypt and openssl — both already Imports: of shinymanager, and both present on every Bioconductor builder.
  • Password hashing moved from libsodium argon2id to scrypt::hashPassword(), the same primitive shinymanager itself stores.
  • Per-user AI key encryption moved from libsodium secretbox to AES-256-GCM with an explicit encrypt-then-MAC HMAC-SHA256 tag. R's openssl package neither emits nor verifies a GCM tag, so authentication is applied explicitly; encryption and MAC subkeys are domain-separated.
  • Existing password hashes and stored AI keys are not readable across this change — see the migration note below.

Migration

• Password hashes and encrypted per-user AI keys written by 1.41.1 or earlier use libsodium formats and cannot be read by 1.41.2. Any user database created during D2 development must be re-created: users need to reset their passwords and re-enter their AI provider keys.

debrowser 1.41.1

Documentation overhaul

• Rewrote the user-guide vignette (vignettes/DEBrowser.Rmd) around the modernized six-step Data Prep wizard and the current top-level tabs (Main Plots, QC Plots, Concordance, Enrichment, Tables). Added coverage for the features the old guide missed — batch-correction QC, cross-contrast concordance, GO/KEGG + GSEA enrichment, reproducibility exports (R / R Markdown / Jupyter / methods paragraph), bookmarking & sharing, theming and keyboard shortcuts, and the optional AI interpretation panel.
• Kept the package small. The full illustrated user guide — with all screenshots and worked examples — lives outside the package at https://debrowser.readthedocs.io (the UMMS-Biocore/debrowser-docs repo, served by Read the Docs). The vignette is a concise, image-free reference that links there, and the README references the same externally hosted screenshots, so no images are bundled in the package tarball.
• Rewrote README.md to mirror the modern walkthrough at a shorter altitude and point to the online guide.
• Removed the unused fontawesome and RColorBrewer entries from Imports (icons come via shiny::icon(); no brewer.pal/RColorBrewer:: usage), clearing the R CMD check "declared Imports should be used" note.

UI design-system consolidation (docs/design plans §1–§6)

• Grid/layout: collapsed four grid idioms to one primitive (bslib::layout_columns(col_widths=)) and two card systems to one wrapper (de_card(), now with a class= passthrough) across every panel; retired layout_column_wrap, hand-rolled display:grid, and ragged rows. Spacing comes from a --de-space-* scale and plot heights from de_plot_h(). Added tools/check-grid.sh to lock the standard in.
• Color/contrast: raised light/dark muted text and introduced theme-resolved --de-accent-ink (accent-as-text) + --de-ink-on-accent tokens for WCAG-AA contrast; --de-cyan is now fill-only.
• Icons: Font Awesome only, via shiny::icon(). Repaired app-wide FA webfont rendering (the Inter UI font was clobbering glyphs), consolidated ad-hoc glyphs, and wired the favicon.
• Loading/motion: replaced the 1.1 MB boot gif with a CSS conic ring; added stepwise withProgress detail to the DE run; added --de-transition, :focus-visible rings, prefers-reduced-motion, and cursor:not-allowed affordances; removed the dead getLoadingMsg overlay and its orphan gifs.
• Handoff: added de_style_guide() + inst/extdata/www/style-guide.html (a component gallery in both themes that doubles as a pixel-regression baseline) and DESIGN.md, the contributor design contract.

Phase A1 — foundation modernization

• Bumped minimum R version to 4.2 and RoxygenNote to 7.3.x.
• Added lintr and styler configs; one-time formatting pass.
• Added GitHub Actions for R-CMD-check (R-release + R-devel), BiocCheck, lintr, and covr coverage (codecov).
• Extended .Rbuildignore for docs, CI, lint, and dev configs.
• Removed stale empty viafoundry_errors.log from the repo.

Phase A2 — test scaffolding + golden snapshots

• Migrated tests/test-*.R to the testthat 3e layout under tests/testthat/, with shared helpers in helper-debrowser.R.
• Added golden snapshot tests for DESeq2, edgeR, limma, getNormalizedMatrix(), and PCA coordinates on the demo data — these are the safety net for Phase A3+ refactors.
• Added a shinytest2 smoke-test scaffold (CI-skipped until A4 stabilises module IDs).
• Fixed silent Treat/Control inversion in the migrated DESeq2 test.

Phase A3a — pure analytic core (DE + normalize + filter)

• Added R/fct_de_methods.R with run_deseq2(), run_edger(), run_limma(), run_de() — pure functions taking structured (named-list) params instead of legacy comma-string params. No Shiny dependency.
• Added R/fct_normalize.R with normalize_counts() and pure apply_batch_correction() (Combat / CombatSeq / Harman). Batch / treatment column names are now arguments instead of input$ lookups.
• Added R/fct_filter.R with filter_low_counts() (max / mean / cpm).
• Added R/utils_validate.R with de_error() — structured stop() raising classed conditions so callers dispatch on class, not message text.
• Legacy runDE(), runDESeq2(), runEdgeR(), runLimma(), getNormalizedMatrix(), correctCombat(), correctHarman() are now thin shims that translate input/comma-string params and delegate. Their signatures are unchanged so existing callers and scripts keep working.
• Fixed silent "Repeated column names found in count matrix" warning in the limma path (legacy code set all column names to factor levels; removing it does not affect results).
• debrowserlowcountfilter module's filter observer shrinks from ~20 lines to 9 by delegating to filter_low_counts().

Phase A3b — pure data-prep functions

• Added R/fct_prep_data.R with apply_de_filters(), get_most_varied(), select_dataset(), search_geneset(), merge_comparisons(), apply_merged_filters(), get_table_data() — pure functions that take a structured filter-params list.
• Added filter_params_from_input() in utils_validate.R to centralise the Shiny-input → pure-fn-params field-name mapping (e.g. input$padj → params$padj_cutoff, input$genesetarea → params$geneset_area).
• Legacy applyFilters(), getMostVariedList(), getSelectedDatasetInput(), getSearchData(), getMergedComparison(), applyFiltersToMergedComparison(), getDataForTables() are now thin shims that delegate to R/fct_prep_data.R. Public signatures unchanged.
• New golden snapshot locks the (Up=551, Down=864, NS=13941) row-count distribution on the demo DE result with default cutoffs (padj 0.05, fold 2) — catches regressions in cutoff logic or normalization.

Phase A4a + A4c — Shiny API modernization

• Migrated all 13 modules from the deprecated callModule() API to moduleServer() (Shiny 1.5+ idiom): debrowserdataload, debrowserlowcountfilter, debrowserbatcheffect, debrowserhistogram, debrowserpcaplot, debrowserIQRplot, debrowserdensityplot, debrowserall2all, debrowserheatmap, debrowsermainplot, debrowserbarmainplot, debrowserboxmainplot, debrowserdeanalysis. Public function signatures changed from (input, output, session, …) to (id, …) to match the modern Shiny convention.
• Removed the library("debrowser") self-import inside deUI() — was a no-op at best and a side-effect at worst.
• Replaced the runtime installpack() / loadpack() package-loading helpers with standard requireNamespace(pkg, quietly = TRUE) checks in R/GOterm.R. Deleted R/installpack.R and its exported functions (installpack, loadpack).
• Dropped the unused aes_string import (deprecated in ggplot2 3.0).
• condSelect.R is deliberately left untouched — full rewrite folded into Phase B2 alongside the three-stage-shell wizard redesign.

Phase A5 — slim dependencies

• Moved seven rarely-used packages from Imports: to Suggests: so a fresh install pulls a smaller dependency graph: Harman, pathview, org.Mm.eg.db, apeglm, ashr, enrichplot, DOSE.
• Added require_pkg(pkg, feature) helper in R/utils_validate.R that raises a debrowser_error of class missing_suggested_pkg with the install command when a Suggested package is needed but unavailable.
• Gated every direct call site:
  • Harman::harman() / Harman::reconstructData() — harman_correct()
  • DESeq2::lfcShrink(type="apeglm"/"ashr") — run_deseq2()
  • enrichplot::dotplot() / enrichplot::gseaplot() — gopanel.R, GOterm.R::compareClust, server.R GSEA render path
  • DOSE::enrichDO() — getEnrichDO() (the compareCluster(fun = "enrichDO") branch in compareClust() keeps its existing in-place requireNamespace gate)
  • pathview::pathview() — already gated in drawKEGG(); now namespaced
• Stripped the corresponding @import / @importFrom lines from R/server.R and R/GOterm.R; NAMESPACE no longer pulls these packages at load time.

Phase B1 — bslib chrome + theme swap

• Replaced shinydashboard::dashboardPage shell with bslib::page_navbar and per-tab bslib::layout_sidebar. Top navbar now hosts five sections (Data Prep / Main Plots / QC Plots / GO Term / Tables) plus a light/dark toggle (bslib::input_dark_mode).
• Theme: Slate (#0f172a) navbar + OK-blue (#0369a1) primary, Bootstrap 5, Inter typography. New de_theme() helper.
• Migrated all 22 shinydashboard::box() call sites to bslib::card via a new de_card() helper (with optional download button in the header). Wide layout containers use raw bslib::card; narrow widget cards use de_card.
• DE Filter (cutoff + comparison-selector controls) moved from the sidebar into a card at the top of the DE Analysis wizard panel.
• Migrated all 24 shinydashboard::menuItem() collapsible widget containers to bslib::accordion + bslib::accordion_panel (in R/IQR.R, R/barmain.R, R/all2all.R, R/density.R, R/boxmain.R, R/plotSize.R, R/mainScatter.R, R/heatmap.R, R/uifuncs.R).
• Replaced getTabUpdateJS()'s shinydashboard .sidebar-menu jQuery with server-side bslib::nav_show/nav_hide observers in deServer. Same trigger button ids, same behavior.
• togglePanels() body rewritten to bslib::nav_show/nav_hide/ nav_select. Function signature unchanged — all callers untouched.
• The standalone heatmap app (startHeatmap()) shell heatmapUI() also migrated to bslib::page_navbar with the same Slate + OK-blue theme; controls now live in the Heatmap tab's layout_sidebar.
• de_card() defaults to full_screen = FALSE to avoid bslib's expand-overlay interfering with htmlwidget click handlers.
• CSS file shinydashboard_additional.css audited and renamed to debrowser.css; shrunk from 145 to ~30 lines of app-specific positioning rules.
• Dropped shinydashboard from Imports. Added bslib (>= 0.7.0). Added explicit @importFrom shiny tagList req to compensate for symbols previously pulled through shinydashboard's dependency chain.
• Dark-mode plot theming (plotly/heatmaply/ggplot color flips) deferred to Phase B6.

Phase B2.5 — Comparison Selection wizard rewrite

• Rewrote R/condSelect.R (≈900 LOC monolith) into three focused files: R/fct_condselect.R (pure helpers + validation predicates), R/mod_condselect.R (condSelectUI + condSelectServer module), and R/prep_data_container.R (the DE runner with a structured signature).
• New module API: condSelectUI(id) and condSelectServer(id, data, metadata). Returns list(n_comparisons, start_de, is_ready, comparisons_spec).
• prepDataContainer() signature changed from (data, counter, input, meta) to (data, metadata, comparisons_spec). The leaky condselect$input boundary in R/server.R is gone.
• UX: single-comparison default with "Add another comparison" footer for multi-comparison; editable per-side Treatment/Control labels with metadata- driven defaults; reference-word direction heuristic (control|ctrl|wt|wildtype|...) with always-visible swap button; per-method advanced settings + covariates collapsed by default; inline non-toast validation messages (.text-warning / .text-danger).
• Internal conds codes ("Cond1"/"Cond2") preserved so R/fct_de_methods.R, R/fct_prep_data.R, R/deprogs.R, R/barmain.R, and downstream plotting need no changes.
• Removed exports (no known external callers): debrowsercondselect, debrowsercondselectServer, selectedInput, getSelectInputBox, getMetaSelector, getGroupSelector, getConditionSelector, getConditionSelectorFromMeta, getMethodDetails, getCovariateDetails, selectConditions, get_conditions_given_selection, getSampleNames.
• New tests: test-condselect-helpers.R (helpers), test-condselect-validation.R (predicates), test-prepdatacontainer.R (prep_comparison_inputs purity). Total +73 assertions (126 → 199 PASS).

Phase B3 — Sane defaults harmonization

• Switched DE cutoff input from fold-change to |log2FC| convention. The cutoff numeric inputs are now labelled padj <= and |log2FC| >=.
• Added [ Strict ] [ Standard ] preset buttons above the DE cutoff inputs. Strict (padj 0.01, |log2FC| 1) is the default; Standard is (padj 0.05, |log2FC| 1). Manual edits clear the preset highlight unless the new pair matches a preset exactly.
• Cutoff inputs (DE padj, DE |log2FC|, GO p.adjust) are now numericInput with bounds + native validation, replacing textInput widgets that silently produced NaN downstream when users typed non-numeric values.
• New helper module R/fct_cutoffs.R owns the single source of truth for default values and preset definitions: default_cutoffs(), cutoff_presets(), match_preset(), log2fc_to_fold(), fold_to_log2fc(), install_cutoff_preset_observers(). The hardcoded fallback in generateTestData() now reads from default_cutoffs().
• Internal-only Shiny input rename: input$foldChange -> input$log2fc_cutoff. Public cutOffSelectionUI API is unchanged; new exported companion cutOffSelectionServer(id) wires preset observers for the namespaced widget.

Phase E3.B — Rich report generation + Jupyter + view-in-tab

• Export dropdown gains three new items, bringing the total to six:
  • Rmd source -- downloads the raw .Rmd body (no render).
  • View HTML in tab -- renders the Rmd to a tempdir, registers it as a Shiny resource path, and opens the rendered HTML in a new browser tab via Shiny.addCustomMessageHandler('debrowser_open_tab',...).
  • Jupyter notebook -- downloads the same content as a .ipynb file with R-kernel (ir) code cells; opens directly in JupyterLab. The pre-existing Rmd -> HTML item is renamed to plain HTML (it always meant "render and download"); the new View HTML in tab is the in-browser counterpart.
• emit_rmd() now produces a manuscript-style report mirroring a reference Rmd contributed by a user (Haania mouse PA/DMSO study). YAML uses code_folding: hide so chunks are collapsible in the rendered HTML; setup chunk runs eval = TRUE so the report includes actual plots when rendered. New sections (in order):
  • Library + helper-source chunks
  • ## Methods (paragraph from Phase E9's methods_paragraph())
  • ## Pipeline -- load, filter, batch, DE per comparison
  • ## Sample Info -- DT::datatable of metadata
  • ## Quality Control {.tabset} -- Count distribution / All2All / PCA + Scree (all on the all-detected-genes matrix)
  • ## DESeq Analysis {.tabset} -- one tab per comparison with sub-tabs Results / Volcano / MA / Heatmap
  • ## Enrichment (when configured)
  • ## Session Info {.tabset} -- Hide / Show
• New pure helpers in R/fct_export_session.R: emit_ipynb(blocks) parses emit_rmd() output and converts to .ipynb JSON cells.
• New file: inst/templates/report_helpers.R (~534 lines) bundling the report's plotting functions (count_distribution, all2all, run_pca, pca_plot, scree_plot, volcano_plot, ma_plot, heatmap_plot, getNormalizedMatrix, post_processing, add_alias, add_highlights, call_significance). The emitted Rmd / Jupyter / .R all source() this file from the installed package so report styling stays in one place.
• state_react() (in R/server.R) now surfaces full_counts (the filter+batch-corrected matrix on all detected genes) and metadata (the sample-info table) so the QC and Sample Info sections can reference the same data DEBrowser sees.

Phase E12.B — AI interpretation: presets + mount points

• AI interpretation panel widened from fgseaGSEA-only to all 6 Enrichment modes (enrichGO, enrichKEGG, enrichDO, enrichPathway, compareCluster, fgseaGSEA). One mount, one preset (summarize_geneset) works across all modes via per-mode payload adapters.
• New AI panel on the DE Analysis tab (per-comparison, below the results table). Presets: summarize_geneset, suggest_followup, draft_methods. Privacy default for this mount: + Stats.
• New AI panel on the Comparison Concordance tab (below the summary card). Presets: reconcile_enrichments, suggest_followup, draft_methods. In-card pathway picker surfaces when one or more pathways are enriched in two or more comparisons; selecting one triggers cross-comparison fgsea so the prompt sees real NES rows.
• New presets in inst/templates/:
  • ai_reconcile_enrichments.md — explains a pathway's divergent NES across multiple comparisons.
  • ai_suggest_followup.md — two-section response: bioinformatic next-analyses + wet-lab next-experiments.
  • ai_draft_methods.md — journal-style polish of E9's deterministic Methods paragraph. Cannot add or remove facts.
• Sanitized markdown response rendering via commonmark + xml2 (replaces v1's plain <pre>). Strict allow-list: headings, bold, italic, lists, code, blockquote, hr. Links rendered as plain text (no hallucinated URLs are clickable). Images and scripts stripped.
• Privacy modes adapted per payload shape: de_table and concordance default to + Stats; the draft_methods preset hides the radio entirely (no genes / stats in payload).
• No new Imports. commonmark + xml2 added to Suggests (both already transitively present via rmarkdown / httr2).
• Streaming responses still deferred.

Phase E12.A — AI interpretation foundation

• New top-right Settings dropdown in the navbar with an AI configuration modal: master switch (off by default), provider picker (Anthropic / OpenAI / Ollama), dynamic model lookup via ellmer::models_*, encrypted API-key storage via the OS keychain (keyring package), and a default privacy mode setting.
• New AI interpretation card on the Enrichment tab below the Leading Edge card. Renders only when the master switch is on, a provider is configured, and (for non-Ollama providers) an API key is present. v1 ships one question preset: "Summarize this gene set's biology", attached to the currently-selected fgsea pathway's leading-edge genes.
• Privacy modes per call (default: Symbols only):
  • Symbols only -- gene symbols of the leading edge.
  • + Stats -- also log2FoldChange and adjusted p-value per gene.
  • + Stats + Enrichment -- also the term name, p-value, and overlap count of the selected pathway. A "What will be sent?" disclosure shows the literal prompt body (live preview) and a character count before the user clicks Ask.
• New exported helpers in pure files: ai_interpret(question, payload, privacy_mode, provider_chat, top_n, template_dir) (R/fct_ai_interpret.R), list_models(provider, api_key) and ai_chat(provider, model, api_key) (R/fct_ai_providers.R). Internal helpers cover settings I/O and encrypted key storage (R/fct_ai_settings.R).
• New error class hierarchy: ai_error extends simpleError; subclasses ai_no_key, ai_rate_limit, ai_network, ai_invalid_response, ai_disabled. The Shiny module maps each subclass to a friendly notification with a recovery hint.
• LLM responses are rendered as plain preformatted text (tags$pre); no markdown parsing, no HTML execution, no automatic link traversal -- defense against untrusted-content patterns in model output.
• Three new Suggests gated via require_pkg: ellmer (>= 0.1.0), whisker, keyring. R CMD check passes with all three uninstalled -- the AI features are gracefully unavailable in that case.
• AI is disabled by default. No network calls happen unless the user explicitly enables AI features and configures a provider.
• Phase E12.B will extend with the remaining 3 question presets (reconcile enrichments, suggest follow-up experiments, draft methods narrative) and 2 mount points (DE Analysis tab results, Comparison Concordance summary).

Phase E9 — Methods-paragraph autogen

• Phase E3's Export dropdown now emits a single manuscript-ready methods paragraph (~150-250 words) with inline citations and version stamps, replacing the previous per-step bullet list. The paragraph appears in three places:
  • At the top of the exported .R script as a wrapped comment block.
  • In the rendered .Rmd -> HTML report's "## Methods" section.
  • In a new Copy methods text Export menu item that opens a modal with the paragraph in selectable preformatted text plus a "Download as .txt" button.
• New exported methods_paragraph(blocks) function (in R/fct_methods_text.R); upgraded internal methods_sentences() helper now produces citation-rich, version-stamped per-step sentences. Both functions are pure (no Shiny dependency) and consume the build_session_blocks() output from Phase E3.
• New internal .method_refs registry maps method keys to list(name, version_pkg, cite) for nine entries: DEBrowser, DESeq2, edgeR, limma, ComBat, ComBat-seq, Harman, fgsea, MSigDB. Citations are inline "(Author et al., YEAR)" plain text.
• Soft fallback when a cited package is not installed: citation reads "(version unknown)" and a deduplicated showNotification warns the user. Methods text export never errors on a missing version lookup.

Phase E3 — Reproducibility export

• New top-right Export dropdown in the navbar with two items:
  • R script -- downloads a runnable .R script that reproduces the full analytical pipeline (data load -> low-count filter -> batch correction -> DE per comparison -> GSEA if loaded). Calls only already-exported pure helpers (filter_low_counts, apply_batch_correction, run_de, run_gsea, msigdb_pathways), so the script has no Shiny dependency. Sets per-comparison deN variables in the workspace, writes per-comparison TSVs to ./debrowser_results/, and prints sessionInfo() at the end.
  • Rmd -> HTML -- renders a self-contained HTML report with the same pipeline as code chunks (eval = FALSE by default) plus an auto-generated Methods paragraph. Gated on the rmarkdown package being installed; falls back to raw .Rmd download if pandoc fails.
• New pure helpers in R/fct_export_session.R: build_session_blocks(), emit_r_script(), emit_rmd(), sanitize_label(). New R/fct_methods_text.R::methods_sentences() produces the per-step prose consumed by both emitters; Phase E9 will upgrade it to a citation-rich paragraph generator.
• enrichmentGmtServer() return is now list(pathways, state) instead of just the pathways reactive (additive; consumers extend the destructure).
• Both export items are gated by a "Run a DE analysis before exporting" notification until DE has been run.
• Frozen sessionInfo() of the export-time R session is embedded in the .R script header for audit reproducibility; live sessionInfo() is also called at script end.
• Comparison labels with collisions get _2, _3 suffixes in TSV filenames; unsafe characters in labels are replaced with underscores.

Phase E11 — Comparison Concordance tab (top-level)

• New top-level Comparison Concordance tab between QC Plots and Enrichment. Auto-shown when the user has set up two or more comparisons in CondSelect; hidden for single-comparison sessions. Compares the user's existing comparisons against each other (no DE re-running — reads dc()[[i]]$init_data produced by the main DE pipeline).
• Five cards driven by live padj / lfc cutoffs:
  • DEG bar (up red rightward / down blue leftward, ordered by total DEG count)
  • Pairwise DEG count heatmap (symmetric groups x groups matrix)
  • UpSet plot of significant-gene-set overlap across comparisons
  • Pairwise log2FC scatter with Spearman correlation
  • Pairwise concordance summary table (DT)
• New pure helpers in R/fct_method_concordance.R: concordance_sets(), concordance_summary(), plot_method_upset(), plot_method_scatter(), comparison_labels(), de_direction_summary(), plot_de_direction_bar(), plot_de_pairwise_heatmap(), plus run_de_methods() for programmatic use.
• UpSetR added to Suggests (gated via require_pkg("UpSetR")).

Phase E2.5 — Consolidated Enrichment tab

• The previously-separate GO Term and Enrichment tabs are now a single Enrichment tab. The legacy GO Term modes (enrichGO / enrichKEGG / Disease / compareClusters / GSEA via clusterProfiler::gseGO) and the new fgsea-based GSEA share one top-level tab. The standalone Enrichment tab introduced in E1 has been removed; its content is folded in here.
• New radio choice "GSEA (fgsea / .gmt or MSigDB)" under the Enrichment-method picker. Selecting it reveals the GMT/MSigDB picker and Advanced controls (min/max set size, permutations, seed) inside the same sidebar that hosts the legacy GO Term options.
• Both render styles coexist via conditional panels: the legacy modes keep their plot+table tabset; the fgsea mode renders results table + enrichment plot + leading edge cards plus a multi-comparison NES heatmap when more than one comparison is loaded — same widgets the standalone Enrichment tab used.
• enrichmentUI() / enrichmentServer() (the standalone-tab module pair from E1) remain exported as a public API for users who want to embed the enrichment tab elsewhere; the consolidated panel reuses the smaller enrichmentGmtServer() and enrichmentNesHeatmapServer() building blocks directly.
• togglePanels() reverts from a 0..5 loop with backwards-compat rule to a clean 0..4 loop, since panel5 no longer exists.

Phase E2 — MSigDB integration (gene-set source picker)

• The Enrichment tab's gene-set picker now offers MSigDB as a sibling source to manual .gmt upload. Pick a species (the 20 species msigdbr ships, including human, mouse, rat, fly, yeast, zebrafish, C. elegans, and more), a top-level collection (Hallmark, Curated, Ontology, Cell type, ...), and an optional subcollection (e.g. CP:KEGG, GO:BP). Click "Load gene sets" to pull the named-list of pathways into the running GSEA session.
• New pure helper msigdb_pathways(species, collection, subcollection) in R/fct_gsea.R wraps msigdbr::msigdbr() and reshapes its long-format tibble into the same named-list-of- character-vectors shape gmt_to_pathways() returns, so all downstream code (run_gsea, NES heatmap, leading edge) is source-agnostic. Errors from msigdbr (unknown species, unknown collection, empty result) are normalized to the empty_input classed condition.
• msigdbr added to Suggests (~50MB local install but no install-time network — Bioc-friendly). Calls go through require_pkg("msigdbr") with the install command for users who don't have it.
• Per-session in-module cache keyed on (species, collection, subcollection) so re-clicking "Load" with the same inputs is instant.
• The GO Term tab is unchanged in this release; folding ORA into the Enrichment tab as the second method is deferred to E2.5.

Phase E1 — Enrichment tab (GSEA via fgsea)

• New top-level Enrichment tab next to GO Term, driven by ranked-list Gene Set Enrichment Analysis. Pre-DE the tab is hidden; once DE has run, paste a .gmt file (or use the bundled inst/extdata/test-gmt/hallmark-mini.gmt fixture) and the results table populates with NES, padj, leading edge.
• When more than one comparison is loaded, the NES heatmap card appears below the results, plotting NES across pathways x comparisons (significance stars, axis flip, padj cutoff slider).
• New pure helpers in R/fct_gsea.R (@export): gmt_to_pathways(path) (fgsea-gated wrapper around fgsea::gmtPathways), run_gsea(de_table, pathways, ...) (DE table -> tidy enrichment data.frame), and nes_heatmap_data(results_by_comparison, sig_only, sig_threshold) (long-format reshape for the heatmap).
• New Shiny modules in R/mod_enrichment.R, R/mod_enrichment_gmt.R, R/mod_enrichment_nes_heatmap.R. The GMT picker is the integration point Phase E2 will use to add MSigDB as a sibling source; the NES heatmap module is the same widget Phase E11 will reuse for cross-method comparison.
• fgsea added to Suggests (Bioconductor); calls go through require_pkg("fgsea") so users without it installed see the install command instead of a stack trace.
• Reference architecture (gsea_analysis shape, NES heatmap card, GMT picker layout) adapted from https://github.com/nephantes/gsea-explorer (Via Scientific) — re-implemented against this package's pure-helper conventions.

Phase E4 — Sample QC dashboard (always-on cards)

• QC Plots tab now exposes four new cards for raw-count sample inspection: Library Depth (per-sample total counts, with >2-SD outlier flag), Feature Detection Rate (% of features with non-zero counts per sample), Mitochondrial Read % (sum of ^MT-/^mt-/Mt- rows per sample, with empty-state when no MT genes are detected), and Sample Distance Heatmap (clustered Euclidean distance on VST-transformed counts).
• New R/fct_qc.R exports the underlying pure helpers (library_depth_summary, detection_rate, mt_pct_per_sample, sample_distance_matrix, flag_outliers_2sd) so they can be reused outside the Shiny app.
• New Mapping / rRNA Stats card ships as an empty-state stub describing the optional sidecar TSV format (sample, mapped_pct, rRNA_pct); the upload handler itself lands in a follow-up.
• Cards consume post-filter, post-batch, pre-normalize counts via batch()$BatchEffect()$count so library-size metrics report the correct raw values.
• Three additional post-DE cards (Dispersion, Size factors, Cook's outlier flag) are deferred to a follow-up phase pending DESeq2 dds retention through prepDataContainer.

Phase E4.5 — Post-DE QC cards + dds retention

• run_deseq2() gains a return_dds = FALSE argument; when TRUE it returns list(res, dds) so the fitted DESeqDataSet is recoverable for downstream QC. Threaded through runDESeq2(), runDE(), debrowserdeanalysis(), and prepDataContainer() (which now stashes a dds slot per comparison alongside init_data). Default behaviour is unchanged so existing callers (generateTestData, per-method tests) keep their data.frame contract.
• QC Plots tab adds three post-DE cards driven by the active comparison's dds: Dispersion Estimates (DESeq2 plotDispEsts of gene-wise / fitted / shrunken values), Size Factors vs Library Size (scaled bars per sample with Spearman ρ in the subtitle), and Cook's Outlier Counts (per-sample count of high-Cook genes vs the vignette threshold 4 / (n_samples - n_params)).
• New pure helpers in R/fct_qc.R: size_factor_library_summary(dds) and cooks_outlier_summary(dds, threshold = NULL). The Spearman correlation and active threshold are attached as attributes on the returned data.frame.
• Cards render a friendly empty-state alert when no fitted DESeqDataSet is available (pre-DE, or non-DESeq2 method).
• QC sidebar's "Select Columns" checkboxes now also drive cards 1-4 (Library Depth, Detection Rate, MT %, Sample Distance) and cards 6-7 (Size Factors, Cook's): unchecking a sample hides its bar/row across every per-sample card. Card 5 (Dispersion) is gene-level so column selection has no effect there. New pure helpers qc_keep_cols(counts, selected) and qc_keep_meta_rows(meta, selected) in R/fct_qc.R.

Phase B4 — Friendly errors

• User-facing error messages now follow a consistent "what went wrong + what to do" format with correct severity (red blocks, yellow warns, green/blue empty-result).
• Replaced raw R diagnostics in file-upload errors (separator mismatch, duplicate gene IDs, column/metadata mismatch).
• Empty enrichment results no longer display as red errors — they were a category bug.
• Six hand-rolled "Please install " messages in GO/KEGG paths collapsed into the existing require_pkg() helper.
• No behavior change beyond message text and notification persistence.

Phase B3.5 — Sane defaults follow-up

• DESeq2 default test changed from Wald to LRT, harmonizing the pure-helper, parser fallback, test-data, and (where applicable) help text with the UI default already in place.
• DESeq2 LFC shrinkage now defaults to apeglm. Install via BiocManager::install("apeglm") if not already available; a friendly install message surfaces on first DE run otherwise. apeglm remains in Suggests, not Imports.
• Low-count filter auto-applies on data load (method = Max, cutoff = 10 — the previous default values, now applied without a Filter click). Click Filter with a different cutoff/method to override, or set cutoff = 0 to restore the unfiltered counts.

User-visible

• Raised startDEBrowser() upload limit from 30 MB to 90 MB.