A d3 implementation of bundleviews.
Bundleviews are a visualization technique that uses an inverted radial layout to visualize hierarchical data (like software projects). In addition to the hierarchical data, relations between data entries are visualized using hierarchical edge bundles. This allows to cluster dependencies along hierarchies, ultimately revealing higher-level dependencies:
Using the bundling strength, we can provide a trade-off between low-level and high-level insights based on adjacent relations. The bundling strength increases from left to right in the above example.
See and play with some examples.
Using bundleviews we are able to interactively explore our data and thereby reveal interesting pattern. Here we take a look at the flare visualization library:
In the above example, the visualization reveals that any class in flare's physics module is only imported by the class ForeDirectedLayout.
If you just want to use the visualization, read the following instructions. If you instead want to contribute, see here.
Clone the repository and init the contained submodules:
git clone --recursive https://github.com/onsetsu/d3-bundleview.git
cd d3-bundleview
Next, start a local http server, e.g. if you still have Python 2.7:
serverNoCache.py
Then, point your browser (preferably newer versions of Chrome) to the project's index page http://localhost:8080/index.html
.
To visualize your own data sets, they have to be in a certain json format. Here is a simplified example:
{
"nodes": {
"id": 0,
"label": "",
"children": [
// some nesting level later
{
"id": 3,
"label": "app.js",
"attributes": {
"rloc": 162,
"cyclomatic complexity": 4
}
},
// ...
{
"id": 34,
"label": "lib.js",
"attributes": {
"rloc": 367,
"cyclomatic complexity": 16
}
},
// ...
]
},
"relations":[
{
"source":3,
"target":34
},
// ...
]
}
Notes:
- The json root has only two fields:
nodes
andrelations
. nodes
describe the hierarchical tree structre used to create the outer radial layout.- All nodes have to have a unique
id
and optionally can have alabel
displayed in the visualization. - All non-leaf nodes have the
children
attribute, while leaf nodes have theattributes
map instead.attributes
contain a map from a nemed metric to a number or a string. Each attribute must be present in each leaf node.
- All nodes have to have a unique
relations
describe the inner bundle layout.- Relations only refer to the
id
s of leaf nodes assource
andtarget
.
- Relations only refer to the
To visualize your data, adjust the existing index.html
or write your own. There, import the visualization:
import { Bundleview } from 'path-to-vis/lib/bundleview.js';
Then, call the visualization's constructor with your fetched data as well as the selector of a parent element:
new Bundleview(dataJson, 'parent css selector');
If you are interested in contributing, first fork the repository into your userspace.
Then, clone the repo locally with initialized submodules:
git clone --recursive https://github.com/<USERNAME>/d3-bundleview.git
cd d3-bundleview
Then start a local http server, e.g. the included serverNoCache.py
.
Start editing and create pull requests.
Where do I start?
To get yourself into complex projects, it makes sense to apply common techniques of reverse engineering: Skim the most important files in a short period of time. Start with some refactorings, even if you haven't fully understand the project. That way you easily get a deeper understanding of what is going on and can make valuable contributions early on.
When you get stuck, do not hesitate to ask questions.
Important files:
- index.js: The main entrance point to the project. You build and configure your bundleview here.
- lib/bundleview.js: The main library file that contains all the logic used to create the bundleview, including layouts, path generation, and interactions.
- dbuggr.css, clusterview.css: Style sheets that control the appearance of nodes and relations, mostly used to control highlighting.
What contributions are valuable?
Everthing including, but not limited to:
- Refactorings
- Further real world data sets
- Performance Optimizations
- Items on the roadmap, preferably the top items
If you find a bug or have a feature request, please open an issue. Or consider contributing to the project.
A collection of future work items prioritized by feasibility, with near future items first and more visionary items later.
Check input data and provide meaningful warnings and error messages.
Right now, empty directories, i.e. nodes without an attributes
and children
field are not allowed. So, the following node would result in an error:
{
"id": 25,
"label": "dir",
"children": []
}
Dynamically add or remove nodes or relations in an existing bundleview. Note, that each insertion or deletion affects several aspects of the visualization, including metric boundaries, and therefore potentially all color and size scales.
Same as nodes, relations could also be attributed, with varying appearance based on certain metrics.
{
"source":3,
"target":34,
"attributes": {
"time": "2006-10-17",
"type": "commit"
}
}
According to these metrics, we can adjust the width and color(-gradient) of each node.
With this, we could for example visualize time-dependent interactions between hierarchical entities as in the corresponding paper: