31:T506,md`There are numerous methods for designing visualizations, including _visual analysis grammars_ like [Vega-Lite](https://observablehq.com/@uwdata/introduction-to-vega-lite) and _visualization grammars_ like [D3.js](https://d3js.org/). Visual analysis grammars break visualization design down into a process of specifying _mappings_ (or _visual encodings_) between data fields and the properties of graphical objects called _marks_. Such grammars are useful for concisely and rapidly creating recognizable visualizations, while providing more design flexibility (or _expressivity_) than the chart typologies commonly found in spreadsheet tools. However, describing visualization design in these high-level terms limits the types of visualizations we can create. For example, we can only use the available marks, and can only bind data to supported encoding channels. For more expressive power, we must take one step down the [ladder of abstraction](http://worrydream.com/LadderOfAbstraction/): from _visual analysis_ grammars to more general-purpose _visualization_ grammars. With visualization grammars, we still specify how data values map to the properties of graphical marks, but we now have an additional set of operators to specify this mapping with more fine-grained control.`32:T726,md`At this point, we're nearing the limit of what we can do with D3 and the HTML DOM. In particular, HTML is largely restricted to rectangular shapes and is governed by a [complex layout model](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/The_box_model) that can often interfere with the way we wish to position and size marks for visualization purposes. In the previous chart, we relied entirely on the underlying layout model to position the bars instead of using a data-driven approach. This method breaks our _visual encoding_ abstraction of mapping data values to visual properties. In this case, each element is positioned based on the order in which it was created rather than a data value, and thus yields a more difficult and brittle design process. Now imagine we want to rotate our bar chart into a column chart (i.e., tall bars instead of long ones): we would need to use an [inline](https://www.w3schools.com/css/css_inline-block.asp) [layout](https://www.w3schools.com/css/css_float.asp) [mechanism](https://css-tricks.com/snippets/css/a-guide-to-flexbox/) to position bars side-by-side rather than as stacked elements. As with the example above, this approach similarly lacks a connection to the relevant data properties. As a result, rather than persevere with HTML, let's instead switch to [SVG (Scalable Vector Graphics)](https://developer.mozilla.org/en-US/docs/Web/SVG). SVG gives us a much richer set of [graphical primitives](https://developer.mozilla.org/en-US/docs/Web/SVG/Element) to work with including curves, lines, and arbitrary shapes. Like HTML, SVG elements can be styled using CSS and can be programmatically manipulated via the DOM. So everything we've learned so far in this notebook still applies. Let's recreate our bar chart, this time using SVG \`\` elements:`33:T51a,{ const width = 400; const height = 200; const container = d3.create('svg') .attr('width', width) .attr('height', height); // Update the x scale here. const xscale = d3.scaleLinear() .domain([0, d3.max(barData, d => d.value)]) .range([0, width]); // Update the y scale here. const yscale = d3.scaleBand() .domain(barData.map(d => d.key)) .range([0, height]); container.selectAll('rect') .data(barData) .join('rect') .attr('x', 0) // Update the x position .attr('y', d => yscale(d.key)) // Update the y position .attr('width', d => xscale(d.value)) // Update the width .attr('height', yscale.bandwidth()) // Update the height .style('fill', d => color(d.key)) .style('stroke', 'white'); container.selectAll('text') .data(barData) .join('text') .attr('x', d => xscale(d.value)) // Update the x position .attr('y', d => yscale(d.key)) // Update the y position .attr('dx', -20) // Update the x offset .attr('dy', '1.5em') // Update the y offset .attr('fill', 'white') .style('font-size', 'small') .style('text-anchor', 'middle') .text(d => d.value); return container.node(); }34:T606,md` After working with Vega-Lite and moving to D3, you might be thinking: "What a lot of low-level work for such a simple chart!" _(You would not be wrong!)_ However, the example above introduces most of the components you will need to construct a variety of more complex visualizations. The concepts & utilities you've learned will become second nature as you start to build more ambitious charts! Borrowing from [Scott Murray](https://alignedleft.com/work/d3-book-2e), D3 is _not_ a charting library. Rather, it is more apt to call it a visualization _kernel_ as it offers a series of modules for constructing visualizations including [loading](https://github.com/d3/d3-fetch) and [parsing](https://github.com/d3/d3-dsv) data, [binding](https://github.com/d3/d3-selection) and [encoding](https://github.com/d3/d3-scale) DOM elements, and calculating more advanced layouts such as [force-directed layouts](https://github.com/d3/d3-force) or [cartographic projections](https://github.com/d3/d3-geo). This notebook only scratches the surface of all the functionality D3 provides. Luckily, as D3 is one of the most widely used JavaScript libraries, there is a rich and diverse set of examples to learn from. We recommend perusing the [@d3 Observable notebooks](https://observablehq.com/@d3) or looking through the [curated gallery of examples](https://observablehq.com/@d3/gallery). When you're ready for more—including animation & interaction—[move on to Part 2](https://observablehq.com/@uwdata/introduction-to-d3-part-2)!`35:[{"id":"68f89ebe654f81a62174c4cf1446d2beff0b96ee642277cc4e5c81dbc57368c037d4adcd7ae174604a7b7c3be073b0dc106baee5e6004ae2ce333be09a26eeda","href":"https://static.observableusercontent.com/files/68f89ebe654f81a62174c4cf1446d2beff0b96ee642277cc4e5c81dbc57368c037d4adcd7ae174604a7b7c3be073b0dc106baee5e6004ae2ce333be09a26eeda","name":"Screen Shot 2020-03-02 at 7.13.09 AM.png","type":"image/png","lastModified":1600625885369.922,"size":20018},{"id":"f439de574431e955df9589f743d0e5d37373c2ed87ad38204dea1a5ef8474fc88879e6c50c3ba8ec82cc1f62261970a87a5c7fd1c0321cd2993270a1f3be05f1","href":"https://static.observableusercontent.com/files/f439de574431e955df9589f743d0e5d37373c2ed87ad38204dea1a5ef8474fc88879e6c50c3ba8ec82cc1f62261970a87a5c7fd1c0321cd2993270a1f3be05f1","name":"Screen Shot 2020-03-02 at 9.11.37 AM.png","type":"image/png","lastModified":1600625885369.922,"size":25363},{"id":"d6d9378d3a831b7abbd577d36861aae886588e8cb9277caa50c790dcb2ca54f1f35158297e477e03f2aa0d0804add25c1ba2784fffc3a9fba922036c46b1f1fa","href":"https://static.observableusercontent.com/files/d6d9378d3a831b7abbd577d36861aae886588e8cb9277caa50c790dcb2ca54f1f35158297e477e03f2aa0d0804add25c1ba2784fffc3a9fba922036c46b1f1fa","name":"barchart-upsidedown.png","type":"image/png","lastModified":1602837660133.733,"size":8484}] 2f:{"title":"Introduction to D3, Part 1","cells":[{"id":0,"value":"md`# Introduction to D3, Part 1`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1117,"value":"md`_(Note: this is a revised version of an [original notebook by Arvind Satyanarayan](https://observablehq.com/@mitvis/introduction-to-d3). The current notebook includes modified text and code updated for D3 v6 and higher.)_`","pinned":false,"hidden":false,"mode":"ojs"},{"id":4,"value":"$31","pinned":false,"hidden":false,"mode":"ojs"},{"id":1121,"value":"md`In this notebook, we will gain familiarity with one of the most widely used visualization grammars: [D3.js](https://d3js.org/). Let's start by importing the D3 library:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":29,"value":"d3 = require('d3@7')","pinned":true,"hidden":false,"mode":"ojs"},{"id":32,"value":"md`Next let's load a dataset to work with. We'll use a dataset on global health and population measures from 1955–2005, compiled by the [Gapminder Foundation](https://www.gapminder.org/) and shared in [Hans Rosling's popular TED talk](https://www.youtube.com/watch?v=hVimVzgtD6w).`","pinned":false,"hidden":false,"mode":"ojs"},{"id":34,"value":"gapminder = datasets['gapminder.json']()","pinned":false,"hidden":false,"mode":"ojs"},{"id":38,"value":"aq.from(gapminder).view({ limit: 15, height: 450 })","pinned":false,"hidden":false,"mode":"ojs"},{"id":16,"value":"md`

\n## Selections and Data Binding`","pinned":false,"hidden":false,"mode":"ojs"},{"id":22,"value":"md`Rather than confining us to a pre-determined set of graphical marks, D3 takes a much more general approach: _any element_ of the DOM (the [Document Object Model](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model/Introduction), or the programmatic representation of a webpage) can be a data-driven mark.\n\nFor instance, we could \"visualize\" a subset of our dataset as an ordered list (\\`

\\`) are marks:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":125,"value":"// extract the 10 most populous countries in 2005\nlistData = gapminder\n .filter(d => d.year === 2005)\n .sort((a, b) => b.pop - a.pop)\n .slice(0, 10)","pinned":false,"hidden":false,"mode":"ojs"},{"id":49,"value":"list = {\n const fmt = d3.format(',');\n const ol = d3.create('ol');\n \n ol.selectAll('li') // selects all 'li' elements (which may or may not exist!)\n .data(listData) // provides the backing data\n .join('li') // joins data with the selection, creating 'li' elements as needed\n .text(d => `${d.country}: ${fmt(d.pop)}`) // add formatted text to 'li' elements\n \n return ol.node(); // return the DOM element node of the 'ol' element\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":123,"value":"md`To enable this functionality, D3's core operator is the [_selection_](https://d3js.org/d3-selection). Selections specify a set of DOM elements that share the same tag name, class attribute, or any other supported [CSS Selector](https://www.w3schools.com/cssref/css_selectors.asp). Selections are specified with the [\\`d3.select\\`](https://d3js.org/d3-selection/selecting#select) and [\\`d3.selectAll\\`](https://d3js.org/d3-selection/selecting#selectAll) functions, which roughly map to their native DOM equivalents ([\\`document.querySelector\\`](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector) and [\\`document.querySelectorAll\\`](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelectorAll)).`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1335,"value":"md`Using our selection as the base, we can employ the [\\`selection.data()\\`](https://d3js.org/d3-selection/joining#selection_data) operator to bind DOM elements to some backing data. We can then display the DOM node for the ordered list using \\`ol.node()\\`.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1334,"value":"{\n const ol = d3.create('ol');\n \n ol.selectAll('li') // select all list elements (orange circle below)\n .data(listData) // bind all our data values (blue circle below)\n \n return ol.node(); // return the DOM element node of the 'ol' element\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":1333,"value":"md`However, notice that the current visualization is blank! We have not yet created the new DOM elements for the list items. Rather, the call to \\`selection.data()\\` returns a _new_ selection with three different states: _enter_, _update_, and _exit_.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1332,"value":"selection = {\n const ol = d3.create('ol');\n return ol.selectAll('li').data(listData);\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":1331,"value":"datajoin = html``","pinned":false,"hidden":false,"mode":"ojs"},{"id":1330,"value":"md`_Credit: [Mike Bostock](https://bost.ocks.org/mike/join/)_`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1329,"value":"md`For every value in our backing data, the operator checks whether a corresponding DOM element exists in a one-to-one manner:\n\n * The **enter** state is a selection that contains _placeholders_ for every data value that did not have a corresponding element in the original selection.\n\n * The **update** state is a selection that contains _existing_ elements that match a bound data value.\n\n * The **exit** state is a selection that also contains _existing_ elements, but for which a matching data value was not found.\n\nWe can address the three states separately, but the [\\`selection.join()\\`](https://d3js.org/d3-selection/joining#selection_join) operator gives us a more convenient interface:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1328,"value":"{\n const ol = d3.create('ol');\n\n ol.selectAll('li') // select all list elements (orange circle above)\n .data(listData) // bind all our data values (blue circle above)\n .join('li') // merge the 'enter' and 'update' sets, create 'li' elements as needed\n\n return ol.node(); // return the DOM element node of the 'ol' element\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":1327,"value":"md`By default, if we just pass a string to \\`selection.join()\\`, entering elements are appended to the selection, exiting elements are removed, and updating elements simply pass through. However, we can also address the three states separately. For instance, the code snippet below is the long form version of the one above:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1326,"value":"vis = {\n const ol = d3.create('ol');\n \n ol.selectAll('li') // select all list elements (orange circle above)\n .data(listData) // bind all our data values (blue circle above)\n .join(\n enter => enter.append('li'), // <-- append an li element for each entering item\n update => update, // <-- do nothing with items that match an existing element\n exit => exit.remove() // <-- remove li elements whose backing data is now gone\n )\n \n return ol.node(); // return the DOM element node of the 'ol' element\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":1325,"value":"md`We now have a new list item element for each element in our dataset, but we have yet to specify the content and visual style of the elements themselves. An advantage of D3 is that we can manipulate a selection _declaratively_. This means that rather than iterating over every item returned by the selector (like we would have had to do using \\`document.querySelectorAll\\`), we can operate on the selection as a whole:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1324,"value":"{\n const ol = d3.create('ol');\n\n ol.selectAll('li') // select all list elements (orange circle above)\n .data(listData) // bind all our data values (blue circle above)\n .join('li') // merge the 'enter' and 'update' sets, create 'li' elements as needed\n .attr('class', 'country') // <-- set CSS class to 'country'\n .text(d => `${d.country}: ${d.pop}`) // <-- add text to 'li' elements\n\n return ol.node(); // return the DOM element node of the 'ol' element\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":1323,"value":"md`Using selections, you can update the style even of elements that have already been created. For example, we can select the new list items with the CSS class \\`'country'\\` to update the style of our previous list:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":159,"value":"// Run this cell to recolor just the first item in the list above\nd3.select('li.country').style('color', randomColor()), null","pinned":true,"hidden":false,"mode":"ojs"},{"id":173,"value":"// Run this cell to recolor ALL items in the list above\n// Sets all items to the same randomly selected color\nd3.selectAll('li.country').style('color', randomColor()), null","pinned":true,"hidden":false,"mode":"ojs"},{"id":1322,"value":"md`For the enter / update / exit cycle, matches are determined by the second argument to \\`.data()\\`, which specifies a key function. If no key function is specified, D3 conducts a join-by-index: the first data value is joined to the first DOM element, the second value to the second element, and so on. In the code for the exercise below, we instead join the data based on the country attribute.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1149,"value":"md`
`","pinned":false,"hidden":false,"mode":"ojs"},{"id":298,"value":"md`Exercise: Modify the _enter_, _update_, and _exit_ functions in the code below such that entering items are colored green, updating items are colored blue, and exiting items are _not_ removed but rather colored red.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1104,"value":"md`You can use the sliders below to change the elements in the backing \\`listData\\` to test your changes to \\`enter\\`, \\`update\\`, and \\`exit\\`, and reset the visualization with the button.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":105,"value":"viewof year = Scrubber(\n // min to max years in 5 year increments\n d3.range(d3.min(gapminder, d => d.year), d3.max(gapminder, d => d.year) + 1, 5), \n { \n autoplay: false, delay: 500, loop: false, // experiment with these settings!\n format: year => 'year = ' + year + reset, // display the variable name and force cell to rerun on reset\n initial: listData[0].year // initial year of listData elements\n }\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":108,"value":"viewof n = Scrubber(\n d3.range(0, 15, 1),\n { \n autoplay: false, delay: 500, loop: false, // experiment with these settings!\n format: n => 'n = ' + n + reset, // display the variable name and force cell to rerun on reset\n initial: listData.length // initial number of listData elements\n }\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":1316,"value":"viewof reset = html``","pinned":false,"hidden":false,"mode":"ojs"},{"id":319,"value":"{\n const ol = d3.select(html`
`);\n \n const update = reset; // Rerun this cell when the reset button is clicked.\n \n ol.selectAll('li') // select all list elements (orange circle above)\n .data(listData) // bind all our data values (blue circle above)\n .join('li') // a selection that merges the \"enter\" and \"update\" states\n .text(d => `${d.country}: ${d.pop}`)\n \n return ol.node();\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":306,"value":"{\n const ol = d3.select('ol#enter-update-exit');\n\n // use a new dataset, manipulable with the variables defined above\n const newData = gapminder\n .filter(d => d.year === year)\n .sort((a, b) => b.pop - a.pop)\n .slice(0, n);\n \n ol.selectAll('li') // select all list elements\n .data(newData, d => d.country) // bind our data values; what happens when we remove the key function?\n .join( \n enter => enter.append('li'),\n update => update,\n exit => exit.remove()\n ) \n .text(d => `${d.country}: ${d.pop}`);\n \n return newData;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":1154,"value":"md`
`","pinned":false,"hidden":false,"mode":"ojs"},{"id":335,"value":"md`Why all of this complexity? D3's data join operators give us a general way to draw our visualization's marks. As a result, we don't have to worry about any kind of iteration or branching (i.e., no \\`for\\` loops or \\`if\\` statements). We can focus on _what_ we want our visualization to look like, rather than writing out each step for _how_ it should be computed. This property is called _declarative_ (in contrast to _imperative_) specification or programming and helps keep our code more readable and understandable. And, as we'll see in [Part 2](https://observablehq.com/@uwdata/introduction-to-d3-part-2) of this introduction, D3's data join makes it more convenient to specify animated transitions as items are entering, updating, or exiting.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":354,"value":"md`
\n## A Simple Bar Chart`","pinned":false,"hidden":false,"mode":"ojs"},{"id":357,"value":"md`Before we get more complex, let's try our hand at making a simple bar chart showing the average life expectancy (\\`value\\`) for different geographic regions (\\`key\\`), using D3 to create basic HTML \\`
\\` elements.\n\nTry to recreate the bar chart below. You will want to bind the bar data to new \\`div\\` elements, style them appropriately, and add the text. One thing to keep in mind: How might you increase the size of the bars to fill the width of the screen?`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1310,"value":"md`The current page \\`width\\` = ${width} px.` // Observable's built-in width property!","pinned":true,"hidden":false,"mode":"ojs"},{"id":1309,"value":"FileAttachment(\"Screen Shot 2020-03-02 at 7.13.09 AM.png\").image()","pinned":false,"hidden":false,"mode":"ojs"},{"id":364,"value":"// compute average life expectancy per region ('cluster')\n// output values as 'key' (cluster) and 'value' (life_expect)\nbarData = aq.from(gapminder)\n .filter(d => d.year === 2005)\n .groupby('cluster')\n .rollup({ mean: d => op.floor(op.mean(d.life_expect)) })\n .orderby('cluster')\n .select({ cluster: 'key', mean: 'value' })\n .objects()","pinned":false,"hidden":false,"mode":"ojs"},{"id":362,"value":"{\n const container = d3.create('div');\n \n const data = barData;\n \n const barChart = container.selectAll('div')\n /* TODO: Add code here to generate the bar chart within the container. */\n \n barChart\n .style('background', 'steelblue') // Set the background color of the div to 'steelblue'\n .style('border', '1px solid white') // Set the border of the div as 'white'\n .style('font-size', 'small') // Set the text font size in the div to 'small'\n .style('color', 'white') // Set the text font color to 'white'\n .style('text-align', 'right') // Set the text alignment in the div to 'right'\n .style('padding', '3px') // HINT: CSS styles require units, not just numbers\n /* TODO: Add code here to finish updating the visual properties of the bars */\n \n return container.node();\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":409,"value":"md`Did you find yourself \"hard-wiring\" a scale factor for the width of the bars? If so, our simple bar chart exposes one weakness in how we might specify visual encodings: The _width_ of our bars could be dependent on a magic number, which scales the data value to a pixel width. Ideally such scaling should not be brittle, it should adapt to the range of data values as well as the desired total width of the chart.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":420,"value":"md`
\n## Scale Functions`","pinned":false,"hidden":false,"mode":"ojs"},{"id":423,"value":"md`Rather than implicitly dealing with scaling issues, or introducing maintenance and readability costs associated with magic numbers, D3 offers us a variety of [scale functions](https://d3js.org/d3-scale) to automatically map a _domain_ of data values to a _range_ of pixel values.\n\nFor instance, we can use the following scale to determine the width of our bars:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":426,"value":"xscale = d3.scaleLinear()\n .domain([0, d3.max(barData, d => d.value)])\n .range([0, width]) // Observable's built-in width property!","pinned":true,"hidden":false,"mode":"ojs"},{"id":433,"value":"md`\\`xscale\\` is a function that linearly maps an input value to the given range:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":437,"value":"xscale(49)","pinned":true,"hidden":false,"mode":"ojs"},{"id":442,"value":"md`We can now use it to scale our bar widths like so:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":432,"value":"{\n const container = d3.create('div');\n\n container.selectAll('div')\n .data(barData)\n .join('div')\n .style('background', 'steelblue')\n .style('border', '1px solid white')\n .style('font-size', 'small')\n .style('color', 'white')\n .style('text-align', 'right')\n .style('padding', '3px')\n .style('width', d => `${xscale(d.value)}px`) // <-- Use xscale instead of a magic number\n .text(d => d.value);\n\n return container.node();\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":448,"value":"md`Scales are a workhorse of visualization design! For example, we might want to assign each bar a different color. One option to do so could involve a large ternary expression or if-else statement. We can instead use a [color scale](https://d3js.org/d3-scale-chromatic) like so:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":452,"value":"color = d3.scaleOrdinal(d3.schemeTableau10).domain(barData.map(d => d.key)); \n// Default color schemes are here: https://d3js.org/d3-scale-chromatic/categorical\n// Try another one! For example: d3.schemePurples[6] or d3.schemePaired","pinned":true,"hidden":false,"mode":"ojs"},{"id":456,"value":"{\n const container = d3.create('div');\n\n container.selectAll('div')\n .data(barData)\n .join('div')\n .style('background', d => color(d.key)) // <-- Use color scale to specify the bar color\n .style('border', '1px solid white')\n .style('font-size', 'small')\n .style('color', 'white')\n .style('text-align', 'right')\n .style('padding', '3px')\n .style('width', d => `${xscale(d.value)}px`)\n .text(d => d.value);\n\n return container.node();\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":461,"value":"md`
\n## SVG: Scalable Vector Graphics`","pinned":false,"hidden":false,"mode":"ojs"},{"id":462,"value":"$32","pinned":false,"hidden":false,"mode":"ojs"},{"id":498,"value":"{\n const barHeight = 25;\n const height = barData.length * barHeight;\n\n // create svg element, specify total width and height\n const container = d3.create('svg')\n .attr('width', width)\n .attr('height', height);\n\n // add SVG 'rect' elements for bars\n container.selectAll('rect')\n .data(barData)\n .join('rect')\n .attr('x', 0)\n .attr('y', (d, i) => i * barHeight)\n .attr('width', d => xscale(d.value))\n .attr('height', barHeight)\n .style('fill', d => color(d.key))\n .style('stroke', 'white');\n\n // add SVG 'text' elements for labels\n container.selectAll('text')\n .data(barData)\n .join('text')\n .attr('x', d => xscale(d.value))\n .attr('y', (d, i) => i * barHeight)\n .attr('dx', -20)\n .attr('dy', '1.25em')\n .attr('fill', 'white')\n .style('font-size', 'small')\n .text(d => d.value);\n\n // return SVG DOM element\n return container.node();\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":555,"value":"md`Perhaps the biggest change in our shift from HTML to SVG is that we are entirely responsible for how our bars are laid out. Whereas before we could rely on \\`
\\` elements gaining a height based on their content and padding, and on the [flow layout model](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flow_Layout) to position them one after another, in SVG we have to explicitly set the \\`x\\`, \\`y\\` positions of all elements, and the \\`width\\` and \\`height\\` of our \\`\\` elements.\n\nA _magic number_ has snuck back into our specification. Can you spot it?`","pinned":false,"hidden":false,"mode":"ojs"},{"id":583,"value":"md`Using SVG does not mean we need to hard-wire the height of our bars. Instead, we can use [band scales](https://observablehq.com/@d3/d3-scaleband) to automatically divide up the total height of our SVG element (\\`150px\\`) into equally-sized bars.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":779,"value":"height = 150","pinned":true,"hidden":false,"mode":"ojs"},{"id":586,"value":"yscale = d3.scaleBand()\n .domain(barData.map(d => d.key))\n .range([0, height]) // Try flipping this to [height, 0] and see the effect on the bars below.","pinned":true,"hidden":false,"mode":"ojs"},{"id":595,"value":"md`Now we can use our new \\`yscale\\` like so:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":609,"value":"{\n const container = d3.create('svg')\n .attr('width', width)\n .attr('height', height);\n\n container.selectAll('rect')\n .data(barData)\n .join('rect')\n .attr('x', 0)\n .attr('y', d => yscale(d.key)) // <-- Use yscale instead of manually positioning bars\n .attr('width', d => xscale(d.value))\n .attr('height', yscale.bandwidth()) // <-- Band scales split a pixel range into equal-sized bands\n .style('fill', d => color(d.key))\n .style('stroke', 'white');\n\n container.selectAll('text')\n .data(barData)\n .join('text')\n .attr('x', d => xscale(d.value))\n .attr('y', d => yscale(d.key)) // <-- Use yscale instead of manually positioning labels\n .attr('dx', -20)\n .attr('dy', '1.2em')\n .attr('fill', 'white')\n .style('font-size', 'small')\n .text(d => d.value);\n\n return container.node();\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":619,"value":"md`With SVG, rotating our bar chart into a column chart becomes much more straightforward than it would have been with HTML.` ","pinned":false,"hidden":false,"mode":"ojs"},{"id":659,"value":"md``","pinned":false,"hidden":false,"mode":"ojs"},{"id":1344,"value":"md`Edit the code below to change your bar chart from a horizontal orientation to a vertical orientation (as in the image above). _Hint: Think about how the scales of a horizontal bar chart differ from those of a vertical bar chart._`","pinned":false,"hidden":false,"mode":"ojs"},{"id":627,"value":"$33","pinned":true,"hidden":false,"mode":"ojs"},{"id":1299,"value":"md`As you work through this example, you might find that while updating the orientation is more straightforward with this approach, properly positioning the bars remains challenging. Your first attempt may result in a chart like the following:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1298,"value":"md``","pinned":false,"hidden":false,"mode":"ojs"},{"id":1297,"value":"md`This outcome is because the origin \\`(0, 0)\\` of the SVG coordinate system is in the top-left hand corner of the SVG element. Because of this idiosyncrasy, our values are mapped such that the top of the chart corresponds to zero and values increase as you move downward. To address this mismatch from our expectations, we can update the definition of our scales:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1296,"value":"yscaleFixed = d3.scaleLinear()\n .domain([0, d3.max(barData, d => d.value)])\n .range([height, 0])","pinned":true,"hidden":false,"mode":"ojs"},{"id":1295,"value":"md`With this new definition, the zero point of the SVG coordinate system is mapped to the largest value in our dataset, whereas zero corresponds to our expected baseline: the height of the chart. Using the new scale, try updating your bar chart to match the original image. _Hint: The y position is the position for the top of the bars!_`","pinned":false,"hidden":false,"mode":"ojs"},{"id":679,"value":"md`As we can see, scales really are at the heart of our visualization design process. As a result, it's often very helpful to visualize the scales themselves as axes and legends. D3 can help with this, but we first have to take a bit of a tangent...`","pinned":false,"hidden":false,"mode":"ojs"},{"id":686,"value":"md`
\n## \\`\\`: The SVG Group Element`","pinned":false,"hidden":false,"mode":"ojs"},{"id":696,"value":"md`SVG's \\`\\` element allows us to group a set of elements together, not unlike desktop presentation packages like Keynote or Powerpoint. Once grouped, all children can be transformed together — for example, we can position the overall group rather than the individual children. Each \\`\\` also establishes its own coordinate system, with the origin \\`(0, 0\\`) in the top-left hand corner.\n\nFor example, we can rewrite our bar chart visualization using \\`\\` elements as follows. Notice that the \\`\\` and \\`\\` elements are now children of \\`\\`, inherit its data, and only need minimal positioning due to the group's \\`transform\\`.` ","pinned":false,"hidden":false,"mode":"ojs"},{"id":713,"value":"{\n const container = d3.create('svg')\n .attr('width', width)\n .attr('height', height);\n\n const g = container.selectAll('g')\n .data(barData)\n .enter() // <-- We use \"enter\" (not \"join\") so we can later append and only for new data.\n .append('g')\n .attr('transform', d => `translate(0, ${yscale(d.key)})`);\n\n g.append('rect')\n // We no longer need to bind data to , or specify y positions.\n .attr('width', d => xscale(d.value))\n .attr('height', yscale.bandwidth())\n .style('fill', d => color(d.key))\n .style('stroke', 'white');\n\n g.append('text')\n // We no longer need to bind data to , or specify y positions.\n .attr('x', d => xscale(d.value))\n .attr('dx', -20)\n .attr('dy', '1.2em')\n .attr('fill', 'white')\n .style('font-size', 'small')\n .text(d => d.value);\n \n return container.node();\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":725,"value":"md`Alright, now that we've met \\`\\`, let's get back to the main event!`","pinned":false,"hidden":false,"mode":"ojs"},{"id":728,"value":"md`
\n## Visualizing Scales: Axes & Legends`","pinned":false,"hidden":false,"mode":"ojs"},{"id":731,"value":"md`Axes and legends visualize our scale functions using text labels, shapes, and lines. We could construct them manually (as in [this notebook](https://observablehq.com/@d3/color-legend)) but D3 (and its developer community) offers us some helper modules to make our lives easier.\n\nLet's start with axes. With the way we're currently drawing our bar chart, we haven't left any room for axes — the bars are flush with the left and bottom sides of our SVG container. To give us the space we need, we use the [margin convention](https://observablehq.com/@d3/margin-convention):`","pinned":false,"hidden":false,"mode":"ojs"},{"id":740,"value":"graphic","pinned":false,"hidden":false,"mode":"ojs"},{"id":744,"value":"md`_Credit: [Mike Bostock](https://observablehq.com/@d3/margin-convention)_`","pinned":false,"hidden":false,"mode":"ojs"},{"id":748,"value":"md`Rather than only defining the \\`width\\` and \\`height\\` of our visualization, and using these variables to drive the ranges of our \\`x\\` and \\`y\\` scales, we will define an additional \\`margin\\` object with a property for each of the four sides:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":761,"value":"margin = ({top: 10, right: 10, bottom: 20, left: 20})","pinned":true,"hidden":false,"mode":"ojs"},{"id":764,"value":"md`Our scales will then use this margin offset to determine their range:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":772,"value":"// Domain (data values): [0, 78], Range (pixel values): [20, width - 10]\nxMargin = xscale.copy().range([margin.left, width - margin.right])","pinned":true,"hidden":false,"mode":"ojs"},{"id":794,"value":"// Remember (0, 0) is the top-left hand corner; try flipping the elements and see what happens!\n// Domain (data values): [0, 1, 2, 3, 4, 5], Range (pixel values): [height - 20, 10]\nyMargin = yscale.copy().range([height - margin.bottom, margin.top])","pinned":true,"hidden":false,"mode":"ojs"},{"id":796,"value":"md`Using these scales, our bar chart currently looks like this. We now have some whitespace around the left and bottom of the SVG element, just waiting for our axes! \n\nYou may also notice that the order of our bars has switched from previous examples to account for the SVG coordinate system; the blue bar (where \\`key\\` is 0) is now positioned at the expected zero point of our future axis.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":801,"value":"{\n const container = d3.create('svg')\n .attr('width', width)\n .attr('height', height)\n .style('border', '1px dotted #999'); // <-- A dotted border helps us see the added margin\n\n const g = container.selectAll('g')\n .data(barData)\n .enter() \n .append('g')\n .attr('transform', d => `translate(${margin.left}, ${yMargin(d.key)})`);\n\n g.append('rect')\n .attr('width', d => xMargin(d.value) - xMargin(0)) // <-- We must subtract our left offset.\n .attr('height', yMargin.bandwidth())\n .style('fill', d => color(d.key))\n .style('stroke', 'white');\n\n g.append('text')\n .attr('x', d => xMargin(d.value) - xMargin(0)) // <-- We must subtract our left offset.\n .attr('dx', -20)\n .attr('dy', '1em')\n .attr('fill', 'white')\n .style('font-size', 'small')\n .text(d => d.value);\n\n return container.node();\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":811,"value":"md`The [d3-axis](https://github.com/d3/d3-axis) module offers a variety of helper functions to draw our axes, and customize their display (e.g., how many ticks are shown, what are their values, _etc._). An axis helper is meant to be called to populate a \\`\\` element. Also note how we apply a \\`translate\\` transformation to position the axes along the edges of the SVG element, offset by our margin.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":816,"value":"{\n const container = d3.create('svg')\n .attr('width', width)\n .attr('height', height)\n .style('border', '1px dotted #999'); \n\n container.append('g')\n .attr('transform', `translate(0, ${height - margin.bottom})`)\n .call(d3.axisBottom(xMargin));\n\n container.append('g')\n .attr('transform', `translate(${margin.left}, 0)`)\n .call(d3.axisLeft(yMargin));\n\n return container.node();\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":827,"value":"md`Our last step is then to merge all our code together, bars + axes:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":832,"value":"{\n const container = d3.create('svg')\n .attr('width', width)\n .attr('height', height);\n\n const g = container.selectAll('g')\n .data(barData)\n .enter() \n .append('g')\n .attr('transform', d => `translate(${margin.left}, ${yMargin(d.key)})`);\n\n g.append('rect')\n .attr('width', d => xMargin(d.value) - xMargin(0))\n .attr('height', yMargin.bandwidth())\n .style('fill', d => color(d.key))\n .style('stroke', 'white');\n\n g.append('text')\n .attr('x', d => xMargin(d.value) - xMargin(0))\n .attr('dx', -20)\n .attr('dy', '1em')\n .attr('fill', 'white')\n .style('font-size', 'small')\n .text(d => d.value);\n\n container.append('g')\n .attr('transform', `translate(0, ${height - margin.bottom})`)\n .call(d3.axisBottom(xMargin));\n\n container.append('g')\n .attr('transform', `translate(${margin.left}, 0)`)\n .call(d3.axisLeft(yMargin));\n\n return container.node();\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":887,"value":"md`Unfortunately, D3 does not offer a built-in mechanism for creating legends, but we will see how to create our own when we build an interactive legend in [Part 2](https://observablehq.com/@uwdata/introduction-to-d3-part-2)!`","pinned":false,"hidden":false,"mode":"ojs"},{"id":883,"value":"md`
\n## Summary`","pinned":false,"hidden":false,"mode":"ojs"},{"id":884,"value":"$34","pinned":false,"hidden":false,"mode":"ojs"},{"id":1108,"value":"md`
\n### Acknowledgements`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1111,"value":"md`This notebook is a revised version of Arvind Satyanarayan's [Introduction to D3](https://observablehq.com/@mitvis/introduction-to-d3), which in turn was heavily inspired by Mike Bostock's [Let's Make a Bar Chart](https://bost.ocks.org/mike/bar/) series. Jane Hoffswell made major contributions to this revision.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":674,"value":"md`
\n## Imports & Utilities`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1128,"value":"import {aq, op} from '@uwdata/arquero'","pinned":false,"hidden":false,"mode":"ojs"},{"id":736,"value":"import {graphic} from '@d3/margin-convention'","pinned":false,"hidden":false,"mode":"ojs"},{"id":1291,"value":"import {Scrubber} from \"@mbostock/scrubber\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":1133,"value":"datasets = require('vega-datasets')","pinned":false,"hidden":false,"mode":"ojs"},{"id":160,"value":"randomColor = () => `#${Math.floor(Math.random()*16777215).toString(16)}`","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W35","stdlib":"1","titling":"auto"}