An Introduction to SimpleUpset
In SimpleUpset: Create Upset Plots

knitr::opts_chunk$set(
  collapse = TRUE, message = FALSE, warning = FALSE,
  fig.width = 10, fig.height = 8,
  comment = "#>"
)

library(tidyverse)
library(SimpleUpset)
library(pander)
theme_set(theme_bw())

The package SimpleUpset has been written to ensure that UpSet plots [@6876017] remain consistently available to the ecosystem of R users. The underlying functions are built depending heavily on the package infrastructure provided by the tidyverse [@wickham-tidy].

A modified version of the movies data will be used for this set of examples, based on the file originally provided in the package UpSetR [@Gehlenborg2019-up]. This version of the data has a reduced number of categories and also has the decade of release included.

movies <- system.file("extdata", "movies.tsv.gz", package = "SimpleUpset") %>%
  read_tsv() %>%
  mutate(
    Decade = fct_inorder(Decade) %>% fct_rev()
  )

movies %>% 
  count(Decade) %>% 
  pander(
    caption = "Summary of movies by decade",
    justify = "lr"
  )

Basic Usage

At it's most simple, the function simpleUpSet requires a data.frame with sets to include for display using the UpSet plots. The sets should be strictly 0/1 values which can be coerced to logical values, or logical values directly.

sets <- c("Action", "Comedy", "Drama", "Thriller", "Romance")
simpleUpSet(movies, sets)

The number of intersections can be controlled using the arguments n_intersect to define a maximum number plotted, or min_size to only show those greater than any given size.

Customising Plots

Each of the panels in the complete UpSet figure is referred to as being either 1. sets (the bottom left), 2. intersect (the top right panel), or 3. grid, representing the intersections matrix at the bottom right. Default layers for each panel are produced by the functions default_set_layers(), default_intersect_layers() or default_grid_layers(). The default calls to ggplot layers, scales, themes etc are easily visible by passing the argument, dry_run = TRUE. These can then be copied to a new object to begin customisation from a low level.

default_set_layers(dry_run = TRUE)

A more simple strategy is to pass a set of key parameters to each function as described on the help page. Any additional layers are handled simply by the ellipsis (...).

simpleUpSet(
  movies, sets, min_size = 20,
  intersect_layers = default_intersect_layers(
    fill = "Decade",
    scale_fill_brewer(palette = "Paired"),
    theme(
      legend.position = "inside",
      legend.position.inside = c(0.99, 0.99),
      legend.justification.inside = c(1, 1)
    )
  ),
  set_layers = default_set_layers(
    fill = "Decade", scale_fill_brewer(palette = "Paired"),
    guides(fill = guide_none()), expand = c(0.3, 0)
  )
)

Highlighting Intersections and Sets

Sets and intersections can be simply highlighted using the set name for sets, or by using a case_when() statement to define highlights. If the highlight column is added to the underlying data object, this column can additionally be used for determining intersection order.

## Define the sets to be coloured by name, the use scale_fill_manual
set_cols <- c(
  Action = "red", Comedy = "grey23", Drama = "red", 
  Romance = "grey23", Thriller = "grey23"
)
set_list <- default_set_layers(fill = "set", scale_fill_manual(values = set_cols))
## Use the highlights to colour the intersection bars based on the column 
## 'highlight', in conjunction with the case_when statement
intersect_list <- default_intersect_layers(
    fill = "highlight", scale_fill_manual(values = "red", na.value = "grey23")
  )
## When passing the 'highlight' column, this will be passed to both points
## and segments. Each layer can be manually edited to override this if preferred
grid_list <- default_grid_layers(
  colour = "highlight", scale_colour_manual(values = "red", na.value = "grey23")
)
simpleUpSet(
  movies, sets, min_size = 20,
  set_layers = set_list,
  intersect_layers = intersect_list,
  grid_layers = grid_list,
  sort_intersect = list(highlight, desc(size)),
  highlight = case_when(Action & Drama ~ TRUE)
) &
  plot_annotation(title = "Using Highlights") &
  theme(legend.position = "none", plot.title = element_text(hjust = 2/3))

Alternatively, the complete set of intersections containing any one of the sets can be highlighted simply by filling bars using that individual set.

simpleUpSet(
  movies, sets, min_size = 20, 
  intersect_layers = default_intersect_layers(
    fill ="Comedy", 
    scale_fill_manual(values = c("grey23", "blue")), 
    guides(fill = guide_none())
  ),
  grid_layers = default_grid_layers(
    colour = "Comedy", scale_colour_manual(values = c("grey23", "blue"))
  )
)

Adding Plots to Upper Panels

Additional panels can be included using the annotations argument.

## Add a simple boxplot
simpleUpSet(
  movies, sets, n_intersect = 10,
  set_layers = default_set_layers(expand = c(0.3, 0)),
  intersect_layers = default_intersect_layers(expand = c(0, 0.1)),
  annotations = list(geom_boxplot(aes(y = AvgRating))),
)

There is no particular limit to the complexity of the upper panels, beyond what is contained within the dataset, or what can be considered as useful for communication with readers.

simpleUpSet(
  movies, sets, n_intersect = 10,
  set_layers = default_set_layers(expand = c(0.3, 0)),
  intersect_layers = default_intersect_layers(expand = c(0, 0.1)),
  annotations = list(
    list(
      aes(y = AvgRating),
      geom_jitter(aes(colour = Decade), height = 0, width = 0.3, alpha = 0.5),
      geom_violin(fill = NA, quantiles = 0.5, quantile.linetype = 1),
      scale_colour_brewer(palette = "Paired"),
      guides(colour = guide_legend(nrow = 2, reverse = TRUE))
    )
  ), guides = "collect"
) &
  theme(legend.position = "bottom")