GraphScape

(Last Update: 2021-05-20)

GraphScape(paper) is a directed graph model of the visualization design space that supports automated reasoning about visualization similarity and sequencing. It uses the Vega-Lite language to model individual charts. This repository contains source code for building GraphScape models and automatically recommending sequences of charts.

• APIs
  • .sequence
  • .transition
  • .apply
  • .path
• Sequence Recommender Web Application
• Development Instructions
• Cite Us!

APIs

# graphscape.sequence(charts, options[, editOpSet, callback]) <>

Generate recommended sequence orders for a collection of Vega-Lite charts. The return value is a ranked array of potential sequences and associated metadata.

Input

Parameter	Type	Description
charts	Array	An array of Vega-Lite unit charts.
options	Object	{ "fixFirst": true / false } fixFirst: indicates whether the first chart in charts should be pinned as the first chart of the recommended sequence (true) or not (false).
editOpSet	Object	(Optional) Specifies custom rules for calculating sequence costss
callback	Function	(Optional) function(result) { ... } A callback function to invoke with the results.

Output

The output is a ranked array of objects, each containing a sequence ordering and related metadata.

Property	Type	Description
charts	Array	The given input charts. If options.fixFirst was false, a null specification for an empty chart is included as the first entry.
sequence	Array	Order of indexes of input charts.
transitions	Array	Transitions between each pair of two adjacent charts with id.
sequenceCost	Number	Final GraphScape sequence cost.
sumOfTransitionCosts	Number	Sum of transition costs.
patterns	Array	Observed patterns of the sequence. Each pattern is consist of pattern, appear, coverage, and patternScore. pattern : An array of transition ids composing the pattern. appear : An array of indexes of transitions where the pattern appears in the sequence. coverage : How much the pattern cover the sequence. patternScore : Final pattern score, which is the same as coverage now.
globalWeightingTerm	Number	Global weighting term.
filterSequenceCost	Number	Filter sequence cost.
filterSequenceCostReasons	Array	Sum of filter value change score Increment of value : +1 Decrement of value : -1 Otherwise : 0

Sample Code (node.js)

const gs = require('./graphscape.js')
const charts = []; // an array of Vega-Lite charts
charts.push({
  "data": {"url": "data/cars.json"},
  "mark": "point",
  "encoding": {
    "x": {"field": "Horsepower","type": "quantitative"},
  }
});
charts.push({
  "data": {"url": "data/cars.json"},
  "mark": "point",
  "encoding": {
    "x": {"field": "Horsepower","type": "quantitative"},
    "y": {"field": "Miles_per_Gallon","type": "quantitative"}
  }
});
const options = { "fixFirst": false };
console.log(gs.sequence(charts, options));

# graphscape.transition(source chart, target chart) <>

Generate a transition from a source Vega-Lite chart to a target Vega-Lite chart. The transition has the minimum edit operation costs.

Input

Parameter	Type	Description
source chart	Object	A Vega-Lite unit chart.
target chart	Object	A Vega-Lite unit chart.

Output

The output is a ranked array of objects, each containing a sequence ordering and related metadata.

Property	Type	Description
mark	Array	Edit operations in mark category.
transform	Array	Edit operations in transform category.
encoding	Array	Edit operations in encoding category.
cost	Number	Sum of all costs of edit operations in this transition.

Sample Code (node.js)

const gs = require('./graphscape.js')
const source = {
  "data": {"url": "data/cars.json"},
  "mark": "point",
  "encoding": {
    "x": {"field": "Horsepower","type": "quantitative"},
  }
};
const target = {
  "data": {"url": "data/cars.json"},
  "mark": "point",
  "encoding": {
    "x": {"field": "Horsepower","type": "quantitative"},
    "y": {"field": "Miles_per_Gallon","type": "quantitative"}
  }
};

console.log(gs.transition(source, target));

# graphscape.apply(startChart, endChart, editOps) <>

Applies edit operations on the start chart to synthesize the intermeidate chart between the start and end. The edit operations should be provided with the corresponding end chart.

Input

Parameter	Type	Description
startChart	Vega-Lite Spec	The start chart that the edit operations are applied to.
editOps	Array	Edit operations between the start and end charts. Users can get these by .transition.
endChart	Vega-Lite Spec	The end chart. The given edit operations should be extracted from the transition between the start and end.

Output

A Vega-Lite Spec.

Sample Code (node.js)

const gs = require('./graphscape.js')
const startVL = {
  "$schema": "https://vega.github.io/schema/vega-lite/v4.json",
  "data": {"url": "data/penguins.json"},
  "mark": "point",
  "encoding": {"x": {"field": "A", "type": "nominal"}}
};
const endVL = {
  "$schema": "https://vega.github.io/schema/vega-lite/v4.json",
  "data": {"url": "data/penguins.json"},
  "mark": "point",
  "encoding": {
    "y": {"field": "A", "type": "quantitative", "aggregate": "mean" }
  }
};
const transition = await gs.transition(startVL, endVL);
const chart = gs.apply(startVL, endVL, transition.encoding)
console.log(chart);
/*
{
  "$schema": "https://vega.github.io/schema/vega-lite/v4.json",
  "data": {"url": "data/penguins.json"},
  "mark": "point",
  "encoding": {"y": {"field": "A", "type": "quantitative"}}
}
*/

# graphscape.path(startChart, endChart, M) <>

Recommends paths (chart sequences) from the start to the end with M transitions. Each path will have M+1 charts. Unlike .sequence, it generates intermediate charts for given two ends.

Input

Parameter	Type	Description
startChart	Vega-Lite Spec	The start chart for paths.
endChart	Vega-Lite Spec	The end chart for paths.
M	Inteager	The number of transitions for the paths. If M is undefined, it returns all possible paths.

Output

If M is specified, it returns a path array (Array<Path>). If not, it returns object having possible Ms and corresponding paths as keys and values({ "1": Array<Path>, "2": ..., ...})

Each path has these properties:

{
  "sequence": [startChart, ..., endChart ],
  // The partition of the edit operations from the start and the end.
  "editOpPartition": [editOpArray1, ..., editOpArrayM],

  "eval": {
    // GraphScape's heuristic evaluation score for this path. Higher means better.
    "score": 1, //Number
    "satisfiedRules": ... // The reasons for the scores.
  }
}

Sample Code (node.js)

const gs = require('./graphscape.js')
const startVL = {
  "$schema": "https://vega.github.io/schema/vega-lite/v4.json",
  "data": {"url": "data/penguins.json"},
  "mark": "point",
  "encoding": {"x": {"field": "A", "type": "nominal"}}
};
const endVL = {
  "$schema": "https://vega.github.io/schema/vega-lite/v4.json",
  "data": {"url": "data/penguins.json"},
  "mark": "point",
  "encoding": {
    "y": {"field": "A", "type": "quantitative", "aggregate": "mean" }
  }
};
const paths = await gs.path(startVL, endVL);
console.log(paths)

*More details of the implementation will be available in here(TBD).

Sequence Recommender Web Application

The app/ folder contains a sequence recommender web application. Given a set of input Vega-Lite specifications, it produces a recommended sequence intended to improve chart reading and comprehension. To run this app, first you should install bower components:

$ cd app
$ bower install

Next, launch a local webserver to run the application. For example:

$ python -m SimpleHTTPServer 9000 # for Python 2
$ python -m http.server 9000 # for Python 3

To use a custom build of graphscape.js, copy your new graphscape.js file and paste it into the app/js folder.

Development Instructions

1. MATLAB is required to solve lp.m.
2. Install npm dependencies via npm install.
3. You can customize rankings of edit operations by modifying lp.js and running the following commands:

$ cd src/rule
$ node lp.js
$ matlab < lp.m
$ node genEditOpSet.js # This will generate editOpSet.js.

# After creating your rankings, you must re-build `graphscape.js` to apply changes.
$ cd
$ npm run test
$ npm run build

Cite us!

If you use GraphScpae in published research, please cite this paper.