UpSet.js Jupyter 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 Jupyter wrapper.

In this tutorial the basic widget functionality is explained.

Let's begin with importing the widget and some utilities

This wrapper is implemented in Python 3 with mypy typings and generics. The generic type T of the UpSetJSWidget is type of element that we wanna handle. In the following example we handle str elements.

Basic User Interface

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

An UpSet plot consists of three areas:

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.

In the bottom right corner there are two buttons for exporting the chart in either PNG or SVG image format.

Input Formats

In the current version the UpSet.js wrapper supports three input data formats: dictionary, expression and through a Pandas dataframe.

Dictionary Input

The first format is a dictionary of type Dict[str, List[T]], T refers again to the elements type, in this case it is a list of str. The key of the dictionary entry is the set name while the value is the list of elements this set has.

Expression Input

The second format is a mapping of type Dict[str,number], i.e., it has to have an .items() -> Iterator[Tuple[str, number]] method. The key of the dictionary entry is the set combination name while the value is the number of elements in this sets.

Data Frame Input

The second format is a a binary/boolean data frame. The index column contains the list of elements. Each regular color represents a sets with boolean values (e.g., 0 and 1) whether the row represented by the index value is part of the set or not.

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

Basic Attrributes

.elems returns the list of extracted elements

.sets returns the list of extracted sets as UpSetSet objects

Similariy, .combinations returns the list of set intersections that are visualized as UpSetIntersection objects.

Note: the attribute is called .combinations instead of .intersections since one customized the generation of the set combinations that are visualized. E.g., one can also generate set unions.

.generate_intersections, .generate_distinct_intersections, and .generate_unions let you customize the generation of the set combinations

Interaction

UpSet.js allows three intersection modes settable via .mode

with .selection one manually sets the selection that is currently highlighted. Manually setting the selection is only useful in click and static modes.

The current selection is synced with the server. It is designed to work with the interact of the ipywidgets package. In the following example the current selected set will be automatically written below the chart and updated interactivly.

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.

Attributes

UpSet.js supports rendering boxplots as aggregations for numerical attributes of elements. The are given as part of the data frame. The attributes element can either have a list of column names or a data frame with the same index

Styling

Theme

UpSet.js supports three themes: light, dark, and vega. The theme can be set by the .theme property

Labels

Log Scale

setting .numerical_scale = 'log' switches to a log scale, similarly 'linear' goes back to a linear scale

Size

the .width and .height properties can be used to specify the width and height of the chart respectively. In general, the .layout of the Jupyter Widgets can be used to customize it.