Author avatar

Hong Xiao

Short Guide to Getting Started with D3

Hong Xiao

  • May 17, 2019
  • 9 Min read
  • 5,450 Views
  • May 17, 2019
  • 9 Min read
  • 5,450 Views
Web Development
D3
Introduction

Introduction

D3 (short for Data-Driven Documents) is a Javascript library to manipulate documents with given data. In this guide, we will set up the environment with d3js, explore some basic concepts, and a bar chart which you can build directly with d3js, like this: result bar chart

Then, we will provide some "next-step" tasks, as well as links to more information and references. Let's get started.

Setup and Verification

There are a few options to set up a d3js environment on your machine, and we will explore each of them in this section.

First of all, you can use d3js in a vanilla <script> tag, like this:

1<script src="https://d3js.org/d3.v5.min.js"></script>
javascript

This will expose a d3 global variable, and you can verify this by typing

1console.log(d3.version);
javascript

in the console of your browser. This statement will print out the version of d3js you are using, which is 5.9.2 at the tie of this writing.

The second option is to install d3js via a package manager, like npm or yarn, create a bundle with a bundler, and import d3 accordingly.

1import * as d3 from "d3";
javascript

The third option is to use d3js in nodejs, as such:

1var d3 = require("d3");
javascript

For the simplicity of this guide, we use the first approach (with a <script> tag) to set up our environment.

Concepts

Before we dive in, there are a few concepts in d3js to be clarified. The typical way is to attach data to the DOM (document object model) in d3js. We will cover d3-scale, d3-axis, and the "data-join" pattern, before we actually build our vertical bar chart.

Use d3-scale for abstract-data-to-visual-representation Mapping

When directly programming with SVG (short for 'Scalable Vector Graphics'), typically you will do the following for a simple rectangle:

1<svg>
2    <g>
3        <rect x="0" y="0" height="100" width="50">
4        </rect>
5    </g>
6</svg>
html

As you can imagine, in a bar chart, we need to create many <rect> elements, calculate their attributes, and attach them to the <svg> element This is a daunting task by itself, and d3-scale can help us to do the calculation. From the official documentation, we will use the scaleBand() method for x, and scaleLinear() for y. These are the building blocks in our case for calculating the x, y, height and width attributes for the rectangles.

We will use the following logic to create the x and y scale functions:

1var x = d3.scaleBand()
2  .domain(DOMAIN_OF_DATA)
3  .range([RANGE_LEFT, RANGE_RIGHT]);
4
5var y = d3.scaleLinear()
6  .domain([0, MAX_OF_VALUE_DATA])
7  .range([RANGE_BOTTOM, RANGE_TOP]);
javascript

Note that scales does the mapping from domain to range.

Render Human-readable Marks for Scales Using d3-axis

Besides the rectangles, we also need to add the x-axis and y-axis in our bar chart. This is where d3-axis comes in handy. We would like to have a bottom axis for x, and a left axis for y. Here are the code snippets to create them:

1var xAxis = g => g
2  .attr("transform", `translate(0,${height - margin.bottom})`)
3  .call(d3.axisBottom(x));
4
5var yAxis = g => g
6  .attr("transform", `translate(${margin.left},0)`)
7  .call(d3.axisLeft(y));
javascript

Note that the SVG coordinates start with the top-left point as (0, 0). This means we need to do a translate for the y-axis so that the logic (0, 0) is at the bottom left. More details of SVG transforming can be found here.

The data-join Pattern and Its Usage

The last concept of d3js in use is the 'data-join' pattern, which might look strange at first sight.

1var svg = d3.select('svg');
2var g = svg.append("g");
3
4g.selectAll("rect")
5  .data(data)
6  .join("rect")
7  .attr("x", d => x(d.name))
8  .attr("y", d => y(d.value))
9  .attr("height", d => y(0) - y(d.value))
10  .attr("width", x.bandwidth());
javascript

Essentially, the above code snippet creates a few rect elements with given 'data', and 'join' them accordingly. Then it calls the x and y scale functions to map the name-value pairs in the data to the proper x and y coordinates on the screen. It also calculates the height and width attributes for each rectangle. You can verify the result by looking at the result elements in Chrome Developer Tool, for something like this:

1<rect x="41.95402298850573" y="150.11923076923077" height="219.88076923076923" width="17.586206896551726"></rect>
html

There are a few tutorials online explaining this pattern in d3js, and my personal favorite is this article by the author of d3js.

Putting Everything Together

With all the above concepts explained and code snippets available, let us put everything together to build our bar chart. Note that we have the following components in the chart:

  • The rectangle elements in the document, based on the data.
  • The x-axis and y-axis with ticks and text, which are built on top the of x and y scale functions.

In our html file, we create a svg element:

1<svg height="450" width="600"></svg>
html

In the javascript, first we’ll define the data variable:

1var data = [
2  {name: "A", value: "0.08167"},
3  {name: "B", value: "0.01492"},
4  {name: "C", value: "0.02782"},
5  {name: "D", value: "0.04253"},
6  {name: "E", value: "0.12702"},
7  {name: "F", value: "0.02288"},
8  {name: "G", value: "0.02015"},
9  {name: "H", value: "0.06094"},
10  {name: "I", value: "0.06966"},
11  {name: "J", value: "0.00153"},
12  {name: "K", value: "0.00772"},
13  {name: "L", value: "0.04025"},
14  {name: "M", value: "0.02406"},
15  {name: "N", value: "0.06749"},
16  {name: "O", value: "0.07507"},
17  {name: "P", value: "0.01929"},
18  {name: "Q", value: "0.00095"},
19  {name: "R", value: "0.05987"},
20  {name: "S", value: "0.06327"},
21  {name: "T", value: "0.09056"},
22  {name: "U", value: "0.02758"},
23  {name: "V", value: "0.00978"},
24  {name: "W", value: "0.0236"},
25  {name: "X", value: "0.0015"},
26  {name: "Y", value: "0.01974"},
27  {name: "Z", value: "0.00074"}
28];
javascript

Then, we define the constant variables of height, width, and margin:

1var height = 400;
2var width = 550;
3var margin = ({top: 20, right: 20, bottom: 20, left: 20});
javascript

After that comes the x and y scale functions:

1var x = d3.scaleBand()
2  .domain(data.map(d => d.name))
3  .range([margin.left, width - margin.right])
4  .padding(0.1);
5
6var y = d3.scaleLinear()
7  .domain([0, d3.max(data, d => d.value)])
8  .range([height - margin.bottom, margin.top]);
javascript

The xAxis and yAxis functions:

1var xAxis = g => g
2  .attr("transform", `translate(0,${height - margin.bottom})`)
3  .call(d3.axisBottom(x));
4
5var yAxis = g => g
6  .attr("transform", `translate(${margin.left},0)`)
7  .call(d3.axisLeft(y));
javascript

And finally, use all the above constants and functions:

1var svg = d3.select('svg');
2
3var g = svg.append("g").attr("fill", "orange");
4
5g.selectAll("rect")
6  .data(data)
7  .join("rect")
8  .attr("x", d => x(d.name))
9  .attr("y", d => y(d.value))
10  .attr("height", d => y(0) - y(d.value))
11  .attr("width", x.bandwidth());
12
13svg.append("g").call(xAxis);
14
15svg.append("g").call(yAxis);
javascript

Here we go, we have the final bar chart with all the components mentioned above.

Next Steps

There are many different types of visualizations you can do with d3js, and in this guide we merely scratched the surface of it. Some improvement ideas include:

  • Adding interactions using CSS.
  • Adding transformations using functionalities provided in d3-transform.
  • Visualize a line chart with the same data.

Conclusion and Additional Information

The code example in this guide is inspired by the examples on bl.ocoks.org and observablehq.com, the official d3js website is https://d3js.org/, and D3 In Depths also provides good tutorials for d3js.

The finished project can be found here.

You can find more courses on d3js on Pluralsight:

LEARN MORE