Add Text Description Generation via upset-altxt

.github/workflows/test.yml

@@ -20,6 +20,7 @@ jobs:
         shell: bash -el {0}
         run: |
           conda install pytest pytest-cov coveralls ${{ matrix.conda-deps }}
+          pip install upset-alttxt==0.5.2
           python setup.py install
           cp ci/matplotlibrc matplotlibrc
       - name: test

README.rst

@@ -130,6 +130,7 @@ Installation requires:
 * pandas
 * matplotlib >= 2.0
 * seaborn to use `UpSet.add_catplot`
+* upset-alttxt v0.5.2 to use `UpSet.get_alt_text`
 
 It should then be possible to::
 

doc/requirements.txt

@@ -10,3 +10,4 @@ scikit-learn
 nbsphinx
 sphinx<2
 sphinx-rtd-theme
+upset-alttxt

examples/plot_alt_text.py

@@ -0,0 +1,72 @@
+"""
+==========================================
+Data Vis: Alt text generation in UpSetPlot
+==========================================
+
+Explore text description generation via upset-alttxt (2025).
+
+When text description generation is enabled, there are no changes to the actual plot.
+The generated text description can be accessed after creating the UpSet plot object.
+
+"""
+
+from matplotlib import pyplot as plt
+
+from upsetplot import UpSet, generate_counts
+
+# Load the dataset into a DataFrame
+example = generate_counts()
+
+##########################################################################
+
+print("Generating a plot AND grammar for textual description")
+upset = UpSet(
+    example,
+    subset_size="count",
+    sort_by="-cardinality",
+    sort_categories_by="-cardinality",
+    orientation="vertical",
+    gen_grammar=True,
+)
+upset.plot()
+plt.suptitle("UpSet plot with text description generated'")
+text_description = upset.get_alt_text()
+
+print("==================================")
+print("Long Description (markdown formatted)")
+print("==================================")
+print(text_description["longDescription"])
+
+print("==================================")
+print("Short Description")
+print("==================================")
+print(text_description["shortDescription"])
+
+print("\n==================================")
+print("Technique Description")
+print("==================================")
+print(text_description["techniqueDescription"])
+
+plt.show()
+
+
+print("\nNow to generate the same plot with no alt text generation")
+
+# To disable grammar generation, simply ignore the gen_grammar parameter or set it to False.
+upset = UpSet(
+    example,
+    subset_size="count",
+    sort_by="-cardinality",
+    sort_categories_by="-cardinality",
+    orientation="vertical",
+)
+
+upset.plot()
+plt.suptitle("UpSet plot with no alt text generation")
+
+try:
+    text_description = upset.get_alt_text()
+except ValueError:
+    print("gen_grammar must be set to True for any alt text generation.")
+
+plt.show()

upsetplot/__init__.py

@@ -3,6 +3,10 @@
 import os
 
 if os.environ.get("__IN-SETUP", None) != "1":
+    from .alt_text import (
+        fetch_alt_text,
+        generate_grammar,
+    )
     from .data import (
         from_contents,
         from_indicators,
@@ -24,4 +28,6 @@
         "from_contents",
         "from_indicators",
         "query",
+        "generate_grammar",
+        "fetch_alt_text",
     ]