# DEBrowser: Interactive Differential Expression Analysis

> 📖 Full illustrated user guide. This vignette is a concise reference. The complete, screenshot-by-screenshot walkthrough — the Data Prep wizard, every QC plot, enrichment, and the worked examples — lives at https://debrowser.readthedocs.io. It is kept outside the package so the package itself stays small.

# Introduction

Differential expression (DE) analysis is a core step in RNA-Seq and other high-throughput studies: given counts for two or more groups of samples, which genes or regions change more than expected by chance? DEBrowser turns that analysis into an interactive, point-and-click experience. It wraps three established Bioconductor engines — DESeq2 (Love et al., 2014), edgeR (Robinson et al., 2010), and limma (Ritchie et al., 2015) — in a Shiny application so that changing a cutoff, a normalization method, or a comparison re-draws every plot and table in real time.

Beyond the DE test itself, DEBrowser bundles quality-control views (PCA, sample-to-sample correlation, IQR, density), batch-effect correction, interactive scatter/volcano/MA plots with linked heatmaps, GO/KEGG and GSEA enrichment, cross-contrast concordance, exportable result tables, and an optional AI interpretation assistant — all without writing code.

The interface is organized as a six-step Data Prep wizard (Quick start → Upload → Filter & normalize → Batch effect → Comparison → DE analysis) followed by five result tabs — Main Plots, QC Plots, Concordance, Enrichment, and Tables — reachable with the number keys `1`–`6`. A light/dark theme toggle (the moon/sun button, or the `T` key) rounds out the chrome.

# Quick start

Install DEBrowser from Bioconductor and launch it:

    # 1. Install DEBrowser and its dependencies
    if (!requireNamespace("BiocManager", quietly = TRUE))
        install.packages("BiocManager")
    BiocManager::install("debrowser")

    # 2. Load the library
    library(debrowser)

    # 3. Start DEBrowser
    startDEBrowser()

`startDEBrowser()` opens the app in your browser on a fixed port (`3838` by default, so bookmark URLs stay stable across restarts). If your operating system is missing system libraries, see Operating System Dependencies below.

The fastest way to see DEBrowser in action is the Quick Start step: it explains what each stage does and lets you load a bundled demo (Vernia et al., 2014) with one click, so you can walk the whole pipeline before bringing your own data.

# Scriptable analytic core

DEBrowser’s normalization, filtering, and DE steps are also available as pure functions you can call directly — handy for scripting or reproducing an interactive analysis. For example, median-ratio-normalize the bundled demo counts:

    library(debrowser)
    load(system.file("extdata", "demo", "demodata.Rda", package = "debrowser"))

    norm <- getNormalizedMatrix(demodata, method = "MRN")
    round(head(norm[, seq_len(4)]), 1)
    #>          control_rep1 control_rep2 control_rep3 exper_rep1
    #> AK212155          0.0          0.0          0.0        0.0
    #> Sp2              62.4         52.6         62.4       53.0
    #> AK051368          0.6          0.0          0.0        4.1
    #> Ubiad1           84.4         94.2        104.9      123.3
    #> Src              27.1         21.8         30.2       21.4
    #> Racgap1           8.8          9.9          6.6        9.2

The same building blocks (`filter_low_counts()`, `run_deseq2()`, `run_edger()`, `run_limma()`, `run_de()`) power the interactive app and can be composed in a script.

# The Data Prep pipeline

All data loading and preparation happens on the Data Prep tab, organized as a wizard down the left rail. Steps light up as their prerequisites are met.

## Uploading counts and metadata

On the Upload data step, drop in a count matrix and, optionally, a metadata table. Both accept comma-, semicolon-, or tab-separated files (`.csv`, `.tsv`, `.txt`, or gzip-compressed `.csv.gz`). To try DEBrowser without your own data, click Vernia et al. or Donnard et al. under Demos, then Upload.

The count matrix has genes/regions in the first column and one raw-count column per sample. DEBrowser reads gene names from the first column, skips other non-numeric columns, and reads counts from the numeric columns:

gene | transcript | exper_rep1 | exper_rep2 | control_rep1 | control_rep2
--- | --- | --- | --- | --- | ---
DQ714826 | uc007tfl.1 | 0.00 | 0.00 | 0.00 | 0.00
AK028549 | uc011wpi.1 | 2.00 | 1.29 | 0.00 | 0.00

> DESeq2 requires un-normalized counts (it models library size internally). Only use pre-normalized values with edgeR or limma.

The optional metadata table maps each sample to a condition and, if relevant, a batch — this is what powers batch correction and grouped comparisons:

sample | batch | condition
--- | --- | ---
exper_rep1 | 1 | A
control_rep1 | 2 | B

Once loaded, DEBrowser shows an upload summary — sample count, gene count, number of conditions, a preview of the count matrix, and the sample-design table — so you can confirm the data was parsed as expected.

## Low-count filtering & normalization

The Filter & normalize step trims features with little or no signal. Pick a filtering method — Max, Mean, or CPM — and a cutoff; DEBrowser shows the row count before and after filtering side by side, plus per-sample count histograms.

## Batch-effect correction

The Batch effect step (optional) corrects technical confounders. Choose a normalization method (MRN, TMM, RLE, upperquartile, or none) and a correction method (ComBat, ComBat-Seq, or Harman), then Submit. Inline QC plots — PCA, IQR, and Density, each with a Before / After view — let you confirm that samples cluster by biology rather than by batch.

## Choosing comparisons and running DE

The Comparison step is where you define which groups to test. DEBrowser auto-populates a first comparison from your conditions; use Add comparison to set up several contrasts at once (each becomes its own DE result set you can switch between later). Assign samples to the Treatment and Control side, pick the DE engine and its parameters, then click Start DE. DEBrowser reports progress in stages (Normalizing → Fitting → Contrasts) and, when finished, unlocks the result tabs and jumps to Main Plots.

# Differential expression engines

DEBrowser exposes the parameters that matter for each engine on the Comparison step, under Advanced model settings.

## DESeq2

DESeq2 groups samples into conditions and computes, for every gene, the probability of differential expression using a negative binomial model, reporting both nominal and multiple-testing-corrected (`padj`) p-values.

- fitType — `parametric`, `local`, or `mean`: how dispersions are fit to the mean intensity.
- betaPrior — whether to place a zero-mean normal prior on the non-intercept coefficients.
- testType — `Wald` (nbinomWaldTest) or `LRT` (likelihood-ratio test).
- rowsum.filter — features with total count below this value are filtered out.

DESeq2 needs raw, un-normalized integer counts.

## edgeR

- Normalization — `TMM`, `RLE`, `upperquartile`, or `none`.
- Dispersion — a numeric dispersion or a string telling edgeR to estimate it from the data.
- testType — `exactTest` or `glmLRT`.
- rowsum.filter — low-total-count features are removed.

## limma

limma is ideal when data are already normalized (e.g. spike-in or another scaling), in which case prefer it over DESeq2 or edgeR.

- Normalization — `TMM`, `RLE`, `upperquartile`, or `none`.
- Fit Type — `ls` (least squares) or `robust` (robust regression).
- Norm. Bet. Arrays — normalize between arrays so intensities/log-ratios share similar distributions across samples.
- rowsum.filter — low-total-count features are removed.

# Exploring results

Main Plots is DEBrowser’s interactive heart: choose Scatter, Volcano Plot, or MA Plot; genes are colored Up (red), Down (blue), or NS (grey) by your `padj` and log2-fold-change cutoffs, and every change is instant. Hover a point for its identity and per-sample bar graphs, and lasso- or box-select a region to spawn a linked heatmap of just those genes.

The other result tabs:

- QC Plots — all-to-all correlation, PCA, IQR, density, and several sample-level QC views, independent of any single comparison.
- Concordance — where two or more comparisons agree and disagree.
- Enrichment — GO/KEGG over-representation (clusterProfiler) and GSEA (fgsea) with a leading-edge and NES-heatmap view.
- Tables — searchable, sortable result tables (All Detected, Up/Down, Most varied, Comparison differences) with regex search that applies everywhere.

## Heatmap clustering & scale

Heatmaps (on the QC tab and next to a Main-Plot selection) support several linkage methods (complete, ward.D2, single, average, mcquitty, median, centroid) and distance methods (cor, euclidean, maximum, manhattan, canberra, minkowski). The Scale Option panel controls centering, scaling, `log2`, and a pseudo-count. See the online guide for details.

# Bookmarking, export & reproducibility

The Bookmark button captures the entire analysis state behind a stable URL you can revisit or share. The Export menu turns your interactive session into reusable artifacts: an R script, R Markdown / HTML, a Jupyter notebook, or a copy-ready methods paragraph for a manuscript.

# AI interpretation (optional)

DEBrowser includes an optional AI assistant that summarizes the biology of a gene set alongside a selected GSEA pathway on the Enrichment tab. It is off by default — no network calls happen until you enable it and configure a provider (Anthropic, OpenAI, or local Ollama). Per-call privacy modes control what leaves your machine; API keys are stored encrypted in your OS keychain via `keyring`, never in plaintext. Install the extras once:

    install.packages(c("ellmer", "whisker", "keyring"))

If any are missing, AI stays unavailable and the rest of the app is unaffected. `R CMD check` and `BiocCheck` both pass without any AI package installed. For provider setup (including a local, privacy-preserving Ollama install), see the online guide.

# Operating system dependencies

On Fedora / Red Hat / CentOS:

    openssl-devel libxml2-devel libcurl-devel libpng-devel

On Ubuntu / Debian:

    sudo apt-get install libcurl4-openssl-dev libssl-dev \
      libxml2-dev libudunits2-dev

# Session information

    #> R version 4.6.1 (2026-06-24)
    #> Platform: x86_64-pc-linux-gnu
    #> Running under: Ubuntu 26.04 LTS
    #>
    #> Matrix products: default
    #> BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
    #> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.32.so;  LAPACK version 3.12.0
    #>
    #> locale:
    #>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C
    #>  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8
    #>  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8
    #>  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C
    #>  [9] LC_ADDRESS=C               LC_TELEPHONE=C
    #> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
    #>
    #> time zone: Etc/UTC
    #> tzcode source: system (glibc)
    #>
    #> attached base packages:
    #> [1] stats     graphics  grDevices utils     datasets  methods   base
    #>
    #> other attached packages:
    #> [1] debrowser_1.41.2 rmarkdown_2.31
    #>
    #> loaded via a namespace (and not attached):
    #>   [1] splines_4.6.1               later_1.4.8
    #>   [3] bitops_1.0-9                ggplotify_0.1.3
    #>   [5] tibble_3.3.1                polyclip_1.10-7
    #>   [7] enrichit_0.2.0              XML_3.99-0.23
    #>   [9] lifecycle_1.0.5             httr2_1.3.0
    #>  [11] edgeR_4.11.4                processx_3.9.0
    #>  [13] lattice_0.22-9              MASS_7.3-66
    #>  [15] dendextend_1.19.1           magrittr_2.0.5
    #>  [17] limma_3.69.2                plotly_4.12.1
    #>  [19] sass_0.4.10                 jquerylib_0.1.4
    #>  [21] yaml_2.3.12                 shinyBS_0.65.0
    #>  [23] httpuv_1.6.17               otel_0.2.0
    #>  [25] ggtangle_0.1.2              DBI_1.3.0
    #>  [27] buildtools_1.0.0            RColorBrewer_1.1-3
    #>  [29] abind_1.4-8                 GenomicRanges_1.65.1
    #>  [31] purrr_1.2.2                 BiocGenerics_0.59.10
    #>  [33] RCurl_1.98-1.19             yulab.utils_0.2.4
    #>  [35] tweenr_2.0.3                rappdirs_0.3.4
    #>  [37] sva_3.61.0                  aisdk_1.4.12
    #>  [39] gdtools_0.5.1               seriation_1.5.8
    #>  [41] IRanges_2.47.2              S4Vectors_0.51.5
    #>  [43] enrichplot_1.33.0           ggrepel_0.9.8
    #>  [45] tidytree_0.4.8              maketools_1.3.2
    #>  [47] genefilter_1.95.0           annotate_1.91.0
    #>  [49] codetools_0.2-20            DelayedArray_0.39.3
    #>  [51] DOSE_4.7.2                  DT_0.34.0
    #>  [53] ggforce_0.5.0               tidyselect_1.2.1
    #>  [55] aplot_0.3.1                 farver_2.1.2
    #>  [57] viridis_0.6.5               TSP_1.2.7
    #>  [59] matrixStats_1.5.0           stats4_4.6.1
    #>  [61] Seqinfo_1.3.0               webshot_0.5.5
    #>  [63] jsonlite_2.0.0              survival_3.8-9
    #>  [65] iterators_1.0.14            systemfonts_1.3.2
    #>  [67] foreach_1.5.2               tools_4.6.1
    #>  [69] ggnewscale_0.5.2            treeio_1.37.0
    #>  [71] Rcpp_1.1.2                  glue_1.8.1
    #>  [73] gridExtra_2.3.1             SparseArray_1.13.2
    #>  [75] BiocBaseUtils_1.15.1        mgcv_1.9-4
    #>  [77] xfun_0.60                   DESeq2_1.53.2
    #>  [79] qvalue_2.45.0               MatrixGenerics_1.25.0
    #>  [81] dplyr_1.2.1                 ca_0.71.1
    #>  [83] withr_3.0.3                 fastmap_1.2.0
    #>  [85] shinyjs_2.1.1               caTools_1.18.4
    #>  [87] callr_3.8.0                 digest_0.6.39
    #>  [89] R6_2.6.1                    mime_0.13
    #>  [91] gridGraphics_0.5-1          GO.db_3.23.1
    #>  [93] gtools_3.9.5                RSQLite_3.53.3
    #>  [95] tidyr_1.3.2                 generics_0.1.4
    #>  [97] fontLiberation_0.1.0        data.table_1.18.4
    #>  [99] httr_1.4.8                  htmlwidgets_1.6.4
    #> [101] S4Arrays_1.13.0             scatterpie_0.2.6
    #> [103] pkgconfig_2.0.3             gtable_0.3.6
    #> [105] blob_1.3.0                  registry_0.5-1
    #> [107] S7_0.2.2                    XVector_0.53.0
    #> [109] sys_3.4.3                   clusterProfiler_4.21.0
    #> [111] htmltools_0.5.9             fontBitstreamVera_0.1.1
    #> [113] scales_1.4.0                Biobase_2.73.1
    #> [115] png_0.1-9                   ggfun_0.2.1
    #> [117] knitr_1.51                  reshape2_1.4.5
    #> [119] nlme_3.1-170                org.Hs.eg.db_3.23.1
    #> [121] cachem_1.1.0                stringr_1.6.0
    #> [123] KernSmooth_2.23-26          parallel_4.6.1
    #> [125] miniUI_0.1.2                AnnotationDbi_1.75.2
    #> [127] pillar_1.11.1               grid_4.6.1
    #> [129] vctrs_0.7.3                 gplots_3.3.0
    #> [131] promises_1.5.0              tidydr_0.0.6
    #> [133] cluster_2.1.8.2             xtable_1.8-8
    #> [135] evaluate_1.0.5              cli_3.6.6
    #> [137] locfit_1.5-9.12             compiler_4.6.1
    #> [139] rlang_1.3.0                 crayon_1.5.3
    #> [141] heatmaply_1.6.0             ps_1.9.3
    #> [143] plyr_1.8.9                  fs_2.1.0
    #> [145] ggiraph_0.9.6               stringi_1.8.7
    #> [147] viridisLite_0.4.3           BiocParallel_1.47.0
    #> [149] assertthat_0.2.1            Biostrings_2.81.5
    #> [151] lazyeval_0.2.3              colourpicker_1.3.0
    #> [153] GOSemSim_2.39.2             fontquiver_0.2.1
    #> [155] Matrix_1.7-6                patchwork_1.3.2
    #> [157] bit64_4.8.2                 ggplot2_4.0.3
    #> [159] statmod_1.5.2               KEGGREST_1.53.6
    #> [161] shiny_1.14.0                SummarizedExperiment_1.43.0
    #> [163] igraph_2.3.3                memoise_2.0.1
    #> [165] bslib_0.11.0                ggtree_4.3.0
    #> [167] bit_4.6.0                   gson_0.2.0
    #> [169] ape_5.8-1

# References

1. Love M.I. et al. (2014) Moderated estimation of fold change and dispersion for RNA-seq data with DESeq2. Genome Biol. 15, 550.
2. Robinson M.D. et al. (2010) edgeR: a Bioconductor package for differential expression analysis of digital gene expression data. Bioinformatics 26, 139–140.
3. Ritchie M.E. et al. (2015) limma powers differential expression analyses for RNA-sequencing and microarray studies. Nucleic Acids Res. 43, e47.
4. Vernia S. et al. (2014) The PPARα-FGF21 hormone axis contributes to metabolic regulation by the hepatic JNK signaling pathway. Cell Metab. 20, 512–525.