d3

<!DOCTYPE html> <html> <head> <meta http-equiv="content-type" content="text/html;charset=utf-8"> <title>d3.js ~ Documentation</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> <b><a href="../api/">Documentation</a></b> <a href="http://github.com/mbostock/d3/archives/master">Download</a> </div> <div class="sidebar"> <h1>d3.js</h1> </div> <h1 id='documentation'>Documentation</h1> <h2 id='tutorials'>Tutorials</h2> <div class='gallery'> <div class='list'> <a href='../tutorial/bar-1.html'> <img src='../tutorial/bar-1.png' /> </a> <h4><a href='../tutorial/bar-1.html'>A Bar Chart, Part 1</a></h4> <p>Learn the basics of D3 with this introductory tutorial. Using the example of a no-frills, static bar chart, this guide describes the core D3 concepts, including selections, functional properties, and scales. You'll also see how D3 can be applied to HTML, CSS and SVG.</p> </div> <div class='list'> <a href='../tutorial/bar-2.html'> <img src='../tutorial/bar-2.png' /> </a> <h4><a href='../tutorial/bar-2.html'>A Bar Chart, Part 2</a></h4> <p>A continuation of the above introductory tutorial, this guide covers more exciting dynamic aspects of D3, including transitions and data joins. Learn how to create realtime visualizations and specify enter and exit animations.</p> </div> <div class='list'> <a href='../tutorial/protovis.html'> <img src='../tutorial/protovis.png' /> </a> <h4><a href='../tutorial/protovis.html'>For Protovis Users</a></h4> <p>An introduction to D3 for users of Protovis. Covers design motivation as well as tips on converting Protovis visualizations to D3.</p> </div> </div><br clear='left' /> <h2 id='user_guides'>User Guides</h2> <div class='gallery'> <div class='list'> <a href='http://www.janwillemtulp.com/category/d3/'> <img src='janwillemtulp.png' /> </a> <h4><a href='http://www.janwillemtulp.com/category/d3/'>Jan Willem Tulp's Blog</a></h4> <p>Jan Willem Tulp has posted a number of introductory tutorials on D3 to his blog.</p> </div> <div class='list'> <a href='http://groups.google.com/group/d3-js'> <img src='group.png' /> </a> <h4><a href='http://groups.google.com/group/d3-js'>Google Group d3-js</a></h4> <p>Questions about D3? Post them to our Google Group.</p> </div> </div><br clear='left' /> <h2 id='reference'>Reference</h2> <h3 id='d3'>d3</h3> <p>ascending, descending, min, max, keys, values, entries, split, merge, range, xhr, text, json, html, xml, format, nest (map, key, sortKeys, sortValues, rollup, entries), ns, event, rgb, hsl, ease.</p> <h5 id='id1'><code>d3.select(node)</code></h5> <p>Returns a selection containing the specified node. <em>node</em> can be one of two things:</p> <ul> <li>string: a selector, such as “tag” or “.class”</li> <li>object: a DOM element</li> </ul> <h5 id='id2'><code>d3.selectAll(nodes)</code></h5> <p>Returns a selection containing the specified nodes. <em>nodes</em> can be one of two things:</p> <ul> <li>string: a selector, such as “tag” or “.class”</li> <li>array: an array of DOM element</li> </ul> <h5 id='id3'><code>d3.transition()</code></h5> <p>Returns a new transition. Nodes can then be selected, as an alternative to deriving a transition from an existing selection.</p> <h4 id='selections'>Selections</h4> <h5 id='id4'><code>selection.filter()</code></h5> <p>…</p> <h5 id='id5'><code>selection.data()</code></h5> <p>…</p> <h5 id='id6'><code>selection.classed()</code></h5> <p>…</p> <h5 id='id7'><code>selection.insert()</code></h5> <p>…</p> <h5 id='id8'><code>selection.sort()</code></h5> <p>…</p> <h5 id='id9'><code>selection.empty()</code></h5> <p>Returns true if the selection is empty.</p> <h5 id='id10'><code>selection.node()</code></h5> <p>Return the DOM node for the first element in the selection.</p> <h5 id='id11'><code>selection.append(name)</code></h5> <p>Append a new element <em>name</em> as the last child for every element in the selection.</p> <h5 id='id12'><code>selection.remove()</code></h5> <p>Remove selected elements.</p> <h5 id='id13'><code>selection.call(function[, optargs…])</code></h5> <p>Call <em>function</em> once for the entire selection. The function is invoked with the entire selection as an array of elements as the first argument and any <em>optargs</em> as subsequent arguments.</p> <h5 id='id14'><code>selection.each(function)</code></h5> <p>Call <em>function</em> for every element in the selection. The function is invoked with two arguments: the bound data for the element and the index of the bound data.</p> <h5 id='id15'><code>selection.attr(name[, value])</code></h5> <p>Get or set the value of the attribute <em>name</em> for every element in the selection. <em>value</em> can be one of four things:</p> <ul> <li>empty: get the value of the attribute for the first element in the selection</li> <li>null: remove the attribute</li> <li>constant: set the attribute to the supplied value for each element.</li> <li>function: set the attribute to the result of evaluating the function for each element in the selection. The function is invoked with two arguments: the bound data for the element and the index of the bound data.</li> </ul> <h5 id='id16'><code>selection.style(name[, value[, priority]])</code></h5> <p>Get or set the CSS style property <em>name</em> for every element in the selection. <em>priority</em> can be “important”. <em>value</em> can be one of four things:</p> <ul> <li>empty: get the value of the style property for the first element in the selection</li> <li>null: remove the style property</li> <li>constant: set the style property to the supplied value for each element.</li> <li>function: set the style property to the result of evaluating the function for each element in the selection. The function is invoked with two arguments: the bound data for the element and the index of the bound data.</li> </ul> <h5 id='id17'><code>selection.property(name[, value])</code></h5> <p>Get or set the Javascript object property <em>name</em> for every element in the selection. <em>value</em> can be one of four things:</p> <ul> <li>empty: get the value of the object property for the first element in the selection</li> <li>null: remove the object property</li> <li>constant: set the object property to the supplied value for each element.</li> <li>function: set the object property to the result of evaluating the function for each element in the selection. The function is invoked with two arguments: the bound data for the element and the index of the bound data.</li> </ul> <h5 id='_and_'><code>selection.text([value])</code> and <code>selection.html([value])</code></h5> <p>Get or set the content inside the selected elements. <em>text()</em> sets the contents as text (via createTextNode(), <em>html()</em> sets the contents as HTML (via innerHTML). <em>value</em> can be one of four things:</p> <ul> <li>empty: get the value of the content for the first element in the selection</li> <li>null: remove the content</li> <li>constant: set the content to the supplied value for each element.</li> <li>function: set the content to the result of evaluating the function for each element in the selection. The function is invoked with two arguments: the bound data for the element and the index of the bound data.</li> </ul> <h5 id='id18'><code>selection.on(type, listener)</code></h5> <p>Arrange for <em>listener</em> to be invoked when a DOM event of type <em>type</em> occurs on the selected elements. Any previous <em>listener</em> of that type is removed (set <em>listener</em> to null to remove a listener without adding a new one). The <em>listener</em> function is invoked with two arguments: the bound data for the element and the index of the bound data. To access the event itself from within the listener use <code>d3.event</code>.</p> <h5 id='id19'><code>selection.transition()</code></h5> <p>Initiate a transition for the selected elements. See d3.transition for details.</p> <h4 id='transitions'>transitions</h4> <p>delay, duration, ease, attrTween, attr, styleTween, style, select, selectAll, remove, each.</p> <h3 id='d3scale'>d3.scale</h3> <h4 id='id20'><code>d3.scale.linear</code></h4> <p>Map a number in the domain to a number in the range with a linear function.</p> <div class='highlight'><pre><code class='js'><span class='lineno'>1</span> <span class='nx'>s</span> <span class='o'>=</span> <span class='nx'>d3</span><span class='p'>.</span><span class='nx'>scale</span><span class='p'>.</span><span class='nx'>linear</span><span class='p'>().</span><span class='nx'>domain</span><span class='p'>([</span><span class='mi'>0</span><span class='p'>,</span><span class='mi'>100</span><span class='p'>]).</span><span class='nx'>range</span><span class='p'>([</span><span class='mi'>10</span><span class='p'>,</span><span class='mi'>20</span><span class='p'>])</span> <span class='lineno'>2</span> <span class='nx'>s</span><span class='p'>(</span><span class='mi'>50</span><span class='p'>)</span> <span class='o'>==</span> <span class='mi'>15</span> </code></pre> </div> <p>(domain, range, clamp, invert, rangeRound, interpolate, ticks, tickFormat)</p> <h4 id='id21'><code>d3.scale.pow</code></h4> <p>Map a number in the domain to a number in the range with a power function.</p> <div class='highlight'><pre><code class='js'><span class='lineno'>1</span> <span class='nx'>s</span> <span class='o'>=</span> <span class='nx'>d3</span><span class='p'>.</span><span class='nx'>scale</span><span class='p'>.</span><span class='nx'>pow</span><span class='p'>().</span><span class='nx'>domain</span><span class='p'>([</span><span class='mi'>0</span><span class='p'>,</span><span class='mi'>10</span><span class='p'>]).</span><span class='nx'>range</span><span class='p'>([</span><span class='mi'>0</span><span class='p'>,</span><span class='mi'>10</span><span class='p'>]).</span><span class='nx'>exponent</span><span class='p'>(</span><span class='mi'>2</span><span class='p'>)</span> <span class='lineno'>2</span> <span class='nx'>s</span><span class='p'>(</span><span class='mi'>5</span><span class='p'>)</span> <span class='o'>==</span> <span class='mf'>2.5</span> </code></pre> </div> <p>(domain, range, clamp, invert, rangeRound, interpolate, ticks, tickFormat, exponent)</p> <h4 id='id22'><code>d3.scale.sqrt</code></h4> <p>Map a number in the domain to a number in the range with a square root function. Equivalent to pow.exponent(0.5)</p> <h4 id='id23'><code>d3.scale.log</code></h4> <p>Map a number in the domain to a number in the range with a logarithmic function.</p> <div class='highlight'><pre><code class='js'><span class='lineno'>1</span> <span class='nx'>s</span> <span class='o'>=</span> <span class='nx'>d3</span><span class='p'>.</span><span class='nx'>scale</span><span class='p'>.</span><span class='nx'>log</span><span class='p'>().</span><span class='nx'>domain</span><span class='p'>([</span><span class='mi'>1</span><span class='p'>,</span><span class='mi'>10</span><span class='p'>]).</span><span class='nx'>range</span><span class='p'>([</span><span class='mi'>0</span><span class='p'>,</span><span class='mi'>10</span><span class='p'>])</span> <span class='lineno'>2</span> <span class='nx'>s</span><span class='p'>(</span><span class='mi'>5</span><span class='p'>)</span> <span class='o'>==</span> <span class='mf'>6.9897000433601875</span> </code></pre> </div> <p>(domain, range, clamp, invert, rangeRound, interpolate, ticks, tickFormat)</p> <h4 id='id24'><code>d3.scale.ordinal</code></h4> <p>Map an element in the domain set to an element in the range set.</p> <div class='highlight'><pre><code class='js'><span class='lineno'>1</span> <span class='nx'>s</span> <span class='o'>=</span> <span class='nx'>d3</span><span class='p'>.</span><span class='nx'>scale</span><span class='p'>.</span><span class='nx'>ordinal</span><span class='p'>().</span><span class='nx'>domain</span><span class='p'>([</span><span class='s2'>"a"</span><span class='p'>,</span> <span class='s2'>"b"</span><span class='p'>,</span> <span class='s2'>"c"</span><span class='p'>]).</span><span class='nx'>range</span><span class='p'>([</span><span class='s2'>"one"</span><span class='p'>,</span> <span class='s2'>"two"</span><span class='p'>,</span> <span class='s2'>"three"</span><span class='p'>])</span> <span class='lineno'>2</span> <span class='nx'>s</span><span class='p'>(</span><span class='s2'>"b"</span><span class='p'>)</span> <span class='o'>==</span> <span class='s2'>"two"</span> </code></pre> </div> <p>(domain, rangePoints, rangeBands, rangeRoundBands, rangeBand)</p> <h4 id='id25'><code>d3.scale.category{10,20,20b,20c}</code></h4> <p>Ordinal scales that map the domain to a range of 10 or 20 colours defined by a <a href='http://colorbrewer2.org'>ColorBrewer</a> scale.</p> <h4 id='id26'><code>d3.scale.quantize</code></h4> <p>Map a number in the domain to an element of a set in the range.</p> <div class='highlight'><pre><code class='js'><span class='lineno'>1</span> <span class='nx'>s</span> <span class='o'>=</span> <span class='nx'>d3</span><span class='p'>.</span><span class='nx'>scale</span><span class='p'>.</span><span class='nx'>quantize</span><span class='p'>().</span><span class='nx'>domain</span><span class='p'>([</span><span class='mi'>0</span><span class='p'>,</span><span class='mi'>4</span><span class='p'>]).</span><span class='nx'>range</span><span class='p'>([</span><span class='s2'>"zero"</span><span class='p'>,</span> <span class='s2'>"one"</span><span class='p'>,</span> <span class='s2'>"two"</span><span class='p'>,</span> <span class='s2'>"three"</span><span class='p'>])</span> <span class='lineno'>2</span> <span class='nx'>s</span><span class='p'>(</span><span class='mf'>2.7</span><span class='p'>)</span> <span class='o'>==</span> <span class='s2'>"two"</span> </code></pre> </div> <p>(domain, range)</p> <h4 id='id27'><code>d3.scale.quantile</code></h4> <p>…</p> <p>(quantiles)</p> <h3 id='interpolation'>interpolation</h3> <p>In D3, interpolation functions map numbers in the interval [0,1] to some output range. Interpolation functions can be used directly or passed as parameters to a scale’s <code>interpolate</code> method.</p> <h4 id='id28'><code>interpolateNumber</code></h4> <p>Interpolate via a linear scale to the specified interval.</p> <div class='highlight'><pre><code class='js'><span class='lineno'>1</span> <span class='nx'>i</span> <span class='o'>=</span> <span class='nx'>d3</span><span class='p'>.</span><span class='nx'>interpolateNumber</span><span class='p'>(</span><span class='mi'>10</span><span class='p'>,</span><span class='mi'>20</span><span class='p'>)</span> <span class='lineno'>2</span> <span class='nx'>i</span><span class='p'>(</span><span class='mf'>0.47</span><span class='p'>)</span> <span class='o'>==</span> <span class='mf'>14.7</span> </code></pre> </div> <h4 id='id29'><code>interpolateRound</code></h4> <p>Interpolate via a linear scale to the specified interval, rounding the output to the nearest integer</p> <div class='highlight'><pre><code class='js'><span class='lineno'>1</span> <span class='nx'>d3</span><span class='p'>.</span><span class='nx'>interpolateRound</span><span class='p'>(</span><span class='mi'>10</span><span class='p'>,</span><span class='mi'>20</span><span class='p'>)(</span><span class='mf'>0.47</span><span class='p'>)</span> <span class='o'>==</span> <span class='mi'>15</span> </code></pre> </div> <h4 id='id30'><code>interpolateRgb</code></h4> <p>Interpolate between two RGB specified colors, interpolating linearly in red, green, and blue.</p> <div class='highlight'><pre><code class='js'><span class='lineno'>1</span> <span class='nx'>d3</span><span class='p'>.</span><span class='nx'>interpolateRgb</span><span class='p'>(</span><span class='s2'>"#ff0000"</span><span class='p'>,</span> <span class='s2'>"#0000ff"</span><span class='p'>)(</span><span class='mf'>0.3</span><span class='p'>)</span> <span class='o'>==</span> <span class='s2'>"rgb(179,0,77)"</span> </code></pre> </div> <h4 id='id31'><code>interpolateHsl</code></h4> <p>Interpolate between two HSL specified colors, interpolating linearly in hue, saturation, and lightness. The output is an RGB specification for compatibility with limited CSS implementations.</p> <div class='highlight'><pre><code class='js'><span class='lineno'>1</span> <span class='nx'>d3</span><span class='p'>.</span><span class='nx'>interpolateHsl</span><span class='p'>(</span><span class='s2'>"hsl(180,75,50)"</span><span class='p'>,</span><span class='s2'>"hsl(180,0,0)"</span><span class='p'>)(</span><span class='mf'>0.5</span><span class='p'>)</span> <span class='o'>==</span> <span class='s2'>"#285858"</span> </code></pre> </div> <h4 id='id32'><code>interpolateString</code></h4> <p>Interpolate between two strings with embedded numbers; inputs can be font sizes, color strings, SVG path data, etc. The output is a string. Numbers embedded in the start and end string are discovered and numeric interpolators constructed between them; a templatized string is used to generate interpolated outputs.</p> <div class='highlight'><pre><code class='js'><span class='lineno'>1</span> <span class='nx'>d3</span><span class='p'>.</span><span class='nx'>interpolateString</span><span class='p'>(</span><span class='s2'>"10px sans-serif"</span><span class='p'>,</span> <span class='s2'>"20px sans-serif"</span><span class='p'>)(</span><span class='mf'>0.5</span><span class='p'>)</span> <span class='o'>==</span> <span class='s2'>"15px sans-serif"</span> </code></pre> </div> <h4 id='id33'><code>interpolateArray</code></h4> <p>Interpolate between two arrays by iterating interpolators over the elements. For each value in the start and end array, a generic interpolator is constructed using <code>d3.interpolate</code>. The array interpolator returns an array containing the result of evaluating the nested interpolators.</p> <div class='highlight'><pre><code class='js'><span class='lineno'>1</span> <span class='nx'>d3</span><span class='p'>.</span><span class='nx'>interpolateArray</span><span class='p'>([</span><span class='mi'>0</span><span class='p'>,</span><span class='mi'>1</span><span class='p'>,</span><span class='mi'>2</span><span class='p'>],</span> <span class='p'>[</span><span class='mi'>1</span><span class='p'>,</span><span class='mi'>2</span><span class='p'>,</span><span class='mi'>3</span><span class='p'>])(</span><span class='mf'>0.5</span><span class='p'>)</span> <span class='o'>==</span> <span class='p'>[</span><span class='mf'>0.5</span><span class='p'>,</span><span class='mf'>1.5</span><span class='p'>,</span><span class='mf'>2.5</span><span class='p'>]</span> </code></pre> </div> <h4 id='id34'><code>interpolateObject</code></h4> <p>Interpolate between two objects by iterating interpolators over the object properties. For each value in the start and end object, a generic interpolator is constructed using <code>d3.interpolate</code>. The object interpolator returns an object containing the result of evaluating the nested interpolators.</p> <div class='highlight'><pre><code class='js'><span class='lineno'>1</span> <span class='nx'>d3</span><span class='p'>.</span><span class='nx'>interpolateObject</span><span class='p'>({</span><span class='nx'>foo</span><span class='o'>:</span> <span class='mi'>0</span><span class='p'>,</span> <span class='nx'>bar</span><span class='o'>:</span> <span class='mi'>1</span><span class='p'>},</span> <span class='p'>{</span><span class='nx'>foo</span><span class='o'>:</span> <span class='mi'>1</span><span class='p'>,</span> <span class='nx'>bar</span><span class='o'>:</span> <span class='mi'>2</span><span class='p'>})(</span><span class='mf'>0.5</span><span class='p'>)</span> <span class='o'>==</span> <span class='p'>{</span><span class='nx'>foo</span><span class='o'>:</span> <span class='mf'>0.5</span><span class='p'>,</span> <span class='nx'>bar</span><span class='o'>:</span> <span class='mf'>1.5</span><span class='p'>}</span> </code></pre> </div> <h4 id='id35'><code>interpolate</code></h4> <p>A function that determines the type of interpolation required and in turn calls <code>interpolateNumber</code>, <code>interpolateRgb</code>, <code>interpolateString</code>, <code>interpolateArray</code>, or <code>interpolateObject</code> as appropriate.</p> <h3 id='d3svg'>d3.svg</h3> <p>mouse, arc (innerRadius, outerRadius, startAngle, endAngle), line (x, y, interpolate, tension) area, (x, y0, y1, interpolate, tension), chord (radius, source, target, startAngle, endAngle).</p> <h3 id='d3time'>d3.time</h3> <p>format (format, parse, toString).</p> <h3 id='d3layout'>d3.layout</h3> <p>chord (matrix, padding, sortGroups, sortSubgroups, sortChords, chords, groups), stack (order, offset), force (on, nodes, links, size, distance, start, stop, resume, drag), pie (value, sort, startAngle, endAngle), treemap (children, value, size, round).</p> <h3 id='d3geom'>d3.geom</h3> <p>contour, hull, voronoi, delaunay, quadtree, polygon (area, clip).</p> <h3 id='d3geo'>d3.geo</h3> <p>albers (origin, parallels, scale, translate), albersUsa (scale, translate), mercator (scale, translate), path (projection, area, pointRadius).</p> <h3 id='d3csv'>d3.csv</h3> <p>parse, parseRows, format.</p> </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>