The UpSet component and the create_upset figure factory — every property with its type, default, and what it does, plus the data constructors, intersection modes, themes, and the data model.
Import: from dash_upset import UpSet, create_upset
UpSet is the Dash component you put in a layout; create_upset is the figure factory beneath it, returning a plotly.graph_objects.Figure for notebooks, static export, or your own dcc.Graph. Both take the same data + keyword arguments; every argument except data is keyword-only and optional. Want to see each one change the plot live? Open the Component Explorer.
The Dash component. Put it in your layout; it builds the same figure as create_upset and turns clicks into two component properties your callbacks read the standard Dash way: Input(id, property).
Accepts data and sets plus every create_upset keyword below, and the usual component props: id, style, className, and an optional plotly.js config.
from dash import Dash
from dash_upset import UpSet
app = Dash(__name__)
app.layout = UpSet(id="genes", data=df, sets=["A", "B", "C"])Set when an intersection-size bar or a matrix dot is clicked: {"label", "sets", "size"} (size only for bar clicks). None until the first click.
@callback(
Output("out", "children"),
Input("genes", "selected_intersection"),
)
def show(selection):
return str(selection)Set when a set-size bar is clicked: a list of set names. Read it with Input("genes", "selected_sets").
When on, clicking recolors the selected marks to selection_color as a visible cue: the clicked intersection's bar and its member dots, or the clicked set's bar and its dots. Set False to leave the plot unchanged on click (the selection is still reported to callbacks).
The color painted on the selected marks when highlight_selection is on. Any CSS color.
The figure factory. Composes the intersection-size bars, set-size bars, and the membership dot matrix into one shared-axes figure.
When data is a dataframe, the columns to treat as sets, in order; other columns (ids, attributes) are ignored. Unused when data is already an UpSetData.
How each subset is counted. The dot matrix is identical in every mode — the dots fix which sets a column represents (its degree). mode only changes how the bar height for that column is counted.
"distinct" counts elements in exactly those sets and no others (the classic exclusive intersection — columns are mutually exclusive, so bars sum to the total). "intersect" counts elements in at least those sets, i.e. the full |A ∩ B| including elements also in other sets. "union" counts elements in at least one, i.e. |A ∪ B|. The two inclusive modes overlap, so their bars do not sum to the total.
Worked example. Say 84 elements are in A and B only, and 40 more are in A, B, and C. The A & B column (degree 2) shows 84 in distinct mode, but 124 (84 + 40) in intersect mode — same column, different count.
Order of the intersection columns: "cardinality" (largest first), "degree" (fewest sets first), "deviation" (most surprising vs. independence first), or "input". Prefix any key with - to reverse, e.g. "-degree".
Order of the set rows: "cardinality", "name" (alphabetical), or "input". Prefix with - to reverse.
Hide any subset smaller than this. Applies to the mode-dependent size, inclusive.
Hide any subset larger than this (inclusive). Useful for suppressing a dominant intersection that flattens the rest.
Hide subsets that involve fewer than this many sets. Set to 2 to show only genuine overlaps.
Hide subsets that involve more than this many sets.
Keep only the N largest subsets by size. Ties at the cutoff are all kept, so you may get a few more than N (matching upsetplot).
Include the degree-0 subset (elements in no set at all). Off by default.
Print the size above each intersection bar.
Print each bar's share of the total. Combined with show_counts the label reads "N (X%)"; on its own it reads "X%".
Visual theme. "light" and "dark" recolor the marks and chrome (bars, dots, connectors, grid, baseline, text, and paper background) for the surface. "auto" resolves to light for a static figure; inside the Dash component it follows the page's color scheme live.
The colorblind-safe variants also set a CVD-safe colorway: "okabe-ito-light" / "okabe-ito-dark", "colorbrewer-light" / "colorbrewer-dark" (Set2 / Dark2), and "tol-light" / "tol-dark" (Paul Tol Bright). An explicit color always wins over the theme.
fig = create_upset(data, theme="okabe-ito-dark")Color of the data marks (bars, active dots, connectors). Defaults to the theme's ink; any value you pass overrides the theme.
Color of the non-member (empty) matrix dots. Defaults to the theme's inactive tone.
Optional figure title, drawn top-left.
A text description of the plot for screen readers. It is stored on the figure (layout.meta["description"]) and the UpSet component applies it as the graph's aria-label (with role="img"). Leave it unset to auto-generate a concise summary — set count, set names, intersection count, and the largest shown intersection.
Title of the intersection-size axis. Omit for the automatic label ("Intersection size", or the mode-specific variant); pass a string to override it, or None to hide it.
Title of the set-size axis. Omit for "Set size"; pass a string to override, or None to hide it.
Show the numeric tick labels on the intersection-size axis.
Show the numeric tick labels on the set-size axis.
"horizontal" (default) lays intersections along the x-axis as columns, with set-size bars on the left. "vertical" transposes the plot: sets become columns, intersections become rows, set-size bars sit on top, and intersection-size bars extend to the right — handy for many intersections in a narrow width.
Figure size in pixels. width=None is responsive; height=None is computed from the number of sets so rows stay legible.
Plotly template underneath the theme's explicit colors. None inherits the global default.
Four ways to build an UpSetData, mirroring the upsetplot conventions. Pick whichever matches the shape your data is already in.
Pre-aggregated exclusive intersection sizes. Keys are set-name tuples or sep-joined strings; the empty key is the "in no set" group. Values are the distinct sizes; set totals are derived for you.
from_counts({"A": 10, "B": 4, "A&B": 6})One collection of set names per element (an empty collection means the element is in no set). Pass element_ids to name the elements.
from_memberships([("A",), ("A", "B"), ()])A mapping of {set_name: iterable_of_element_ids}. An element listed twice in one set is counted once.
from_contents({"A": ["x", "y"], "B": ["y", "z"]})A boolean indicator table (rows = elements, columns = sets) from any narwhals-supported dataframe — pandas, Polars, PyArrow, cuDF, Modin — or a plain mapping of boolean columns. A pandas-style index supplies element ids when present.
from_indicators(df) # df: boolean columns, one per setEvery constructor normalizes to one canonical model the renderer consumes. You rarely build these by hand.
Ordered set names with their total sizes, plus the exclusive intersections. Exposes the total_size property and a set_size(name) method.
One exclusive intersection: the elements in exactly sets. elements is kept for the element-based constructors and is None for from_counts. Exposes the degree property (number of participating sets).