Radial Bubble Tree

bubble tree screenshot

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.

Requirements

BubbleTree depends on the following JS libraries

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.

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

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

Display Properties

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". bubbleStyles* - Object that holds bubble style declarations, grouped into taxonomies.

Example:

config.bubbleStyles = {
    'cofog': BubbleTree.Styles.Cofog,
    'itb-function': BubbleTree.Styles.ItbFunction,
};

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' }
    }
}

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:

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

Tooltip integration

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

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

Basic setup

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.

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

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