Development version from github

The development version is available in github.

## Dependencies
install.packages("htmlwidgets")
## Install from github
devtools::install_github("patzaw/bscui")

Vignette requirements

The following packages are not dependencies of ‘bscui’ strictly speaking but are required to run code examples discussed in this document.

library(bscui)
library(xml2)
library(dplyr)
library(readr)
library(stringr)
library(glue)
library(scales)
library(reactable)
library(reactable.extras)

Display session info

sessionInfo()

## R version 4.4.1 (2024-06-14)
## Platform: x86_64-pc-linux-gnu
## Running under: Ubuntu 24.04.1 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.26.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=C              
##  [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] scales_1.3.0   glue_1.8.0     stringr_1.5.1  readr_2.1.5    dplyr_1.1.4   
## [6] xml2_1.3.6     bscui_0.1.5    knitr_1.48     rmarkdown_2.28
## 
## loaded via a namespace (and not attached):
##  [1] jsonlite_1.8.9    compiler_4.4.1    tidyselect_1.2.1  jquerylib_0.1.4  
##  [5] yaml_2.3.10       fastmap_1.2.0     R6_2.5.1          generics_0.1.3   
##  [9] htmlwidgets_1.6.4 tibble_3.2.1      maketools_1.3.1   munsell_0.5.1    
## [13] bslib_0.8.0       pillar_1.9.0      tzdb_0.4.0        rlang_1.1.4      
## [17] utf8_1.2.4        cachem_1.1.0      stringi_1.8.4     xfun_0.49        
## [21] sass_0.4.9        sys_3.4.3         cli_3.6.3         magrittr_2.0.3   
## [25] digest_0.6.37     hms_1.1.3         lifecycle_1.0.4   vctrs_0.6.5      
## [29] evaluate_1.0.1    buildtools_1.0.0  colorspace_2.1-1  fansi_1.0.6      
## [33] tools_4.4.1       pkgconfig_2.0.3   htmltools_0.5.8.1

• xml2 is used to read SVG files
• readr and dplyr are used to read and manipulate tables with figure contextual information
• stringr and glue are used to facilitate the creation of html tags
• scales is used to generate color scales
• reactable and reactable.extras are used to manipulate information in a table displayed in the Shiny example

Simple example: Animal cells

This example relies on a figure of animal cells taken from SwissBioPics.

svg <- xml2::read_xml(system.file(
   "examples", "Animal_cells.svg.gz",
   package="bscui"
))

The simplest way to display the figure is shown below.

figure <- bscui(svg)
figure

The figure can be grabbed with mouse and enlarged or shrunk using the mouse wheel. Clicking on the button at the top-left corner of the figure displays a menu with various functions, including resetting the view and exporting the figure in SVG or PNG format. Several configuration choices are made by default but can be changed, such as the zoom range or the width of the menu.

info <- readr::read_tsv(system.file(
   "examples", "uniprot_cellular_locations.txt.gz",
   package="bscui"
), col_types=strrep("c", 6)) |> 
   mutate(id = str_remove(`Subcellular location ID`, "-"))

ui_elements <- info |> 
   mutate(
      ui_type = "selectable",
      title = glue(
         '<div style="width:300px; height:100px; overflow:auto; padding:5px;',
         'font-size:75%;',
         'border:black 1px solid; background:#FFFFF0AA;">',
         "<strong>{Name}</strong>: {Description}",
         "</div>",
         .sep=" "
      )
   ) |>
   select(id, ui_type, title)
ui_elements

## # A tibble: 563 × 3
##    id     ui_type    title                                                      
##    <chr>  <chr>      <glue>                                                     
##  1 SL0002 selectable <div style="width:300px; height:100px; overflow:auto; padd…
##  2 SL0003 selectable <div style="width:300px; height:100px; overflow:auto; padd…
##  3 SL0004 selectable <div style="width:300px; height:100px; overflow:auto; padd…
##  4 SL0005 selectable <div style="width:300px; height:100px; overflow:auto; padd…
##  5 SL0006 selectable <div style="width:300px; height:100px; overflow:auto; padd…
##  6 SL0007 selectable <div style="width:300px; height:100px; overflow:auto; padd…
##  7 SL0008 selectable <div style="width:300px; height:100px; overflow:auto; padd…
##  8 SL0009 selectable <div style="width:300px; height:100px; overflow:auto; padd…
##  9 SL0010 selectable <div style="width:300px; height:100px; overflow:auto; padd…
## 10 SL0011 selectable <div style="width:300px; height:100px; overflow:auto; padd…
## # ℹ 553 more rows

figure <- figure |> 
   set_bscui_ui_elements(ui_elements)
figure

figure <- figure |> 
   set_bscui_styles(
      bind_rows(
         info |>
            filter(Name == "Cytosol") |>
            mutate(fill = "#FF7F7F"),
         info |>
            filter(Name == "Nucleoplasm") |>
            mutate(fill = "#7F7FFF")
      ) |> 
         select(
            id, fill
         )
   ) |> 
   set_bscui_styles(
      info |>
         filter(Name == "Endosome") |>
         mutate(stroke = "yellow", strokeWidth = "2px") |> 
         select(id, stroke, strokeWidth)
   )
figure

nucleus_part <- c(
   "SL0191", "SL0190", "SL0182", "SL0188", "SL0494", "SL0180",
   "SL0031", "SL0465", "SL0127", "SL0186"
)
figure <- figure |>
   set_bscui_attributes(
      info |>
         filter(
            !id %in% nucleus_part
         ) |>
         mutate(display="none") |>
         select(id, display)
   ) |> 
   set_bscui_attributes(tibble(id="sib_copyright", display="none")) |>
   set_bscui_attributes(tibble(id="SL0188", transform="scale(1.8 1.8)")) |> 
   set_bscui_attributes(
      tibble(id="SL0188", transform="translate(-237 -202)"),
      append=TRUE
   )
figure |> 
   set_bscui_options(
      show_menu=FALSE, zoom_min=1, zoom_max=1, clip=TRUE,
      hover_width=1
   )

bscui(svg) |>
   htmlwidgets::saveWidget(file = "figure.html")

bscui(svg) |>
   set_bscui_options(show_menu=FALSE) |> 
   export_bscui_to_image(file = "figure.png", zoom=6)

Sys.setenv(
    "CHROMOTE_CHROME" = "C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe"
)

Mapping data: Wikipathways

The following example demonstrates how to use ‘bscui’ to map numeric data with colors on the figure. In this example, gene expression data are used to color elements of the Principal pathways of carbon metabolism taken from WikiPathways.

svg <- xml2::read_xml(system.file(
   "examples", "WP112.svg.gz",
   package="bscui"
))
info <- read_tsv(system.file(
   "examples", "WP112.txt.gz",
   package="bscui"
), col_types="c")

Gene expression data were taken from a publication describing the effects of the provided nitrogen sources on baker’s yeast gene expression (Godard et al. 2007). The supplementary Table S1 provides a list of genes displaying significant variations in expression under at least one tested nitrogen condition compared to urea.

deg <- read_tsv(system.file(
   "examples", "DEG-by-nitrogen-source_MCB-Godard-2007.txt.gz",
   package="bscui"
), col_types=paste0(strrep("c", 3), strrep("n", 41)))

Below, we focus on the ALANINE condition and extract the M value comparing the expression of genes when this amino-acid is used as the nitrogen source instead of urea in yeast culture: $M = log_2\left(Expression\,on\,alanine \over Expression\,on\,urea\right)$

condition <- "ALANINE"
toTake <- c("ORF", paste(condition, "M"))
cond_deg <- deg |> 
   select(all_of(toTake)) |> 
   setNames(c("ensembl", "M")) |> 
   filter(!is.na(M))

We define a color scale on M values and define the style of the SVG elements accordingly.

col_scale <- col_numeric(
   "RdYlBu", domain=range(cond_deg$M), reverse=TRUE
)
styles <- cond_deg |> 
   mutate(
      fill=col_scale(M)
   ) |> 
   inner_join(select(info,id, ensembl), by="ensembl") |> 
   select(id, fill)

Finally, we create tooltips on SVG elements showing the type of biological object and the M value when available.

elements <- info |> 
   mutate(
      ui_type="selectable",
      bg = case_when(
         category == "GeneProduct" ~ "#FDFDBD",
         category == "Metabolite" ~ "#BDFDFD",
         TRUE ~ "white"
      )
   ) |> 
   left_join(cond_deg, by="ensembl") |> 
   mutate(
      de = ifelse(
         !is.na(M),
         glue("log2({condition}/UREA) = {round(M,2)}<br/>"),
         ""
      )
   ) |> 
   mutate(
      title = glue(
         '<div style="padding:5px;border:solid;background:{bg}">',
         '<strong>{name}</strong><br/>',
         '{de}',
         '<a href={href} target="_blank">{category} information</a>',
         '</div>'
      )
   ) |> 
   select(id, ui_type, title)

And we use this information to create the figure.

bscui(svg) |> 
   set_bscui_ui_elements(elements) |> 
   set_bscui_styles(styles)

Building and inserting the figure (P1)

Building the figure and inserting it in ‘shiny’ user interface is straightforward and relies on the bscuiOutput() and renderBscui() functions:

ui <- fluidPage(
   bscuiOutput("anatomogram")
)
server <- function(input, output, session){
   output$anatomogram <- renderBscui({
      bscui(svg)|>
         set_bscui_ui_elements(ui_elements)
   })
}

UI elements need to be defined with set_bscui_ui_elements() to make the figure interactive and to allow ‘shiny’ interactions.

Interactions (P2)

The following information are exposed to ‘shiny’ from the ‘bscui’ widget:

• input$bscuiID_selected reports selected elements
• input$bscuiID_operated reports operated button elements
• input$bscuiID_hovered reports hovered elements

bscuiID is used to refer to the figure output id, “anatomogram” in the example above.

Modifying the figure (P3)

Creating a “bscui_Proxy” object allows figure modification without redrawing it. It’s done by calling the bscuiProxy() within the sever function:

server <- function(input, output, session){
   output$anatomogram <- renderBscui({
      bscui(svg)|>
         set_bscui_ui_elements(ui_elements)
   })
   anatomogram_proxy <- bscuiProxy("anatomogram")
}

The following functions can then be used to modify the figure:

• order_bscui_elements() changes the display order of chosen elements
• add_bscui_element() adds an element to the figure
• remove_bscui_elements() removes chosen elements from the figure

Finally, the get_bscui_svg() function makes the updated figure SVG available via input$bscuiID_svg (input$anatomogram_svg in the example).

Updating figure elements (P4)

The example above relies on the ‘reactable’ and ‘reactable.extras’ packages to display available elements (organs) and change their properties. The following functions are applied to a “bscui_Proxy” (anatomogram_proxy in the example above).

• update_bscui_ui_elements() changes the type and the title of elements. It is used in the example above to select the type (“selectable”, “button” or “none”) of each element from the “UI” column.

• update_bscui_attributes() sets attributes of SVG elements. It is used in the example above to display or hide the different organs from the “Displayed” column.

• update_bscui_styles() sets styles of SVG elements. It is used in the example above to modify the color of the organs from the “Color” column.

• update_bscui_selection() updates the list of selected elements. In the example, it is used to select organs from the “Selection” column of the table (organs can therefore be selected either from the table or directly from the diagram).

• click_bscui_element() triggers a click on a “button” element. It is not used in the example.