From 765e4a737e01735f5d66fe96bd086c75d0e176de Mon Sep 17 00:00:00 2001 From: Will Dean Date: Tue, 3 Jun 2025 12:47:45 -0400 Subject: [PATCH 1/5] basic docs setup --- docs/index.md | 147 ++++++++++++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 28 ++++++++++ 2 files changed, 175 insertions(+) create mode 100644 docs/index.md create mode 100644 mkdocs.yml diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..df13c50 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,147 @@ +# VSUP: Value-Suppressing Uncertainty Palettes + +A Python package for visualizing data with uncertainty using Value-Suppressing Uncertainty Palettes (VSUPs). Inspired by https://github.com/uwdata/vsup. + +## Installation + +```bash +pip install vsup +``` + +### Development + +The project is developed with [uv](https://docs.astral.sh/uv/). + +To check for a local python environment, run: + +```bash +uv run python +``` + +Also install the [pre-commit](https://pre-commit.com/) hooks with: + +```bash +uv tool install pre-commit +pre-commit install +``` + +## Usage +```python +from vsup import VSUP +import numpy as np +import matplotlib.pyplot as plt + +# Create a grid of values and uncertainties for better visualization +n_points = 50 +step = 1/n_points +values = np.linspace(step/2, 1-step/2, n_points) +uncertainties = np.linspace(step/2, 1-step/2, n_points) + +# Create a 2D grid +values, uncertainties = np.meshgrid(values, uncertainties) + +# Colorize the data +axs = plt.subplots(3, 3, figsize=(9, 9))[1] + +for row, quantization in zip(axs, [None, 'linear','tree']): + for ax, mode in zip(row, ["us", "ul", "usl"]): + + vsup = VSUP(palette='flare', mode=mode, quantization=quantization) + + colors = vsup(values, uncertainties) + ax.pcolormesh(values, uncertainties, colors) + ax.set_xlabel("Value") + ax.set_ylabel("Uncertainty") +``` + +## Example + + +```python {marimo} +import marimo as mo + +import micropip +await micropip.install(["vsup", "matplotlib", "numpy"]) + +from matplotlib import colormaps + +seaborn_colors = ["flare"] +matplotlib_colors = list(colormaps) +colors = seaborn_colors + matplotlib_colors + +palette = mo.ui.dropdown(options=colors, value="flare", label="Palette:") +palette +``` + +```python {marimo} +def palette_not_selected(): + return mo.md("Please select a palette first.") + +def showcase_palette(palette: str): + try: + from vsup import VSUP + import numpy as np + import matplotlib.pyplot as plt + except ImportError: + return mo.md("Packages are still loading, please wait a moment.") + + # Create a grid of values and uncertainties for better visualization + n_points = 50 + step = 1/n_points + values = np.linspace(step/2, 1-step/2, n_points) + uncertainties = np.linspace(step/2, 1-step/2, n_points) + + # Create a 2D grid + values, uncertainties = np.meshgrid(values, uncertainties) + + # Colorize the data + size = 9 + fig, axs = plt.subplots(3, 3, figsize=(size, size)) + + for row, quantization in zip(axs, [None, 'linear','tree']): + for ax, mode in zip(row, ["us", "ul", "usl"]): + + vsup = VSUP(palette=palette, mode=mode, quantization=quantization) + + colors = vsup(values, uncertainties) + ax.pcolormesh(values, uncertainties, colors) + # ax.set_title(f"{mode}") #\n({description})") + ax.set_xlabel("Value") + ax.set_ylabel("Uncertainty") + + fig.suptitle(f"VSUP: {palette} palette") + plt.tight_layout() + return fig + +func = palette_not_selected if not palette.value else lambda : showcase_palette(palette.value) +func() +``` + +## Features + +- Three visualization modes: + - USL: Uncertainty mapped to Saturation (chroma) and Lightness + - US: Uncertainty mapped to Saturation + - UL: Uncertainty mapped to Lightness +- Two quantization mods: + - Linear: independent binning of values and uncertainties + - Tree: value bins depend on uncertainty bin: lower uncertainty, higher value resolution +- Support for any matplotlib and seaborn colormaps + +## Citation + +If you use this package in your research, please cite the original VSUP paper: + +``` +@inproceedings{2018-uncertainty-palettes, + title = {Value-Suppressing Uncertainty Palettes}, + author = {Michael Correll AND Dominik Moritz AND Jeffrey Heer}, + booktitle = {ACM Human Factors in Computing Systems (CHI)}, + year = {2018}, + url = {http://idl.cs.washington.edu/papers/uncertainty-palettes}, +} +``` + +## License + +MIT License diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..09cb335 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,28 @@ +site_name: VSUP + +theme: + name: "material" + +repo_name: VSUP +repo_url: https://github.com/JohnGoertz/vsup +site_url: https://JohnGoertz.github.io/vsup + +plugins: +- search +- marimo + +markdown_extensions: + - admonition + - pymdownx.details + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences + - pymdownx.arithmatex: + generic: true + +nav: + - Overview: index.md From db05c2d134bb6eacfd059118a016aa294800236e Mon Sep 17 00:00:00 2001 From: Will Dean Date: Tue, 3 Jun 2025 12:48:47 -0400 Subject: [PATCH 2/5] basic docs setup --- docs/index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index df13c50..7b4dc1b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -56,7 +56,6 @@ for row, quantization in zip(axs, [None, 'linear','tree']): ## Example - ```python {marimo} import marimo as mo From b60346a3ddc2c0c7a83ef9015690e203d3809e79 Mon Sep 17 00:00:00 2001 From: Will Dean Date: Tue, 3 Jun 2025 12:50:48 -0400 Subject: [PATCH 3/5] embed link like in readme --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 7b4dc1b..6c5441f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,6 @@ # VSUP: Value-Suppressing Uncertainty Palettes -A Python package for visualizing data with uncertainty using Value-Suppressing Uncertainty Palettes (VSUPs). Inspired by https://github.com/uwdata/vsup. +A Python package for visualizing data with uncertainty using Value-Suppressing Uncertainty Palettes (VSUPs). Inspired by [https://github.com/uwdata/vsup](https://github.com/uwdata/vsup). ## Installation From 79531df2c10efeed0e148d5690f65531c71bfa79 Mon Sep 17 00:00:00 2001 From: Will Dean Date: Tue, 3 Jun 2025 12:55:38 -0400 Subject: [PATCH 4/5] action to push up docs --- .github/workflows/docs.yml | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 .github/workflows/docs.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..62a01f4 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,21 @@ +--- +name: Docs +on: + push: + branches: + - master + - main +permissions: + contents: write +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + - run: pip install mkdocs mkdocs-marimo mkdocs-material + - run: mkdocs gh-deploy --force From 9a1e87b2ceaaa02dea6fa8ef8eb0fca14a902abf Mon Sep 17 00:00:00 2001 From: Will Dean Date: Tue, 3 Jun 2025 13:02:06 -0400 Subject: [PATCH 5/5] take the same code from README" --- docs/index.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/index.md b/docs/index.md index 6c5441f..1b2a3be 100644 --- a/docs/index.md +++ b/docs/index.md @@ -33,9 +33,9 @@ import matplotlib.pyplot as plt # Create a grid of values and uncertainties for better visualization n_points = 50 -step = 1/n_points -values = np.linspace(step/2, 1-step/2, n_points) -uncertainties = np.linspace(step/2, 1-step/2, n_points) +step = 1 / n_points +values = np.linspace(step / 2, 1 - step / 2, n_points) +uncertainties = np.linspace(step / 2, 1 - step / 2, n_points) # Create a 2D grid values, uncertainties = np.meshgrid(values, uncertainties) @@ -43,13 +43,13 @@ values, uncertainties = np.meshgrid(values, uncertainties) # Colorize the data axs = plt.subplots(3, 3, figsize=(9, 9))[1] -for row, quantization in zip(axs, [None, 'linear','tree']): +for row, quantization in zip(axs, [None, "linear", "tree"]): for ax, mode in zip(row, ["us", "ul", "usl"]): - - vsup = VSUP(palette='flare', mode=mode, quantization=quantization) + vsup = VSUP(palette="flare", mode=mode, quantization=quantization) colors = vsup(values, uncertainties) ax.pcolormesh(values, uncertainties, colors) + # ax.set_title(f"{mode}") #\n({description})") ax.set_xlabel("Value") ax.set_ylabel("Uncertainty") ```