Getting Started with D3.js

You are thinking about including some nice charts and graphics into your current project? Maybe you heard about D3.js, as some people claim it the universal JavaScript visualization framework. Maybe you also heard about a steep learning curve. Let’s see if this is really true!

First of all, what is D3.js?
D3.js is an open source JavaScript framework written by Mike Bostock helping you to manipulate documents based on data.

Okay, let’s first have a look at the syntax
Therefore, lets look at the following hello world example. It will append an <h1> element saying ‘Hello World!’ to the content <div> element.

<!DOCTYPE html>
<html>
    <head>
        <script src="http://d3js.org/d3.v3.min.js"></script>
    </head>
    <body>
    <div id="content"></div>
        <script> 
            d3.select('#content')
                .append('h1')
                .text('Hello World!');
        </script>
    </body>
</html>

As you can see the syntax is very similar to frameworks like JQuery and obviously, it saves you a lot of code lines as it offers a nice fluent API.

But let’s see how we can bind data to it:

d3.select('#content')
   .selectAll('h1')
   .data(['Sarah', 'Robert', 'Maria', 'Marc'])
   .enter()
   .append('h1')
   .text(function(name) {return 'Hello ' + name + '!'});

What happens? The data function gets our names array as parameter and for each name we append an <h1> element with a personalized greeting message. For a second, we ignore the selectAll(‘h1’) and enter() method call, as we will explore them later. Looking into the browser we can see the following:

Hello Sarah!
Hello Robert!
Hello Maria!
Hello Marc!

Not bad for a start! Inspecting the element in the browser, we see the following generated markup:

[...]
    <div id="content">
        <h1>Hello Sarah!</h1>
        <h1>Hello Robert!</h1>
        <h1>Hello Maria!</h1>
        <h1>Hello Marc!</h1>
    </div>
[...]

This already shows one enourmous advantage of D3.js: You acctually see the generated code and can spot errors easily.

Now, let’s have a closer look at the data-document connection
As mentioned in the beginning, D3.js helps you to manipulate documents based on data. Therefore, we only take care about handing the right data over to D3.js, so the framework can do the magic for us. To understand how D3.js handles data, we’ll first have a look at how data might change over time. Let’s take the document from our last example. Every name is one data entry. 

Data-Document Example 1

Easy. Now let’s assume new data comes in:

Data-Document Example 2

As new data is coming in, the document needs to be updated. The entries of Robert and Maria need to be removed, Sarah and Marc can stay unchanged and Mike, Sam and Nora need a new entry each. Fortunately, using D3.js we don’t have to care about finding out which nodes need to be added and removed. D3.js will take care about it. It will also reuse old nodes to improve performance. This is one key benefit of D3.js.

So how can we tell D3.js what to do when?
To let D3.js update our data, we initially need a data join, so D3.js knows our data. Therefore, we select all existing nodes and connect them with our data. We can also hand over a function, so D3.js knows how to identify data nodes. As we initally don’t have <h1> nodes, the selectAll function will return an empty set.

var textElements = svg.selectAll('h1').data(data, function(d) { return d; });

After the first iteration, the selectAll will hand over the existing nodes, in our case Sarah, Robert, Marc and Maria. So we can now update these existing nodes. For example, we can change their CSS class to grey:

textElements.attr({'class': 'grey'});

Additionally, we can tell D3.js what to do with entering nodes, in our case Mike, Sam and Nora. For example, we can add an <h1> element for each of them and set the CSS class to green for each of them:

textElements.enter().append('h1').attr({'class': 'green'});

As D3.js now updated the old nodes and added the new ones, we can define what will happen to both of them. In our cases this will affect the nodes of Mike, Sarah, Sam, Mark and Nora. For example, we can rotate them:

textElements.attr({'transform', rotate(30 20,40)});

Furthermore, we can specify what D3.js will do to nodes like Robert and Maria, that are not contained in the data set any more. Let’s change their CSS class to red:

textElements.exit().attr({'class': 'red'});

You can find the full example code to illustrate the data-document connection of D3.js as JSFiddle here: https://jsfiddle.net/q5sgh4rs/1/

But how to visualize data with D3.js?
Now that we know about the basics of D3.js, let’s go to the most interesting part of D3.js: drawing graphics. To do so, we use SVG, which stands for scalable vector graphics. Maybe you already know it from other contexts. In a nutshell, it’s a XML-based vector image language supporting animation and interaction. Fortunately, we can just add SVG tags in our HTML and all common browsers will display it directly. This also facilitates debugging, as we can inspect generated elements in the browser. In the following, we see some basic SVG elements and their attributes:

SVG elements

To get a better understanding of how SVG looks like, we’ll have a look at it as a basic example of SVG code, generating a rectangle, a line and a circle.

<svg>
 <rect x="10" y="15" width="60" height="20" />
 <line x1="95" y1="35" x2="105" y2="15" />
 <circle cx="130" cy="25" r="6" />
</svg>

To generate the same code using D3.js, we need to add an SVG to our content <div> and then append the tree elements with their attributes like this:

var svg = d3.select('#content').append('svg');
svg.append('rect').attr({x: 10, y: 15, width: 60, height: 20});
svg.append('line').attr({x1: 85, y1: 35, x2: 105, y2: 15});
svg.append('circle').attr({cx: 130, cy: 25, r: 6});

Of course, for static SVG code, we wouldn’t do this, but as we already saw, D3.js can fill attributes with our data. So we are now able to create charts! Let’s see how this works:

<div id="content"></div>
<script>
 d3.select('#content')
        .append('svg')
            .selectAll('rect')
            .data([100, 200, 150, 60, 50])
            .enter()
            .append('rect')
                .attr('x', 0)
                .attr('y', function(data, index) {return index * 25})
                .attr('height', 20)
                .attr('width', function(data, index) {return data});
</script>

This will draw our first bar chart for us! Have a look at it: https://jsfiddle.net/tLhomz11/2/

How to turn this basic bar chart into an amazing one?
Now that we started drawing charts, we can make use of all the nice features D3.js offers. First of all, we will adjust the width of each bar to fill the available space by using a linear scale, so we don’t have to scale our values by hand. Therefore, we specify the range we want to get values in and the domain we have. In our case, the data is in between 0 and 200 and we would like to scale it to a range of 0 to 400, like this:

var xScale = d3.scale.linear().range([0, 400]).domain([0,200]);

If we now specify x values, we just use this function and get an eqivalent value in the right range. If we don’t know our maximum value for the domain, we can use the d3.max() function to calculate it based on the data set we want to display.

To add an axis to our bar chart, we can use the following function and call it on our SVG. To get it in the right position, we need to transform it below the chart.

[svg from above].call(d3.svg.axis().scale(xScale).orient("bottom"));

Now, we can also add interaction and react to user input. For example, we can give an alert, if someone clicks one our chart:

[svg from above].on("click", function () {
    alert("Houston, we get attention here!");
})

Adding a text node for each line, we get the following chart rendered in the browser:

Coding Example Result

If you would like to play around with it, here is the code: https://jsfiddle.net/Loco5ddt/

If you would like to see even more D3.js code, using the same data to display a pie chart and adding an update button, look at the following one: https://jsfiddle.net/4eqzyquL/

Data import
Finally, we can import our data in CSV, TSV or JSON format. To import a JSON file, for example, use the following code. Of course, you can also fetch your JSON via a server call instead of importing a static file.

d3.json("data.json", function(data) {
    [access your data using the data variable]
}

What else does D3,js offer?
Just to name a few, D3.js helps you with layouts, geometry, scales, ranges, data transformation, array and math functions, colors, time formating and scales, geography, as well as drag & drop.

There are a lot of examples online: https://github.com/mbostock/d3/wiki/Gallery

TL;DR
+ based on web standards
+ totally flexible
+ easy to debug
+ many, many examples online
+ Libaries build on D3.js (NVD3.js, C3.js or IVML)
– a lot of code compared to other libraries
– for standard charts too heavy

Learning more
As this blog post is based on a presentation held at the MunichJS Meetup, you can find the original slides here: http://slides.com/elisabethengel/d3js#/ The recording is available on youTube: https://www.youtube.com/watch?v=EYmJEsReewo

For further information, have a look at:

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s