*! version 0.0.1 22may2026

Title

upset_plot -- UpSet plots for binary indicator variables.

Syntax

upset_plot
varlist
[if] [in]
[weight]
[, options]

Main
over(varname[, over_suboptions]) groups over which bars are drawn

bar(#, bar_suboptions) look of #th bar

intopts:(barchart_options) control appearance of intersection bar chart

setopts:(barchart_options) control appearance of set bar chart

gridopts:(grid_options) control appearance of grid

Options
sort(sort_rule_or_values) specify ordering of intersection bars

keepfirst(#) display only the first # intersection patterns

fillin include intersections with zero frequency

notable suppress display of intersection and set frequency tables

Add plots
addplot(plot) add other plots to the upset plot

Titles, Legend, Overall
twoway_options all options except axis_options, by(),
and recast()

fweights are allowed; see weight.

over_suboptions

relabel(over_label_info) change varname value labels

sort(#[ #[ ...]]) change order of varname values

descending: reverse order of varname values

bar_suboptions

color:(colorstyle) outline and fill color and opacity

fcolor:(colorstyle) fill color and opacity

fintensity:(intensitystyle) fill intensity

lcolor:(colorstyle) outline color and opacity

lwidth:(linewidthstyle) thickness of outline

lpattern:(linepatternstyle) outline pattern (solid, dashed, etc.)

lalign:(linealignmentstyle) outline alignment (inside, outside, center)

lstyle:(linestyle) overall look of outline

bstyle:(areastyle) overall look of bar, all settings above

grid_options

oncolor:(colorstylelist) color and opacity of active markers

offcolor:(colorstylelist) color and opacity of inactive markers

mcolor:(colorstylelist) synonym for oncolor()

msymbol:(symbolstylelist) shape of markers

msize:(markersizestylelist) size of markers

msangle:(anglestylelist) angle of marker symbols

mfcolor:(colorstylelist) inside or "fill" color and opacities

mlcolor:(colorstylelist) outline color and opacities

mlwidth:(linewidthstylelist) outline thicknesses

mlalign:(linealignmentstylelist) outline alignment(inside, outside, center)

mlstyle:(linestylelist) thickness and color, overall style of outlines

mstyle:(markerstylelist) overall style of markers; all settings above

mlabstyle:(markerlabelstyle) overall style of varlist labels

mlabgap:(size) gap between left-most marker and varlist labels

mlabangle:(anglestyle) angle of varlist labels

mlabtextstyle:(textstyle) overall style of varlist label text

mlabsize:(textsizestyle) size of varlist labels

mlabcolor:(colorstyle) color and opacity of varlist labels

mlabformat:(%fmt) format of varlist labels

lpattern:(linepatternstyle) whether vertical grid lines are solid, dashed, etc.

lwidth:(linewidthstyle) thickness of vertical grid lines

lcolor:(colorstyle) color and opacity of vertical grid lines

lalign:(linealignmentstyle) vertical grid line alignment (inside, outside, center)

lstyle:(linestyle) overall style of vertical grid lines

sort_rule_or_values, the argument allowed by sort(), is defined as:

[#[ #[ ...]]] [[+|-] sort_rule[ [+|-] sort_rule[ ...]]]
[, sort_suboptions]

# is either a base-2 or base-10 representation of one of the patterns defined by varlist. See Reordering the bars under Remarks below.

sort_rule

pattern: sort by numeric representation of varlist pattern

frequency: sort by varlist pattern frequency

bitsum: sort by varlist pattern bit sum

random: sort in random order

sort_suboptions

intwo specify that #s are given in base-2 (the default)

inten specify that #s are given in base-10

over_label_info, the argument allowed by relabel() within over(), is defined as:

# "text" ["text" ...] [# "text" ["text" ...] [ ...]]

Description

upset_plot calculates and displays intersection and set frequencies
for combinations of binary indicator variables in varlist, using the UpSet
plot design described by Lex et al. (2014).

Options

Main

over(varname[, over_suboptions]) specifies a numeric categorical variable
used to stack the intersection and set bars.

bar(#, bar_suboptions) specifies the look of the bars. bar(1, ...)
refers to the bar associated with the first over(varname) value. If
over() is not specified, bar(1, ...) controls the look of all bars
in the plot.

intopts(barchart_options) specifies the rendition of the vertical
intersection bar chart. barchart_options are similar to axis_options
and title_options in twoway_options: full details are provided in
upset_barchart_options.

setopts(barchart_options) specifies the rendition of the horizontal set
bar chart. barchart_options are similar to axis_options and
title_options in twoway_options: full details are provided in
upset_barchart_options.

gridopts(grid_options) specifies the look of the markers in the grid. The
oncolor(colorstylelist) and offcolor(colorstylelist) suboptions
control the color of the active and inactive markers, respectively. All other
grid_options apply uniformly to all markers regardless of
active/inactive status.

Options

sort(sort_rule_or_values) controls how intersection bars are ordered. By
default, bars are ordered by descending frequency and then by ascending
numeric representation of the corresponding varlist pattern.

keepfirst(#) displays only the first # bars in the intersection bar chart.

fillin specifies that intersection patterns with zero frequency should be
displayed in the intersection bar chart. By default, these are excluded.

notable suppress display of intersection and set frequency tables.

Add plots

addplot(plot) adds graph twoway plots to the graph; see addplot_option.

Titles, Legend, Overall

twoway_options specifies most options documented in twoway_options,
including titling (see title_options) and graph saving options (see
saving_option).

upset_plot does not support the recast() and by()
options. The axis_options suboptions will generally have no effect
on plot rendition.

Remarks

Remarks are presented under the following headings:

Rescaling
Reordering the bars
Other remarks

Rescaling

In order to present both bar charts in the same region, upset_plot
significantly rescales the data. The default dimensions are as follows:

Intersection bar chart
+-+ -+
| | |
| | |
| | |
| | +-+ |
| | | | |
| | | | +-+ |ysize(3)
| | | | | | +-+ +-+ |
| | | | | | | | | | |
| | | | | | | | | | +-+ +-+ |
| | | | | | | | | | | | | | +-+ |
| | | | | | | | | | | | | | | | |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -+ -+
set bar chart |gap(0.1)
+----------+ -+ -+
+----------+ ° ° ° ° ° ° ° ° |
+-----+ |
+-----+ ° ° ° ° ° ° ° ° |1
+--------+ |
+--------+ ° ° ° ° ° ° ° ° -+

+----------+ +-----------------------------+
ysize(0.5) 1
+----+
gap(0.2)

The point of intersection between the vertical axis in the intersection bar chart
and the horizontal axis in the set bar chart is the point (0,0) on the
original axes. All listed dimensions – except the width and height of the
grid – can be changed using intopts() and setopts().

Added lines, text, and plots may need rescaling to appear as intended.

Reordering the bars

The order of bars in the set bar chart is determined by the order they are
supplied to upset_plot. The order of bars in the intersection bar chart is
determined by the sort() option.

sort() allows the user to order specific bars according to their
base-2 or base-10 representations, and/or to order them by their frequency,
pattern (the numeric representation of varlist patterns), or
bitsum (the number of nonzero bits in the base-2 representations of
varlist patterns).

You may prefix frequency, pattern, and bitsum with a +
or - to sort them in ascending or descending order, respectively.

The default sort() behavior is -frequency pattern (that is, bars are
ordered first by decreasing frequency and then by increasing numeric value).

Other remarks

Sorting is performed before keepfirst() executes. Bars omitted by the
keepfirst() option are counted in the set frequencies.

The set bar chart is rendered such that its y-axis is horizontal. Changes to
set bar chart size, ticks, tick labels, or titles must be done through
ysize(), yscale(), ylabel(), or ytitle(), as appropriate.

Because each axis element is rendered separately, yscale(off) does not
suppress ticks, tick labels, or titles as it does in standard twoway
graphs: these can be suppressed using ylabel() and ytitle(), if
needed.

Examples

Setup

. use upset_plot_dataex

Create an upset plot for patterns defined by a, b, c, d

. upset_plot a b c d

(click to run)

Same as above, but now over values defined by variable over

. upset_plot a b c d, over(over)

(click to run)

Same as above, but with pretty colors

. upset_plot a b c d, over(over) bar(1, color(stc2)) bar(2, color(stc2*0.66)) bar(3, color(stc2*0.33))

(click to run)

Repeating the first plot, but with a modified grid

. upset_plot a b c d, gridopts(msymbol(O S D T) oncolor(stc2 stc2 stc2 stc2))

(click to run)

Repeating the first plot, but with percentage bar labels and no axis lines

. local plotsyn yscale(off) ylabel(none) ytitle("") xscale(off) blabel(total)

. upset_plot a b c d, intopts(`plotsyn') setopts(`plotsyn')

(click to run)

Repeating the first plot, but with user-specified tick placement

. upset_plot a b c d, intopts(ylabel(0(100)500)) setopts(ylabel(#3))

(click to run)

Repeating the first plot, but with 0000 placed first and subsequent bars ordered by decreasing bit sum and then by increasing frequency, with empty bars shown

. upset_plot a b c d, fillin sort(0000 -bitsum frequency)

(click to run)

Stored results

upset_plot stores the following in r():

Scalars

r(N) number of observations

r(n_var) number of binary indicator variables

r(n_over) number of distinct values of over(varname)

Macros

r(cmd) upset_plot

r(cmdline) command as typed

r(varlist) binary indicator variables

r(overvar) categorical over variable

Matrices

r(intmatrix) intersection matrix

r(setmatrix) set matrix

Note that results stored in r() are updated when the command is replayed
and will be replaced when any r-class command is run after the estimation command.

References

Lex, A., Gehlenborg, N., Strobelt, H., Vuillemot, R., & Pfister, H. (2014). UPSET:
Visualization of intersecting sets. IEEE Transactions on Visualization and Computer
Graphics, 20(12), 1983–1992. https://www.doi.org/10.1109/tvcg.2014.2346248

Authors

Dylan Taylor, London School of Hygiene and Tropical Medicine, London

dylanjamestaylor00@gmail.com