bio-data-visualization-upset-plots

name	bio-data-visualization-upset-plots
description	Build UpSet plots to visualize set intersections beyond 4 sets (where Venn fails) using ComplexUpset (modern, ggplot2-grammar) or the unmaintained UpSetR, with explicit cardinality vs degree sorting, attribute panels, and query highlighting. Use when comparing overlap across many gene sets, peak sets, variant lists, or any set membership matrix where Venn diagrams become illegible.
origin	openai4s
category	bioskills/data-visualization
metadata	{"tool_type":"mixed","primary_tool":"ComplexUpset","third_party":{"name":"GPTomics/bioSkills","repository":"https://github.com/GPTomics/bioSkills","commit":"d91ed3d563019e649dc854c56ccd62551359488a","license":"MIT"}}

Version Compatibility

Reference examples tested with: ComplexUpset 1.3+ (R, Krassowski), UpSetR 1.4.0 (last 2019 release; effectively unmaintained), upsetplot 0.9+ (Python).

Before using code patterns, verify installed versions match. If versions differ:

• R: packageVersion('<pkg>') then ?function_name
• Python: pip show <package> then help(module.function)

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.

UpSet Plots

"Show set intersections for 4+ sets" -> Replace Venn diagrams (which become illegible past 4 sets) with UpSet (Lex 2014 IEEE TVCG 20:1983). The display: a matrix of dots indicating which sets participate in each intersection, with a vertical bar above each column showing intersection size and horizontal bars on the left showing per-set total size. Sort by intersection size (cardinality) for "biggest overlaps first" or by degree (number of sets) for grouped layout.

• R: ComplexUpset::upset (Krassowski; ggplot2-native, recommended), UpSetR::upset (Conway 2017; legacy, unmaintained)
• Python: upsetplot.UpSet

The Single Most Important Modern Insight -- UpSetR Is Effectively Unmaintained

UpSetR (Conway, Lex, Gehlenborg 2017 Bioinformatics 33:2938) is the original R implementation but has had no CRAN release since v1.4.0 (2019). ComplexUpset (Krassowski; CRAN active through 2025-07) is the actively maintained ggplot2-grammar replacement. For new work in 2026, prefer ComplexUpset. Caveat: ggplot2 4.0 (mid-2025) broke ComplexUpset's upset() function (issue #213); pin to compatible versions until patched.

The Lex 2014 paper and underlying UpSet visualization concept are not affected — the visualization is the same; the difference is which R package implements it best in the current ecosystem.

ComplexUpset (Modern Default)

Goal: Render a set-intersection plot with cardinality-sorted bars, optional metadata stacks (e.g., percent of intersection significant), and pre-specified queries highlighting biologically relevant intersections.

Approach: Convert set memberships to a long-format data frame with one row per element and binary columns per set; pass to upset() with intersections='all' or pre-specified subset; use ComplexUpset::upset_query to highlight intersections.

library(ComplexUpset)
library(ggplot2)

# Convert from list of sets to long format
sets <- list(SetA = c('Gene1','Gene2','Gene3','Gene4'),
             SetB = c('Gene2','Gene3','Gene5','Gene6'),
             SetC = c('Gene1','Gene3','Gene6','Gene7'),
             SetD = c('Gene3','Gene4','Gene7','Gene8'))

# Long-format binary membership matrix
all_elements <- uniqueunlistsets
df  data.frameelement  all_elements
 s  sets dfs  dfelement  setss


upsetdf
      intersect  sets                          
      n_intersections                               
      sort_intersections                  
      sort_intersections_by              
      base_annotations  
            intersection_size
              counts  
              text  size  
      themes  upset_modify_themes
            themepanel.grid  element_blank

Sorting -- Cardinality vs Degree

Cardinality sort (default): intersections ordered by size (largest first). Reveals "the biggest overlap is A∩B."

Degree sort: intersections grouped by number of sets they include (1-set intersections, then 2-set, then 3-set, etc.). Reveals "how distributed are the overlaps across set counts?"

Choose based on the scientific question. Cardinality is the default for "find the biggest overlap"; degree is appropriate when comparing across "exclusive to 1 set" vs "shared by all."

Pre-Specified Queries / Highlighting

upset(df,
      intersect = names(sets),
      queries = list(
          upset_query(intersect = c('SetA', 'SetB'),
                       color = '#D55E00', fill = '#D55E00',
                       only_components = c('intersections_matrix', 'Intersection size')),
          upset_query(intersect = c('SetA', 'SetC', 'SetD'),
                       color = '#0072B2', fill = '#0072B2',
                       only_components = c('intersections_matrix', 

Attribute Panels (ComplexUpset Strength)

Unlike UpSetR's "boxplot.summary," ComplexUpset supports arbitrary ggplot annotations stacked above the intersection bars:

upset(df,
      intersect = names(sets),
      annotations = list(
          'log2 FC' = ggplot(mapping = aes(x = intersection, y = log2FC)) +
                       geom_boxplot() + theme_classic(),
          'Significant fraction' = ggplot(mapping = aes(x = intersection, fill = significant)) +
                                    geom_bar(position = 'fill') +
                                    scale_fill_manual(values = c('TRUE' = '#D55E00', 'FALSE' = 'grey80') 
                                    theme_classic

upsetplot (Python)

from upsetplot import from_contents, UpSet
import matplotlib.pyplot as plt

sets = {'SetA': ['Gene1','Gene2','Gene3','Gene4'],
        'SetB': ['Gene2','Gene3','Gene5','Gene6'],
        'SetC': ['Gene1','Gene3','Gene6','Gene7']}
data = from_contents(sets)

upset = UpSet(data,
              subset_size='count',
              show_counts=True,
              sort_by='cardinality',                    # 'cardinality' OR 'degree'
              sort_categories_by='cardinality',
              facecolor='#0072B2',
              element_size=40)
upset.style_subsets(present=['SetA', 'SetB'], facecolor='#D55E00')   # highlight specific intersection
fig = plt.figure(figsize=(8, 5))
upset.plot(fig=fig)
plt.savefig('upset.pdf', bbox_inches='tight')

UpSetR (Legacy — Use Only for Reproducibility)

library(UpSetR)
upset(fromList(sets),
      nsets = 4, nintersects = 20,
      order.by = 'freq',
      decreasing = TRUE,
      mb.ratio = c(0.6, 0.4),
      point.size = 3,
      line.size = 1,
      text.scale = c(1.5, 1.3, 1.3, 1, 1.5, 1.3))

UpSetR works but lacks ggplot2 grammar and active maintenance. Reproducing a paper's UpSetR figure is the main reason to use it in 2026.

Per-Method Failure Modes

Using UpSetR for new work in 2026

Trigger: Following older tutorials that default to UpSetR.

Mechanism: UpSetR has not had a CRAN release since 2019; integration with current ggplot2 / R ecosystem stale.

Symptom: Limited customization; ggplot2 layer not available; eventual breakage.

Fix: Switch to ComplexUpset for new figures. UpSetR is fine for reproducing old figures.

ggplot2 4.0 broke ComplexUpset

Trigger: ggplot2 4.0 (mid-2025) introduced API changes; ComplexUpset's upset() errored.

Mechanism: Upstream ggplot2 changes affected ComplexUpset internals (issue #213).

Symptom: "Error in upset(): ..." after ggplot2 upgrade.

Fix: Pin compatible versions (renv::install('ggplot2@3.5.2')) until ComplexUpset patches. Check GitHub issues for fix status.

Too many sets makes UpSet unreadable

Trigger: UpSet with 10+ sets and n_intersections = Inf.

Mechanism: Number of possible intersections is 2^N − 1; with 10 sets that's 1023 columns.

Symptom: Vertical bars too thin to read; matrix dots unrecognizable.

Fix: Set n_intersections = 20 (or whatever fits); pre-filter to relevant intersections via intersections = list(c('SetA','SetB'), c('SetA','SetC','SetD')).

Single-set "intersections" obscure cross-set overlap story

Trigger: Default sort by cardinality puts "set exclusives" first (often largest).

Mechanism: "SetA only" is technically a 1-set intersection; usually larger than any 2+set overlap.

Symptom: First 4-5 bars are "exclusive to X," obscuring the cross-set story.

Fix: Filter via intersections argument to exclude 1-set; OR sort by degree to group; OR use mode='intersect' (vs 'distinct') for different counting.

Element duplicate across sets in fromList

Trigger: Same element appears in multiple sets but stored as duplicate rows.

Mechanism: fromList expects each element appears once per set; duplicates inflate counts.

Symptom: Intersection counts don't sum to known totals.

Fix: lapply(sets, unique) before fromList.

upsetplot from_contents vs from_indicators

Trigger: Wrong input format function used.

Mechanism: from_contents for dict of element lists; from_indicators for already-pivoted binary frame.

Symptom: TypeError or wrong intersections.

Fix: Check input shape; use the appropriate constructor.

Reconciliation: When Implementations Differ

Pattern	Cause	Action
ComplexUpset and UpSetR show different intersection counts	Different element duplication handling	lapply(sets, unique); verify both agree
ComplexUpset slow on >10 sets	2^N intersections enumerated	Pre-specify relevant intersections; use n_intersections
upsetplot Python output differs from R	sort_by default differs	Set sort_by explicitly in both
Excluding 1-set intersections	mode='distinct' vs 'intersect'	intersections parameter; document

Quantitative Thresholds

Threshold	Value	Source
Max sets for legible UpSet	8-10	Visualization practical
Show top intersections	15-25	Above this matrix too thin
When to use UpSet vs Venn	>3 sets	Lex 2014
2^N intersections	grows exponentially	Set n_intersections limit

Common Errors

Error / symptom	Cause	Solution
Intersection columns too thin	Too many intersections shown	n_intersections = 20; pre-filter
1-set bars dominate	Default cardinality sort	Exclude 1-set OR sort by degree
Intersection counts wrong	Duplicate elements in fromList input	lapply(sets, unique)
UpSetR error after R upgrade	Unmaintained package	Switch to ComplexUpset
ComplexUpset breaks after ggplot2 update	ggplot2 4.0 issue #213	Pin ggplot2 ≤ 3.5.2
Python upsetplot mismatch with R	Different default sort	Standardize sort_by

References

• Conway JR, Lex A, Gehlenborg N. 2017. UpSetR: an R package for the visualization of intersecting sets and their properties. Bioinformatics 33(18):2938-2940.
• Krassowski M. 2020. ComplexUpset (R package). https://github.com/krassowski/complex-upset
• Lex A, Gehlenborg N, Strobelt H, Vuillemot R, Pfister H. 2014. UpSet: visualization of intersecting sets. IEEE Trans Vis Comput Graph 20(12):1983-1992.

Related Skills

• data-visualization/heatmaps-clustering - Alternative for smaller set membership (Venn alternative is OncoPrint-style)
• pathway-analysis/go-enrichment - Gene-set overlaps to visualize
• differential-expression/de-results - DE gene-list comparisons
• data-visualization/flow-and-transition-plots - Alluvial as alternative for membership flow