# UpSetR: static set intersection plots from R

> UpSetR is an R package that renders static UpSet plots, the matrix layout Lex and Gehlenborg published for visualising set intersections and their aggregates. It ships with ggplot2, four vignettes and two sample data sets, and it is installed from CRAN rather than built from the repository.

**hms-dbmi/UpSetR** — An R implementation of the UpSet set visualization technique published by Lex, Gehlenborg, et al..  

- Repository: https://github.com/hms-dbmi/UpSetR
- Website: https://cran.rstudio.com/web/packages/UpSetR
- Stars: 842 · Forks: 164
- Language: HTML
- License: NOASSERTION
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/hms-dbmi-upsetr

## What the UpSet matrix actually shows

UpSetR generates static UpSet plots, and the README describes the technique as visualising set intersections in a matrix layout that introduces aggregates based on groupings and queries. The point of that layout is that a Venn diagram stops working past a handful of sets, while a matrix of dots and bars keeps working as the number of sets grows.

The useful consequence is that the plot is not a picture of the sets themselves but of the intersections between them. Each column is one combination, and the bar above it is the number of elements in that combination. A column with no bar is an empty intersection, which is exactly the fact a reader wants to see confirmed rather than inferred from absence.

The technique comes from Lex, Gehlenborg, Strobelt, Vuillemot and Pfister, published as UpSet: Visualization of Intersecting Sets in IEEE Transactions on Visualization and Computer Graphics in 2014. The original interactive tool lives at upset.app, and the README points there for further detail on the technique itself. UpSetR is the static implementation, and it was published as an R package with its own paper by Conway, Lex and Gehlenborg in Bioinformatics.

One naming detail is worth knowing. The package is UpSetR, and the project page for the R package is hosted at cran.rstudio.com/web/packages/UpSetR, while the source repository is hms-dbmi/UpSetR.

## Queries and attribute plots carry the analysis

Two features do most of the analytical work, and they are the subject of dedicated vignettes.

Queries let you select parts of the intersection space and highlight them in the plot. The vignette list includes Basic Usage, Queries, Attribute Plots and Set Metadata. A query is expressed with the `intersects` helper and a set of parameters, and several queries can be combined in one call. The third example in the README builds two queries at once, one for war movies and one for noir movies, so a reader can see the overlap of each genre in a single figure rather than in two separate plots.

Attribute plots add panels aligned with the matrix columns, so each intersection carries extra summaries rather than only a count. The example call passes `attribute.plots` with a list of plots, including scatter plots of ReleaseDate against AvgRating, Watches against AvgRating and a histogram of ReleaseDate. Each column of the matrix then gets a small panel above or below it.

The queries also propagate into the attribute panels, which is where the second example earns its keep. In that call both the histogram and the scatter plot are marked with `queries=T`, so the highlighted genre subsets appear inside the panels as well as in the matrix.

Set Metadata is the fourth vignette, and it covers annotating the sets themselves rather than the intersections, which is what you need when a set has a meaningful label or category.

## Installing UpSetR and loading the sample data

The README gives two install paths. The released version comes from CRAN, and since the package is on CRAN there is nothing to compile.

```R
install.packages("UpSetR")
```

The development version from GitHub uses devtools.

```R
devtools::install_github("hms-dbmi/UpSetR")
```

The sample data sets ship inside the package and are loaded from its extdata directory.

```R
movies <- read.csv( system.file("extdata", "movies.csv", package = "UpSetR"), header=T, sep=";" )
mutations <- read.csv( system.file("extdata", "mutations.csv", package = "UpSetR"), header=T, sep = ",")
```

The movies data set was created by the GroupLens Lab and curated by Bilal Alsallakh. The mutations data set was originally created by the TCGA Consortium and holds mutations for the 100 most mutated genes in a glioblastoma multiforme cohort. That second example is more than filler, because gene mutation overlaps are exactly the case the matrix layout was designed for: a dozen genes, a set of intersections, and the interesting rows sitting in combinations that a summary table buries.

The package also ships a Shiny wrapper whose source is in the separate UpSetR-shiny repository, and a hosted demo of that wrapper at gehlenborglab.shinyapps.io/upsetr/.

## Ordering and colouring the matrix

The third README example is the one to read for the practical options, because it changes three things at once.

```R
upset(mutations, sets = c("PTEN", "TP53", "EGFR", "PIK3R1", "RB1"), sets.bar.color = "#56B4E9",
order.by = "freq", empty.intersections = "on")
```

`sets` selects which columns of the data become the sets, so you can plot a subset of the available ones. `sets.bar.color` paints the set size bars in a single colour rather than one colour per set, which is what the README means by mimicking the plot published by Lex and Gehlenborg in Nature Methods in 2014.

`order.by` sets the sort order of the intersection columns, and `"freq"` means the columns are arranged by how many elements they hold, which puts the common combinations on the left where they are easy to find. `empty.intersections = "on"` keeps the empty combinations in the matrix instead of dropping them. That single switch changes the meaning of the plot: with empty intersections off, a reader sees only the combinations that occur, and with them on, the reader also sees that certain combinations do not occur at all.

For a paper, that distinction decides whether the figure is a summary of findings or a picture of coverage, and the README example makes the second choice deliberately.

## Where UpSetR is the wrong tool

The first limitation is that the output is static. The README is explicit that UpSetR generates static UpSet plots, and the original interactive implementation is a separate piece of software at upset.app. A reader cannot filter, hover or re-query the figure. If the analysis is exploratory, a static image forces the loop of editing the script and re-rendering, and the Shiny wrapper exists precisely because that friction matters.

The second limitation is the gap in release history. The recent releases listed are v1.4.0 from 2019-05-03, v1.3.3 from 2017-03-21 and v1.3.2 from 2017-01-04. The repository is not archived and the last push was on 2026-05-20, so work continues on the main branch, but the tagged releases are years behind the tip. Anyone who needs a fix from the current source has to use the devtools path and accept a package that CRAN has not reviewed.

The third is the licence. The repository records a custom licence that GitHub cannot classify, so the terms have to be read in the LICENSE file rather than assumed. For a package published on CRAN that also means checking the CRAN page, since the ecosystem may impose different terms than the source repository does.

The fourth is the ecosystem. UpSetR is an R package, and the README points to a Python implementation called py-upset, written by a different author, for Python users. If your pipeline is not already in R, the cost of switching languages to get one plot is usually higher than using the Python route or a general purpose plotting library.

The fifth is scale. A matrix plot with every possible intersection is unreadable once the number of sets grows, and the fix is queries, which means the interesting regions have to be known in advance.

## UpSetR against py-upset, the Shiny app and ComplexUpset

The README names its own alternatives, which is useful because they differ in approach rather than in style.

py-upset is a Python package created by the GitHub user ImSoErgodic. The difference in approach is the language and the ecosystem it plugs into, since it sits inside a Python data stack rather than the R one. UpSetR sits inside ggplot2, so the set size bars, the matrix and the attribute panels are all standard ggplot2 output, and the same theme and styling machinery applies.

The Shiny app is the interactive counterpart rather than a competitor. Its source is in the UpSetR-shiny repository and a hosted instance runs at gehlenborglab.shinyapps.io/upsetr/. Where UpSetR produces a figure to embed in a paper or a slide, the Shiny version lets a reader query the same intersection space in the browser. The static package wins on reproducibility, since a script produces the same figure every time, and the interactive app wins on exploration.

For R users who want more control over the figure than UpSetR gives, ComplexUpset is the common alternative, since it builds on ggplot2 and adds support for alternative set encodings, custom annotations and text annotations of the intersections. The trade-off is the same one that runs through the whole R plotting world: more control, more to learn, and a package with a smaller body of published examples tied to a specific paper.

Against a Venn diagram, the choice is about the number of sets. Below three, a Venn is more immediately readable. Above that, the matrix wins, and UpSetR is the standard way to produce one from R.

## Licence, citation and what to check before using it

The licence field on the repository carries a custom licence that GitHub cannot classify, so the LICENSE file is the authoritative text and should be read before the package is redistributed or modified in a commercial context. This is not a usual position for a CRAN package, so it is worth confirming what terms actually apply to your use.

The project asks for citation in two layers. If you use UpSetR in a paper, cite the R package paper, UpSetR: An R Package for the Visualization of Intersecting Sets and their Properties by Conway, Lex and Gehlenborg, with the Bioinformatics DOI. The original technique and the interactive tool are described in the 2014 IEEE Transactions on Visualization and Computer Graphics paper by Lex and colleagues, and that citation belongs alongside the package citation since the technique is the contribution and the package is one implementation.

For a figure in a paper specifically, the README points to a separate UpSetR-paper repository holding a range of UpSetR plots used in the R package paper, which is a reasonable source of layout inspiration.

Before using it, three things are worth confirming. That the CRAN version carries the features you need rather than the GitHub tip, since the newest tag is from 2019. That the licence file permits your intended use. And that your data really is set intersection data, since a plot of a single set or of two sets with no interesting overlap is better served by a plain bar chart.

## Conclusion

UpSetR suits an R analyst who needs a static, publication ready picture of how several sets overlap, including the parts of the data most tables hide, such as the intersections nobody queried. It is the wrong tool for a reader who needs to explore the data interactively, because the plot is a fixed image and the interactive original lives elsewhere, and it is a poor fit for a Python pipeline. Before adopting it, check the licence file, which is a custom one that CRAN and GitHub label differently, and confirm that the CRAN version covers the features you need, since the newest release tag in the repository is v1.4.0 from 2019-05-03.

## FAQ

### How do I install UpSetR in R?

The released version installs from CRAN with install.packages("UpSetR"), and the development version from GitHub installs with devtools::install_github("hms-dbmi/UpSetR").

### What data sets ship with UpSetR?

Two. The movies data set was created by the GroupLens Lab and curated by Bilal Alsallakh, and the mutations data set came from the TCGA Consortium and holds mutations for the 100 most mutated genes in a glioblastoma multiforme cohort. Both are loaded with read.csv from system.file("extdata", ..., package = "UpSetR").

### What is the difference between UpSetR and the original UpSet tool?

UpSetR generates static UpSet plots, while the original tool at upset.app is interactive. UpSetR is also the R package implementation, with a separate Shiny wrapper whose source sits in the UpSetR-shiny repository.

### How do I show empty intersections in an UpSetR plot?

Set empty.intersections = "on" in the upset call. The README example uses it together with order.by = "freq" and a sets.bar.color value.

### Is there a Python version of UpSetR?

Yes. The README points to py-upset, a Python package for UpSet plots created by the GitHub user ImSoErgodic.

### How do I add extra panels above the UpSetR matrix?

Use the attribute.plots argument with a list of plots such as scatter_plot and histogram, and set queries=T on a plot to show the highlighted queries inside it as well. The Attribute Plots vignette covers this in detail.

## Sources

- [hms-dbmi/UpSetR on GitHub](https://github.com/hms-dbmi/UpSetR)
- [Issues](https://github.com/hms-dbmi/UpSetR/issues)
- [Project website](https://cran.rstudio.com/web/packages/UpSetR)
- [README](https://github.com/hms-dbmi/UpSetR/blob/master/README.md)
- [Releases](https://github.com/hms-dbmi/UpSetR/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hms-dbmi-upsetr