30:T59f,md`So far in [6.859](http://vis.csail.mit.edu/classes/6.859/), we've primarily been working with _visual analysis grammars_ like [Vega-Lite](https://observablehq.com/@mitvis/data-types-graphical-marks-and-visual-encoding-channels) or VizQL (Tableau). These 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_. They're useful for concisely and rapidly creating recognizable visualizations, while giving us more design flexibility (or _expressivity_) than chart typologies like Microsoft Excel. However, describing visualization design in these high-level terms can also limit 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. 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:`31:T6b1,md`At this point, we're rapidly hitting 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). Turns out, we've been implicitly relying on HTML's layout model for our bar chart above: each \`

\`'s vertical position was based on the order it was created, rather than its data value. Now imagine we wanted to rotate our bar chart into a column chart (i.e., tall bars instead of long ones). To do so, we would likely 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. **Designing visualizations in this way would break our _visual encoding_ abstraction of mapping data values to visual properties, and thus yields a more difficult and brittle design process.** As a result, rather than persevering with HTML, we will instead switch to using [SVG](https://developer.mozilla.org/en-US/docs/Web/SVG) (or [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. Phew! Let's recreate our bar chart, but this time using SVG and \`\` elements:`32:T4e4,{ const height = 500; const svg = d3.create('svg') .attr('width', width) .attr('height', height); const xScale = d3.scaleLinear() .domain([0, d3.max(gapminder, d => d.fertility)]) .range([margin.left, width - margin.right]) .nice(); const yScale = d3.scaleLinear() .domain([0, d3.max(gapminder, d => d.life_expect)]) .range([height - margin.bottom, margin.top]) .nice(); const colorScale = d3.scaleOrdinal() .domain(gapminder.map(d => d.cluster)) .range(d3.schemeTableau10); // try other schemes, too! const year = 1955; const data = gapminder.filter(d => d.year === year); const symbol = d3.symbol(); svg.append('g') .attr('transform', d => `translate(${margin.left}, ${margin.top})`) .selectAll('path') // d3-shape functions (like d3.symbol) generate attributes for SVG elements .data(data) .join('path') .attr('transform', d => `translate(${xScale(d.fertility)}, ${yScale(d.life_expect)})`) .attr('fill', d => colorScale(d.cluster)) .attr('d', d => symbol()) // Notice, the output of the d3.symbol is wired up to the "d" attribute. gapminderScatterAxesLabel(svg, height, xScale, yScale, year); return svg.node(); }33:T4ad,function gapminderScatterAxesLabel(svg, height, xScale, yScale, year) { svg.append('g') .attr('transform', `translate(0, ${height - margin.bottom})`) .call(d3.axisBottom(xScale)) // Add x-axis title 'text' element. .append('text') .attr('text-anchor', 'end') .attr('fill', 'black') .attr('font-size', '12px') .attr('font-weight', 'bold') .attr('x', width - margin.right) .attr('y', -10) .text('Fertility'); svg.append('g') .attr('transform', `translate(${margin.left}, 0)`) .call(d3.axisLeft(yScale)) // Add y-axis title 'text' element. .append('text') .attr('transform', `translate(20, ${margin.top}) rotate(-90)`) .attr('text-anchor', 'end') .attr('fill', 'black') .attr('font-size', '12px') .attr('font-weight', 'bold') .text('Life Expectancy'); // Add a background label for the current year. const yearLabel = svg.append('text') .attr('class', 'year') .attr('x', 40) .attr('y', height - margin.bottom - 20) .attr('fill', '#ccc') .attr('font-family', 'Helvetica Neue, Arial') .attr('font-weight', 500) .attr('font-size', 80) .text(year); }34:T55e,{ const height = 500; const svg = d3.create('svg') .attr('width', width) .attr('height', height); const xScale = d3.scaleLinear() .domain([0, d3.max(gapminder, d => d.fertility)]) .range([margin.left, width - margin.right]) .nice(); const yScale = d3.scaleLinear() .domain([0, d3.max(gapminder, d => d.life_expect)]) .range([height - margin.bottom, margin.top]) .nice(); const colorScale = d3.scaleOrdinal() .domain(gapminder.map(d => d.cluster)) .range(d3.schemeTableau10); // try other schemes, too! /* TODO: Add code here for two new scales for shape and size. Hint: d3.symbols is an array of all built-in symbol types. */ const year = 1955; const data = gapminder.filter(d => d.year === year); svg.append('g') .attr('transform', d => `translate(${margin.left}, ${margin.top})`) .selectAll('path') .data(data) .join('path') .sort((a, b) => b.pop - a.pop) .attr('opacity', 0.75) .attr('transform', d => `translate(${xScale(d.fertility)}, ${yScale(d.life_expect)})`) .attr('fill', d => colorScale(d.cluster)) .attr('d', d => { const symbol = d3.symbol().size(/* TODO */).type(/* TODO */); return symbol() }); gapminderScatterAxesLabel(svg, height, xScale, yScale, year); return svg.node(); }35:T575,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. For more, we recommend perusing the [@d3 Observable notebooks](https://observablehq.com/@d3) or looking through the [curated gallery of examples](https://observablehq.com/@d3/gallery).`36:[{"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":1583151210295.882,"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":1583158331748.666,"size":25363},{"id":"4c33f55d72b1dce460e1ebc045b89a1a2ad5fe159f7e0d2dbedad1c0ea8d628b3f20f77bed2e1ae1ffe3ffb27cffc5b79c4f8dd3de9b604e307b21b78d26609a","href":"https://static.observableusercontent.com/files/4c33f55d72b1dce460e1ebc045b89a1a2ad5fe159f7e0d2dbedad1c0ea8d628b3f20f77bed2e1ae1ffe3ffb27cffc5b79c4f8dd3de9b604e307b21b78d26609a","name":"gapminder-scatter.png","type":"image/png","lastModified":1615826797270.308,"size":92638}] 2e:{"title":"Introduction to D3","cells":[{"id":0,"value":"md`# Introduction to D3`","pinned":false,"hidden":false,"mode":"ojs"},{"id":4,"value":"$30","pinned":false,"hidden":false,"mode":"ojs"},{"id":29,"value":"d3 = require('d3@6')","pinned":true,"hidden":false,"mode":"ojs"},{"id":32,"value":"md`And before we get much further, let's load a dataset for us 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 = (await require('vega-datasets'))['gapminder.json']()","pinned":false,"hidden":false,"mode":"ojs"},{"id":38,"value":"printTable(gapminder.slice(0, 10))","pinned":false,"hidden":false,"mode":"ojs"},{"id":16,"value":"md`## Selections`","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 .attr('class', 'country')\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://github.com/d3/d3-selection): 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://github.com/d3/d3-selection#select) or [\\`d3.selectAll\\`](https://github.com/d3/d3-selection#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)) but differ in two key ways.\n\nFirst, we can manipulate a selection _declaratively_. This means that rather than iterating over every item returned by the selector (like we would've had to when using \\`document.querySelectorAll\\`), we can operate on the selection as a whole:`","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\nd3.selectAll('li.country').style('color', randomColor()), null","pinned":true,"hidden":false,"mode":"ojs"},{"id":197,"value":"md`## Data Binding`","pinned":false,"hidden":false,"mode":"ojs"},{"id":184,"value":"md`Second, and more importantly for our purposes today, we can use the [\\`selection.data\\`](https://github.com/d3/d3-selection/blob/master/README.md#selection_data) operator to create DOM elements using some backing data.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":200,"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 for Observable to render\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":212,"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":217,"value":"html``","pinned":false,"hidden":false,"mode":"ojs"},{"id":241,"value":"md`_Credit: [Mike Bostock](https://bost.ocks.org/mike/join/)_`","pinned":false,"hidden":false,"mode":"ojs"},{"id":249,"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\nMatches are determined by the second argument to \\`.data\\`, which specifies a _key_ function. If no key function is specified (like our code cell above), 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.\n\nWe can address the three states separately, but the [\\`selection.join\\`](https://github.com/d3/d3-selection/blob/master/README.md#selection_join) operator gives us a more convenient interface for doing so:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":282,"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') // a selection that merges the \"enter\" and \"update\" states\n\n return ol.node();\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":287,"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":293,"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(\n enter => enter.append('li'),\n update => update,\n exit => exit.remove()\n )\n \n return ol.node();\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":1132,"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. \\`selection.join\\` returns a selection representing the _enter_ and _update_ steps, which we can then declaratively manipulate like before:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1137,"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')\n .attr('class', 'country') // set each list element's \"class\" attribute to \"country\"\n .text(d => `${d.country}: ${fmt(d.pop)}`) // add text to each list element\n \n return ol.node();\n}","pinned":true,"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 blue, and exiting items are _not_ removed but rather colored red.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1144,"value":"md`You can use the slides below to change the elements in the backing \\`listData\\` to test your changes to \\`enter\\`, \\`update\\`, and \\`exit\\`.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":105,"value":"viewof year = Range([d3.min(gapminder, d => d.year), d3.max(gapminder, d => d.year)], {label: 'year', step: 5})","pinned":false,"hidden":false,"mode":"ojs"},{"id":108,"value":"viewof n = Range([0, 15], {label: 'n', step: 1})","pinned":false,"hidden":false,"mode":"ojs"},{"id":319,"value":"{\n const ol = d3.select(html`
`);\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, which can be manipulated with the sliders 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) // bind our data values; what do you notice about which li's are red/green/blue?\n .join(\n enter => enter.append('li'),\n update => update,\n exit => exit.remove()\n ) \n .text(d => `${d.country}: ${fmt(d.pop)}`)\n \n return newData;\n}","pinned":true,"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 later lectures, 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`## 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.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":395,"value":"FileAttachment(\"Screen Shot 2020-03-02 at 7.13.09 AM.png\").image()","pinned":false,"hidden":false,"mode":"ojs"},{"id":364,"value":"barData = d3.rollups(gapminder, vals => ~~d3.mean(vals, d => d.life_expect), d => d.cluster)\n .map(d => ({key: d[0], value: d[1]}))\n .sort((a, b) => +a.key - +b.key)","pinned":false,"hidden":false,"mode":"ojs"},{"id":362,"value":"{\n const container = d3.create('div');\n \n const barChart = container.selectAll(/* TODO */)\n\n /* TODO: Add code here to generate the bar chart within the container. \n (Hint: The \"barData\" variable holds the data to visualize.) */\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 divs to 'white'\n .style('padding', '3px') // Give the bars some padding\n .style('font-size', 'small') // Set the font size of text inside the div to 'small'\n /* TODO: Add code here to finish styling the visual properties and content of
elements */\n \n return container.node();\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":409,"value":"md`Not too bad, but our simple bar chart exposes one weakness in the way we're currently specifying our visual encodings. The _width_ of our bars are currently dependent on a magic number. This number scales the data value to a pixel width, but there's a lot of magic wrapped up in it including the minimum and maximum values in our data, and the desired width of the chart.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":420,"value":"md`## Scale Functions`","pinned":false,"hidden":false,"mode":"ojs"},{"id":423,"value":"md`Rather than implicitly dealing with these issues, or introducing maintenance and readability costs associated with magic numbers, D3 offers us a variety of [scale functions](https://github.com/d3/d3-scale#d3-scale) to automatically map a _domain_ or data values to a _range_ of pixel values.\n\nSo, for instance, we can use the following scale to determine the width of our bars (\\`width\\` is a built in variable that Observable provides us: ${width}px):`","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]) ","pinned":true,"hidden":false,"mode":"ojs"},{"id":433,"value":"md`Here, \\`xscale\\` is a function that linearly scales an input value to map 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`Thus, 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 here.\n .text(d => d.value)\n \n return container.node();\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":448,"value":"md`Scales are the workhorse of visualization design, and help our code remain as _declarative_ as possible. For example, we might want to assign each bar a different color. One option to doing so would involve a large ternary expression or if-then-else statement. We can instead use a [color scale](https://github.com/d3/d3-scale-chromatic#d3-scale-chromatic) like so:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":452,"value":"colorScale = d3.scaleOrdinal(d3.schemeTableau10).domain(barData.map(d => d.key)); \n// Default color schemes are here: https://github.com/d3/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 => colorScale(d.key))\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`## SVG: Scalable Vector Graphics`","pinned":false,"hidden":false,"mode":"ojs"},{"id":462,"value":"$31","pinned":false,"hidden":false,"mode":"ojs"},{"id":498,"value":"{\n const barHeight = 25,\n 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 => colorScale(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.2em')\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 code. Can you spot it?`","pinned":false,"hidden":false,"mode":"ojs"},{"id":583,"value":"md`Using SVG does not mean we need to imperatively determine 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 into equally-sized bars.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":779,"value":"viewof height = Range([50, 200], {label: 'height', step: 25})","pinned":false,"hidden":false,"mode":"ojs"},{"id":586,"value":"yScale = d3.scaleBand()\n .domain(barData.map(d => d.key))\n .range([height, 0]) // Try flipping this to [0, height] and see the effect on the bars below.","pinned":true,"hidden":false,"mode":"ojs"},{"id":595,"value":"md`Notice that this scale maps to a range of \\`[height, 0]\\` and not \\`[0, height]\\` as we might initially have guessed. This is because the origin \\`(0, 0)\\` of the SVG coordinate system is in the top-left hand corner of the SVG element.\n\nAnd now, we can use our new y scale 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 the \"yScale\" here instead of manually positioning bars\n .attr('width', d => xScale(d.value))\n .attr('height', yScale.bandwidth()) // Band scales divide a pixel range into equally-sized bands\n .style('fill', d => colorScale(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 the \"yScale\" here 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":1219,"value":"md`Exercise: Edit the code below to change our bar chart from a horizontal orientation to a vertical orientation (as shown 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":"{\n const width = 400, \n height = 200;\n \n const container = d3.create('svg')\n .attr('width', width)\n .attr('height', height);\n \n // Redefine the x scale here.\n const x = /* add code here */;\n \n // Redefine the y scale here.\n const y = /* add code here */;\n \n container.selectAll('rect')\n .data(barData)\n .join('rect')\n .attr('x', d => /* add code here */)\n .attr('y', d => /* add code here */) \n .attr('width', d => /* add code here */)\n .attr('height', d => /* add code here */) \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 => /* add code here */)\n .attr('y', d => /* add code here */) \n .attr('dx', /* add code here */)\n .attr('dy', '1em')\n .attr('fill', 'white')\n .style('font-size', 'small')\n .style('text-anchor', 'middle')\n .text(d => d.value)\n \n return container.node();\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":679,"value":"md`As you can see, scales are really 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 offers us some helper modules to do just that but we have to take a bit of a tangent first.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":686,"value":"md`## \\`\\`: 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 similar to how we might do so in 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, the \\`\\` and \\`\\` elements are now children of the \\`\\`, 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 // Notice, 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 => colorScale(d.key))\n .style('stroke', 'white');\n \n g.append('text')\n // Notice, 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`## 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 [like in this notebook](https://observablehq.com/@d3/color-legend) but D3 (and its wider 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 to 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. Notice, we now have some whitespace around the left and bottom of the SVG element just waiting for our axes!`","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 whitespace.\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)) // Notice, we must subtract our left offset.\n .attr('height', yMargin.bandwidth())\n .style('fill', d => colorScale(d.key))\n .style('stroke', 'white');\n \n g.append('text')\n .attr('x', d => xMargin(d.value) - xMargin(0)) // Notice, 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 along with a \\`\\` element like so. Notice 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 => colorScale(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. Luckily, the [d3-legend](https://d3-legend.susielu.com/) library by Susie Lu gives us reusable components for color, shape, and size legends. You can invoke them against \\`\\` elements much like the \\`d3.axis\\` components we saw above. (Mike Bostock also has a [color legend](https://observablehq.com/@d3/color-legend) notebook which you can import from.)`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1242,"value":"md`## Shapes`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1247,"value":"md`Besides allowing us to maintain our visual encoding abstraction (mapping data values to visual properties), SVG also gives us a much richer palette of shapes to use as marks. [Built-in shapes](https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Basic_Shapes) include \\`rect\\`, \\`circle\\`, \\`ellipse\\` and \\`line\\`, as well as the more general-purpose \\`polyline\\`, \\`polygon\\`, and \\`path\\`. \n\nWhile you can use any of these elements directly, the [d3-shape](https://github.com/d3/d3-shape) module offers several helper functions that simplify generating visualization-specific marks (e.g., lines, scatterplot symbols, and arcs & wedges for donut and pie charts). \n\nThe output of these generator functions is then used to set the \\`d\\` attribute of SVG \\`path\\` elements, like so:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1256,"value":"$32","pinned":true,"hidden":false,"mode":"ojs"},{"id":1331,"value":"$33","pinned":false,"hidden":false,"mode":"ojs"},{"id":1323,"value":"md`But, we don't have to stop there. Exercise: How do we create the scatterplot below? _Hint: We'll need a couple of new scales, which we then use to set properties on the symbol generator function_.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1319,"value":"FileAttachment(\"gapminder-scatter.png\").image()","pinned":false,"hidden":false,"mode":"ojs"},{"id":1292,"value":"$34","pinned":true,"hidden":false,"mode":"ojs"},{"id":1344,"value":"md`For more, check out the [d3-shape](https://observablehq.com/collection/@d3/d3-shape) Observable notebook collection, which has many more examples of how you can use the other shape generator functions including [pie charts](https://observablehq.com/@d3/pie-chart?collection=@d3/d3-shape), [donut charts](https://observablehq.com/@d3/donut-chart?collection=@d3/d3-shape), [area charts](https://observablehq.com/@d3/area-chart?collection=@d3/d3-shape), and [various](https://observablehq.com/@d3/stacked-area-chart?collection=@d3/d3-shape) [ways](https://observablehq.com/@d3/streamgraph?collection=@d3/d3-shape) [to](https://observablehq.com/@d3/stacked-normalized-horizontal-bar?collection=@d3/d3-shape) [stack](https://observablehq.com/@d3/stacked-horizontal-bar-chart?collection=@d3/d3-shape).`","pinned":false,"hidden":false,"mode":"ojs"},{"id":883,"value":"md`## Summary`","pinned":false,"hidden":false,"mode":"ojs"},{"id":884,"value":"$35","pinned":false,"hidden":false,"mode":"ojs"},{"id":1108,"value":"md`### Acknowledgements`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1111,"value":"md`This tutorial is heavily inspired by Mike Bostock's [Let's Make a Bar Chart](https://bost.ocks.org/mike/bar/) series, and [updates](https://observablehq.com/@uwdata/introduction-to-d3-part-1) from UW's Interactive Data Lab have been propagated back.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":674,"value":"md`## Utilities`","pinned":false,"hidden":false,"mode":"ojs"},{"id":736,"value":"import {graphic} from '@d3/margin-convention'","pinned":false,"hidden":false,"mode":"ojs"},{"id":160,"value":"randomColor = () => `#${Math.floor(Math.random()*16777215).toString(16)}`","pinned":false,"hidden":false,"mode":"ojs"},{"id":36,"value":"import {fromColumns, printTable} from '@uwdata/data-utilities'","pinned":false,"hidden":false,"mode":"ojs"},{"id":1149,"value":"import {Range} from \"@observablehq/inputs\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":1176,"value":"fmt = d3.format(',')","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W36","stdlib":"1","titling":"auto"}