Introduction to UpSet.js

Samuel Gratzl

2023-01-11

Source: vignettes/upsetjs.Rmd

UpSet.js R Widget

UpSet.js is a JavaScript re-implementation of UpSetR which itself is based on UpSet.

The core library is written in React but provides also bundle editions for plain JavaScript use and this R wrapper using HTMLWidget.

In this tutorial the basic widget functionality is explained.

Let’s begin with importing the library

# devtools::install_url("https://github.com/upsetjs/upsetjs_r/releases/latest/download/upsetjs.tar.gz")
library(upsetjs)

Basic User Interface

Note: The input data will be described in more detail in the next section

example of list input (list of named vectors, each having a list of contained elements)

listInput <- list(one = c("a", "b", "c", "e", "g", "h", "k", "l", "m"), two = c("a",
    "b", "d", "e", "j"), three = c("a", "e", "f", "g", "h", "i", "j", "l", "m"))

w <- upsetjs() %>%
    fromList(listInput) %>%
    interactiveChart()
w

An UpSet plot consists of three areas:

  • The bottom left area shows the list of sets as a vertical bar chart. The length of the bar corresponds to the cardinality of the set, i.e., the number of elements in this set.
  • The top right area shows the list of set intersections as a horizontal bar chart. Again the length corresponds to the cardinality of the set
  • The bottom right area shows which intersection consists of which sets. A dark dot indicates that the set is part of this set intersection. The line connecting the dots is just to visually group the dots.

Moving the mouse over a bar or a dot will automatically highlight the corresponding set or set intersection in orange. In addition, the number elements which are shared with the highlighted sets are also highlighted. This gives a quick overview how sets and set intersections are related to each other. More details, in the Interaction section.

Input Formats

In the current version the UpSet.js wrapper supports three input data formats: list, expression, and through a data.frame.

List Input

The first format is a list. The key of the list entry is the set name while the value is the vector of elements this set has. See also UpsetR

upsetjs() %>%
    fromList(list(one = c("a", "b", "c", "e", "g", "h", "k", "l", "m"), two = c("a",
        "b", "d", "e", "j"), three = c("a", "e", "f", "g", "h", "i", "j", "l", "m")))

Expression Input

The second version is a a variant in which not the elements are given but their cardinality. Thus, besides the sets also all the set intersections have to be defined. Moreover, this version has only limited interactivty support.

# example of expression input
expressionInput <- list(one = 9, two = 5, three = 9, `one&two` = 3, `one&three` = 6,
    `two&three` = 3, `one&two&three` = 2)


upsetjs() %>%
    fromExpression(expressionInput) %>%
    interactiveChart()

Data Frame Input

The last format is a a binary/boolean data frame. The rownames contain the list of elements. Each regular column represents a set with boolean values (e.g., 0 and 1) whether the row represented by the rowname is part of the set or not.

The following data frame defines the same set structure as the dictionary format before.

# boolean table with rows = elements, columns = sets, cell = is row part of
# this set
dataFrame <- as.data.frame(list(one = c(1, 1, 1, 0, 1, 0, 1, 1, 0, 0, 1, 1, 1), two = c(1,
    1, 0, 1, 1, 0, 0, 0, 0, 1, 0, 0, 0), three = c(1, 0, 0, 0, 1, 1, 1, 1, 1, 1,
    0, 1, 1)), row.names = c("a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k",
    "l", "m"))


upsetjs() %>%
    fromDataFrame(dataFrame)

Data Intersections

In case of an expressionInput the combinations of sets are directly given.

generateIntersections, generateDistinctIntersections, and generateUnions let you customize the generation of the set combinations

  • min … minimum number of sets in a set combination
  • max … maximum number of sets in a set combination, NULL means no limit
  • empty … include empty set combinations with no elements. By default they are not included
  • order.by … sort set combinations either by cardinality (number of elements) or by degree (number of sets
  • limit … show only the first limit set combinations
upsetjs() %>%
    fromList(listInput) %>%
    generateIntersections(min = 2, max = NULL, empty = TRUE, order.by = "cardinality",
        limit = NULL)
upsetjs() %>%
    fromList(listInput) %>%
    generateUnions(min = 0, max = 2, empty = TRUE, order.by = "degree", limit = NULL)

Interaction

Interactivity

by setting the interactiveFlag flag, the user can interactively highlight sets within the chart.

Selection

with setSelection one manually sets the selection that is currently highlighted. The set is referenced by its name, a vector with multiple names is detected as an intersection name

upsetjs() %>%
    fromList(listInput) %>%
    setSelection("one")
upsetjs() %>%
    fromList(listInput) %>%
    setSelection(c("one", "two"))

In case UpSet.js will be used in a R Shiny context, it reports the current selection based using two custom events:

  • <outputid>_hover when the user hovers over an item
  • <outputid>_click when the user clicks on an item
  • <outputid>_contextMenu when the user right clicks on an item

both events are list objects with a name attribute that is either NULL or the name of the set. In addition, there is an elems attribute which contains the list of highlighted elements.

See also Shiny examples at events.R

Queries

besides the selection UpSet.js supports defining queries. A query can be a list of elements or a set that should be highlighted. A query consists of a name, a color, and either the list of elements or the set (combination) to highlight.

upsetjs() %>%
    fromList(listInput) %>%
    addQuery("Q1", color = "red", elems = c("a", "b", "c")) %>%
    addQuery("Q2", color = "blue", set = "two")

Attributes

UpSet.js supports rendering boxplots as aggregations for numerical attributes of elements and mosaic plots for categorical attributes. The are given as part of the data frame. The attributes element has to be a list or a data frame.

dataFrame <- as.data.frame(list(one = c(1, 1, 1, 0, 1, 0, 1, 1, 0, 0, 1, 1, 1), two = c(1,
    1, 0, 1, 1, 0, 0, 0, 0, 1, 0, 0, 0), three = c(1, 0, 0, 0, 1, 1, 1, 1, 1, 1,
    0, 1, 1)), row.names = c("a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k",
    "l", "m"))

upsetjs() %>%
    fromDataFrame(dataFrame, attributes = list(attr = runif(nrow(dataFrame))))

Styling

Theme

UpSet.js supports thre themes: light, dark, and vega. The theme can be set by the chartTheme function

upsetjs() %>%
    fromList(listInput) %>%
    chartTheme("dark")

Title 

upsetjs() %>%
    fromList(listInput) %>%
    chartLabels(title = "Chart Title", description = "this is a long chart description")

Labels 

upsetjs() %>%
    fromList(listInput) %>%
    chartLabels(combination.name = "Combination Label", set.name = "Set Label")

Log Scale

setting chartLayout(numerical.scale = 'log') switches to a log scale, similarly 'linear' goes back to a linear scale

upsetjs() %>%
    fromList(listInput) %>%
    chartLayout(numerical.scale = "log")