Hey, so this post is broken. I moved platforms and some of my old tutorials don’t play nicely with WordPress. I’m working on fixing them, but in the meantime you can view the old version here: https://cagrimmett-jekyll.s3.amazonaws.com/til/2016/08/19/d3-pie-chart.html

• Part 1: Let’s Make a Pie Chart with D3.js (this post)
• Part 2: Let’s Update a Pie Chart in Realtime with D3.js
• Part 3: Smooth Pie Chart Transitions with D3.js

This is part of my ongoing effort to relearn D3.js. This short tutorial applies what I’ve learned about data joins, arcs, and labels. It varies slightly from other examples like Mike Bostock’s Pie Chart block because I’m using D3.js version 4 and the API for arcs and pies is different from version 3, which most tutorials are based on. I figured this out through some trial and error. Always read the documentation!

I’m eventually going to use this pie chart as a base to learn how to update charts in real time based on interactions like button pushes or clicks.

Getting Started

1. Always include the library:
2. Make a div to hold the chart:

3. D3 stands for Data-Driven Documents. So what do we always start with when creating something with D3? Data!

Since I’m eventually going to figure out how to update this chart in real time based on button presses, I’m going to start with some dummy data for three easy-to-press buttons: q, w, and e. As always, I log it to the console for quick debugging:

var data = [{"letter":"q","presses":1},{"letter":"w","presses":5},{"letter":"e","presses":2}]; console.log(data);

We’ll also need some basics like width, height, and radius since we are dealing with a circle here. Make them variables so your code is reusable later:

var width = 300, 	height = 300, 	// Think back to 5th grade. Radius is 1/2 of the diameter. What is the limiting factor on the diameter? Width or height, whichever is smaller 	radius = Math.min(width, height) / 2;

Next we need a color scheme. Be referring to the API, we learn that we should use .scaleOrdinal() for this:

var color = d3.scaleOrdinal() 	.range(["#2C93E8","#838690","#F56C4E"]);

Setting up the pie and arcs

We need to set up the pie based on our data. According to the documentation, d3.pie() computes the necessary angles based on data to generate a pie or doughnut chart, but does not make shapes directly. We need to use an arc generator for that.

var pie = d3.pie() 	.value(function(d) { return d.presses; })(data);

Before we create the SVG and join data with shapes, let’s define some arguments for the two arcs we want: The main arc (for the chart) and the arc to hold the labels. We need an inner and outer radius for each. If you change the inner radius to any number greater than 0 on the main arc you’ll get a doughnut.

var arc = d3.arc() 	.outerRadius(radius - 10) 	.innerRadius(0);  var labelArc = d3.arc() 	.outerRadius(radius - 40) 	.innerRadius(radius - 40);

Making the shapes

We always start with an SVG. Select the div we created to hold the chart, append an SVG, give the SVG the attributes defined above, and create a group to hold the arcs. Don’t forget to move the center points, or else the chart will be centered in the upper right corner:

var svg = d3.select("#pie") 	.append("svg") 	.attr("width", width) 	.attr("height", height) 		.append("g") 		.attr("transform", "translate(" + width/2 + "," + height/2 +")"); // Moving the center point. 1/2 the width and 1/2 the height

Now let’s join the data generated by .pie() with the arcs to generate the necessary groups to hold the upcoming paths. Give them the class “arc”.

var g = svg.selectAll("arc") 	.data(pie) 	.enter().append("g") 	.attr("class", "arc");

Now we can append the paths created by the .arc() functions with the variables we defined above. We’re using the color variable we defined above to get the colors we want for the various arcs:

g.append("path") 	.attr("d", arc) 	.style("fill", function(d) { return color(d.data.letter);});

Once you save, you should see a chart. Now we’re cooking with data!

Labels

Let’s put some labels on it now. We’ll need to append some text tags in each arc, set the position with a transform defined by the labelArc variable we defined earlier, then access the correct letter to add to the label. Then we’ll make it white so it shows up a little better:

g.append("text") 	.attr("transform", function(d) { return "translate(" + labelArc.centroid(d) + ")"; }) 	.text(function(d) { return d.data.letter;}) 	.style("fill", "#fff");

There you have it! A basic pie chart. Play around with the variables so you understand better what is going on.

Hey, so this post is broken. I moved platforms and some of my old tutorials don’t play nicely with WordPress. I’m working on fixing them, but in the meantime you can view the old version here: https://cagrimmett-jekyll.s3.amazonaws.com/til/2016/08/17/d3-lets-make-a-grid.html

I’ve been on a mission to relearn the fundamentals of D3.js from the ground up. This tutorial is a way to apply what I learned about data joins, click events, and selections. Along the way I learned about building arrays.

I also wrote this up as a block for those interested.

Basics

We want to make a 10×10 grid using D3.js. D3’s strength is transforming DOM elements using data. This means we’ll need some data and we’ll want to use SVG and rect elements.

Data

We could write an array of data for the grid by hand, but we wouldn’t learn anything then, would we? Let’s generate one with Javascript.

Picture a grid in your head. It is made up of rows and columns of squares. Since this is ultimately going to be represented by an SVG, let’s think about how an SVG is structured:

What you see here is a basic structure of rows and columns. That means that when we make our data array, we want to make a nested array of rows and cells/columns inside those rows. We’ll need to use iteration to do this. Easy-peasy.

The other question we’ll have when making these arrays is, “What attributes will this grid need?”. Think about how you’d draw a grid: You start in the upper right corner of a piece of paper, draw a 1×1 square, move over the width of 1 square and draw another, and repeat until you get to the end of the row. Then you’d go back to the first square, draw one underneath it, and repeat the process. Here we’ve described positions, widths, and heights. In SVG world these are x, y, width, and height.

Here is the function I’m using to create the underlying data for the upcoming grid. It makes an array that holds 10 other arrays, which each hold 10 values:

function gridData() { 	var data = new Array(); 	var xpos = 1; //starting xpos and ypos at 1 so the stroke will show when we make the grid below 	var ypos = 1; 	var width = 50; 	var height = 50; 	 	// iterate for rows	 	for (var row = 0; row < 10; row++) { 		data.push( new Array() ); 		 		// iterate for cells/columns inside rows 		for (var column = 0; column < 10; column++) { 			data[row].push({ 				x: xpos, 				y: ypos, 				width: width, 				height: height 			}) 			// increment the x position. I.e. move it over by 50 (width variable) 			xpos += width; 		} 		// reset the x position after a row is complete 		xpos = 1; 		// increment the y position for the next row. Move it down 50 (height variable) 		ypos += height;	 	} 	return data; }

Making a Grid with D3 Data Joins

We made a cool array above and now we’ll make the data correspond to svg:rect objects to make our grid. First we’ll need to make a div to append everything to (and, of course, don’t forget to include the latest version of D3 in your header):

 id="grid">

Now we need to assign our data to a variable so we can access it:

var gridData = gridData();	 // I like to log the data to the console for quick debugging console.log(gridData);

Next, let’s append an SVG to the div we made and set its width and height attributes:

var grid = d3.select("#grid") 	.append("svg") 	.attr("width","510px") 	.attr("height","510px");

Next, we can apply what we learned in Mike Bostock’s Thinking With Joins to make our rows:

var row = grid.selectAll(".row") 	.data(gridData) 	.enter().append("g") 	.attr("class", "row");

And finally we make the individual cells/columns. Translating the data is a bit trickier, but the key is understanding that we are doing a selectAll on the rows, which means that any reference to data is to the contents of the single array that is bound to that row. We’ll then use a key function to access the attributes we defined (x, y, width, height):

var column = row.selectAll(".square") 	.data(function(d) { return d; }) 	.enter().append("rect") 	.attr("class","square") 	.attr("x", function(d) { return d.x; }) 	.attr("y", function(d) { return d.y; }) 	.attr("width", function(d) { return d.width; }) 	.attr("height", function(d) { return d.height; }) 	.style("fill", "#fff") 	.style("stroke", "#222");

You’ll note that I added style fill and stroke attributes to make the grid visible.

When we put it all together, here is what we get:

Note: If you are viewing this on your phone, you might want to switch over to a tablet or desktop. I haven’t optimized this example for mobile because that will needlessly complicate it.

Cool, huh? Go ahead and inspect the element and marvel at your find handiwork. Then change the fill, stroke, width, and height attributes and see how it changes.

Adding Click Functions

Let’s have some fun and add click events to the individual cells. I want to have cells turn blue on the first click, orange on the second, grey on the third, and white again on the fourth. Since D3 is data-driven, we’ll need to add some click data to the arrays and then add functions to change it and set colors based on the number of clicks.

//add this to the gridData function var click: 0;  //add this to the cell/column iteration data.push click: click  //add this to var column = row.selectAll(".square") .on('click', function(d) {        d.click ++;        if ((d.click)%4 == 0 ) { d3.select(this).style("fill","#fff"); } 	   if ((d.click)%4 == 1 ) { d3.select(this).style("fill","#2C93E8"); } 	   if ((d.click)%4 == 2 ) { d3.select(this).style("fill","#F56C4E"); } 	   if ((d.click)%4 == 3 ) { d3.select(this).style("fill","#838690"); }     })

Let’s break down that on('click') function:

• When you click on a cell, it increases the click variable (originally set at 0) by 1.
• The if statements set the color based on how many times it has been clicked mod 4. This satisfies the UI of only having four states: white, blue, orange, and grey. If you go to your console and call up the data for a certain cell, you’ll see that the full number of clicks is available.

Here it is. Click away!

Randomized click counts

What happens when we randomize click counts when we create the data array?

//add this to the gridData function var click: 0;  //add this to the cell/column for loop, just above the data.push line click = Math.round(Math.random() * 100);  //add this to var column = row.selectAll(".square") .style("fill", function(d) { 		if ((d.click)%4 == 0 ) { return "#fff"; } 		if ((d.click)%4 == 1 ) { return "#2C93E8"; } 		if ((d.click)%4 == 2 ) { return "#F56C4E"; } 		if ((d.click)%4 == 3 ) { return "#838690"; } 	})

Note that Math.random() returns a number between 0 and 1, inclusive. Multiple that by 100 if you want a number between 1 and 100.

It changes when you refresh!

Mouseovers: Even more fun with a bigger grid

What happens when we change the click event to a mouseover event and make a bigger grid? It becomes a lot more fun. I’ll leave the implementation as an exercise to the reader. If you’ve been following along and writing this yourself instead of copying and pasting, you probably already know which variables and events to change:

These are my outputs from Mike Bostock’s Three Little Circles Tutorial, slightly modified so I could understand how each of these items work. This is a tutorial about selections and basic data joins.

We start with three basic SVG circles:

 height="50px" width="250px">    cx="40" cy="20" r="10">    cx="80" cy="20" r="10">    cx="120" cy="20" r="10"> 

Now let’s select them and make them a little bigger and orange!

var circle = d3.selectAll("svg#orange circle") 	.style("fill", "darkorange") 	.attr("r", 20);

Now how about making them light blue and having a randomly-generated height that resets every second?

function jump(){ var circle = d3.selectAll("svg#random-height circle") 	.style("fill", "lightblue") 	.attr("cy", function() { return Math.random() * 150 + 10;}); } jump(); setInterval(jump, 1000);

That’s cool!

Now let’s do some data joins. How about making the radius of the circle a function of a data set?

var circle = d3.selectAll("svg#data-radius circle") 	.data([2, 3, 4]) 	.attr("r", function(d){ return d*d; });

Looks like the radius is a square of the data. Go ahead and inspect the element to confirm!

You’ll notice that the function uses the name d to refer to bound data.

Let’t make these purple for variety and write a linear function to space them out horizontally.

var circle = d3.selectAll("svg#data-cx circle") 	.style("fill","purple") 	.data([2, 3, 4]) 	.attr("cx", function(d,i){ return i*100 + 70});

This uses a new function: The index of the element within its selection. The index is often useful for positioning elements sequentially. We call it i by convention.

I’m relearning D3.js. Here are notes from different resources I’m reading.

Notes from the D3js.org Introduction.

Introduction

• D3.js is a javascript library for manipulating documents based on data. It uses HTML, SVG, and CSS to do so. It emphasizes web standards so that you can use modern browsers without proprietary frameworks.
• You can bind data to a DOM (Document Object Model) and apply data-driven transformations to the document.
  • Example: Generate an HTML table from an array of numbers, then use the same data to make an SVG bar chart.

Selections

• D3 makes it a lot easier to modify documents than the W3C DOM API. The W3C method relies on verbose names and manual iteration. D3 employs a declarative approach that operates on arbitrary nodes called selections.

Here is Mike Bostock’s examples for how to change the text color of paragraph elements with the W3C method vs D3 method:

W3C:

var paragraphs = document.getElementsByTagName("p"); for (var i = 0; i < paragraphs.length; i++) {   var paragraph = paragraphs.item(i);   paragraph.style.setProperty("color", "white", null); }

D3:

d3.selectAll("p").style("color", "white");

• Elements may be selected using a variety of predicates, including containment, attribute values, class and ID.
• D3 provides multiple ways to change nodes: Setting attributes and styles, registering event listeners, adding/removing/sorting nodes, and changing HTML or text content.
• Direct access to the DOM is possible because each D3 selection is a simple array of nodes.

Dynamic Properties

• D3 has similar syntax to jQuery, but styles, attributes, and other properties can be specified as functions of data in D3, not just constants.
• D3 provides built-in reusable functions and function factories, such as graphical primitives for area, line and pie charts

To alternate shades of gray for even and odd nodes:

d3.selectAll("p").style("color", function(d, i) {   return i % 2 ? "#fff" : "#eee"; });

• Computed properties often refer to bound data. Data is specified as an array of values, and each value is passed as the first argument (d) to selection functions. With the default join-by-index, the first element in the data array is passed to the first node in the selection, the second element to the second node, and so on. For example, if you bind an array of numbers to paragraph elements, you can use these numbers to compute dynamic font sizes:

d3.selectAll("p")   .data([4, 8, 15, 16, 23, 42])     .style("font-size", function(d) { return d + "px"; });

• Once the data has been bound to the document, you can omit the data operator. D3 will retrieve the previously-bound data. This allows you to recompute properties without rebinding.

Enter and Exit

• With D3’s enter and exit selections you can create new nodes for incoming data and remove outgoing nodes that are no longer needed.
• When data is bound to a selection, each element in the data array is paired with the corresponding node in the selection. If there are fewer nodes than data, the extra data elements form the enter selection, which you can bring to life by using the .enter() selection. Example:

d3.select("body")   .selectAll("p")   .data([4, 8, 15, 16, 23, 42])   .enter().append("p")     .text(function(d) { return "I’m number " + d + "!"; });

• Updating nodes are the result of the data operator. If you forget the enter and exit selections, you will automatically select only the elements for which there exists corresponding data.
• A common pattern is to break the initial selection into three parts: Updating nodes to modify, entering the nodes to add, and exiting the nodes to remove. Example:

// Update… var p = d3.select("body")   .selectAll("p")   .data([4, 8, 15, 16, 23, 42])     .text(function(d) { return d; });  // Enter… p.enter().append("p")     .text(function(d) { return d; });  // Exit… p.exit().remove();

• By handling the three cases (update, enter, exit) separately, you control precisely which operations run on which nodes.
• D3 allows you to transform documents based on data. This includes creating and destroying elements.
• D3 allows you to change an existing document in response to user interaction, animation over time, or even asynchronous inputs from a third-party. A hybrid approach is also possible, where the document is initially rendered on the server and updated on the client via D3.

Transformation, not Representation

• D3 does not introduce a new visual representation. Instead, its graphical marks come from web standards: HTML, SVG, and CSS. If browsers introduce new features tomorrow, you can use them immediately with D3, no update required.
• D3 is easy to debug with the browser’s built-in element inspector. The nodes D2 manipulates are the same ones the browser uses natively.

Transitions

• D3’s transformation focus extends to animated transitions, too. Transitions interpolate styles and attributes over time. The time between can be controlled with easing functions.
• D3’s interpolators support primitives (numbers and numbers within strings like font size, etc) and compound values. They are also extendable.
• Examples:

To fade the background of the page to black:

d3.select("body").transition()     .style("background-color", "black");

Or, to resize circles in a symbol map with a staggered delay:

d3.selectAll("circle").transition()     .duration(750)     .delay(function(d, i) { return i * 10; })     .attr("r", function(d) { return Math.sqrt(d * scale); });

• D3 allows you to modify only the elements that change, which reduces overhead and allows more complexity at high frame rates.
• D3 allows sequencing of complex transitions via events
• D3 does not replace the browser’s toolbox, but instead exposes it and makes it easier to use. You can still use CSS transitions.

Notes from Thinking with Joins by Mike Bostock

• D3 has no primitive for creating multiple DOM elements. The .append() method can create single elements, but if you want multiple, you need to think in a different way.
• Instead of telling D3 how to do something, tell D3 what you want. For example, on the Thinking with Joins page, Mike uses this snippet to tell D3 that the selection “circle” should correspond to data points. This concept is called a data join:

svg.selectAll("circle")   .data(data)   .enter().append("circle")     .attr("cx", function(d) { return d.x; })     .attr("cy", function(d) { return d.y; })     .attr("r", 2.5);

Data points joined to the existing elements produce the update (inner) selection. Leftover unbound data produce the enter (left) selection, which represents missing elements. Any remaining unbound elements produce the exit (right) selection, which represents elements to be removed.

Now let’s explain the svg.selectAll("circle"):

1. First it returns an empty selection since the SVG container was empty. The parent node of the selection was the SVG container.
2. The selection is joined to a data array, resulting in three new selections that represent three possible states: enter, update, or exit. Since the selection was empty, the update and exit selections are empty and the enter selection contains a placeholder for each new data point.
3. The update selection is returned by selection.data and the enter and exit selections hang off the update selection. selection.enter returns the enter selection.
4. The missing elements are added to the SVG container by calling selection.append on the enter selection. This appends a new circle for each data point in the SVG container.

• Thinking with joins means declaring a relationship between a selection (such as a “circle”) and data, then implementing this relationship through the three enter, update, and exit states.
• For static visualizations, the enter selection is sufficient. But you can support dynamic visualizations with minor modifications to update and exit.
• If a given enter, update, or exit selection happens to be empty, the corresponding code does not operate.
• Joins let you target operations to specific states. For example, you can set constant attributes (such as the circle’s radius, defined by the “r” attribute) on enter rather than update. By reselecting elements and minimizing DOM changes, you vastly improve rendering performance!
• Similarly, it allows you to target animations to specific states like expanding circles as the come in and contract circles as they go out.

I was listening to Data Stories Episode 22: NYT Graphics and D3 with Mike Bostock and Shan Carter today and I realized that while I’ve used D3.js for bar charts and mapping projections, I don’t really understand it. I never took the time to learn the fundamentals, so I’ve always been constrained to cobbling together things from other examples.

That needs to change.

Here is a list of resources I plan to go through. I should be able to relearn the basics fairly quickly so that I can spend time making charts of my own. I’ll update completed items with check marks as I go through them.

• Notes – D3js.org Introduction – Actually read the full thing, not skip 1/2 of it like I originally did.
• Chapter 2: Introducing D3 in Interactive Data Visualization for the Web
• Notes – Thinking with Joins by Mike Bostock – Joins are a foundational part of D3. In short, you are declaring a relationship between a selection and data.
• How Selections Work by Mike Bostock
• Notes – Three Little Circles by Mike Bostock – Manipulating circles with selections
• Nested Selections by Mike Bostock
• General Update Pattern, parts 1-3 by Mike Bostock – demonstrates D3’s general update pattern, where a data-join is followed by operations on the enter, update and exit selections
• Chapter 6: Drawing with Data in Interactive Data Visualization for the Web
• Chapter 7: Scales in Interactive Data Visualization for the Web
• Chapter 8: Axes in Interactive Data Visualization for the Web
• Object Constancy by Mike Bostock
• Transitions by Mike Bostock
• Let’s Make a Bar Chart, Parts 1-3 by Mike Bostock
• Let’s Make a Map by Mike Bostock
• Let’s Make a Bubble Map by Mike Bostock