d3

<!DOCTYPE html> <html> <head> <meta http-equiv="content-type" content="text/html;charset=utf-8"> <title>d3.js ~ A Bar Chart, Part 1</title> <script type="text/javascript" src="../d3.js?1.12.0"></script> <style type="text/css"> @import url("../style.css?1.10.0"); @import url("../syntax.css?1.6.0"); </style> </head> <body> <div class="body"> <div class="content"> <div class="topbar"> <a href="../">Overview</a> <a href="../ex/">Examples</a> <a href="../api/">Documentation</a> <a href="http://github.com/mbostock/d3/archives/master">Download</a> </div> <div class="sidebar"> <h1>d3.js</h1> </div> <h1 id='a_bar_chart_part_1'>A Bar Chart, Part 1</h1> <style type='text/css'> .chart { margin-left: 42px; font: 10px sans-serif; shape-rendering: crispEdges; } .chart div { background-color: steelblue; text-align: right; padding: 3px; margin: 1px; color: white; } .chart rect { stroke: white; fill: steelblue; } .chart text.bar { fill: white; } </style> Say you have some data—a simple array of numbers: <div class='highlight'><pre><code class='js'>1 var data = [4, 8, 15, 16, 23, 42]; </code></pre> </div><script type='text/javascript'> var data = [4, 8, 15, 16, 23, 42]; </script> One of the ways you might visualize this univariate data is a bar chart. This guide will examine how to create a simple bar chart using D3, first with basic HTML, and then a more advanced example with SVG. <h2 id='html'>HTML</h2> To get started with HTML, you’ll first need a container for the chart: <div class='highlight'><pre><code class='js'>1 var chart = d3.select("body") 2 .append("div") 3 .attr("class", "chart"); </code></pre> </div> This code selects the document body, which will be the parent of the new chart. Every visible node needs a parent, with the exception of the document’s root node. The chart container, a <code>div</code> element, is then created and appended to the body. The <code>append</code> operator adds the new node as the last child: the chart will appear at the end of the body. D3 uses the <a href='http://en.wikipedia.org/wiki/Method_chaining'>method chaining</a> design pattern. Above, setting the attribute returns the current selection, and the <code>chart</code> variable thus refers to the chart container element. This approach minimizes the amount of code needed to apply many selections and transformations in sequence. The <code>attr</code> operator sets the “class” attribute on the chart container, allowing stylesheets to be applied to the chart elements. This is convenient for static styles, such as the background color and font size. CSS code lives in a <code>style</code> element or an external stylesheet referenced by a <code>link</code> element, rather than the <code>script</code> element used for JavaScript: <div class='highlight'><pre><code class='css'>1 .chart div { 2 font: 10px sans-serif; 3 background-color: steelblue; 4 text-align: right; 5 padding: 3px; 6 margin: 1px; 7 color: white; 8 } </code></pre> </div> Next, add some <code>div</code> elements to the container, setting the width by scaling the data: <div class='highlight'><pre><code class='js'>1 chart.selectAll("div") 2 .data(data) 3 .enter().append("div") 4 .style("width", function(d) { return d * 10 + "px"; }) 5 .text(function(d) { return d; }); </code></pre> </div> This code selects the child <code>div</code> elements of the chart container. This selection is empty because the container was just added. However, by binding this selection to the array of numbers via the <code>data</code> operator, you can obtain the entering selection—a set of placeholder nodes, one per data element, to which you can append the desired child nodes for each bar. The <code>text</code> operator sets the text content of the bars. The identity function, <code>function(d) { return d; }</code>, causes each data value (number) to be formatted using JavaScript’s default string conversion, equivalent to the built-in <code>String</code> function. This may be ugly for some numbers (e.g., 0.12000000000000001). The <code>d3.format</code> class, modeled after Python’s <a href='http://docs.python.org/library/stdtypes.html#string-formatting'>string formatting</a>, is available for more control over how the number is formatted, supporting comma-grouping of thousands and fixed precision. The above code results in a rudimentary bar chart: <script type='text/javascript'> d3.select(".content") .append("div") .attr("class", "chart") .selectAll("div") .data(data) .enter().append("div") .style("width", function(d) { return d * 10 + "px"; }) .text(function(d) { return d; }); </script> One weakness of the code so far is the <a href='http://en.wikipedia.org/wiki/Magic_number_(programming)#Unnamed_numerical_constants'>magic number</a> 10, which scales the data value to the appropriate bar width. This number depends on the domain of the data (the maximum value, 42), and the width of the chart (420). To avoid hard-coding the x-scale of 10, you can use D3’s linear scale class, and compute the maximum value from the data: <div class='highlight'><pre><code class='js'>1 var x = d3.scale.linear() 2 .domain([0, d3.max(data)]) 3 .range(["0px", "420px"]); </code></pre> </div><script type='text/javascript'> var x = d3.scale.linear() .domain([0, d3.max(data)]) .range(["0px", "420px"]); </script> Although it looks like an object, the <code>x</code> variable here is actually a function that converts data values (in the domain) to scaled values (in the range). For example, an input value of 4 returns “40px”, and an input value of 16 returns “160px”. The output range of the scale in this example are strings, with the appropriate <code>px</code> units for CSS. D3’s automatic interpolators detect the numbers within the strings, while retaining the constant remainder. The new scale arguably still has a magic number: 420px, the width of the chart. If you want to make the chart resizable, you can inspect the width of the chart container, <code>chart.style("width")</code>. Or, use percentages rather than pixels. In any case, the reusable scale makes the chart specification easier to modify—for example, you can easily replace the linear scale with a log or root scale. Using the new scale, you can simplify the width style definition: <div class='highlight'><pre><code class='js'>1 chart.selectAll("div") 2 .data(data) 3 .enter().append("div") 4 .style("width", x) 5 .text(String); </code></pre> </div> Now, the HTML representation is very concise, but it’s not very flexible. Displaying reference lines in the background, or generating columns rather than bars, is difficult in pure HTML. Chart types such as pies and streamgraphs are practically impossible. Fortunately, there’s a convenient alternative: <a href='http://en.wikipedia.org/wiki/Scalable_Vector_Graphics'>Scalable Vector Graphics</a> (SVG)! <h2 id='svg'>SVG</h2> You use SVG much the same way as HTML, but it offers substantially more flexibility. To start with SVG, create an <code>svg:svg</code> container instead of a <code>div</code>: <div class='highlight'><pre><code class='js'>1 var chart = d3.select("body") 2 .append("svg:svg") 3 .attr("class", "chart") 4 .attr("width", 420) 5 .attr("height", 20 * data.length); </code></pre> </div> An immediate difference you will notice with SVG is that the units are implicitly pixels, and thus do not need the “px” suffix. Even with pixels, you can rescale the SVG without losing image quality. You can use percentages for relative positioning, too. To use a numeric range for the x-scale: <div class='highlight'><pre><code class='js'>1 var x = d3.scale.linear() 2 .domain([0, d3.max(data)]) 3 .range([0, 420]); </code></pre> </div><script type='text/javascript'> var x = d3.scale.linear() .domain([0, d3.max(data)]) .range([0, 420]); </script> Unlike HTML, SVG does not provide automatic flow layout. Shapes are positioned relative to the top-left corner, called the origin. Thus, by default, the bars would be drawn on top of each other. To fix this, set the y-coordinate and height explicitly: <div class='highlight'><pre><code class='js'>1 chart.selectAll("rect") 2 .data(data) 3 .enter().append("svg:rect") 4 .attr("y", function(d, i) { return i * 20; }) 5 .attr("width", x) 6 .attr("height", 20); </code></pre> </div> Also, the CSS changes slightly when using SVG. Rather than the background, the fill determines the bar color. You can also apply a white border to each bar by setting the stroke style: <div class='highlight'><pre><code class='css'>1 .chart rect { 2 stroke: white; 3 fill: steelblue; 4 } </code></pre> </div> The SVG-based chart is now almost identical to our original. The chart is currently missing labels, but that will be fixed shortly: <script type='text/javascript'> d3.select(".content") .append("svg:svg") .attr("class", "chart") .attr("width", 420) .attr("height", 20 * data.length) .selectAll("rect") .data(data) .enter().append("svg:rect") .attr("y", function(d, i) { return i * 20; }) .attr("width", x) .attr("height", 20); </script> Astute readers will notice that a magic number crept back into the chart description: the bar height of 20 pixels. Arguably, this number isn’t magic—twenty is a reasonable height for the bars, just as fourteen is a reasonable point size for text. However, if you prefer to set a height for the entire chart, use a second scale for the y-axis: <div class='highlight'><pre><code class='js'>1 var y = d3.scale.ordinal() 2 .domain(data) 3 .rangeBands([0, 120]); </code></pre> </div><script type='text/javascript'> var y = d3.scale.ordinal() .domain(data) .rangeBands([0, 120]); </script> As with <code>x</code> previously, <code>y</code> is now a function. It takes as input values from the data array, and for each value returns the corresponding y-coordinate. For example, an input value of 4 returns 0, and an input value of 16 returns 60. This approach requires that the values in our dataset are unique; ordinal scales are often used to encode non-quantitative data, such as country names. Alternatively, you can use array indices as the ordinal domain: [0, 1, 2…]. The new scale plugs into the bar specification, replacing the “y” attribute: <div class='highlight'><pre><code class='js'>1 chart.selectAll("rect") 2 .data(data) 3 .enter().append("svg:rect") 4 .attr("y", y) 5 .attr("width", x) 6 .attr("height", y.rangeBand()); </code></pre> </div> The new scales can also be applied to render labels, showing the associated value. This code centers labels vertically within each bar, and right-aligns text: <div class='highlight'><pre><code class='js'>1 chart.selectAll("text") 2 .data(data) 3 .enter().append("svg:text") 4 .attr("x", x) 5 .attr("y", function(d) { return y(d) + y.rangeBand() / 2; }) 6 .attr("dx", -3) // padding-right 7 .attr("dy", ".35em") // vertical-align: middle 8 .attr("text-anchor", "end") // text-align: right 9 .text(String); </code></pre> </div> The formal <a href='http://www.w3.org/TR/SVG/text.html'>SVG Text</a> specification describes in detail the meaning of the “dx”, “dy” and “text-anchor” attributes. The full spec is dense, as SVG offers a level of control required by only the most ambitious typographers; fortunately, it’s not too hard to remember standard settings for alignment and padding! The SVG chart now looks identical to the earlier HTML version: <script type='text/javascript'> var chart = d3.select(".content") .append("svg:svg") .attr("class", "chart") .attr("width", 420) .attr("height", 120); chart.selectAll("rect") .data(data) .enter().append("svg:rect") .attr("y", y) .attr("width", x) .attr("height", y.rangeBand()); chart.selectAll("text") .data(data) .enter().append("svg:text") .attr("class", "bar") .attr("x", x) .attr("y", function(d) { return y(d) + y.rangeBand() / 2; }) .attr("dx", -3) .attr("dy", ".35em") .attr("text-anchor", "end") .text(String); </script> With the basic chart is in place, you can place additional marks to improve readability. As a first step, pad the SVG container to make space for labels: <div class='highlight'><pre><code class='js'>1 var chart = d3.select(".content") 2 .append("svg:svg") 3 .attr("class", "chart") 4 .attr("width", 440) 5 .attr("height", 140) 6 .append("svg:g") 7 .attr("transform", "translate(10,15)"); </code></pre> </div> The <code>svg:g</code> element is a <a href='http://www.w3.org/TR/SVG/struct.html'>container element</a>, much like the <code>div</code> element in HTML. Setting a <a href='http://www.w3.org/TR/SVG/coords.html#TransformAttribute'>transform</a> on a container affects how its children are positioned. For padding, you need only to translate; however, for advanced graphical effects, you can use any affine transformation, such as scale, rotate and shear! The linear scale, <code>x</code>, provides a <code>ticks</code> routine that generates values in the domain at sensible intervals. For a chart this size, about ten ticks is appropriate; for smaller or larger charts, you can vary the number of ticks to generate. These tick values serve as data for reference lines: <div class='highlight'><pre><code class='js'>1 chart.selectAll("line") 2 .data(x.ticks(10)) 3 .enter().append("svg:line") 4 .attr("x1", x) 5 .attr("x2", x) 6 .attr("y1", 0) 7 .attr("y2", 120) 8 .attr("stroke", "#ccc"); </code></pre> </div> Positioning text above the reference lines reveals their value: <div class='highlight'><pre><code class='js'>1 chart.selectAll("text.rule") 2 .data(x.ticks(10)) 3 .enter().append("svg:text") 4 .attr("class", "rule") 5 .attr("x", x) 6 .attr("y", 0) 7 .attr("dy", -3) 8 .attr("text-anchor", "middle") 9 .text(String); </code></pre> </div> Note that the rule labels are assigned the class “rule”; this avoids a selector collision with the value labels on each bar. (Another way to disambiguate is to put reference labels in a separate <code>g</code> container.) Lastly, add a single black line for the y-axis: <div class='highlight'><pre><code class='js'>1 chart.append("svg:line") 2 .attr("y1", 0) 3 .attr("y2", 120) 4 .attr("stroke", "#000"); </code></pre> </div> Et voilà! <script type='text/javascript'> var chart = d3.select(".content") .append("svg:svg") .attr("class", "chart") .attr("width", 440) .attr("height", 140) .style("margin-left", "32px") // Tweak alignment… .append("svg:g") .attr("transform", "translate(10,15)"); chart.selectAll("line") .data(x.ticks(10)) .enter().append("svg:line") .attr("x1", x) .attr("x2", x) .attr("y1", 0) .attr("y2", 120) .attr("stroke", "#ccc"); chart.selectAll("text.rule") .data(x.ticks(10)) .enter().append("svg:text") .attr("x", x) .attr("y", 0) .attr("dy", -3) .attr("text-anchor", "middle") .text(String); chart.selectAll("rect") .data(data) .enter().append("svg:rect") .attr("y", y) .attr("width", x) .attr("height", y.rangeBand()); chart.selectAll("text.bar") .data(data) .enter().append("svg:text") .attr("class", "bar") .attr("x", x) .attr("y", function(d) { return y(d) + y.rangeBand() / 2; }) .attr("dx", -3) .attr("dy", ".35em") .attr("text-anchor", "end") .text(String); chart.append("svg:line") .attr("y1", 0) .attr("y2", 120) .attr("stroke", "#000"); </script> This tutorial covered many of the core concepts in D3, including selections, dynamic properties, and scales. However, this only scratches the surface! Continue reading <a href='bar-2.html'>part 2</a> to learn about transitions in dynamic visualizations. Or, explore the <a href='../ex/'>examples gallery</a> to see more advanced techniques with D3. </div> <div class="foot">Copyright © 2011 <a href="http://bost.ocks.org/mike">Mike Bostock</a></div> </div> </div> <a href="http://github.com/mbostock/d3"><img style="position:absolute;top:0;right:0;border:0;" width="149" height="149" src="../forkme.png" alt="Fork me on GitHub" /></a> </body> </html>