Skip to content

Latest commit

 

History

History
199 lines (136 loc) · 4.44 KB

docs.md

File metadata and controls

199 lines (136 loc) · 4.44 KB

UpSetAltair Documentation

Overview

UpSetAltair is a Python library for creating interactive UpSet plots using Altair. UpSet plots are used to visualize set intersections, similar to Venn diagrams but more scalable and interactive.

Installation

pip install altair-upset

Basic Usage

import altair_upset as au
import pandas as pd

# Create sample data
data = pd.DataFrame({
    'set1': [1, 0, 1],
    'set2': [1, 1, 0],
    'set3': [0, 1, 1]
})

# Create UpSet plot
chart = au.UpSetAltair(
    data=data,
    title="Sample UpSet Plot",
    sets=["set1", "set2", "set3"]
)

# Display the chart
chart.show()

API Reference

UpSetAltair

UpSetAltair(
    data=None,
    title="",
    subtitle="",
    sets=None,
    abbre=None,
    sort_by="frequency",
    sort_order="ascending",
    width=1200,
    height=700,
    height_ratio=0.6,
    horizontal_bar_chart_width=300,
    color_range=["#55A8DB", "#3070B5", "#30363F", "#F1AD60", "#DF6234", "#BDC6CA"],
    highlight_color="#EA4667",
    glyph_size=200,
    set_label_bg_size=1000,
    line_connection_size=2,
    horizontal_bar_size=20,
    vertical_bar_label_size=16,
    vertical_bar_padding=20,
)

Parameters

  • data : pandas.DataFrame

    • Input data where each column represents a set and contains binary values (0 or 1)
    • Required parameter

  • title : str, default ""

    • Title of the plot

  • subtitle : str or list of str, default ""

    • Subtitle(s) of the plot

  • sets : list of str

    • Names of the sets to visualize
    • Must correspond to column names in the data
    • Required parameter

  • abbre : list of str, default None

    • Abbreviations for set names
    • Must have same length as sets if provided
    • If None, uses full set names

  • sort_by : {"frequency", "degree"}, default "frequency"

    • Method to sort the intersections
    • "frequency": sort by intersection size
    • "degree": sort by number of sets in intersection

  • sort_order : {"ascending", "descending"}, default "ascending"

    • Order of sorting for intersections

  • width : int, default 1200

    • Total width of the plot in pixels

  • height : int, default 700

    • Total height of the plot in pixels

  • height_ratio : float, default 0.6

    • Ratio of vertical bar chart height to total height
    • Must be between 0 and 1

  • horizontal_bar_chart_width : int, default 300

    • Width of the horizontal bar chart in pixels

  • color_range : list of str, default ["#55A8DB", "#3070B5", "#30363F", "#F1AD60", "#DF6234", "#BDC6CA"]

    • List of colors for the sets

  • highlight_color : str, default "#EA4667"

    • Color used for highlighting on hover

  • glyph_size : int, default 200

    • Size of the matrix glyphs in pixels

  • set_label_bg_size : int, default 1000

    • Size of the set label background circles

  • line_connection_size : int, default 2

    • Thickness of connecting lines in pixels

  • horizontal_bar_size : int, default 20

    • Height of horizontal bars in pixels

  • vertical_bar_label_size : int, default 16

    • Font size of vertical bar labels

  • vertical_bar_padding : int, default 20

    • Padding between vertical bars

Interactive Features

The generated UpSet plot includes several interactive features:

  1. Hover Highlighting: Hovering over intersections highlights the connected sets
  2. Legend Filtering: Click on set names in the legend to show/hide specific sets
  3. Tooltips: Hover over bars to see detailed information about intersections

Examples

Basic Example with Custom Colors

chart = au.UpSetAltair(
    data=data,
    title="Custom Colored UpSet Plot",
    sets=["set1", "set2", "set3"],
    color_range=["#1f77b4", "#ff7f0e", "#2ca02c"],
    highlight_color="#d62728"
)

Sorting by Degree

chart = au.UpSetAltair(
    data=data,
    title="UpSet Plot Sorted by Degree",
    sets=["set1", "set2", "set3"],
    sort_by="degree",
    sort_order="descending"
)

Using Abbreviations

chart = au.UpSetAltair(
    data=data,
    title="UpSet Plot with Abbreviations",
    sets=["set1", "set2", "set3"],
    abbre=["S1", "S2", "S3"]
)

Citation

If you use an UpSet plot in a publication, please cite the original paper:

Alexander Lex, Nils Gehlenborg, Hendrik Strobelt, Romain Vuillemot, Hanspeter Pfister. UpSet: Visualization of Intersecting Sets IEEE Transactions on Visualization and Computer Graphics (InfoVis), 20(12): 1983--1992, doi:10.1109/TVCG.2014.2346248, 2014.