Code for generating Value-Suppressing Uncertainty Palettes for use in D3 charts.
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Reverting example to look like what's in the paper. Apr 19, 2018
screenshots Legend docs Apr 20, 2018
src Format with prettier Apr 20, 2018
test More blending modes Apr 18, 2018
.eslintrc Added linting config Apr 5, 2018
.gitignore D3 v5 Apr 5, 2018
.npmignore Add npmignore and prepublish script Apr 5, 2018
.travis.yml Fix travis Apr 5, 2018
LICENSE Initial commit Jan 3, 2018 Update Jun 29, 2018
demo.png Add files via upload Jun 29, 2018
package.json Upgrade deps Jun 13, 2018
rollup.config.js D3 v5 Apr 5, 2018
yarn.lock Upgrade deps Jun 13, 2018

Value-Suppressing Uncertainty Palettes (VSUPs)

npm version Build Status

Code for generating Value-Suppressing Uncertainty Palettes for use in D3 charts. Read more about VSUPs in our introductory blog post and our research paper.


These examples are served from the examples directory.


If you use this module for a publication, please cite VSUPs as:

 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 = {},


yarn add vsup or include the library directly from jsdelivr as

<script src=""></script>


Quantization <>

A quantization defines how values or objects of the form {u: number, v: number} (uncertainty and value) are quantized. They are used instead of a domain in VSUP scales.

This module supports three different quantizations: linearQuantization, squareQuantization, and quantization.


This is a wrapper around d3.scaleQuantize.


Defines a quantization into a rectangular matrix of value and uncertainty.

The constructor takes a single argument n, the number of rows and columns.

var q = vsup.squareQuantization(3);

q is then a function that can be used to discretize uncertainties and values.

> q(0.2,0.1);
{u: 0, v: 0.16666666666666666}

The quantization has the following methods:

  • range
  • n
  • matrix
  • data
  • uncertaintyDomain
  • valueDomain


Similar to squareQuantization but creates a tree quantization. The constructor takes two arguments branchingFactor and treeLayers.

The quantization has the following methods:

  • range
  • branching
  • layers
  • tree
  • data
  • uncertaintyDomain
  • valueDomain

Scales <>

The interface to create a scale mirrors scales in D3. The difference of VSUP scales is that they use a quantization instead of a domain. The range can be set to any color range.

The constructor takes three optional arguments: mode (usl, us, ul), range, and quantization. It returns a function that takes two arguments value and uncertainty.

For example

var s = vsup.scale();

s is now a function that takes two arguments

> s(0.8, 0.1);
"rgb(137, 214, 99)"

The scale has the following methods:

  • range to get or set the color range (e.g. d3.interpolateViridis)
  • colorList
  • colorDists
  • mode
  • quantize

Legends <>

This module implements three kinds of legends (simpleLegend, heatmapLegend, and arcmapLegend) corresponding to the three quantization types.

To add a legend to the DOM, create a legend and attach it to an element. For example:

var legend = vsup.legend().arcmapLegend();

You can find example code in test/legend.html.


A simple legend for linear quantizations.


A rectangular legend for tree quantization or square quantization.


A legend for a tree quantization.


Make a new release

  • Test the examples in test
  • yarn version
  • npm publish
  • git push --tags