README.md

Bundleview Visualization

A d3 implementation of bundleviews.

Try it yourself!

A Primer on 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.

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.

Installation

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.

Usage

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 and relations.
• 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 a label displayed in the visualization.
  • All non-leaf nodes have the children attribute, while leaf nodes have the attributes 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.
• relations describe the inner bundle layout.
  • Relations only refer to the ids of leaf nodes as source and target.

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');

Contribute

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

Issues?

If you find a bug or have a feature request, please open an issue. Or consider contributing to the project.

Roadmap

A collection of future work items prioritized by feasibility, with near future items first and more visionary items later.

Data Validator

Check input data and provide meaningful warnings and error messages.

Deal with empty Directories

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": []
}

Dynamic Data

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.

Attributes for relations

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: