uwdata/draco

Visualization Constraints and Weight Learning

Formalizing Visualization Design Knowledge as Constraints

This reporsitory contains the source for the original Draco project. We develop a much improved Draco 2 at https://github.com/cmudig/draco2.

Draco is a formal framework for representing design knowledge about effective visualization design as a collection of constraints. You can use Draco to find effective visualization visual designs in Vega-Lite. Draco's constraints are implemented in based on Answer Set Programming (ASP) and solved with the Clingo constraint solver. We also implemented a way to learn weights for the recommendation system directly from the results of graphical perception experiment.

Read our introductory blog post about Draco and our research paper for more details. Try Draco in the browser at https://uwdata.github.io/draco-editor.

Status

There Be Dragons! This project is in active development and we are working hard on cleaning up the repository and making it easier to use the recommendation model in Draco. If you want to use this right now, please talk to us. More documentation is forthcoming.

Overview

This repository currently contains:

• draco (pypi) The ASP programs with soft and hard constraints, a python API for running Draco, the CLI, and the python wrapper for the draco-core API. Additionally includes some helper functions that may prove useful.
• draco-core (npm) Holds a Typescript / Javascript friendly copy of the ASP programs, and additionally, a Typescript /Javascript API for all the translation logic of Draco, as described below.

Sibling Repositories

Various functionality and extensions are in the following repositories

• draco-vis

  • A web-friendly Draco! Including a bundled Webassembly module of Draco's solver, Clingo.

• draco-learn

  • Runs a learning-to-rank method on results of perception experiments.

• draco-tools

  • UI tools to create annotated datasets of pairs of visualizations, look at the recommendations, and to explore large datasets of example visualizations.

• draco-analysis

  • Notebooks to analyze the results.

Draco API (Python)

In addition to a wrapper of the Draco-Core API describe below, the python API contains the following functions.

object Result <>

The result of a Draco run, a solution to a draco_query. User result.as_vl() to convert this solution into a Vega-Lite specification.

run (draco_query: List[str] [,constants, files, relax_hard, silence_warnings, debug, clear_cache]) -> Result: <>

Runs a draco_query, defined as a list of Draco ASP facts (strings), against given file asp programs (defaults to base Draco set). Returns a Result if the query is satisfiable. If relax_hard is set to True, hard constraints (hard.lp) will not be strictly enforced, and instead will incur an infinite cost when violated.

is_valid (draco_query: List[str] [,debug]) -> bool: <>

Runs a draco_query, defined as a list of Draco ASP facts (strings), against Draco's hard constraints. Returns true if the visualization defined by the query is a valid one (does not violate hard constraints), and false otherwise. Hard constraints can be found in hard.lp.

data_to_asp (data: List) -> List[str]: <>

Reads an array of data and returns the ASP declaration of it (a list of facts).

read_data_to_asp (file: str) -> List[str]: <>

Reads a file of data (either .json or .csv) and returns the ASP declaration of it (a list of facts).

Draco-Core API (Typescript / Javascript)

vl2asp (spec: TopLevelUnitSpec): string[] <>

Translates a Vega-Lite specification into a list of ASP Draco facts.

cql2asp (spec: any): string[] <>

Translates a CompassQL specification into a list of ASP Draco constraints.

asp2vl (facts: string[]): TopLevelUnitSpec <>

Interprets a list of ASP Draco facts as a Vega-Lite specification.

data2schema (data: any[]): Schema <>

Reads a list of rows and generates a data schema for the dataset. data should be given as a list of dictionaries.

schema2asp (schema: Schema): string[] <>

Translates a data schema into an ASP declaration of the data it describes.

constraints2json (constraintsAsp: string, weightsAsp?: string): Constraint[] <>

Translates the given ASP constraints and matching weights (i.e. for soft constraints) into JSON format.

json2constraints (constraints: Constraint[]): ConstraintAsp <>

Translates the given JSON format ASP constraints into ASP strings for definitions and weights (if applicable, i.e. for soft constraints).

User Info

Installation

Python (Draco API)

Install Clingo

You can install Clingo with conda: conda install -c potassco clingo. On MacOS, you can alternatively run brew install clingo.

Install Draco (Python)

pip install draco

Typescript / Javascript (Draco-Core API)

STOP! If you wish to run Draco in a web browser, consider using draco-vis, which bundles the Clingo solver as a WebAssembly module. The Draco-Core API does not include this functionality by itself. It merely handles the logic of translating between the various interface languages.

yarn add draco-core or npm install draco-core

Developer Info

Installation

Install Clingo.

You can install Clingo with conda: conda install -c potassco clingo. On MacOS, you can alternatively run brew install clingo.

Install node dependencies

yarn or npm install

You might need to activate a Python 2.7 environment to compile the canvas module.

Build JS module

yarn build. We are currently using typescript version 3.2.1 and greater.

Python setup

pip install -r requirements.txt or conda install --file requirements.txt

Install Draco in editable mode. We expect Python 3.

pip install -e .

Now you can call the command line tool draco. For example draco --version or draco --help.

Tests

You should also be able to run the tests (and coverage report)

python setup.py test

Run only ansunit tests

ansunit asp/tests.yaml

Run only python tests

pytest -v

Test types

mypy draco tests --ignore-missing-imports

Running Draco

End to end example

To run Draco on a partial spec.

sh run_pipeline.sh spec

The output would be a .vl.json file (for Vega-Lite spec) and a .png file to preview the visualization (by default, outputs would be in folder __tmp__).

Use CompassQL to generate examples

Run yarn build_cql_examples.

Run Draco directly on a set of ASP constraints

You can use the helper file asp/_all.lp.

clingo asp/_all.lp test.lp

Alternatively, you can invoke Draco with draco -m asp test.lp.

Run APT example

clingo asp/_apt.lp examples/example_apt.lp --opt-mode=optN --quiet=1 --project -c max_extra_encs=0

This only prints the relevant data and restricts the extra encodings that are being generated.

Releases

• Make sure everything works!
• Update __version__ in draco/__init__.py and use the right version below.
• git commit -m "bump version to 0.0.1"
• Tag the last commit git tag -a v0.0.1.
• git push and git push --tags
• Run python setup.py sdist upload.

Resources

Related Repositories

Previous prototypes

• https://github.com/domoritz/vis-csp
• https://github.com/domoritz/vis-constraints

For a bit of historical perspective, after building Compass and CompassQL with @kanitw, @domoritz worked with colleagues at UW on a first constraint-based prototype vis-csp in ASP, then tried Z3 in vis-constraints before going back to ASP for Draco.

Related software

• https://github.com/uwdata/draco-vis
• https://github.com/vega/compassql
• https://github.com/potassco/clingo

Guides

• https://github.com/potassco/guide/releases/

draco's Issues

Write features with data size

Skew

• Add a soft constraint not to add zero when the difference between min and max is less than the distance to 0.
• Discourage line or area without aggregation when the size of the data is larger than the size of the ordinal axis

Add importance to data fields

Users should be able to express whether a field is considered important or not.

Options for adding this are

• A flag to indicate whether a field is important
• A score
• A total order
• Preferences (foo > bar)

Fix outputs

For example, bin: 3 is not valid.

Use different levels of constraints

Some constraints may not be strict but should be above the soft constraints. I don't have time to add this anytime soon, though.

Scale weights

To be between -1000 and +1000.

Write tests for python code

Evaluation

• Can we learn all good visualizations? We may miss important soft constraints so we cannot recommend certain charts.
• Can we recommend the top 10 visualizations from http://viziometrics.org/?
• Do we beat CompassQL in human ratings?

Refactor code

We should aim to not rely too much on files in our APIs. It makes it really hard to write in memory algorithms. Instead, we should mooe around in-memory objects and handle IO separately. I added a few TODOs in the code to show where I see problems.

UI to ask the user for labels

Write learning algorithm

API to check specs

Check only against hard constraints.

Encoding is an array in queries

Simplify react app

Use a single app without ejecting.

Process bahador's data

Inspecting how to sample solutions from partial spec

Given a partial spec, and a set of hard constraints, sample from the set of all possible full specs that satisfies these hard constraints.

Don't stack and bin at the same time

remove scale

Support sort

Sort scales as feature

Write up the algorithms

Add data, task and spec to ui

MLN with ranking

Simplify view

We could use https://vega.github.io/vega/usage/#view instead of creating an SVG and inlining that.

Active learning

Figure out what pairs of visualization we should ask an expert for labels.

Test with schema

Data gen issues

(I will keep adding to this list)

• We don't support square mark types (I just added a constraint for that)
• Prefer to generate aggregation together with lines and area unless its q q (I'm adding soft constraints to learn this)

Test CLI

http://dustinrcollins.com/testing-python-command-line-apps

View visualizations by feature

A simple viewer where we can look at visualizations and see what soft constraints they violate.

Use proper temp dir

https://docs.python.org/3.6/library/tempfile.html

Create pairs

We need pairs that we can ask the user for labels. These pairs should cover interesting correlations.

Interface to pass weights to clingo

Running 'run_pipeline.sh examples/ab.json' produces wrong result

Running run_pipeline.sh examples/ab.json results in a bad result:

The field of encoding e0 is "e1" in the generated file, where "e1" is an encoding id not a field.

The result is supposed to be either a or b for the field.

FYI, soft constraints generated:

% ====== Data definitions ======
fieldtype(a,string).
cardinality(a,3).

fieldtype(b,number).
cardinality(b,6).

% ====== Query constraints ======
mark(bar).

encoding(e0).
channel(e0,x).
:- not field(e0,_).
:- not type(e0,_).
%0 { log(e0) } 1.
%0 { zero(e0) } 1.

encoding(e1).
channel(e1,y).
:- not field(e1,_).
type(e1,quantitative).
aggregate(e1,max).
%0 { log(e1) } 1.
%0 { zero(e1) } 1.

Generated full spec:

{                                                                                                                                              
    "$schema": "https://vega.github.io/schema/vega-lite/v2.0.json",
    "data": {
        "url": "examples/data/ab.csv"
    },
    "encoding": {
        "x": {
            "field": "e1",
            "type": "ordinal"
        },
        "y": {
            "aggregate": "max",
            "field": "b",
            "scale": {
                "zero": true
            },
            "type": "quantitative"
        }
    },
    "mark": "bar"
}

Data Gen Issues

• Better way to generate 'stack' (maybe hard constraints will help)
• D(x) x D(y) x Q(other) should have examples with agg on other
• special case for type when generating
• too many channel-channel
• support count

Get clingo in homebrew

Capture interaction between x/y channels and row/col

Bad in labeler

left, right, both are bad. Red color.

Implement a way to get the number of violating soft constraints

Use clyngor

Task

task - mark
task - channel

Rename methods

For example, load_from_vl_json should be load_query_from_json

Generate feature vecors in parallel

Speed up development

Create good input/output examples

Use CompassQL.

• @domoritz starts with 3-5
• @Mestway adds more afterwards.

Fix setup

Don't ship with binary

Hard constraints

• Don't use bar with just d
• Don't use rule with only x or y
• rule and tick need q
• do not use negative values for size
• size should have high preference for zero, even with bin
• don't allow row without y, column without x
• stack can only have one continuous and it has to be on x or y
• only allow dates to be used for temporal (no string or number)
• we overlap bars when we don't have an ordinal and only q

Write more soft constraints

Get bugs

Get a list of wrong predictions. Quickly view them.

Fix scale.zero and scale.type: log

We should be parsing this spec correctly. Right now, we expect zero and log not to be nested under scale.

{
    "encoding": {
        "x": {
            "bin": 10,
            "field": "horsepower",
            "type": "quantitative"
        },
        "y": {
            "aggregate": "count",
            "scale": {
                "zero": True
            },
            "type": "quantitative"
        }
    },
    "mark": "bar"
}

Explain the algorithm more

• How do we do online learning
• How does our algo compare to existing ones

Data gen