Name: setcola
Owner: UW Interactive Data Lab
Description: High-Level Constraints for Graph Layout
Created: 2018-04-10 22:27:36.0
Updated: 2018-05-12 18:11:57.0
Pushed: 2018-05-11 22:11:48.0
Homepage: https://uwdata.github.io/setcola/
Size: 333
Language: JavaScript
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
SetCoLa is a domain-specific language for specifying high-level graph layout constraints relative to properties of the underlying graph. This repository contains a SetCoLa compiler that generates constraints for WebCoLa and includes an online graph editor.
If you are interested in this work, please see our EuroVis 2018 research paper and consider citing our work:
roceedings{2016-setcola,
title = {SetCoLa: High-Level Constraints for Graph Layout},
author = {Jane Hoffswell AND Alan Borning AND Jeffrey Heer},
booktitle = {Computer Graphics Forum (Proc. EuroVis)},
year = {2018},
url = {http://idl.cs.washington.edu/files/2018-SetCoLa-EuroVis.pdf},
A SetCoLa specification is defined by multiple constraint definitions that specify the desired behavior for the graph layout and may include a set of “guides” (reference elements that serve as positional anchors), which is a list of nodes that include an “x” and/or “y” property. Each constraint definition includes a set definition and constraint application, which may apply one or more constraints to the element of each set.
There are four ways to define sets in SetCoLa: partitioning nodes into sets, specifying sets with predicates, collecting nodes using keys, and composing previously defined sets.
This strategy partitions all the nodes into disjoint sets based on the value of the partitionProperty of the node. You may also specify a list of values to include or exclude, which checks for those values explicitly when completing the partition.
rtition": "partitionProperty", "include": [...], "exclude": [...]}
This strategy defines explict sets based on a predicate on the graph nodes. You may refer to properties of the node using dot syntax. The (optional) name for the set allows you to refer to this set later in the specificaiton.
xpr": "node.color === 'red' || node.color === 'blue'", "name": "setName"}, ...]
This strategy generates sets by identify node keys. Sets generated in this way may not be disjoint.
llect": ["node", "node.neighbors"]}
In the above example, we extract the _id from all the identified nodes and create a set that contains all the identified nodes. In other words, for each node in the graph, we create a set that contains the node and all of its neighbors.
This strategy allows for the hierarchical composition of sets by composing previously defined sets into a new set.
tName"]
In the above example, we create a new set that contains one element: the set named "setName".
There are currently 7 constraint types supported in SetCoLa: alignment, position, order, circle, cluster, hull, and padding.
alignmentnstraint": "align", "axis": "x", "orientation": "center"}
The axis along which to align the nodes can be defined as x or y.
The orientation can be defined as center, left, right, top, or bottom.
positionnstraint": "position", "position": "left", "of": "right_border", "gap": 20}
This constraint positions all the nodes in each set to the left of the guide right_border.
The position can be defined as left, right, above, or below.
The (optional) gap property defines the minimum amount of space between the node and guide.
ordernstraint": "order", "axis": "x", "by": "nodeProperty", "order": [2, 3, 1, 0], "reverse": true, "band": 200}
The axis along which to order the nodes can be defined as x or y.
The property by determines which nodeProperty to use for the order.
The (optional) order property explicitly sets the order that should be used and reverse reverses the sort order.
The (optional) band defines the amont of space that each section of the order should take up.
circlenstraint": "circle", "around": "center", "radius": 10}
Adds additional edges to approximate a circle layout. around can be either center or the name of a guide. The radius determines the size of the circle.
clusternstraint": "cluster"}
Encourages the nodes to cluster together by introducing additional edges.
hullnstraint": "hull"}
Adds an enclosing boundary around the nodes.
paddingnstraint": "padding", "amount": 5}
Adds amount padding around the nodes. Note: At this time, this constraint can only apply to any given node once.
The basic usage of the SetCoLa compiler is shown below. This behavior is demonstrated in the file editor.js.
result = setcola
odes(graph.nodes) // Set the graph nodes
inks(graph.links) // Set the graph links
roups(groups) // (Optional) Set any predefined groups in the graph
uides(guides) // (Optional) Define any guides that are used by the SetCoLa layout
onstraints(setcolaSpec) // Set the constraints
ap(gap) // The default gap size to use for generating the constraints (if not specified in the SetCoLa spec)
ayout(); // Run the layout to convert the SetCoLa constraints to WebCoLa constraints
The call setcola.layout() returns a layout in the following form:
lt = {
odes": [...], // The output nodes (note: this may contain more nodes than originally input)
inks": [...], // The output links (note: this may contain more links than originally input)
uides": [...], // The SetCoLa guides
roups": [...], // The output WebCoLa groups
onstraints": [...], // The output WebCoLa constraints
onstraintDefs": [...] // The original SetCoLa constraints
This output can then be used to produce the actual graph layout using WebCoLa. For more information on WebCoLa, please check out the website. The basic usage of WebCoLa is shown below and demonstrated in the file renderer.js.
la
.nodes(result.nodes)
.links(result.links)
.constraints(result.constraints)
.avoidOverlaps(true)
.start(10,15,20);
This is a small SetCoLa example that shows how to create a simple tree layout.
he SetCoLa constraints
setcolaSpec = [
"name": "layer",
"sets": {"partition": "depth"},
"forEach": [{"constraint": "align", "axis": "x"}]
"name": "sort",
"sets": ["layer"],
"forEach": [{"constraint": "order", "axis": "y", "by": "depth"}]
When applied to this graph:
graph = {
odes": [
{"name": "a"}, {"name": "b"},
{"name": "c"}, {"name": "d"},
{"name": "e"}, {"name": "f"}
inks": [
{"source": 0, "target": 1},
{"source": 0, "target": 2},
{"source": 1, "target": 3},
{"source": 2, "target": 4},
{"source": 2, "target": 5}
SetCoLa produces the following layout:
For more examples, please take a look at our online graph editor.
To produce the SetCoLa compiler module on your local machine, use the following command rollup -c. This command will produce the file dist/setcola.js. You can then host the website locally on a mac using the command python -m SimpleHTTPServer 8080.