publiplots.upsetplot¶

publiplots.upsetplot(data, sort_by='size', ascending=False, min_subset_size=None, max_subset_size=None, min_degree=1, max_degree=None, show_counts=20, color=None, bar_linewidth=None, matrix_linewidth=None, alpha=None, dotsize=None, elementsize=None, title='', intersection_label='', set_label='')[source]¶

Create an UpSet plot for visualizing set intersections.

UpSet plots [1] are an effective way to visualize intersections of multiple sets, providing more clarity than Venn diagrams when dealing with many sets or complex intersection patterns. This implementation is based on the UpSetPlot package [2].

Parameters:

data (DataFrame, Series, or dict of sets) –
Input data in one of the following formats:
- DataFrame: Each column represents a set, rows are elements. Values should be binary (0/1 or True/False) indicating membership.
- Series: MultiIndex series where first level is elements and second level is sets, with binary values.
- dict: Dictionary mapping set names (str) to sets of elements. Example: {'Set A': {1, 2, 3}, 'Set B': {2, 3, 4}}
sort_by ({'size', 'degree', 'name'}, default='size') –
How to sort intersections:
- ’size’: Sort by intersection size (largest first if ascending=False)
- ’degree’: Sort by number of sets in intersection
- ’name’: Sort alphabetically by set names
ascending (bool, default=False) – Sort order. False shows largest/highest degree first.
min_subset_size (int, optional) – Minimum size for an intersection to be displayed. Useful for filtering out small intersections.
max_subset_size (int, optional) – Maximum size for an intersection to be displayed.
min_degree (int, default=1) – Minimum number of sets in an intersection. Set to 2 to exclude individual sets.
max_degree (int, optional) – Maximum number of sets in an intersection. Useful for focusing on simpler intersections.
show_counts (int, default=20) – Maximum number of intersections to display in the plot.
color (str, optional) – Color for bars (both intersection and set size bars). Supports any matplotlib color specification.
bar_linewidth (float, optional) – Width of edges around bars.
matrix_linewidth (float, optional) – Width of lines connecting dots in the matrix.
alpha (float, optional) – Transparency level for bars (0=transparent, 1=opaque).
dotsize (float, optional) – Size of dots in the membership matrix (area in points²). If not specified, calculated from elementsize using circle geometry: dotsize = π * (elementsize * 0.7 / 2)². Typical values: 400-900.
elementsize (float, optional) – Width of each matrix cell/bar in figure points (1/72 inch). Controls the overall scale of the plot. If not specified, calculated from dotsize using circle geometry: diameter = 2 * sqrt(dotsize / π); elementsize = diameter / 0.7 or defaults to 48. Typical values: 32 (compact), 48 (default), 64 (spacious). The figure size is automatically calculated to maintain proper proportions based on this value.
title (str, default="") – Main plot title.
intersection_label (str, default="") – Label for the y-axis of intersection size bars.
set_label (str, default="") – Label for the x-axis of set size bars.

Returns:

fig (Figure) – Matplotlib Figure object.
axes (tuple of (Axes, Axes, Axes)) – Tuple containing three axes: - ax_intersections: Intersection size bar plot (top) - ax_matrix: Set membership matrix (middle) - ax_sets: Set size bar plot (left)

Return type:

Tuple[Figure, Tuple[Axes, Axes, Axes]]

Notes

UpSet plots consist of three main components:

Intersection size bars (top): Show the number of elements in each intersection, sorted by the specified criterion.
Membership matrix (middle): Visualizes which sets contribute to each intersection using dots and connecting lines. Each column represents one intersection, each row represents one set.
Set size bars (left): Show the total size of each individual set.

The implementation is inspired by the UpSetPlot package (https://github.com/jnothman/UpSetPlot) but redesigned to match the publiplots aesthetic with cleaner styling and integration with existing publiplots utilities.

Examples

Create an UpSet plot from a dictionary of sets:

>>> data = {
...     'Set A': {1, 2, 3, 4, 5},
...     'Set B': {3, 4, 5, 6, 7},
...     'Set C': {5, 6, 7, 8, 9}
... }
>>> fig, axes = upsetplot(data, title='Set Intersections')

Create from a DataFrame with binary membership:

>>> df = pd.DataFrame({
...     'Set A': [1, 1, 1, 0, 0],
...     'Set B': [0, 1, 1, 1, 0],
...     'Set C': [0, 0, 1, 1, 1]
... })
>>> fig, axes = upsetplot(df, sort_by='degree', min_degree=2)

Filter to show only intersections with at least 10 elements:

>>> fig, axes = upsetplot(data, min_subset_size=10, show_counts=15)

Customize colors and styling:

>>> fig, axes = upsetplot(
...     data,
...     color='#ff6b6b',
...     elementsize=64  # Larger, more spacious plot
... )

Control plot size via elementsize:

>>> fig, axes = upsetplot(
...     data,
...     elementsize=32  # Compact plot
... )
>>> fig, axes = upsetplot(
...     data,
...     elementsize=64  # Spacious plot
... )