Hey, D3!
This is a quick tutorial on making visualizations with D3. What is D3? Well, Mike Bostock, the creator of D3 and cofounder of ObservableHQ, describes it best: D3.js is a JavaScript library for manipulating documents based on data. D3 helps you bring data to life using HTML, SVG, and CSS. D3’s emphasis on web standards gives you the full capabilities of modern browsers without tying yourself to a proprietary framework, combining powerful visualization components and a data-driven approach to DOM manipulation. d3js.org
While D3 is fairly agnostic about what web standards you use, whether that's SVG, Canvas, WebGL, whatever it may be, many examples, and particularly the more "simpler" examples, use SVG, so this tutorial will use such. If you are completely unfamiliar with SVG objects, I would check out this W3 school tutorial on the basics. (I've read through this site way too many times.)
HeyD3 = { const width = 200, height = 200; const svg = d3.select(DOM.svg(width, height)) .style("width", width) .style("height", height) .style("border", "1px solid #000"); svg.append("text") .style("font-size", "48px") .attr("fill", "#000") .attr("x", width/2) // set the y position .attr("y", height/2) // set the x position .style("text-anchor","middle") // text-anchor styling (style here means its CSS) .text("Hey, D3!"); // set the text return svg.node(); }
Ok! A very basic example. Here we're looking at an SVG with an SVG text object. There is one d3 function being used here, d3.select(). This is very similar to selector functions in other languages and frameworks. This decides the wheres we do our action. For example, in the const svg = d3.select() section, we are selecting the DOM and appending an SVG. Using that selection, we define styles using .style() Below, in the svg.append("text") section, we append an SVG text object to the SVG, and define some attributes using .attr(), as well as more styles. Easy enough, right?
How were we able to access the d3 library? Well, because I loaded it right here.
d3 = require("d3@5")
D3 is all about using data, so let's make some data using the d3.range() function. This will create an array with a length of whatever you provide. Here I made the length 50, then I mapped that array to an object of random x and y values.
HeyData = { const n = 50; // Set length of the array const data = d3.range(n).map(() => { return {x: Math.random(), y: Math.random()} // Object of random x and y values }); return data }
Ok! Let's now combine the SVG with the Data. We're going to use three new d3 functions here: d3.selectAll(), d3.enter(), and d3.scaleLinear(). Take a look at hte code and the output and see if you can figure out what each section does.
SVGwithData = { const width = 500, height = 500; const xScale = d3.scaleLinear() // Creates a Linear Scale .range([0, width]) // Output is 0 to the width (pixels) .domain([0, 1]); // Input is 0 to 1, which is the range of Math.random(), which we used in making the data const yScale = d3.scaleLinear() .range([0, height]) .domain([0, 1]); const svg = d3.select(DOM.svg(width, height)) .style("width", width) .style("height", height) .style("border", "1px solid #000"); svg.selectAll("circle") // Create an "empty selection" .data(HeyData) // Bind the data .enter().append("circle") // Create a circle for each data point .attr("cx", (d) => xScale(d.x)) // Set the X attribute using the xScale and the data .attr("cy", (d) => yScale(d.y)) // Set the Y attribute using the yScale and the data .attr("r", 5) // Give it a radius .style("fill", "#000") return svg.node(); }
The most confusing part here is definitely this: svg.selectAll("circle") // Create an "empty selection" .data(HeyData) // Bind the data .enter().append("circle") // Create a circle for each data point .attr("cx", (d) => xScale(d.x)) // Set the X attribute .attr("cy", (d) => yScale(d.y)) // Set the Y attribute .attr("r", 5) // Give it a radius What is going on?
html` <style> .example { fill: none; fill-opacity: .2; stroke: black; stroke-width: 1.5px; } </style> <svg width="720" height="240"> <g transform="translate(0,128)"> <g transform="translate(300)"> <circle class='example' r="110" style="fill: rgb(49, 130, 189);"></circle> <text y="-120" dy=".35em" text-anchor="middle" style="font-weight: bold;">Data</text> <text x="-50" dy=".35em" text-anchor="middle">Enter</text> </g> <text x="360" dy=".35em" text-anchor="middle">Update</text> <g transform="translate(420)"> <circle class='example' r="110" style="fill: rgb(230, 85, 13);"></circle> <text y="-120" dy=".35em" text-anchor="middle" style="font-weight: bold;">Elements</text> <text x="50" dy=".35em" text-anchor="middle">Exit</text> </g> </g> </svg>`
With most frameworks and languages, if you wanted to make 50 circles from data, you would do a for loop and for each datapoint, draw a circle. With D3, it's a little bit different. It's called Thinking with Joins, and Mike Bostock has an excellent post about it. Essentially, when you want to create, update or destroy objects based on data, you do an evaluation: select what you want, bind the data, then compare. So for our example, we select the circles we want, we bind data (our random array), then we evaluate -> do we have circles but no data? do we have data but no circles? do we have circles and data? In our situation, we have data but no circles, so we use the enter() method to create the circles. This is a hard part about d3. Sometimes animation helps:
GeneralUpdatePattern = { const width = 500, height = 500; const xScale = d3.scaleLinear() // Creates a Linear Scale .range([0, width]) // Output is 0 to the width (pixels) .domain([0, 1]); // Input is 0 to 1, which is the range of Math.random(), which we used in making the data const yScale = d3.scaleLinear() .range([0, height]) .domain([0, 1]); const svg = d3.select(DOM.svg(width, height)) .style("width", width) .style("height", height) .style("border", "1px solid #000"); const makeData = (n) => { return d3.range(n).map(() => { return {x: Math.random(), y: Math.random()} // Object of random x and y values }) }; const title = svg.append("text") .attr("y", 16) .attr("x", 2) .text("Enter") .attr("font-size", "16px") .style("fill", "#000") let n = 10; svg.selectAll("circle") .data(makeData(n)) .enter().append("circle") .attr("cx", (d) => xScale(d.x)) .attr("cy", function(d) { return yScale(d.y) }) .attr("r", 20) d3.interval(() => { let m = Math.floor(Math.random()*10); // ev handle for each sitiation in the title if(m - n == 10) { title.text("Enter"); } else if(m == n) { title.text("Update"); } else if(n == 0 && m > 0) { title.text("Enter"); } else if(m > n) { title.text("Enter + Update"); } else if(m == 0) { title.text("Exit"); } else if(m < n) { title.text("Exit + Update"); } else { title.text("Update"); } const circleSel = svg.selectAll("circle") // Create an "empty selection" .data(makeData(m)); // Enter! circleSel.enter().append("circle") .style("fill", "green") .attr("cx", (d) => xScale(d.x)) .attr("cy", (d) => yScale(d.y)) .attr("r", 20) // Update! circleSel .transition() .duration(1000) .attr("cx", (d) => xScale(d.x)) .attr("cy", (d) => yScale(d.y)) .style("fill", "blue"); // Enter! circleSel.exit() .style("fill", "red") .transition() .duration(1000) .style("opacity", 0) .remove(); // assign new value to old n = m; }, 2000); return svg.node(); }
So if you're making a visualization once, with data that is static, you'll pretty much only use the d3.enter() function. That's why you see it in countless examples (and no for loops.) You've now gone through enough to get some of the very basic D3 examples going. If you haven't already, go through those links in this tutorial, as they're very helpful.