Bubble Tree Documentation

The BubbleTree can be used to display hierarchical (spending) data in an interactive visualization. The setup is easy and independent from the OpenSpending platform. However, there is an optional integration module to connect with data from the OpenSpending API.

Contents:

• Requirements
• Setup
• Data format

Requirements

BubbleTree depends on the following JS libraries

• jQuery
• jQuery History
• jQuery Tooltip
• RaphaelJS
• TweenJS

Setup

Configuration vars

The constructor of the bubble chart takes just one argument, the configuration object which contains all settings that can be set. This section will cover all available configuration variables.

Example:

new BubbleTree.Loader({
    data: treeObj,
    container: '#bubbletree'
});

Data format

The BubbleTree expects the data in a linked tree structure. The core element in the tree are nodes which must at least consist of the properties label and amount:

rootNode = {
    label: "Total budget",
    amount: 1000000
}

The child nodes then are (recursivly) inserted within the children array.** **Note : At least three children should be added on all levels otherwise it gives an exception of amount/rightNode undefined. add dummy child with label 0 and amount 0.

rootNode = {
    label: "Total budget",
    amount: 1000000,
    children: [{
        label: "Health",
        amount: 650000
    }, {
        label: "Government",
        amount: 350000
    }]
}

You can also give the nodes unique identifier by setting the id property.

node = {
    id: "gov"
    label: "Government",
    amount: 350000
}

Another way to identify the nodes is to assign them to a taxonomy by setting the taxonomy and name properties.

node = {
    taxonomy: "cofog",
    name: "05.3",
    label: "Government",
    amount: 350000
}

HTML Integration

You need to tell the BubbleTree at which point in the container HTML the visualization should be inserted. To do this, simply set the container property in configuration. The container can be either a HTML DOM node or a jQuery selector String

• container - String, jQuery selector of the container element for the visualization, must be defined in HTML code, e.g. '#bubbletree'

Note: The container element must be defined in the HTML page, the BubbleTree won't create it itself.

Display Properties

• bubbleType - defines what class is used to render the bubbles. Possible values are plain, icon, donut. Can be either a String if the same type should be used for all bubbles or an array of strings if different bubble types should be used for different tree levels.

config.bubbleType = 'plain'

config.bubbleType = ['donut', 'icon', 'donut']; 

Custom Styling

It is possible to change the default display properties of each bubble by setting up bubble styles. Bubble styles can be defined once for each taxonomy (e.g. COFOG) or for individual node ids. By now, you can use bubble styles to change the colors that come out of the API or to set up icon images for the bubbleType "icon".

Example: Any node with the taxonomy "cofog1" would obtain the specified color and the icon:

config.bubbleStyles = {
    cofog1: {
        '01': { icon: 'government-uk.svg', color: '#C75746' },
        '02': { icon: 'defence.svg', color: '#0AB971' },
        '03': { icon: 'order-safety.svg', color: '#EC2406' }, 
        '04': { icon: 'social-systems.svg', color: '#790586' },
        '05': { icon: 'environment.svg', color: '#2A3A03' },
        '06': { icon: 'our-streets.svg', color: '#D33673' },
        '07': { icon: 'health.svg', color: '#4E6D00' },
        '08': { icon: 'culture.svg', color: '#938626' },
        '09': { icon: 'education.svg' },
        '10': { icon: 'helping-others.svg', color: '#935B3B' }
    }
};

There are two reserved words, that can't be used as taxonomy ids: id and name. Both are used to directly apply styles to bubbles which don't belong to any taxonomy. In the following example, a color is defined for the node with the id "root". Also, all nodes with the name "italy-toscana" will get the color #dd333.

config.bubbleStyles = {
    id: {
        'root': { color: '#cccccc' }
    },
    name: {
        'italy-toscana': { color: '#dd3333' }
    }
}

Bubble sorting

As per default the bubbles are sorted by amount in an alternating way: A,Z,B,Y,C,X,... with A-Z representing the bubbles sorted by amount in descending order. However, you can force sorting by label by setting the sortBy parameter to "label".

config.sortBy = 'label';

Appendix

Integration with OpenSpending API

If you want to connect the BubbleTree with OpenSpending data you might want to use the Aggregator class.

new Aggregator({
    apiUrl: "http://org/api",
    dataset: "cra",
    drilldowns: ["cofog1", "cofog2"],
    cuts: ['year:2008'],
    breakdown: 'region',
    callback: function(data) {
        new BubbleTree.Loader({
            data: data,
            container: '#bubbletree'
        });
    }
});

The following config variables can be used to change the data source:

• apiUrl - String, url of a running OpenSpending API instance, e.g. "http://org/api"
• dataset - String, name of the used dataset, e.g. "israel"
• drilldowns - Array of drilldown taxonomies, e.g. ['primary', 'section', 'entity']
• cuts - Array of filters?, e.g. ['year:2010']
• breakdown - String, taxonomy for sub-breakdowns as displayed in the donut bubbles, e.g. 'cofog1'

For local testing purposes you can also use locally cached api call results by setting the localApiCache property.

• localApiCache - String, url to a locally stored API output JSON

Tooltip integration

In the current implementation, tooltips are not part of the BubbleTree. Instead, the visualization provides a simple API for adding custom tooltips.

• initTooltip - function that will initialize the tooltip for a given bubble.

function initTooltip(node, bubble) {
    
}

Event Handler

The tooltip event handler can be set with the tooltipCallback property in the configuration (see above). The event handler must handle both the tooltip show and hide events. See index.html for an example implementation.

Event Properties

The following event properties are available

• type - can be "SHOW" or "HIDE"
• mousePos - object with numerical properties x and y, stores the actual mouse position at the time the tooltip event was thrown, relative to the container div
• bubblePos - same as mousePos, but stores the position of the bubble instead of the mouse
• node - the node of the bubble that is related to the tooltip event
• origEvent - the original event object as thrown by jQuery
• target - the related Bubble object

Basic setup

• Create an empty HTML page with a blank DIV in it that should be used as a container for the BubbleTree
• Include the required JS libraries, which are
  • jQuery 1.5.2 (http://www.jquery.org)
  • jQuery History (http://tkyk.github.com/jquery-history-plugin/)
  • RaphaelJS 1.5.2 (http://raphaeljs.com/)
  • Tween.js (https://github.com/sole/tween.js)
  • vis4.js (https://bitbucket.org/gka/vis4.js)
• todo: finish tutorial

Custom Taxonomy Styling (e.g. Icons)

Icon Specifications

The icons are stored in /icons/ folder in standard SVG format. However, there are some specifications to ensure that the visualization can use the icons correctly.

• the svg canvas should be 100px * 100px
• the icon itself must be stored in one or many SVG path elements. Every other SVG elements like will be ignored by the viz.
• the icon SVG must not be too large to keep the viz performance. SVG filesize of under 10kb are perfect, everything above 100kb should be avoided.
• the icon paths should not exceed the bubble size

Taxonomy to Icon Mapping

The icon filenames are arbitrary. The mapping between taxonomies and icons is done at JavaScript side by defining the bubbleStyle property in the configuration (see above), which is a three level nested dictionary

• taxonomy_id => nodeStyles
  • node_name => styles
    • styles is a dictionary of visual properties to their actual values, e.g. 'color' = '#dd0000'

Please see index.html and style.cofog.js for a working example.