Using annotations to facilitate interactive exploration
4 June 2025
Package
iSEEde 1.7.0
1 Example data
In this example, we use the ?airway data set.
library("airway")
data("airway")2 Annotating data
This section demonstrates one of many possible workflows for adding annotations to the data set. Those annotations are meant to make it easier for users to identify genes of interest, e.g. by displaying both gene symbols and ENSEMBL gene identifiers as tooltips in the interactive browser.
First, we make a copy of the Ensembl identifiers – currently stored in the
rownames() – to a column in the rowData() component.
rowData(airway)[["ENSEMBL"]] <- rownames(airway)Then, we use the org.Hs.eg.db package to map the
Ensembl identifiers to gene symbols. We store those gene symbols as an
additional column of the rowData() component.
library("org.Hs.eg.db")
rowData(airway)[["SYMBOL"]] <- mapIds(
org.Hs.eg.db, rownames(airway),
"SYMBOL", "ENSEMBL"
)Next, we use the uniquifyFeatureNames() function of the
scuttle package to replace the rownames() by a
unique identifier that is generated as follows:
- The gene symbol if it is unique.
- A concatenate of the gene symbol and Ensembl gene identifier if the gene symbol is not unique.
- The Ensembl identifier if the gene symbol is not available.
library("scuttle")
rownames(airway) <- uniquifyFeatureNames(
ID = rowData(airway)[["ENSEMBL"]],
names = rowData(airway)[["SYMBOL"]]
)
airway
#> class: RangedSummarizedExperiment
#> dim: 63677 8
#> metadata(1): ''
#> assays(1): counts
#> rownames(63677): TSPAN6 TNMD ... APP-DT ENSG00000273493
#> rowData names(12): gene_id gene_name ... ENSEMBL SYMBOL
#> colnames(8): SRR1039508 SRR1039509 ... SRR1039520 SRR1039521
#> colData names(9): SampleName cell ... Sample BioSample3 Differential expression
To generate some example results, we first use edgeR::filterByExpr() to remove
genes whose counts are too low to support a rigorous differential expression
analysis. Then we run a standard Limma-Voom analysis using edgeR::voomLmFit(),
limma::makeContrasts(), and limma::eBayes(); alternatively, we could have
used limma::treat() instead of limma::eBayes().
The linear model includes the dex and cell covariates, indicating the
treatment conditions and cell types, respectively. Here, we are interested in
differences between treatments, adjusted by cell type, and define this
comparison as the dextrt - dexuntrt contrast.
The final differential expression results are fetched using limma::topTable().
library("edgeR")
design <- model.matrix(~ 0 + dex + cell, data = colData(airway))
keep <- filterByExpr(airway, design)
fit <- voomLmFit(airway[keep, ], design, plot = FALSE)
contr <- makeContrasts("dextrt - dexuntrt", levels = design)
fit <- contrasts.fit(fit, contr)
fit <- eBayes(fit)
res_limma <- topTable(fit, sort.by = "P", n = Inf)
head(res_limma)
#> gene_id gene_name entrezid gene_biotype gene_seq_start gene_seq_end seq_name
#> CACNB2 ENSG00000165995 CACNB2 NA protein_coding 18429606 18830798 10
#> DUSP1 ENSG00000120129 DUSP1 NA protein_coding 172195093 172198198 5
#> PRSS35 ENSG00000146250 PRSS35 NA protein_coding 84222194 84235423 6
#> MAOA ENSG00000189221 MAOA NA protein_coding 43515467 43606068 X
#> STEAP2 ENSG00000157214 STEAP2 NA protein_coding 89796904 89867451 7
#> SPARCL1 ENSG00000152583 SPARCL1 NA protein_coding 88394487 88452213 4
#> seq_strand seq_coord_system symbol ENSEMBL SYMBOL logFC AveExpr t
#> CACNB2 1 NA CACNB2 ENSG00000165995 CACNB2 3.205606 3.682244 37.68303
#> DUSP1 -1 NA DUSP1 ENSG00000120129 DUSP1 2.864778 6.644455 28.50569
#> PRSS35 1 NA PRSS35 ENSG00000146250 PRSS35 -2.828184 3.224885 -28.10830
#> MAOA 1 NA MAOA ENSG00000189221 MAOA 3.256085 5.950559 27.66135
#> STEAP2 1 NA STEAP2 ENSG00000157214 STEAP2 1.894559 6.790009 27.40834
#> SPARCL1 -1 NA SPARCL1 ENSG00000152583 SPARCL1 4.489009 4.166904 27.34820
#> P.Value adj.P.Val B
#> CACNB2 1.115938e-10 1.881472e-06 14.45518
#> DUSP1 1.148539e-09 4.309046e-06 13.01074
#> PRSS35 1.291089e-09 4.309046e-06 12.44376
#> MAOA 1.475547e-09 4.309046e-06 12.75540
#> STEAP2 1.592916e-09 4.309046e-06 12.71210
#> SPARCL1 1.622327e-09 4.309046e-06 12.33402Then, we embed this set of differential expression results in the airway
object using the embedContrastResults() method and we use the function contrastResults() to display the contrast results stored in the airway object.
library(iSEEde)
#> Loading required package: iSEE
airway <- embedContrastResults(res_limma, airway,
name = "dextrt - dexuntrt",
class = "limma"
)
contrastResults(airway)
#> DataFrame with 63677 rows and 1 column
#> dextrt - dexuntrt
#> <iSEELimmaResults>
#> TSPAN6 <iSEELimmaResults>
#> TNMD <iSEELimmaResults>
#> DPM1 <iSEELimmaResults>
#> SCYL3 <iSEELimmaResults>
#> FIRRM <iSEELimmaResults>
#> ... ...
#> ENSG00000273489 <iSEELimmaResults>
#> ENSG00000273490 <iSEELimmaResults>
#> ENSG00000273491 <iSEELimmaResults>
#> APP-DT <iSEELimmaResults>
#> ENSG00000273493 <iSEELimmaResults>
contrastResults(airway, "dextrt - dexuntrt")
#> iSEELimmaResults with 63677 rows and 18 columns
#> gene_id gene_name entrezid gene_biotype gene_seq_start gene_seq_end
#> <character> <character> <integer> <character> <integer> <integer>
#> TSPAN6 ENSG00000000003 TSPAN6 NA protein_coding 99883667 99894988
#> TNMD NA NA NA NA NA NA
#> DPM1 ENSG00000000419 DPM1 NA protein_coding 49551404 49575092
#> SCYL3 ENSG00000000457 SCYL3 NA protein_coding 169818772 169863408
#> FIRRM ENSG00000000460 C1orf112 NA protein_coding 169631245 169823221
#> ... ... ... ... ... ... ...
#> ENSG00000273489 NA NA NA NA NA NA
#> ENSG00000273490 NA NA NA NA NA NA
#> ENSG00000273491 NA NA NA NA NA NA
#> APP-DT NA NA NA NA NA NA
#> ENSG00000273493 NA NA NA NA NA NA
#> seq_name seq_strand seq_coord_system symbol ENSEMBL SYMBOL
#> <character> <integer> <integer> <character> <character> <character>
#> TSPAN6 X -1 NA TSPAN6 ENSG00000000003 TSPAN6
#> TNMD NA NA NA NA NA NA
#> DPM1 20 -1 NA DPM1 ENSG00000000419 DPM1
#> SCYL3 1 -1 NA SCYL3 ENSG00000000457 SCYL3
#> FIRRM 1 1 NA C1orf112 ENSG00000000460 FIRRM
#> ... ... ... ... ... ... ...
#> ENSG00000273489 NA NA NA NA NA NA
#> ENSG00000273490 NA NA NA NA NA NA
#> ENSG00000273491 NA NA NA NA NA NA
#> APP-DT NA NA NA NA NA NA
#> ENSG00000273493 NA NA NA NA NA NA
#> logFC AveExpr t P.Value adj.P.Val B
#> <numeric> <numeric> <numeric> <numeric> <numeric> <numeric>
#> TSPAN6 -0.464216 5.02559 -6.589673 0.000136603 0.00171857 0.899306
#> TNMD NA NA NA NA NA NA
#> DPM1 0.125077 4.60191 1.632802 0.139297605 0.25279527 -6.274792
#> SCYL3 -0.042107 3.47269 -0.438929 0.671768770 0.77787936 -7.230811
#> FIRRM -0.228517 1.40857 -0.977961 0.355374953 0.49644090 -6.208897
#> ... ... ... ... ... ... ...
#> ENSG00000273489 NA NA NA NA NA NA
#> ENSG00000273490 NA NA NA NA NA NA
#> ENSG00000273491 NA NA NA NA NA NA
#> APP-DT NA NA NA NA NA NA
#> ENSG00000273493 NA NA NA NA NA NA4 Live app
In this example, we use iSEE::panelDefaults() to specify rowData() fields to
show in the tooltip that is displayed when hovering a data point.
The application is then configured to display the volcano plot and MA plot for the same contrast.
Finally, the configured app is launched.
library(iSEE)
panelDefaults(
TooltipRowData = c("SYMBOL", "ENSEMBL")
)
app <- iSEE(airway, initial = list(
VolcanoPlot(ContrastName = "dextrt - dexuntrt", PanelWidth = 6L),
MAPlot(ContrastName = "dextrt - dexuntrt", PanelWidth = 6L)
))
if (interactive()) {
shiny::runApp(app)
}
5 Reproducibility
The iSEEde package (Rue-Albrecht, 2025) was made possible thanks to:
- R (R Core Team, 2025)
- BiocStyle (Oleś, 2025)
- knitr (Xie, 2025)
- RefManageR (McLean, 2017)
- rmarkdown (Allaire, Xie, Dervieux, McPherson, Luraschi, Ushey, Atkins, Wickham, Cheng, Chang, and Iannone, 2024)
- sessioninfo (Wickham, Chang, Flight, Müller, and Hester, 2025)
- testthat (Wickham, 2011)
This package was developed using biocthis.
Code for creating the vignette
## Create the vignette
library("rmarkdown")
system.time(render("annotations.Rmd", "BiocStyle::html_document"))
## Extract the R code
library("knitr")
knit("annotations.Rmd", tangle = TRUE)Date the vignette was generated.
#> [1] "2025-06-04 19:50:40 EDT"Wallclock time spent generating the vignette.
#> Time difference of 31.346 secsR session information.
#> ─ Session info ───────────────────────────────────────────────────────────────────────────────────────────────────────
#> setting value
#> version R version 4.5.0 (2025-04-11 ucrt)
#> os Windows Server 2022 x64 (build 20348)
#> system x86_64, mingw32
#> ui RTerm
#> language (EN)
#> collate C
#> ctype English_United States.utf8
#> tz America/New_York
#> date 2025-06-04
#> pandoc 2.7.3 @ C:/PROGRA~1/Pandoc/ (via rmarkdown)
#> quarto NA
#>
#> ─ Packages ───────────────────────────────────────────────────────────────────────────────────────────────────────────
#> package * version date (UTC) lib source
#> abind 1.4-8 2024-09-12 [2] CRAN (R 4.5.0)
#> airway * 1.29.0 2025-04-17 [2] Bioconductor 3.22 (R 4.5.0)
#> AnnotationDbi * 1.71.0 2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
#> backports 1.5.0 2024-05-23 [2] CRAN (R 4.5.0)
#> beachmat 2.25.1 2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
#> bibtex 0.5.1 2023-01-26 [2] CRAN (R 4.5.0)
#> Biobase * 2.69.0 2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
#> BiocGenerics * 0.55.0 2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
#> BiocManager 1.30.25 2024-08-28 [2] CRAN (R 4.5.0)
#> BiocParallel 1.43.3 2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
#> BiocStyle * 2.37.0 2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
#> Biostrings 2.77.1 2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
#> bit 4.6.0 2025-03-06 [2] CRAN (R 4.5.0)
#> bit64 4.6.0-1 2025-01-16 [2] CRAN (R 4.5.0)
#> blob 1.2.4 2023-03-17 [2] CRAN (R 4.5.0)
#> bookdown 0.43 2025-04-15 [2] CRAN (R 4.5.0)
#> bslib 0.9.0 2025-01-30 [2] CRAN (R 4.5.0)
#> cachem 1.1.0 2024-05-16 [2] CRAN (R 4.5.0)
#> circlize 0.4.16 2024-02-20 [2] CRAN (R 4.5.0)
#> cli 3.6.5 2025-04-23 [2] CRAN (R 4.5.0)
#> clue 0.3-66 2024-11-13 [2] CRAN (R 4.5.0)
#> cluster 2.1.8.1 2025-03-12 [2] CRAN (R 4.5.0)
#> codetools 0.2-20 2024-03-31 [2] CRAN (R 4.5.0)
#> colorspace 2.1-1 2024-07-26 [2] CRAN (R 4.5.0)
#> colourpicker 1.3.0 2023-08-21 [2] CRAN (R 4.5.0)
#> ComplexHeatmap 2.25.0 2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
#> crayon 1.5.3 2024-06-20 [2] CRAN (R 4.5.0)
#> DBI 1.2.3 2024-06-02 [2] CRAN (R 4.5.0)
#> DelayedArray 0.35.1 2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
#> DESeq2 1.49.1 2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
#> dichromat 2.0-0.1 2022-05-02 [2] CRAN (R 4.5.0)
#> digest 0.6.37 2024-08-19 [2] CRAN (R 4.5.0)
#> doParallel 1.0.17 2022-02-07 [2] CRAN (R 4.5.0)
#> dplyr 1.1.4 2023-11-17 [2] CRAN (R 4.5.0)
#> DT 0.33 2024-04-04 [2] CRAN (R 4.5.0)
#> edgeR * 4.7.2 2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
#> evaluate 1.0.3 2025-01-10 [2] CRAN (R 4.5.0)
#> farver 2.1.2 2024-05-13 [2] CRAN (R 4.5.0)
#> fastmap 1.2.0 2024-05-15 [2] CRAN (R 4.5.0)
#> fontawesome 0.5.3 2024-11-16 [2] CRAN (R 4.5.0)
#> foreach 1.5.2 2022-02-02 [2] CRAN (R 4.5.0)
#> generics * 0.1.4 2025-05-09 [2] CRAN (R 4.5.0)
#> GenomeInfoDb * 1.45.4 2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
#> GenomicRanges * 1.61.0 2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
#> GetoptLong 1.0.5 2020-12-15 [2] CRAN (R 4.5.0)
#> ggplot2 3.5.2 2025-04-09 [2] CRAN (R 4.5.0)
#> ggrepel 0.9.6 2024-09-07 [2] CRAN (R 4.5.0)
#> GlobalOptions 0.1.2 2020-06-10 [2] CRAN (R 4.5.0)
#> glue 1.8.0 2024-09-30 [2] CRAN (R 4.5.0)
#> gtable 0.3.6 2024-10-25 [2] CRAN (R 4.5.0)
#> htmltools 0.5.8.1 2024-04-04 [2] CRAN (R 4.5.0)
#> htmlwidgets 1.6.4 2023-12-06 [2] CRAN (R 4.5.0)
#> httpuv 1.6.16 2025-04-16 [2] CRAN (R 4.5.0)
#> httr 1.4.7 2023-08-15 [2] CRAN (R 4.5.0)
#> igraph 2.1.4 2025-01-23 [2] CRAN (R 4.5.0)
#> IRanges * 2.43.0 2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
#> iSEE * 2.21.1 2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
#> iSEEde * 1.7.0 2025-06-04 [1] Bioconductor 3.22 (R 4.5.0)
#> iterators 1.0.14 2022-02-05 [2] CRAN (R 4.5.0)
#> jquerylib 0.1.4 2021-04-26 [2] CRAN (R 4.5.0)
#> jsonlite 2.0.0 2025-03-27 [2] CRAN (R 4.5.0)
#> KEGGREST 1.49.0 2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
#> knitr 1.50 2025-03-16 [2] CRAN (R 4.5.0)
#> later 1.4.2 2025-04-08 [2] CRAN (R 4.5.0)
#> lattice 0.22-7 2025-04-02 [2] CRAN (R 4.5.0)
#> lifecycle 1.0.4 2023-11-07 [2] CRAN (R 4.5.0)
#> limma * 3.65.1 2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
#> listviewer 4.0.0 2023-09-30 [2] CRAN (R 4.5.0)
#> locfit 1.5-9.12 2025-03-05 [2] CRAN (R 4.5.0)
#> lubridate 1.9.4 2024-12-08 [2] CRAN (R 4.5.0)
#> magrittr 2.0.3 2022-03-30 [2] CRAN (R 4.5.0)
#> Matrix 1.7-3 2025-03-11 [2] CRAN (R 4.5.0)
#> MatrixGenerics * 1.21.0 2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
#> matrixStats * 1.5.0 2025-01-07 [2] CRAN (R 4.5.0)
#> memoise 2.0.1 2021-11-26 [2] CRAN (R 4.5.0)
#> mgcv 1.9-3 2025-04-04 [2] CRAN (R 4.5.0)
#> mime 0.13 2025-03-17 [2] CRAN (R 4.5.0)
#> miniUI 0.1.2 2025-04-17 [2] CRAN (R 4.5.0)
#> nlme 3.1-168 2025-03-31 [2] CRAN (R 4.5.0)
#> org.Hs.eg.db * 3.21.0 2025-04-18 [2] Bioconductor
#> pillar 1.10.2 2025-04-05 [2] CRAN (R 4.5.0)
#> pkgconfig 2.0.3 2019-09-22 [2] CRAN (R 4.5.0)
#> plyr 1.8.9 2023-10-02 [2] CRAN (R 4.5.0)
#> png 0.1-8 2022-11-29 [2] CRAN (R 4.5.0)
#> promises 1.3.3 2025-05-29 [2] CRAN (R 4.5.0)
#> R6 2.6.1 2025-02-15 [2] CRAN (R 4.5.0)
#> RColorBrewer 1.1-3 2022-04-03 [2] CRAN (R 4.5.0)
#> Rcpp 1.0.14 2025-01-12 [2] CRAN (R 4.5.0)
#> RefManageR * 1.4.0 2022-09-30 [2] CRAN (R 4.5.0)
#> rintrojs 0.3.4 2024-01-11 [2] CRAN (R 4.5.0)
#> rjson 0.2.23 2024-09-16 [2] CRAN (R 4.5.0)
#> rlang 1.1.6 2025-04-11 [2] CRAN (R 4.5.0)
#> rmarkdown 2.29 2024-11-04 [2] CRAN (R 4.5.0)
#> RSQLite 2.4.0 2025-05-31 [2] CRAN (R 4.5.0)
#> S4Arrays 1.9.1 2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
#> S4Vectors * 0.47.0 2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
#> sass 0.4.10 2025-04-11 [2] CRAN (R 4.5.0)
#> scales 1.4.0 2025-04-24 [2] CRAN (R 4.5.0)
#> scuttle * 1.19.0 2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
#> sessioninfo * 1.2.3 2025-02-05 [2] CRAN (R 4.5.0)
#> shape 1.4.6.1 2024-02-23 [2] CRAN (R 4.5.0)
#> shiny 1.10.0 2024-12-14 [2] CRAN (R 4.5.0)
#> shinyAce 0.4.4 2025-02-03 [2] CRAN (R 4.5.0)
#> shinydashboard 0.7.3 2025-04-21 [2] CRAN (R 4.5.0)
#> shinyjs 2.1.0 2021-12-23 [2] CRAN (R 4.5.0)
#> shinyWidgets 0.9.0 2025-02-21 [2] CRAN (R 4.5.0)
#> SingleCellExperiment * 1.31.0 2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
#> SparseArray 1.9.0 2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
#> statmod 1.5.0 2023-01-06 [2] CRAN (R 4.5.0)
#> stringi 1.8.7 2025-03-27 [2] CRAN (R 4.5.0)
#> stringr 1.5.1 2023-11-14 [2] CRAN (R 4.5.0)
#> SummarizedExperiment * 1.39.0 2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
#> tibble 3.2.1 2023-03-20 [2] CRAN (R 4.5.0)
#> tidyselect 1.2.1 2024-03-11 [2] CRAN (R 4.5.0)
#> timechange 0.3.0 2024-01-18 [2] CRAN (R 4.5.0)
#> UCSC.utils 1.5.0 2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
#> vctrs 0.6.5 2023-12-01 [2] CRAN (R 4.5.0)
#> vipor 0.4.7 2023-12-18 [2] CRAN (R 4.5.0)
#> viridisLite 0.4.2 2023-05-02 [2] CRAN (R 4.5.0)
#> xfun 0.52 2025-04-02 [2] CRAN (R 4.5.0)
#> xml2 1.3.8 2025-03-14 [2] CRAN (R 4.5.0)
#> xtable 1.8-4 2019-04-21 [2] CRAN (R 4.5.0)
#> XVector 0.49.0 2025-06-04 [2] Bioconductor 3.22 (R 4.5.0)
#> yaml 2.3.10 2024-07-26 [2] CRAN (R 4.5.0)
#>
#> [1] F:/biocbuild/bbs-3.22-bioc/tmpdir/RtmpQnMOhw/Rinst459850025f90
#> [2] F:/biocbuild/bbs-3.22-bioc/R/library
#> * ── Packages attached to the search path.
#>
#> ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────6 Bibliography
This vignette was generated using BiocStyle (Oleś, 2025) with knitr (Xie, 2025) and rmarkdown (Allaire, Xie, Dervieux et al., 2024) running behind the scenes.
Citations made with RefManageR (McLean, 2017).
[1] J. Allaire, Y. Xie, C. Dervieux, et al. rmarkdown: Dynamic Documents for R. R package version 2.29. 2024. URL: https://github.com/rstudio/rmarkdown.
[2] M. W. McLean. “RefManageR: Import and Manage BibTeX and BibLaTeX References in R”. In: The Journal of Open Source Software (2017). DOI: 10.21105/joss.00338.
[3] A. Oleś. BiocStyle: Standard styles for vignettes and other Bioconductor documents. R package version 2.37.0. 2025. DOI: 10.18129/B9.bioc.BiocStyle. URL: https://bioconductor.org/packages/BiocStyle.
[4] R Core Team. R: A Language and Environment for Statistical Computing. R Foundation for Statistical Computing. Vienna, Austria, 2025. URL: https://www.R-project.org/.
[5] K. Rue-Albrecht. iSEEde: iSEE extension for panels related to differential expression analysis. R package version 1.7.0. 2025. DOI: 10.18129/B9.bioc.iSEEde. URL: https://bioconductor.org/packages/iSEEde.
[6] H. Wickham. “testthat: Get Started with Testing”. In: The R Journal 3 (2011), pp. 5–10. URL: https://journal.r-project.org/archive/2011-1/RJournal_2011-1_Wickham.pdf.
[7] H. Wickham, W. Chang, R. Flight, et al. sessioninfo: R Session Information. R package version 1.2.3. 2025. DOI: 10.32614/CRAN.package.sessioninfo. URL: https://CRAN.R-project.org/package=sessioninfo.
[8] Y. Xie. knitr: A General-Purpose Package for Dynamic Report Generation in R. R package version 1.50. 2025. URL: https://yihui.org/knitr/.