UpSetPlot

UpSetPlot supports advanced visualization modes:

• Distributions: By providing a pandas.DataFrame instead of a Series, you can plot the distribution of variables within each subset.
• Vertical Plots: While the default style is "horizontal" (intersections presented left to right), vertical plot styles are also supported.

Install the upsetplot library using pip.

Dependencies:

• pandas
• matplotlib >= 2.0
• seaborn (optional, required only if you want to use UpSet.add_catplot)

After installation, you can use it in your Python scripts by importing upsetplot.

$ pip install upsetplot

UpSet plots visualize set overlaps (intersections) more readably than Venn diagrams.

Internal Data Format: The library uses a pandas.Series where the index consists of multiple boolean indices representing category memberships, and the values are the counts (cardinality) for each subset.

Basic Usage:

1. Prepare a pandas.Series with a MultiIndex of booleans.
2. Call upsetplot.plot(series) to generate the plot.
3. Use matplotlib.pyplot to display or save the result.

from upsetplot import generate_counts, plot
from matplotlib import pyplot

# Generate example data
example = generate_counts()

# Create the plot
plot(example)

# Display or save
pyplot.show()
pyplot.savefig("/path/to/myplot.png")

UpSetPlot can visualize data where objects are assigned to one or more categories. There are three primary ways to represent this membership:

1. Memberships: A list of lists where each inner list contains the categories for an object (e.g., [['A', 'B'], ['B']]).
2. Contents: A dictionary where keys are category names and values are lists/sets of members (e.g., {'A': [1], 'B': [1, 2]}).
3. Indicators: A boolean-valued matrix (often columns in a DataFrame) where True indicates membership (e.g., [[True, True], [False, True]]).

While you can construct these manually, it is highly recommended to use the helper functions from_memberships, from_contents, or from_indicators to ensure compatibility with future versions of the library.

A pandas.DataFrame can be used to carry additional information alongside category memberships. This is useful for visualizing properties of the data using methods like UpSet.add_catplot.

• To count observations: Use subset_size='count'.
• To plot the sum of a specific column: Use sum_over='column_name' in conjunction with subset_size='sum'.

from upsetplot import UpSet, generate_samples

example_samples_df = generate_samples()

# Count observations in each subset
UpSet(example_samples_df, subset_size='count').plot()

# Plot the sum of the 'index' column for each subset
UpSet(example_samples_df, sum_over='index', subset_size='sum').plot()

Use the query() function to perform data querying and transformations on UpSet datasets. This allows you to filter or manipulate the underlying data structure before or during the plotting process.

from upsetplot import query
# query(data, ...)

The upsetplot package provides several functions to transform different data formats into the specific format required for plotting:

• from_contents(contents): Creates a dataset from a collection of sets or lists.
• from_indicators(indicators): Creates a dataset from an indicator matrix (e.g., a DataFrame of boolean columns).
• from_memberships(memberships): Creates a dataset from a list of memberships (e.g., a list of sets).
• generate_counts(data): Generates counts from existing data.
• generate_samples(data, n): Generates samples from existing data.

If you have raw membership data, you can reconstruct the required pandas.Series format using upsetplot.from_memberships.

This function takes a list of lists (where each inner list contains the names of categories a data point belongs to) and a corresponding list of counts (the data parameter).

from upsetplot import from_memberships

example = from_memberships(
    [
        [],             # Absent from all
        ['cat2'],       # Only in cat2
        ['cat1'],       # Only in cat1
        ['cat1', 'cat2'],
        ['cat0'],
        ['cat0', 'cat2'],
        ['cat0', 'cat1'],
        ['cat0', 'cat1', 'cat2'],
    ],
    data=[56, 283, 1279, 5882, 24, 90, 429, 1957]
)

Use the plot() function to create an UpSet plot from a dataset. This is the primary entry point for generating visualizations in the upsetplot package.

from upsetplot import plot
# plot(data)

In addition to from_memberships, upsetplot provides two other ways to prepare data:

• from_contents: Another way to describe categorized data.
• from_indicators: Allows each category to be indicated by a column in a DataFrame (or a function of the column's data, such as checking for missing values).

Use from_memberships when your data is organized by object (i.e., you have a list of categories for each object). The input should be a list of lists, where each inner list contains the categories for one object.

from upsetplot import from_memberships, UpSet

# Data organized by object memberships
animal_membership_lists = [
    ["Mammal"],
    ["Mammal", "Domesticated"],
    ["Mammal", "Herbivore", "Domesticated"],
    # ... etc
]

animals = from_memberships(animal_membership_lists)
UpSet(animals, subset_size="count").plot()